gerbil-mcp

[ { "id": "ffi-binding-scaffold", "title": "Generate FFI bindings from C header files", "description": "A tool that parses a C header file and generates Gambit FFI binding code (.scm file with c-declare, c-define-type, c-lambda declarations). It would recognize common patterns: opaque pointer types, create/destroy function pairs (for automatic cleanup), and simple function signatures. This would dramatically accelerate creating Gerbil bindings for C libraries like LevelDB, SQLite, etc.", "impact": "high", "tags": [ "ffi", "c-header", "scaffold", "generate", "binding", "gambit" ], "use_case": "When creating Gerbil FFI bindings for a C library, generate the boilerplate c-define-type and c-lambda declarations from the header file instead of manually translating each typedef and function signature.", "example_scenario": "User wants to bind libleveldb. They point the tool at leveldb/c.h. It generates: c-define-type declarations for all opaque types (leveldb_t, leveldb_options_t, etc.), c-lambda bindings for all functions, and cleanup functions for types that have corresponding _destroy functions. User then just needs to add the Gerbil wrapper layer.", "estimated_token_reduction": "~5000+ tokens per FFI project. Eliminates manually reading C headers, figuring out type mappings, and writing repetitive c-lambda declarations.", "votes": 1 }, { "id": "ffi-callback-debugger", "title": "Debug FFI callback linkage issues", "description": "A diagnostic tool that checks whether c-define callbacks are correctly linked and callable from C code. It would verify: (1) the c-define generates a properly named C function, (2) extern declarations match c-define signatures, (3) the Scheme runtime is properly initialized before callbacks can fire. Currently, c-define callbacks that fail just hang or crash with no useful error message.", "impact": "medium", "tags": [ "ffi", "c-define", "callback", "debug", "diagnostic" ], "use_case": "When implementing C-to-Scheme callbacks (e.g., for comparators, event handlers), diagnose why the callback hangs or crashes instead of guessing through trial and error.", "example_scenario": "User implements a LevelDB comparator using c-define callbacks. When LevelDB calls the compare callback, the process hangs. The diagnostic tool would show: 'c-define scm_comparator_compare_cb exists but calling it blocks - Scheme runtime may not be in correct state for callbacks from this C context'.", "estimated_token_reduction": "~1000 tokens per callback debugging session. Eliminates trial-and-error approach to diagnosing why callbacks don't work.", "votes": 1 }, { "id": "struct-constructor-info", "title": "Show defstruct/defclass constructor argument order and type", "description": "A tool that, given a struct or class name and its module, shows the exact constructor signature including positional field order, inherited fields, and whether keyword construction is available. Currently gerbil_class_info shows slots and fields but doesn't clearly show the make-X constructor's argument order (especially for inherited structs). This is a major source of errors since defstruct constructors use POSITIONAL args and guessing the field order (especially with inheritance) leads to \"arguments don't match object size\" errors.", "impact": "high", "tags": [ "defstruct", "defclass", "constructor", "positional", "make", "arity" ], "use_case": "When constructing struct/class instances, especially from external libraries where you can't easily read the source. The WebSocket message struct, for example, has fields (data type partial?) but there's no quick way to confirm the constructor order without reading source or experimenting.", "example_scenario": "User needs to create a WebSocket message: make-message. They know the struct has fields data, type, and partial? but don't know if the constructor takes (data type partial?) or (type data partial?). They call gerbil_class_info which shows slots but not the unambiguous constructor signature. They guess wrong and get a runtime error. A dedicated tool would show: make-message(data, type, partial?) — 3 positional args.", "estimated_token_reduction": "~300 tokens per struct construction. Eliminates trial-and-error with gerbil_eval to discover field order, which often takes 2-3 round trips.", "votes": 0 }, { "id": "gambit-primitive-inventory", "title": "List available Gambit runtime primitives (non-module builtins)", "description": "A tool that lists Gambit runtime primitives available without any imports — things like open-process, process-status, process-pid, file-info, directory-files, current-directory, getenv, setenv, user-name, user-info, tty?, path-expand, etc. Currently, discovering these requires gerbil_apropos with guessed names, since they aren't in any :std/* module. A dedicated tool or curated list would prevent wasted searches.", "impact": "medium", "tags": [ "gambit", "builtins", "primitives", "discovery", "inventory" ], "use_case": "When starting a new Gerbil project that needs OS-level functionality (process control, filesystem, environment), you need to know what's available without imports vs what requires :std/os/* modules. Currently requires many trial-and-error apropos calls.", "example_scenario": "User wants to build a shell in Gerbil. Needs to find all process, filesystem, environment, and terminal primitives. Currently requires 10+ apropos calls (fork, exec, waitpid, chdir, dup, pipe, getenv, setenv, etc.) to discover that fork/exec/waitpid/dup2 don't exist while open-process/process-status/process-pid do. A single tool call listing 'process management primitives' would answer this in one round-trip.", "estimated_token_reduction": "~2000 tokens per discovery session. Eliminates 8-10 apropos calls and their results when exploring Gambit-level primitives for a new project.", "votes": 1 }, { "id": "concurrency-pattern-advisor", "title": "Concurrency pattern advisor: suggest the right primitive for a use case", "description": "A tool that, given a concurrency use case description (e.g., \"multiple producers, single consumer\", \"wait for N threads\", \"one-shot async result\"), recommends the appropriate Gerbil concurrency primitive (channel, barrier, completion, rwlock, atom, wg, actor) with a working code template. Currently, users must know all available primitives and their tradeoffs to choose correctly.", "impact": "high", "tags": [ "concurrency", "channel", "barrier", "completion", "atom", "rwlock", "pattern", "advisor" ], "use_case": "When starting a concurrent Gerbil program and needing to choose between channels, barriers, completions, atoms, rwlocks, workgroups, or actors for a specific synchronization pattern.", "example_scenario": "User says \"I need multiple worker threads to process items and collect results.\" Without this tool, Claude must recall all :std/misc primitives, compare tradeoffs, and suggest the right combination (wg + atom, or channels). With this tool, one call returns: \"Use make-wg for the thread pool + atom for result collection\" with a complete code template.", "estimated_token_reduction": "~800 tokens per concurrency design question. Eliminates 3-4 tool calls (module_exports + function_signature + howto + eval) to research and verify the right pattern.", "votes": 0 }, { "id": "sugar-macro-catalog", "title": "Catalog of all :std/sugar macros with signatures and one-line descriptions", "description": "A tool that returns a compact catalog of all macros exported by :std/sugar (and optionally other macro-heavy modules), showing each macro's syntax pattern and a one-line description. Currently, discovering what sugar macros are available requires gerbil_module_exports (which just lists names) plus multiple gerbil_doc or source reads to understand each one. A single catalog call would show: chain (<> pipeline), is (predicate factory), if-let (conditional bind), when-let, awhen, let-hash, with-id, with-destroy, defmethod/alias, syntax-eval, etc.", "impact": "medium", "tags": [ "sugar", "macro", "catalog", "discovery", "syntax", "cheatsheet" ], "use_case": "When writing Gerbil code and wanting to know what syntactic sugar is available before writing verbose code. Also useful when reviewing unfamiliar Gerbil code that uses sugar forms.", "example_scenario": "User is writing a data processing pipeline. Instead of making 5 tool calls (module_exports + doc for chain + doc for is + doc for let-hash + doc for if-let), one catalog call shows all available sugar with patterns, letting Claude immediately use the most appropriate form.", "estimated_token_reduction": "~600 tokens per sugar discovery session. Replaces 4-5 sequential tool calls with one compact result.", "votes": 0 }, { "id": "iterator-constructor-catalog", "title": "Catalog of all iterator constructors with types they work on", "description": "A tool that lists all available iterator constructors (in-range, in-iota, in-naturals, in-hash, in-hash-keys, in-hash-values, in-input-lines, in-input-chars, in-input-bytes, in-coroutine, in-cothread, in-indexed, in-rbtree, in-lru-cache, etc.) with their signatures, the types they iterate over, and whether they're finite or infinite. Currently discovering these requires reading :std/iter source or making many apropos/doc calls.", "impact": "medium", "tags": [ "iterator", "in-range", "in-hash", "catalog", "for", "iter", "constructor" ], "use_case": "When writing for/for-collect/for-fold loops and needing to know which iterator constructor to use for a given data type or pattern.", "example_scenario": "User has an LRU cache and wants to iterate it with for. They don't know in-lru-cache exists. Currently requires: gerbil_module_exports on :std/misc/lru, then gerbil_doc on in-lru-cache. A catalog would show all iterators including in-lru-cache, in-rbtree-keys, etc. in one call.", "estimated_token_reduction": "~400 tokens per iterator lookup. Eliminates 2-3 exploratory tool calls per iteration pattern.", "votes": 0 }, { "id": "struct-field-order-inspector", "title": "Show exact constructor argument order for make-X (including inherited fields)", "description": "Enhance gerbil_class_info or add a new tool that shows the EXACT positional argument order for make-X constructors, especially for structs with inheritance. Currently gerbil_class_info shows slots and fields but doesn't clearly indicate the make-X constructor's argument order. For inherited structs, the order is: parent fields first, then child fields. Getting this wrong causes \"arguments don't match object size\" runtime errors that are hard to debug.", "impact": "high", "tags": [ "struct", "constructor", "make", "field-order", "inheritance", "positional", "arity" ], "use_case": "When constructing instances of structs from external libraries where you can't easily read the source. Especially important for structs with inheritance where field order is non-obvious.", "example_scenario": "User needs to create a point3d instance (inherits from point). They know fields are x, y, z but don't know the constructor is (make-point3d x y z) with parent fields first. They call gerbil_class_info which shows own-fields: (z) and super: point, but doesn't unambiguously show that make-point3d takes (x y z) in that order. A dedicated tool would show: make-point3d(x: <any>, y: <any>, z: <any>) — 3 positional args, parent fields first.", "estimated_token_reduction": "~300 tokens per struct construction. Eliminates trial-and-error with gerbil_eval to discover field order, which takes 2-3 round trips.", "votes": 0 }, { "id": "project-dependency-graph", "title": "Visualize project module dependency graph", "description": "A tool that analyzes a Gerbil project and produces a module dependency graph showing which project modules import from which other project modules. Currently gerbil_module_deps shows dependencies for a single module (including stdlib), and gerbil_project_map shows all modules. But there's no way to see the inter-module dependency structure of a project at a glance. This would show: module A -> module B -> module C, with external deps grouped separately.", "impact": "medium", "tags": [ "project", "dependency", "graph", "module", "import", "architecture", "visualization" ], "use_case": "When onboarding to a new Gerbil project or planning a refactoring that affects module boundaries. Understanding which modules depend on which helps plan changes safely.", "example_scenario": "User asks \"how is this project structured?\" Currently requires: gerbil_project_map (large output) + manual analysis of imports. A dependency graph tool would show the tree: main -> api -> db, main -> api -> handler -> utils, etc. in a compact ASCII tree format.", "estimated_token_reduction": "~1000 tokens per project analysis. Replaces gerbil_project_map's verbose output with a focused dependency view.", "votes": 0 }, { "id": "test-coverage-summary", "title": "Test coverage summary: exported symbols without test cases", "description": "A tool that compares a module's exports against its test file to identify exported symbols that have no corresponding test cases. It would scan *-test.ss files for references to each exported symbol and report which are covered and which are missing. This helps ensure test completeness. Currently requires manual comparison of gerbil_module_exports output with test file contents.", "impact": "medium", "tags": [ "test", "coverage", "exports", "quality", "missing", "completeness" ], "use_case": "After implementing a module, check which exported functions don't have test cases yet. Also useful during code review to assess test completeness.", "example_scenario": "User implements a module with 15 exported functions. They write tests for 10 of them. Instead of manually cross-referencing exports and test file, one tool call shows: \"5 untested exports: fn-a, fn-b, fn-c, fn-d, fn-e\". Could also suggest which test scaffolding to add.", "estimated_token_reduction": "~500 tokens per coverage check. Eliminates manual cross-referencing of module_exports output with test file reads.", "votes": 0 }, { "id": "cookbook-correction-flag", "title": "Flag or correct outdated cookbook recipes that have wrong arities/signatures", "description": "Several existing cookbook recipes contain incorrect information that leads to bugs: (1) \"signal-handler-register-remove\" shows (lambda (sig) ...) but handlers take 0 args, (2) \"tty-mode-set-raw-cooked\" shows 5 args but the function takes 6. When a new recipe is added with a `related` field pointing to an incorrect recipe, there should be a mechanism to flag the old recipe as superseded or auto-update it. Currently both the wrong and correct versions coexist, and gerbil_howto may return the wrong one first.", "impact": "medium", "tags": [ "cookbook", "correction", "outdated", "accuracy", "recipe" ], "use_case": "When a session discovers that an existing recipe has incorrect arity, wrong argument types, or outdated API usage, the corrected recipe should supersede the old one rather than just adding a second entry that may confuse future lookups.", "example_scenario": "Session discovers tty-mode-set! takes 6 args, not 5 as shown in existing recipe. Adds new recipe 'tty-mode-set-six-args' with correct info. But next session searches 'tty-mode-set raw' and gets the OLD wrong recipe first, wastes tokens debugging arity error, then finds the correction.", "estimated_token_reduction": "~300 tokens per incorrect recipe encountered. Prevents re-debugging known-wrong patterns across sessions.", "votes": 0 } ]