Gerbil MCP

沙土鼠mcp

MCP（模型上下文协议）服务器，使AI助手能够实时访问Gerbil Scheme环境。它允许Claude（或任何MCP客户端）评估表达式、检查模块导出、检查语法、扩展宏、编译检查代码、逐步跟踪宏扩展、维护持久REPL会话、配置函数性能、分析堆内存使用情况、跟踪调用计数、可视化调用图、管理包、脚手架项目和测试文件、生成模块存根、使用结构化诊断构建项目、查找符号引用和建议导入——所有这些都是针对真实的Gerbil运行时，而不是从训练数据中猜测。

服务器还提供MCP 资源 用于浏览烹饪书食谱库， 提示 适用于常见的Gerbil工作流程，以及 工具注释 (readOnlyHint/idempotentHint)因此，客户可以就工具安全做出明智的决定。

先决条件

• Node.js >= 18
• 沙比尔方案 已安装 gxi, gxc，以及 gxpkg 可用（用v0.19+测试）

安装

git clone https://github.com/ober/gerbil-mcp.git
cd gerbil-mcp
npm install
npm run build

配置

克劳德代码

使用CLI添加MCP服务器（用户范围--适用于所有项目）：

claude mcp add -s user gerbil \
  -e GERBIL_MCP_GXI_PATH=/opt/gerbil/bin/gxi \
  -- node /absolute/path/to/gerbil-mcp/dist/index.js

或者仅针对单个项目：

claude mcp add -s project gerbil \
  -e GERBIL_MCP_GXI_PATH=/opt/gerbil/bin/gxi \
  -- node /absolute/path/to/gerbil-mcp/dist/index.js

这会将配置写入 ~/.claude.json （用户范围）或 .mcp.json 在项目根（项目范围）中。启动一个新的Claude Code会话以获取服务器。

自动批准所有Gerbil工具

默认情况下，每次调用MCP工具时，Claude Code都会要求确认。由于Gerbil工具是只读自检（没有文件系统写入，没有网络访问），您可以在项目中使用通配符安全地自动批准它们 .claude/settings.local.json （本地，未登记）或 ~/.claude/settings.json （用户范围）：

{
  "permissions": {
    "allow": [
      "mcp__gerbil__*"
    ]
  }
}

GitHub副本（VS代码）

添加一个 .vscode/mcp.json 文件到您的项目：

{
  "servers": {
    "gerbil": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gerbil-mcp/dist/index.js"],
      "env": {
        "GERBIL_MCP_GXI_PATH": "/opt/gerbil/bin/gxi"
      }
    }
  }
}

或者将其添加到您的VS Code用户设置中(settings.json)使其可用于所有项目：

{
  "mcp": {
    "servers": {
      "gerbil": {
        "type": "stdio",
        "command": "node",
        "args": ["/absolute/path/to/gerbil-mcp/dist/index.js"],
        "env": {
          "GERBIL_MCP_GXI_PATH": "/opt/gerbil/bin/gxi"
        }
      }
    }
  }
}

GitHub复制品编码代理

这 复制品编码剂 在GitHub Actions环境中运行。在GitHub.com的存储库设置中配置MCP服务器 设置→ 副驾驶→ 编码代理使用此JSON：

{
  "mcpServers": {
    "gerbil": {
      "type": "stdio",
      "command": "node",
      "args": ["/home/runner/gerbil-mcp/dist/index.js"],
      "tools": ["*"],
      "env": {
        "GERBIL_MCP_GXI_PATH": "$COPILOT_MCP_GERBIL_GXI_PATH"
      }
    }
  }
}

由于代理在GitHub Actions运行器上运行，因此在安装过程中必须安装Gerbil和此服务器。创建 .github/workflows/copilot-setup-steps.yml:

name: "Copilot Setup Steps"
on: workflow_dispatch

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      # Install Gerbil — adjust to your preferred method
      - name: Install Gerbil
        run: |
          # Example: install from a release or package manager
          # See https://cons.io/guide/install.html
          sudo apt-get update && sudo apt-get install -y gerbil

      # Clone and build gerbil-mcp
      - name: Setup gerbil-mcp
        run: |
          git clone https://github.com/ober/gerbil-mcp.git /home/runner/gerbil-mcp
          cd /home/runner/gerbil-mcp
          npm install
          npm run build

添加一个 COPILOT_MCP_GERBIL_GXI_PATH 存储库中的秘密 copilot 环境（例如。 /usr/bin/gxi)指向 gxi 二元的。

GitHub Copilot命令行界面

将服务器添加到 ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "gerbil": {
      "type": "local",
      "command": "node",
      "args": ["/absolute/path/to/gerbil-mcp/dist/index.js"],
      "env": {
        "GERBIL_MCP_GXI_PATH": "/opt/gerbil/bin/gxi"
      },
      "tools": ["*"]
    }
  }
}

要在项目中自动加载针对CLI的Gerbil特定说明，请将示例文件复制到 .github/copilot-instructions.md:

