MCP server: self-describing identity — initialize instructions and bundle-aware descriptions
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 68/100
Research direction
Start with the existing stdio harness and the okf mcp entry point; trace explicit bundle startup plus the initialize and tools/list responses. Done means bundle discovery follows the closed rule, identity appears in instructions and every tool description, explicit behavior is unchanged, and diagnostics stay on stderr while stdout remains JSON-RPC.
Written by the indexing model from the issue text.
Description
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
-
Initialize
instructions. Return aninstructionsstring (mcp_dart ≥ 2.4 supports it) identifying the served bundle — absolute root, title (bundleindex.mdH1), 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. -
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. -
Optional bundle argument with deterministic discovery. Keep the one-server-per-bundle process model — a generic multi-bundle server with a per-call
bundleparameter would reintroduce exactly the ambiguity this issue removes, and no real workflow needs it yet. Instead make registration generic:okf mcpwith 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
instructionsnaming the bundle root and title of the served bundle. - A harness test asserts every
tools/listdescription contains the bundle identity. -
okf mcpwith 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 #11 contract). - Explicit
okf mcp <bundle>behaviour is unchanged.
Context
- #11 (read surface), #12/#13 (writes) fixed the tool names and contracts; this issue changes none of them.
- Downstream, conceptadev/okf-profile#45 proposes a profile-aware
okfp mcpcomposing this server's machinery; whatever identity/instructions seam lands here should be reusable there.
- Dominant language
- Dart
- Stars
- 0
- Forks
- 0
- Avg merge
- 4h 39m
- Merged PRs (30d)
- 4
Getting set up
This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from btwld/okf
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 3/5 1-2 days Newbie friendliness 78/100
-
enhancement
Difficulty 4/5 3-5 days Newbie friendliness 55/100
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
AppFlowy-IO/AppFlowy#9147 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
Difficulty 1/5 Under an hour Newbie friendliness 62/100
ccch1mneyyy/dsh-Go#1682 ·
Maintainers usually reply within 1 day
-
help wanted
Difficulty 1/5 Under an hour Newbie friendliness 76/100
pesaclarity/ujumbe-parsers#64 ·
Maintainers usually reply within 1 day
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
patarapolw/lingua_srs#278 ·
Maintainers usually reply within 1 day