MCP server: self-describing identity — initialize instructions and bundle-aware descriptions

[chrishiguto]

Kind

behavioural

Problem

Agent clients defer MCP tool schemas: until the model actively searches for a tool, the discovery signal is the tool name alone — descriptions and schemas surface only afterwards. Today okf mcp presents a name-only surface (okf-<name>__list-concepts, …) with bundle-blind descriptions ("List every concept in the bundle" — which bundle?), and its initialize result carries no instructions (observed: only capabilities, protocolVersion, serverInfo).

The server is launched per bundle, so it knows exactly which bundle it serves — but it never says so. In the first real deployment (the Anago bundle, 342 concepts, served to Claude Code), the result is that agents fall back to file greps and only reach for the tools when a human names the server explicitly. The per-bundle launch model should be the fix, not the cause: identity is known at startup and can be put in front of the model.

What to build

1. Initialize instructions. Return an instructions string (mcp_dart ≥ 2.4 supports it) identifying the served bundle — absolute root, title (bundle index.md H1), concept count — plus one sentence on when to prefer the tools: enumerating concepts, following relationships (query-graph), and reproducing the CI gate (validate) instead of ad-hoc file reads.

2. Bundle-aware tool descriptions. Interpolate the bundle identity into every tool description at startup, e.g. List every concept in the "<title>" knowledge bundle at <root>, with metadata. The fixed tool names stay fixed; only descriptions gain identity.

3. Optional bundle argument with deterministic discovery. Keep the one-server-per-bundle process model — a generic multi-bundle server with a per-call bundle parameter would reintroduce exactly the ambiguity this issue removes, and no real workflow needs it yet. Instead make registration generic: okf mcp with no argument serves the bundle discovered from the working directory by a closed rule — the cwd itself if it is a bundle root, else the single immediate child directory that is a bundle root; anything else (zero or several candidates) is a startup error on stderr naming the candidates. Clients that launch stdio servers with cwd at the project root then need only one registration line for every project.

Acceptance criteria

• A stdio harness test asserts the initialize result carries instructions naming the bundle root and title of the served bundle.
• A harness test asserts every tools/list description contains the bundle identity.
• okf mcp with no argument serves the cwd-discovered bundle per the closed rule; ambiguous or absent discovery exits non-zero with the diagnostic on stderr, and stdout stays pure JSON-RPC throughout (per the MCP server: read surface #11 contract).
• Explicit okf mcp <bundle> behaviour is unchanged.

Context

• MCP server: read surface #11 (read surface), MCP server: concept writes through prepare and commit #12/MCP server: link and lifecycle writes through prepare and commit #13 (writes) fixed the tool names and contracts; this issue changes none of them.
• Downstream, Profile-aware MCP writes: wayfinder mcp composing OKF change machinery with the §9 projection and dual gate wayfinder#45 proposes a profile-aware okfp mcp composing this server's machinery; whatever identity/instructions seam lands here should be reusable there.

[chrishiguto]

Field observation reinforcing this issue: even with client instructions pointing at the server, a request phrased as "search for X" still routes to filesystem grep — rationally, because the read surface has no text-search tool. list-concepts covers enumeration and query-graph covers relationships, but nothing serves full-body text search, so grep remains the only tool that can do that job and it drags the whole navigation flow back to files.

Proposed addition to this issue's scope (or a sibling): a search-concepts read tool — substring/regex over concept bodies and frontmatter, returning concept IDs with match context, so the follow-up read happens through lookup-concept. That would close the last common task where the filesystem beats the server.