mkdir -p .github
cp /path/to/gerbil-mcp/copilot-instructions.md.gerbil-example .github/copilot-instructions.md

或者，有关所有项目的全局说明，请复制到 ~/.copilot-instructions.md:

cp /path/to/gerbil-mcp/copilot-instructions.md.gerbil-example ~/.copilot-instructions.md

开源代码

OpenCode从以下位置读取MCP配置 opencode.json 文件夹。配置按优先级顺序从多个来源合并：

1. 全局配置: ~/.config/opencode/opencode.json
2. 项目本地配置: opencode.json 在项目根中（或从cwd中走出来）
3. 项目 .opencode/ 目录: .opencode/opencode.json

全局设置（所有项目）

创建或编辑 ~/.config/opencode/opencode.json:

{
  "mcp": {
    "gerbil": {
      "type": "local",
      "command": ["node", "/absolute/path/to/gerbil-mcp/dist/index.js"],
      "environment": {
        "GERBIL_MCP_GXI_PATH": "/opt/gerbil/bin/gxi"
      }
    }
  }
}

项目本地设置（单个项目）

创建 opencode.json 在项目根目录中：

{
  "mcp": {
    "gerbil": {
      "type": "local",
      "command": ["node", "/absolute/path/to/gerbil-mcp/dist/index.js"],
      "environment": {
        "GERBIL_MCP_GXI_PATH": "/opt/gerbil/bin/gxi"
      }
    }
  }
}

要验证配置是否已加载，请运行 opencode debug config 并检查 mcp 本节包括 gerbil 进入。

要自动加载Gerbil特定的说明，请将示例文件复制到您的项目中：

mkdir -p .opencode
cp /path/to/gerbil-mcp/CLAUDE.md.gerbil-example .opencode/AGENTS.md

或获取所有项目的全局指示：

cp /path/to/gerbil-mcp/CLAUDE.md.gerbil-example ~/.config/opencode/AGENTS.md

其他MCP客户端

任何兼容MCP的客户端都可以使用stdio传输进行连接。服务器从stdin读取JSON-RPC并写入stdout：

node /path/to/gerbil-mcp/dist/index.js

环境变量

工具

沙土鼠_瓦尔

计算Gerbil Scheme表达式并返回结果。

expression: "(+ 1 2)"
=> Result: 3

expression: "(json-object->string (hash (\"a\" 1)))"
imports: [":std/text/json"]
=> Result: "{\"a\":1}"

expression: "(config-omit-events (load-config))"
imports: [":myproject/config"]
loadpath: ["/path/to/myproject/.gerbil/lib"]
=> Result: ("event-a" "event-b")

gerbill_模块_导出

列出沙比尔模块中导出的所有符号。

module_path: ":std/text/json"
=> Module :std/text/json exports 21 symbol(s):
     read-json
     write-json
     json-object->string
     ...

沙土鼠_检查_合成物

在不评估的情况下验证Gerbil代码。使用Gerbil扩展器。

code: "(if #t 1 2)"
=> Syntax is valid.

code: "(if)"
=> Syntax error: Bad syntax; invalid syntax-case clause

沙土鼠\_ expand_macro

展示沙比尔表情的核心展开形式。

