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

Open
#35 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
68/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
dart
Domain
api, cli

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

afk enhancement

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 #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.
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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from btwld/okf

All issues in btwld/okf

Similar issues

More Dart issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.