MCP server: self-describing identity — initialize instructions and bundle-aware descriptions
- Dominant language
- Dart
- Stars
- 0
- Forks
- 0
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 31
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-__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 "" 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 #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 mcp` composing this server's machinery; whatever identity/instructions seam lands here should be reusable there.
Contributor guide
No contributing guide indexed for this repository
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.
Assessment
- Tech stack
- dart
- Domain
- api, cli
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100