expression: "(when #t (displayln \"hi\"))"
=> (%#if (%#quote #t) (%#call (%#ref displayln) (%#quote "hi")) (%#quote #!void))

非洲菊

在所有Gambit/Gerbil名称空间中搜索与模式匹配的符号。

pattern: "hash-get"
=> empty namespace:
     __hash-get, hash-get

gerbill_list_std模块

通过扫描Gerbil安装，列出可用的标准库模块。

prefix: "std/text"
=> [std] (16 modules)
     :std/text/base58
     :std/text/base64
     :std/text/csv
     :std/text/json
     ...

沙鼠功能签名

获取模块中导出符号的arity和类型信息。显示每个导出是过程（带参数计数）、宏/语法还是值。

module_path: ":std/text/json"
=> :std/text/json — 21 export(s):
     read-json  procedure  arity:1  (std/text/json/util#read-json)
     write-json  procedure  arity:1  (std/text/json/util#write-json)
     JSON  macro/syntax
     ...

module_path: ":std/text/json", symbol: "read-json"
=> :std/text/json — 1 export(s):
     read-json  procedure  arity:1  (std/text/json/util#read-json)

gerbil_module_deps

显示给定模块导入的模块。支持传递依赖解析。

module_path: ":std/text/json"
=> :std/text/json — 1 direct dependencies:
     :std/text/json/api

module_path: ":std/net/httpd", transitive: true
=> :std/net/httpd — transitive dependency tree (3 unique modules):
     :std/net/httpd
       -> :std/net/httpd/api
     :std/net/httpd/api
       -> :std/net/httpd/handler
     ...

gerbill_load_file

读取Gerbil源文件并提取其顶级定义。分析导入、导出和按类型分类的所有已定义符号。不执行该文件。

file_path: "/path/to/server.ss"
=> File: /path/to/server.ss

   Imports (3):
     :std/net/httpd
     :std/text/json
     :std/logger

   Definitions (4):
     start-server  (define)
     config  (defstruct)
     handle-request  (define)
     setup-routes  (define)

沙土鼠.doc

查找有关符号的全面信息：其类型（过程/宏/值）、arity、限定名和相关符号。

symbol: "read-json", module_path: ":std/text/json"
=> Symbol: read-json

   Kind: procedure
   Qualified name: std/text/json/util#read-json
   Arity: 1
   Module: :std/text/json

   Related symbols:
   "std/text/json/util#" namespace:
     read-json, read-json__%, read-json__0

symbol: "when-let", module_path: ":std/sugar"
=> Symbol: when-let

   Kind: macro/syntax
   Qualified name: when-let
   Module: :std/sugar

沙土鼠检查

运行Gerbil编译器(gxc -S)在代码中捕获编译错误，例如仅语法检查就忽略的未绑定标识符。验证完整的编译管道，而不产生C输出。增强的错误消息可检测已知的编译器内部崩溃并提供诊断提示。

code: "(import :std/text/json) (define (f x) (read-json x))"
=> Compilation check passed. Code compiled successfully (gxc -S).

code: "(import :std/text/json) (define (f x) (nonexistent-fn x))"
=> Compilation errors found:
   *** ERROR IN ""@1.42-1.56
   --- Syntax Error: Reference to unbound identifier
   ... detail: nonexistent-fn

file_path: "/path/to/project/config.ss"
loadpath: ["/path/to/project/.gerbil/lib"]
=> Compilation check passed. /path/to/project/config.ss compiled successfully (gxc -S).

当gxc遇到内部错误时（例如。， stx-car-e，代码生成崩溃），该工具会附加一个提示，解释可能的原因并建议解决方法。

沙鼠_赛马_魔术

使用显示逐步宏扩展 core-expand1 迭代。每一步都显示了一个层次的脱糖过程，从糖的形式到核心形式。

expression: "(when #t (displayln 42))"
=> Macro expansion trace for: (when #t (displayln 42))
   (4 steps)

   [input]   (when #t (displayln 42))
   [step 1]  (if #t (begin (displayln 42)) #!void)
   [step 2]  (%#if #t (begin (displayln 42)) #!void)
   [step 3]  (%#if (%#quote #t) (%#call (%#ref displayln) (%#quote 42)) (%#quote #!void))

expression: "(if-let (x 5) (displayln x) (displayln #f))"
imports: [":std/sugar"]
=> Macro expansion trace for: (if-let (x 5) (displayln x) (displayln #f))
   (2 steps)

   [input]   (if-let (x 5) (displayln x) (displayln #f))
   [step 1]  (let (test 5) (if test (let (x test) (displayln x)) (displayln #f)))

沙土鼠再繁殖期

管理持续的Gerbil REPL会话。状态（定义、导入、变量）在会话内的评估中持续存在，与 gerbil_eval 它是无国籍的。

action: "create"
=> Session created: a1b2c3d4

action: "create", project_path: "/path/to/myproject"
=> Session created: b2c3d4e5
   GERBIL_LOADPATH configured with:
     /path/to/myproject/.gerbil/lib
   Project package: myproject

action: "create", preload_file: "/path/to/myproject/server.ss"
=> Session created: d4e5f6g7

   Preloaded imports from /path/to/myproject/server.ss:
   Loaded (3):
     (import :std/net/httpd)
     (import :std/text/json)
     (import :std/logger)

action: "eval", session_id: "a1b2c3d4", expression: "(define x 42)"
=> (void)

action: "eval", session_id: "a1b2c3d4", expression: "(+ x 10)"
=> 52

action: "list"
=> Active REPL sessions (1):
     a1b2c3d4  (age: 45s, idle: 2s)

action: "destroy", session_id: "a1b2c3d4"
=> Session "a1b2c3d4" destroyed.

会话在10分钟不活动后自动过期。最多5个并发会话。

当 project_path 如果提供，会话将自动添加 {project_path}/.gerbil/lib 到加载路径并读取 gerbil.pkg 用于信息显示。这使您可以交互式地导入和测试项目本地模块，而无需更改导入路径。

当 preload_file 如果提供了，会话将读取文件的导入表单，并在创建后对其进行评估。这使您可以立即使用文件导入模块中的函数，而无需手动导入每个模块——这对于调试测试文件或探索模块的上下文非常有用。

沙土鼠_轮_测试

运行沙比尔测试并返回结构化结果。支持两种模式： 单文件模式 (file_path)通过以下方式运行单个测试文件 gxi，以及 目录模式 (directory)通过以下方式运行项目范围内的测试 gerbil test 通过递归发现。

之一 file_path 或 directory 是必需的。

file_path: "/path/to/tests.ss"
=> Result: PASSED

   Test Summary:
     math: OK

   Checks: 3 total

   --- Full output ---
   ... check (+ 1 2) is equal? to 3
   ...

directory: "/path/to/project"
=> Result: PASSED

   Test Summary:
     billing: OK
     detection: OK

   Checks: 24 total

   --- Full output ---
   ...

directory: "/path/to/project", filter: "billing"
=> Result: PASSED

   Filter: billing

   Test Summary:
     billing: OK

   Checks: 12 total
   ...

沙土鼠_ffi_inspect

检查沙比尔模块的FFI（外部功能接口）绑定。将导出分类为C常量（大写）、C风格函数（下划线名称）或Gerbil包装器。显示常量值和函数的线性度。可选地提供来源 file_path 也提取 begin-foreign 和 extern 声明。

module_path: ":std/os/signal"
=> FFI inspection of :std/os/signal:

   C Constants (35):
     SIG_SETMASK = 3
     SIG_BLOCK = 1
     SIGTERM = 15
     SIGKILL = 9
     ...

   C-style Functions (1):
     make_sigset  arity:0

   Gerbil Wrappers (8):
     sigprocmask  procedure arity:3
     kill  procedure arity:2
     ...

gerbill_class_info

检查沙比尔 defclass/defstruct 类型描述符。显示类型名称、插槽、自身字段、结构与类、超类型、优先级列表（MRO）和构造函数。

type_name: "Error", module_path: ":std/error"
=> Type: Error (class)

   Slots: continuation message irritants where
   Own fields: continuation message irritants where
   Super: (none)
   Precedence: StackTrace -> Exception -> object -> t
   Constructor: :init!

type_name: "JSON", module_path: ":std/text/json"
=> Type: JSON (class)

   Slots: (none)
   Own fields: (none)
   Super: (none)
   Precedence: object -> t
   Constructor: (none)

非洲菊定义

查找沙比尔符号的定义位置。返回限定名、模块文件路径、源文件路径（如果可用）、类型和arity。可选地包括定义的源代码预览。

symbol: "read-json", module_path: ":std/text/json"
=> Symbol: read-json

   Kind: procedure
   Qualified name: std/text/json/util#read-json
   Arity: 1
   Module: :std/text/json
   Module file: /opt/gerbil/.../std/text/json/util.ssi
   Source file: (not available — compiled module)

symbol: "read-json", module_path: ":std/text/json", source_preview: true
=> Symbol: read-json
   ...
   Source preview:

(def (read-json port) ...)

gerbil_build_project

Build or clean a Gerbil project directory using gxpkg.

project_path：“/path/to/my project”，action:“build”，release:true
=>构建成功（发布）。

…编译输出。..

gerbil_package_info

List installed Gerbil packages, search the package directory, or show package metadata.

操作：“列表”
=>已安装的软件包（3）：

github.com/user/pkg1 github.com/user/pkg2 ...

操作：“搜索”，查询：“json”
=>“json”的搜索结果：

github.com/... json processing library ...

gerbil_format

Pretty-print/format Gerbil Scheme expressions using Gambit's pretty-print.

代码：“（定义（f x y）（cond（（>x y），（+x 1））（（\（定义（f x y）
（第二（（>x y）（+x 1））
（（\基准测试：（let循环…）

迭代次数：3
总壁时间：1.71ms
平均壁时间：571.6us
用户时间：1.50ms
系统时间：0.0us
GC时间：0.0us
GC计数：0
分配的字节数：2.3 MB

结果：49995000

gerbil_error_hierarchy

Show the full Gerbil exception/error class hierarchy as a tree.

=>沙比尔错误类型层次结构：

吨
--对象
--例外情况
|-- StackTrace
||--错误
|||--违反合同
|||--UnboundKeyError
||--IOError
||||--输入过早结束
|||--已关闭
|||--超时
-上下文错误。
|--运行时异常

优先级列表：
错误：StackTrace->异常->对象->t
IOError:错误->堆栈跟踪->异常->对象->t
...

gerbil_version

Report Gerbil and Gambit versions, installation path, and system type. No parameters required.

=>沙比尔环境

沙比尔版本：v0.19-dev
Gambit版本：v4.9.7-6-g64f4d369
沙比尔主页：/opt/Gerbil/v0.19-dev/
系统类型：（操作系统“linux”）

gerbil_scaffold

Create a new Gerbil project from a template using gxpkg new. Generates gerbil.pkg, build.ss, and initial source files.

project_path：“/tmp/my project”，包：“myapp”，链接：“github.com/user/my项目”
=>在/tmp/my项目中搭建的项目。

gerbil_package_manage

Install, update, or uninstall Gerbil packages.

操作：“安装”，包：“github.com/powerful gerbills/gerbill crypto”
=>已成功安装github.com/mighty-gerbills/gerbill-crypto软件包。

操作：“更新”，包：“全部”
=>包全部更新成功。

操作：“卸载”，包：“github.com/powerful gerbills/gerbill crypto”，强制：true
=>已成功卸载github.com/mighty-gerbills/gerbill-crypto软件包。

gerbil_find_callers

Find all files that reference a given symbol. Recursively scans .ss files in a directory for occurrences and reports file paths with line numbers.

符号：“读取json”，目录：“/path/to/project”
=>引用“read-json”（2个文件）：

/path/to/project/server.ss lines: 15,28 /path/to/project/api.ss lines: 7

符号：“读取json”，目录：“/path/to/project”，模块路径：“：std/text/json”
=>引用“read-json”（1个文件）：

/path/to/project/server.ss lines: 15,28

gerbil_suggest_imports

Find which standard library module exports a given symbol. Scans common :std/* modules and reports matching import statements.

符号：“读取json”
=>符号“read-json”导出方式为：

(import :std/text/json)

符号：“for/collect”
=>符号“for/collect”由以下方式导出：

(import :std/iter)

For less common modules, use gerbil_apropos + gerbil_module_exports as a fallback.

gerbil_diagnostics

Run gxc -S on a file or all .ss files in a project and return structured diagnostics with file, line, column, severity, and message.

file_path：“/path/to/module.ss”
=>编译干净：/path/to/module.ss

project_path：“/path/to/project”
=>/path/to/project的诊断：

/path/to/project/server.ss:12:5：错误：对未绑定标识符的引用：foo
/path/to/project/utils.ss：编译干净

gerbil_document_symbols

List all definitions in a Gerbil source file with name, kind, and line number.

file_path：“/path/to/server.ss”
=>/path/to/server.ss中的符号（5）：

L1 import (import :std/net/httpd ...) L4 procedure start-server L8 struct config L12 procedure handle-request L20 procedure setup-routes

gerbil_workspace_symbols

Search for symbol definitions across all .ss files in a project directory. Returns matching definitions with name, kind, line number, and file path.

查询：“句柄”，目录：“/path/to/project”
=>与“句柄”匹配的工作区符号（3个结果）：

handle-request procedure L12 server.ss handle-error procedure L5 errors.ss handle-auth procedure L18 auth.ss

gerbil_rename_symbol

Rename a symbol across all .ss files in a project directory. Default is dry-run mode (showing proposed changes). Set dry_run to false to apply changes. Uses word-boundary detection to avoid renaming partial matches.

old_name：“处理请求”，new_name：“进程请求”，目录：“/path/to/project”
=>模拟运行：重命名“句柄请求”→ “处理请求”

服务器.ss：
L12:（def（处理请求…）→ （def（进程请求…）
L45：（处理请求ctx）→ （处理请求ctx）
api.ss：
L7：（出口处理请求）→ （出口流程请求）

2个文件中出现3次。

gerbil_lint

Static analysis for common Gerbil issues: unused imports, duplicate definitions, style warnings (define vs def, missing transparent:), shadowed standard bindings, hash literal symbol key warnings, and compilation errors via gxc.

file_path：“/path/to/module.ss”
=>Lint:/path/to/module.ss
1个错误，2个警告，1条信息

[WARNING] L3 (possibly-unused-import): Import :std/format may be unused [WARNING] L10 (hash-symbol-key): Hash literal uses bare symbol key 'CRITICAL' — this creates a symbol key, not a string. Use ("CRITICAL" ...) for string keys. [INFO] L5 (style-prefer-def): Prefer "def" over "define" (supports optional/keyword args)

gerbil_project_info

Single-call summary of a Gerbil project: package name, build targets, source files, and external dependencies. Reads gerbil.pkg, build.ss, and scans source files.

project_path：“/path/to/myproject”
=>包：myproject
位置：/path/to/myproject

构建目标：
\[lib\]配置
\[lib\]服务器
\[exe\]主->myapp

源文件（5）：
./
config.ss
服务器.ss
main.ss
utils/
帮助者.ss
db.ss

外部依赖关系（3）：
：std/net/httpd
：std/text/json
：std:db/postgresql

gerbil_project_map

Single call that returns all modules in a project with their exports, key definitions grouped by kind, and import dependencies. More detailed than gerbil_project_info — shows the full symbol map.

project_path：“/path/to/myproject”
=>项目：myproject
位置：/path/to/myproject
模块：3

模块：config.ss
导出：加载配置、配置端口、配置主机
结构：配置
步骤：加载配置、配置端口、配置主机
外部导入：：std/text/json

模块：server.ss
导出：启动服务器，停止服务器
程序：启动服务器、停止服务器、处理请求
外部导入：：std/net/httpd，：std/text/json
国内进口：。/config

模块：main.ss
程序：主要
外部导入：：std:getopt
国内进口：。/服务器。/config

gerbil_check_balance

Check parenthesis/bracket/brace balance in Gerbil Scheme code. Pure delimiter scanner — no subprocess, runs in milliseconds. Reports unclosed delimiters, unexpected closers, and mismatches with positions.

file_path：“/path/to/module.ss”
=>平衡正常——12个顶级表单，156个分隔符

代码：“（def（f x）（+x 1）”
=>平衡误差：

Unclosed '(' opened at line 1, column 1

gerbil_read_forms

Read a Gerbil source file using the actual Gerbil reader and list all top-level forms with their index, start/end line numbers, and a summary (car of list or type). On reader error, reports the error position plus any forms read before the error.

file_path：“/path/to/module.ss”
=>/path/to/module.ss中的表单（4个表单）：

[0] L1-L3 (import ...) [1] L5-L5 (export ...) [2] L7-L12 (def ...) [3] L14-L20 (defstruct ...)

gerbil_profile

Instrument specific functions with call counting and timing while running an expression. Reports per-function call count, cumulative time, average time, and percentage of wall time. Also reports overall wall time, CPU time, GC time, and bytes allocated. Instruments top-level bindings via set!; does not work on lexical bindings.

表达式：“（begin（对于每个读取的json输入）'done）”
函数：\[“读取json”，“哈希放！”\]
导入：\[“：std/text/json”\]
=>配置文件：（开始…）

挂墙时间：4.5秒|用户：4.3秒| GC：0.2秒|分配：150 MB

函数调用时间平均值%
读取json 1000 3.200s 3.200ms 71.1%
哈希放！50000 1.100s 0.022ms 24.4%

结果：完成

gerbil_heap_profile

Capture GC heap metrics before and after running an expression. Reports heap size, allocation, live objects, movable objects, and still objects. Forces garbage collection before each snapshot for accurate measurements. Uses :std/debug/heap memory-usage function.

表达式：“（使向量10000000）”
=>堆配置文件：（使向量10000000）

Delta前后的度量
gc堆大小68.0 MB 136.0 MB+68.0 MB
气相色谱分配56.2 MB 147.3 MB+91.1 MB
gc直播28.5 MB 41.6 MB+13.1 MB
gc可移动存储空间26.6 MB 39.7 MB+13.1 MB
gc仍然为1.9 MB 1.9 MB+0.0 MB

结果：#（0 0…）

gerbil_trace_calls

Count how many times specified functions are called while running an expression. Lightweight instrumentation with minimal overhead (no timing). Instruments top-level bindings via set!; does not work on lexical bindings.

表达式：“（let循环（i 0））（if（\调用跟踪：（let循环…）

函数调用
哈希放！100

结果：完成

gerbil_call_graph

Analyze which functions call which other functions in a Gerbil source file. Uses static analysis (no execution). Shows a tree visualization and flat listing of call relationships between locally defined functions. Optionally filter to show only the tree rooted at a specific function.

file_path：“/path/to/server.ss”
=>调用图：/path/to/server.ss

主要的
+--助手
+--过程数据
|+--解析输入
|+--验证
+--输出结果

定义函数：5
main（L10）->辅助程序、流程数据、输出结果
处理数据（L20）->解析输入，验证
解析输入（L30）->（无本地调用）
验证（L40）->（无本地呼叫）
助手（L50）->（无本地呼叫）

file_path：“/path/to/server.ss”，函数：“进程数据”
=>调用图：/path/to/server.ss（以进程数据为根）

过程数据
+--解析输入
+--验证

...

gerbil_scaffold_test

Generate a :std/test skeleton from a module's exports. Introspects the module to discover exported procedures, macros, and values, then produces a ready-to-fill test file. Does not write to disk — returns the generated text.

module_path：“：std/text/json”
=>（导入：std/test:std/text/json）
（导出json测试）

（def json测试
（测试套件“std/text/json”
（测试用例“读取json”
（检查（读取json arg1）=>。..))
（测试用例“写json”
（检查（写入json arg1）=>。..))
...))

module_path:“：std/text/json”，suite_name：“我的json测试”
=>（导入：std/test:std/text/json）
（导出我的json测试）

（定义我的json测试
（测试套件“std/text/json”
...))

gerbil_build_and_report

Run gerbil build on a project directory and return structured diagnostics. On success, reports a summary. On failure, parses compiler errors into structured file:line:column diagnostics. Uses the modern gerbil CLI (not gxpkg).

project_path：“/path/to/myproject”
=>构建成功。

…编译输出。..

project_path：“/path/to/myproject”，标志：\[“--optimized”\]
=>构建成功（--已优化）。

project_path：“/path/to/myproject”，加载路径：\[“~/.gerbil/lib”，“/path/to/deps/.gerbil/lib”\]
=>构建成功。

project_path：“/path/to/breaked项目”
=>构建失败：2个错误，0个警告

[ERROR] server.ss:12:5 — Reference to unbound identifier: foo [ERROR] utils.ss:30:10 — Syntax Error: cannot find library module

gerbil_generate_module_stub

Generate a module skeleton by introspecting an existing module's exports and signatures. Produces (def ...) stubs for procedures with arity-based argument placeholders, (defrules ...) for macros, and (def ...) for values. Does not write to disk — returns the generated text.

module_path：“：std/text/json”
=>（导入：std/text/json）
（导出读json写json json对象->字符串…）

（def（读取json arg1）
...)

（def（写json arg1）
...)

...

module_path:“：std/text/json”，package_prefix:“myapp”，导入：\[“：std/iter”\]
=>（软件包：myapp）

（导入：std/text/json:std/iter）
（导出读json写json…）

（def（读取json arg1）
...)
...

gerbil_check_exports

Static analysis tool that checks export/import consistency across a Gerbil project. Detects symbols exported but not defined in the file, and cross-module import mismatches where file A imports from project module B but uses symbols that B does not export. Pure static analysis — no subprocess, fast.

project_path：“/path/to/myproject”
=>导出一致性检查：/path/to/myproject

发现2个问题：

\[ERROR\]server.ss:3--此文件中未定义导出符号“handle-auth”
\[警告\]api.ss:5--从导入“流程数据”。/服务器，但是。/服务器不导出它

gerbil_generate_module

Generate a Gerbil module by reading a template file and applying word-boundary-aware string substitutions. Returns the generated text (does NOT write to disk). Useful for creating mechanical variations of an existing module pattern.

template_path：“/path/to/handler.ss”
替换：〔｛“from”：“user”，“to”：“admin”｝，｛“from“：user”，“to”：“admin”｝〕
=>（导入：myapp/admin-db）
（导出管理员处理程序管理员列表）

（def（管理员处理程序请求）
...)
...

gerbil_howto

Search curated Gerbil Scheme idioms and recipes by keyword. Returns code examples with imports and usage notes. Supports merging in additional recipes from an external JSON cookbook file.

查询：“json解析”
=>找到了3个“json解析”的配方：

## 解析JSON字符串

导入：：std/text/json

(import :std/text/json) (def data (call-with-input-string "{\"name\":\"alice\"}" read-json))

...

查询：“自定义食谱”，cookbook_path：“/path/to/project/.claude/kookbooks.json”
=>找到1个“自定义配方”的配方：

## 我的自定义食谱

...

When cookbook_path is provided, recipes from the external file are merged with the built-in set. External recipes override built-in ones if they share the same id.

gerbil_howto_add

Append a new Gerbil Scheme recipe to a JSON cookbook file. If a recipe with the same id already exists, it is replaced (update semantics). Convention: use .claude/cookbooks.json in the project root.

cookbook_path：“/path/to/project/.claude/kookbooks.json”
id：“csv读取”
title:“读取CSV文件”
标签：\[“csv”、“文件”、“读取”、“解析”\]
导入：\[“：std/text/csv”\]
code:“（导入：std/text/csv）\\n（调用输入文件“data.csv”读取csv）”
=>在/path/to/project/.claude/kookos.json中添加了食谱“csv read”（共1个食谱）。

gerbil_file_summary

Structural overview of a Gerbil source file without reading the whole file. Shows imports, exports, and definitions grouped by kind. Pure TypeScript — no subprocess, fast.

file_path：“/path/to/server.ss”
=>文件：server.ss（1.2 KB）

进口：
：std/net/httpd
：std/text/json

出口：
启动服务器，停止服务器

程序：
L4启动服务器
L12停止服务器
L20处理请求

结构：
L8配置

gerbil_make

Run a Makefile target in a Gerbil project directory. Returns structured output with exit code, stdout, and stderr.

project_path：“/path/to/project”，target:“build”
=>成功完成目标“构建”。

…构建输出。..

project_path：“/path/to/project”
=>在/path/to/project中找不到Makefile。

gerbil_describe

Evaluate a Gerbil Scheme expression and describe the resulting value's type, structure, and key properties. Useful for understanding what a function returns or what a data structure contains.

表达式：“（hash（“name”“alice”）（“age”30））”
=>哈希表（2个条目）
“name”=>“alice”
“年龄”=>30岁

表达式：“\[1 2 3\]”
=>列表（长度3）
1
2
3

表达式：“42”
=>精确整数：42

表达式：“汽车”
=>程序

Resources

The server exposes MCP resources for browsing the built-in cookbook recipe library.

gerbil://cookbooks

Returns a JSON index of all cookbook recipes with id, title, and tags for each entry. Useful for browsing available patterns without fetching full code.

gerbil://cookbooks/{id}

Returns the full JSON detail for a single recipe, including code, imports, notes, and related recipes.

Prompts

The server provides reusable prompt templates that MCP clients can invoke to get Gerbil-aware instructions.

explain-code

Explain a piece of Gerbil Scheme code with awareness of Gerbil-specific idioms (bracket list syntax, keyword colons, dot-syntax methods, macros).

convert-to-gerbil

Convert code from another language to idiomatic Gerbil Scheme, following Gerbil conventions (def, brackets, :std/iter, match, chain, etc.).

generate-tests

Generate comprehensive tests for a Gerbil module using the :std/test framework, following naming conventions (*-test.ss, *-test export).

review-code

Review Gerbil Scheme code for issues with a checklist of common Gerbil pitfalls (define vs def, #f vs '(), missing -O, unsafe declares, etc.).

write-gerbil-module

Get guidance for writing a new Gerbil Scheme module, following Gerbil conventions (def, defstruct, keyword args, :std/iter, etc.).

debug-gerbil-error

Get help debugging a Gerbil Scheme error with a structured debugging workflow that leverages the available MCP tools.

port-to-gerbil

Port code from another Scheme dialect (Racket, Guile, Chicken, Chez) to idiomatic Gerbil with a mapping of key differences (hash-ref → hash-get, #:keyword → keyword:, etc.).

How It Works

Most tools invoke gxi -e as a short-lived subprocess — no persistent state between calls. Expressions are wrapped in error-handling code using with-catch and output structured markers (GERBIL-MCP-RESULT: / GERBIL-MCP-ERROR:) that the TypeScript layer parses.

The gerbil_compile_check tool uses gxc -S (the Gerbil compiler in expand-only mode) to catch errors beyond what the expander alone detects. When gxc hits internal compiler crashes, the tool post-processes the error output to detect known patterns (e.g., stx-car-e, code generation failures) and appends diagnostic hints.

The gerbil_repl_session tool spawns a persistent gxi subprocess with piped stdin/stdout, using a sentinel-based protocol to delimit expression output across multiple evaluations. Sessions can be created with a project_path or explicit loadpath to set GERBIL_LOADPATH for the subprocess, enabling project-local module imports.

Several tools (gerbil_eval, gerbil_compile_check, gerbil_repl_session, gerbil_profile, gerbil_heap_profile, gerbil_trace_calls) accept a loadpath parameter that sets GERBIL_LOADPATH on the subprocess environment. This allows operating within a project's build context — for example, importing modules from a project's .gerbil/lib directory.

The gerbil_profile and gerbil_trace_calls tools use Scheme-side instrumentation via eval/set! to replace top-level function bindings with wrappers that count calls (and measure timing for profile). The gerbil_heap_profile tool uses :std/debug/heap memory-usage to capture GC metrics before and after expression evaluation, forcing garbage collection for accurate snapshots.

The gerbil_call_graph tool is pure TypeScript — it reads a source file, parses function definitions using paren-depth tracking, and builds an adjacency list by scanning function bodies for references to other defined functions.

The gerbil_build_project, gerbil_package_info, gerbil_scaffold, and gerbil_package_manage tools invoke gxpkg as a subprocess for package management, project scaffolding, and building. The gerbil_build_and_report tool invokes the modern gerbil build CLI and parses its output into structured diagnostics using the same parseGxcErrors() parser as gerbil_diagnostics.

The gerbil_scaffold_test and gerbil_generate_module_stub tools use the same Gerbil introspection mechanism as gerbil_function_signature — importing a module and iterating its exports to classify each as procedure (with arity), macro, or value — then formatting the results as ready-to-use Scheme source code.

User input is injected via (read (open-input-string ...)) rather than string interpolation, letting Scheme's reader handle all quoting. Subprocess execution uses execFile (not exec) to avoid shell injection.

Project Structure

src/
index.ts服务器入口点、工具提示和资源注册
gxi.ts gxi/gxc/gxpkg子流程包装器、REPL会话管理器
prompts.ts MCP提示模板（7个提示）
resources.ts MCP资源（食谱索引和食谱详细信息）
工具/
eval.ts沙比尔_瓦尔
module-exports.ts gerbill_module_exports
check-syntax.ts非洲菊_check_syntax
expand-macro.ts沙土鼠\_ expand_macro
沙土鼠提案
list-modules.ts.gerbil_list_std-modules
函数签名.ts沙比尔函数签名
module-deps.ts gerbill_module_deps
load-file.ts gerbill_load_file
doc.ts沙鼠.doc
compile-check.ts沙土鼠compile-check
trace-macro.ts非洲菊_追踪-macro
回复会话.ts沙鼠回复会话
run-tests.ts gerbill_run_tests
ffi-inspect.ts沙土鼠_ffi_inspect
class info.ts gerbill_class_info
查找定义ts gerbill_find_definition
build-project.ts非洲菊_建筑工程
package-info.ts沙鼠包装信息
format.ts格式
benchmark.ts沙鼠基准
error-hierarchy.ts gerbill_error_hierarchy
version.ts-gerbil_version
沙鼠脚手架
package-manage.ts沙土鼠包装管理
find-callers.ts沙鼠来电
suggest-imports.ts非洲菊\_ suggest_imports
沙鼠诊断学
文件符号.s非洲菊_文件符号
工作空间符号s.ts非洲菊_工作空间符号
重命名符号.ts沙土鼠_重命名符号
lint.ts沙鼠
project-info.ts沙土鼠项目信息
project-map.ts沙土鼠项目地图
check-balance.ts沙比尔\_ check-balance
阅读表格s.ts非洲菊阅读表格
profile.ts沙比尔文件
heap-profile.ts沙鼠heap-profile
tracecalls.ts沙鼠追踪通话
call-graph.ts沙比尔调用图
沙鼠脚手架试验
build-and-report.ts格比尔建筑与报告
generate-module-stub.ts非洲菊generate-momodule_stub
check-exports.ts gerbill_check_exports
generate-module.ts gerbill_generate_module
如何.沙鼠_如何
如何添加.ts非洲菊_如何添加
file-summary.ts非洲菊file_summary
make.ts非洲菊
描述了沙鼠
parse-utils.ts共享解析实用程序
测试/
tools.test.ts所有MCP工具的功能测试

License

MIT