gerbil-mcp

An MCP (Model Context Protocol) server that gives AI assistants live access to a Gerbil Scheme development environment. Instead of guessing from training data, LLMs can evaluate expressions, check syntax, expand macros, compile code, run tests, inspect modules, profile performance, and scaffold projects — all against a real Gerbil runtime.

• Features
• Installation
• Usage
• Architecture
• Development
• License

Features

The server exposes 169 tools organized by category:

Evaluation & REPL — eval, repl_session, describe, trace_eval

Syntax & Compilation — check_syntax, batch_syntax_check, compile_check, verify, verify_changes, diagnostics, lint, check_balance, read_forms, source_form_spans, invalid_context_definition_diagnoser

Module Introspection — module_exists, module_exports, symbol_exists_batch, module_deps, function_signature, module_catalog, module_quickstart, list_std_modules, stdlib_source, dynamic_reference, diff_modules, cross_package_diff

Symbol Navigation — apropos, doc, find_definition, find_callers, suggest_imports, smart_complete, document_symbols, workspace_symbols, file_summary, load_file, resolve_imports

Macro Development — expand_macro, trace_macro, macro_expansion_size, macro_hygiene_check, macro_pattern_detector, macro_template_library, boilerplate_converter, exe_macro_check

FFI & C Bindings — ffi_inspect, ffi_scaffold, ffi_callback_debug, ffi_type_check, ffi_null_safety, ffi_buffer_size_audit, ffi_link_check, ffi_utf8_byte_length_audit, blocking_ffi_check, variadic_ffi_check, detect_ifdef_stubs, demangle, stack_trace_decode, binary_audit, obfuscate_link_file

Build & Package — build_project, build_and_report, build_chain, build_conflict_check, build_progress, build_linkage_diagnostic, build_ss_audit, check_c_library, stale_static, stale_linked_pkg, pkg_link_sync, package_info, package_manage, scaffold, make, qt_test_runner

Testing — run_tests, scaffold_test, test_coverage, test_fixture_gen, test_assertion_audit, check_test_arity, check_arity, signature_impact, dispatch_coverage_analysis

Project Analysis — project_info, project_map, project_dep_graph, project_health_check, check_exports, check_import_conflicts, export_reexport_conflicts, pre_add_symbol_check, check_duplicates, dead_code, dependency_cycles, cross_module_check, migration_check

Code Quality — write_file, rename_symbol, balanced_replace, balanced_insert, wrap_form, splice_form, call_graph, tail_position_check, return_type_analysis, method_dispatch_audit, interface_compliance_check, pattern_cache_check, sigchld_check, validate_example_imports, example_api_coverage

Performance — profile, heap_profile, trace_calls, benchmark, benchmark_compare

Security — security_scan, security_pattern_add

Refactoring & Generation — generate_module_stub, generate_module, generate_api_docs, translate_scheme, project_template, format

Scaffolding — httpd_handler_scaffold, parser_grammar_scaffold, actor_ensemble_scaffold, db_pattern_scaffold, graceful_shutdown_scaffold, signal_trace

Cookbook & Knowledge — howto, howto_get, howto_add, howto_run, howto_verify, cookbook_task_bundle, request_advisor, task_workflow_advisor, failure_advisor, repair_error, verify_plan, compact_tool_manifest, error_fix_lookup (via error_fix_add), explain_error, error_hierarchy, function_behavior, class_info, event_system_guide, gambit_primitive_lookup, gambit_source_extract, gambuild_extract

Feature Suggestions — list_features, suggest_feature, vote_feature

Other — version, preflight_check, sxml_inspect, port_fd_inspector, concurrent_plan_validate

Tool-surface modes

GERBIL_MCP_MODE controls how many tools are advertised in tools/list:

Mode	Advertised	Payload	Best for
full	169 (all)	~140 KB	Cloud models (Claude, GPT, Gemini)
hybrid (default)	19 (including dispatcher)	~43 KB	General local LLMs
mini	19 (including dispatcher, manifest-free)	~18 KB	Gerbil-fine-tuned models

In hybrid/mini mode, reach any tool through the gerbil dispatcher by stable t: id, short name, canonical name, or alias: gerbil(tool: "dead_code", args: {project_path: "src"}). Use gerbil(tool: "search", args: {query: "unused definitions"}) to discover a tool and gerbil(tool: "describe", args: {name: "t:..."}) for its schema.

Installation

Prerequisites

