AGENTS.md@src/KyberWeave.Mcp · diff
git:20260914.3e94d8d to git:20260929.03c6a0c
10 added, 0 removed. Audit A to A.
# KyberWeave.Mcp
The `kyber-weave-mcp` binary. A stdio MCP server exposing the documentation graph to
agents.
Read [`/AGENTS.md`](../../AGENTS.md) first for repository-wide rules.
## Never write to stdout
**stdout is the JSON-RPC transport.** One stray line corrupts it and the client reports a
protocol error with no useful detail.
- No `Console.WriteLine`, no `AnsiConsole`, no `Console.Out` — anywhere in this project or
in a code path it reaches.
- Logging is pinned to stderr in `Program.cs` via `LogToStandardErrorThreshold =
LogLevel.Trace`. Do not relax it.
- This is why the server is a **separate executable** from the CLI rather than a
`kyber-weave mcp` subcommand: the CLI is built on Spectre.Console, which writes to
stdout. Separate entry points make the corruption structurally impossible instead of a
matter of discipline. Do not merge them.
## Composition root
`Program.cs` constructs the single `DocumentIndexHost` and hands it the factories Core
needs. Tools receive it by injection. Core never builds these itself — see
[`../KyberWeave.Core/AGENTS.md`](../KyberWeave.Core/AGENTS.md).
Repository root resolution order is `--repo-root`, then `KYBER_WEAVE_REPO_ROOT`, then the
working directory. The working directory is accepted only when it contains a Kyber-Weave
host configuration created by `kyber-weave docs init`; the server never walks up to a parent
Git repository and never serves an unbound default corpus. A missing binding is reported on
stderr with an actionable `kyber-weave docs init` command.
+ After resolution, an optional client assertion is checked: `--expect-root <path>`, or
+ `KYBER_WEAVE_EXPECT_ROOT` when the flag is absent, must name the resolved root or the server
+ refuses to serve — `KW-MCP-ROOT-002` on stderr, exit 1. The flag wins over the environment.
+ This is the rail against a same-named server pinned to another checkout by a global or
+ headless harness config; it does not replace correct project-local wiring.
+
## Tools return text for a model, not data for a program
`DocsTools` formats results as prose an agent reads. Three properties matter when editing:
**Cap everything.** Sections at `SectionCharCap`, joins at `JoinCap`, documents by the
caller's budget. A retrieval tool that returns a whole corpus is a slower grep.
**Say when the answer is weak.** A miss reports that it is a real miss and how many
documents were considered, so the caller knows it may now fall back to grep. An
unresolvable code join prints `(unresolved)`. An ambiguous one is annotated
`(+N other same-named)` so the reader verifies instead of trusting.
**Name what was omitted.** Excerpts list the headings that did not fit, and distinguish
dropped-for-space from dropped-for-irrelevance — only the former makes asking again with a
larger budget worthwhile.
Adding a tool means adding an `[McpServerTool]` method with a `[Description]` written as
routing metadata: a capability clause, then the conditions that should fire it. Only the
broadest tool in the set carries an exclusion; the rest state their territory positively.
+ Every tool response must also lead with the shared provenance header — the absolute root,
+ short HEAD revision with dirty marker, and live document count — so a caller can tell which
+ corpus answered. `CorpusProvenance` formats it, `docs_status` returns it alone, and the
+ header is emitted whole while any budget is taken from the body.
## Staleness is handled for you
`DocumentIndexHost.Current()` rebuilds whichever half has gone stale on each call. Do not
add caching in the tools layer.
## Documented behaviour
The tool contract, client wiring, and troubleshooting live in
[`docs/docgraph/mcp-runbook.md`](../../docs/docgraph/mcp-runbook.md). Changing a tool name,
parameter, default, or cap means updating that page in the same change.