README.md — sigil-mcp

1# sigil-mcp

3Library for building Model Context Protocol clients and servers in

4[Sigil](https://codeberg.org/sigil/sigil). Provides the server loop,

5JSON-RPC 2.0 framing, and channel-based message routing primitives so

6any Sigil project can expose tools and resources to MCP clients.

8sigil-cli ships a built-in dev-tools server on top of this library,

9invoked via `sigil mcp serve`, which exposes documentation, lint,

10format, test execution, and nREPL-backed evaluation so AI agents can

11work idiomatically against a live Sigil project.

13## Modules

15| Module | Purpose |

16|------------------------|--------------------------------------------------------|

17| `(sigil mcp)` | Top-level re-exports plus package-tool discovery |

18| `(sigil mcp server)` | Server loop, message routing, handler registration |

19| `(sigil mcp client)` | Client lifecycle, correlation, cancellation, events |

20| `(sigil mcp protocol)` | JSON-RPC 2.0 framing and MCP message shapes |

21| `(sigil mcp channel)` | Helpers for channel-based server transports |

23## Building your own MCP server

25```scheme

26(import (sigil mcp))

28(define server

29 (mcp-server name: "my-server" version: "1.0"))

31(mcp-server-register-tool! server

32 name: "echo"

33 description: "Echoes its input back."

34 handler: (lambda (args) ...))

36(mcp-server-run server)

37```

39For a complete example, see sigil-cli's `(sigil cli mcp)` module or

40projects like bureau, courier, folio, and minder.

42## Build and test

44```

45sigil deps install

46sigil build

47sigil test --report

48```

50The `sigil` executable bundles the released MCP modules. When testing local

51changes to a module that is also built in, add `-L src` before the command so

52the checkout takes precedence:

54```

55sigil -L src test test/test-protocol.sgl test/test-client.sgl --report

56```

58Run unchanged server integration suites through the normal package test path;

59the current toolchain's source-path override does not expose every private

60server binding used by those tests:

62```

63sigil test test/test-server.sgl test/test-nrepl-tools.sgl test/test-channel.sgl --report

64```

66Local development against an unreleased sigil monorepo:

68```

69sigil deps install --redirects ./dev-redirects.sgl

70sigil build --redirects ./dev-redirects.sgl

71```

73## License

75BSD-3-Clause. See `LICENSE` in the sigil monorepo for the canonical copy.