• Gerbil Scheme v0.19, using the supported development installation at /opt/gerbil/
• make, Python 3, and the C compiler used to build that Gerbil installation
• OpenSSL 3 development libraries for the static executable

From source

git clone https://git.cons.io/ober/gerbil-mcp
cd gerbil-mcp
make clean build
# binary: .gerbil/bin/gerbil-mcp
.gerbil/bin/gerbil-mcp --version

VERSION is the canonical gerbil-mcp application version. The build verifies that it matches both gerbil.pkg and the version returned in the MCP initialize response, so clients can reliably detect stale installations.

That Gerbil path is also the Makefile default, so make clean build is enough when the installation is present at the supported location. The build sets GERBIL_HOME, GERBIL_PATH, and PATH from the selected GERBIL executable.

The Makefile sets LIBRARY_PATH for openssl automatically (Homebrew on macOS, /usr/lib on Linux). Override with make build LIBRARY_PATH=/path/to/openssl/lib.

Verify and run

make test
GERBIL_MCP_MODE=hybrid .gerbil/bin/gerbil-mcp

Install on PATH (optional)

make install
make install PREFIX=$HOME/.local

The installed binary finds its data files automatically for standard prefixes. For non-standard prefixes, set GERBIL_MCP_DATA_DIR=<prefix>/share/gerbil-mcp.

Usage

The server uses stdio transport (JSON-RPC over stdin/stdout). Configure it in your MCP client:

Claude Code

claude mcp add -s user gerbil \
  -e GERBIL_MCP_MODE=full \
  -- /path/to/gerbil-mcp/.gerbil/bin/gerbil-mcp

OpenCode

Add to ~/.config/opencode/opencode.json or project-local opencode.json:

{
  "mcp": {
    "gerbil": {
      "type": "local",
      "command": ["/path/to/gerbil-mcp/.gerbil/bin/gerbil-mcp"],
      "environment": {
        "GERBIL_MCP_MODE": "hybrid"
      }
    }
  }
}

To require every .ss mutation to go through Gerbil MCP, use the OpenCode .ss write-gate example. It blocks built-in edits to .ss files while leaving other edits and Bash commands available.

Codex

Add to ~/.codex/config.toml:

[mcp_servers.gerbil]
command = "/path/to/gerbil-mcp/.gerbil/bin/gerbil-mcp"
args = []
env = { GERBIL_MCP_MODE = "full" }

Other MCP clients

Any MCP-compatible client can connect via stdio:

/path/to/gerbil-mcp/.gerbil/bin/gerbil-mcp

Environment Variables

Variable	Default	Description
GERBIL_MCP_MODE	hybrid	Tool-surface mode: full, hybrid, or mini
GERBIL_MCP_GXI_PATH	auto-detected	Path to gxi binary
GERBIL_MCP_GXC_PATH	auto-detected	Path to gxc compiler
GERBIL_MCP_GXPKG_PATH	auto-detected	Path to gxpkg
GERBIL_MCP_DATA_DIR	auto-detected	Directory for JSON data files
GERBIL_HOME	derived from GERBIL during builds	Gerbil installation directory

Architecture

main.ss              Entry point: loads instructions, registers tools, runs server
mcp/
  jsonrpc.ss         stdio JSON-RPC 2.0 read/dispatch/write loop
  schema.ss          Input-schema DSL → validate + JSON Schema generation
  registry.ss        Tool/prompt/resource tables and dispatch
  toolkit.ss         Facade module re-exporting shared utilities for tool authors
proc.ss              gxi/gxc/gxpkg/gerbil subprocess wrappers
repl.ss              Persistent gxi REPL session manager
util/                strings, regex, parse, scanner, balance, json-store, cookbook, verify
tools/               One .ss per tool module (162 files), each exports register-<name>!
prompts.ss           MCP prompt templates (explain-code, convert-to-gerbil, etc.)
resources.ss         Cookbook and stdlib reference resources
data/                Runtime JSON: cookbooks, security-rules, features, error-fixes
test/                :std/test suites (24 chunk test files + MCP client)
scripts/             regen.py (build.ss generator), run-tests.sh, check-gerbil.sh

Tool files import only :gerbil-mcp/mcp/toolkit, which re-exports the schema DSL, registry API, subprocess helpers, string utilities, and parsing functions. Each tool file defines a schema, a handler, and a register-<name>! function called at startup by lib.ss.

Development

See CONTRIBUTING.md for detailed guidelines.

make build
make test
make check
make regen       # Regenerate build.ss from .ss files, then build

License

MIT. See source file headers for copyright information.