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 147 tools organized by category:

Evaluation & REPL — eval, repl_session, describe, trace_eval

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

Module Introspection — module_exports, 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, 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 — rename_symbol, balanced_replace, 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, 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	147 (all)	~154 KB	Cloud models (Claude, GPT, Gemini)
hybrid (default)	13 + dispatcher	~31 KB	General local LLMs
mini	13 (manifest-free)	~12 KB	Gerbil-fine-tuned models

In hybrid/mini mode, reach any tool via the gerbil dispatcher: gerbil(tool: "dead_code", args: {project_path: "src"}).

Installation

Prerequisites

• Gerbil Scheme v0.18.x with gxi, gxc, gxpkg, and gerbil on PATH

Build with Gerbil v0.18.x — not v0.19. The v0.19 stdlib is mid-reorganization and has removed modules gerbil-mcp depends on. make build runs a preflight check and stops with a clear message if you're on v0.19.

From source

git clone https://git.cons.io/ober/gerbil-mcp
cd gerbil-mcp
make build      # -> .gerbil/bin/gerbil-mcp (static binary)

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.

Install on PATH (optional)

make install                       # -> /usr/local/bin/gerbil-mcp
make install PREFIX=$HOME/.local   # -> ~/.local/bin/gerbil-mcp

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"
      }
    }
  }
}

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	/opt/gerbil	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 (147 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 (23 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       # Compile the project
make test        # Run the full test suite
make check       # Build + test
make regen       # Regenerate build.ss from .ss files, then build

License

MIT. See source file headers for copyright information.