Roadmap: MCP and agent surface

The MCP tool surface agents see and the host-agnostic layer above it. Part of the roadmap hub.

MCP Agent Ergonomics & Attach Surface

Status: done (2026-07-04/05)

Two same-week phases that made MCP agents cheap to serve and demarkus pleasant to drive from Claude Code / Desktop. Plans: /plans/mcp-client-ergonomics.md and /plans/mcp-resources-prompts.md. Both fully shipped AND deployed on both MCP surfaces (local demarkus-mcp and the broker gateway).

Shipped:

Size-adaptive mark_fetch: full body under 8KB; above it an outline (heading tree with GitHub-slug #anchors + per-section line counts + opening paragraph + hint). url#anchor slices one section at any size; force overrides. Killed the five-figure-token fetches of append-heavy docs (measured: a 52KB roadmap → 5.9KB outline).
Session unchanged-dedup: re-fetch of an unchanged doc returns status: unchanged since vN (identity = version+etag; identity-flip edge cases spelled out). Process-scoped in the local client; MCP-session-keyed at the broker (multi-tenant safe: no session → no dedup; LRU eviction at cap, since mcp-go only unregisters sessions on explicit DELETE).
mark_explore: one-call orientation card (outline head, opening paragraph, outbound links, backlinks, siblings; 10/section + "+N more").
MCP resources: documents as client-attachable context, zero tool turns: mark:// URI templates, #anchor section attach, well-known + background-listed picker entries (client) / per-world index hubs (broker).
MCP prompts: orient / recall / whats-new as server-vended slash commands; the broker variants sweep worlds via mark_worlds.
Shared packages client/mdoutline (outline/slice + render helpers) and client/fetchdedup (dedup identity + notice text); one implementation for both surfaces (the changedNote mirror drifted twice in review before hoisting; lesson in /debugging.md).
One #section grammar everywhere: mark_fetch, mark_explore, MCP resource URIs, and the demarkus-library librarian's open tool (adopted 2026-07-05) all share the same anchors from the same implementation.
Deployed: plugin users via client v0.15.0→v0.17.0 (tools 0.4.1+, pin chain now self-driving after the #228 pin-bump automation fix); knowledge.demarkus.io via broker 0.5.0 (ergonomics) and 0.6.0 (resources+prompts).

Remaining: none. Follow-ups all landed (broker parity, resources/prompts, librarian adoption).

Host-Agnostic MCP Layer

Status: done (added 2026-08-27; closed 2026-10-20, each item shipped under another entry)

2026-10-20: all three items are in place. (1) demarkus-mcp sends server instructions on initialize (host line, section-first and read-outcome guidance from mcpfmt), as do both gateway profiles; goldens pin them (layering plan, step 1). (2) demarkus-mcp vends orient, recall, whats-new, journal and context as MCP prompts; the memory gateway vends soul-context, soul-journal and soul-export. (3) The write gates run in the store in both tiers since server 0.70.0 (ADR 0045, PRs 625 and 628), so a host without hooks gets the same refusals. The .mcpb Desktop extension was not built. What a plugin-less host still lacks is the remaining prompt set, tracked as memory gateway parity.

Original framing: Claude Desktop (and any non-Claude-Code host) got only raw mark_* tools: no plugin prompt guidance, no gates, no skills. Rather than building anything Desktop-specific, push the plugin's value down into the MCP layer so every host inherits it. Context in journal 2026-08-27.

Server instructions in demarkus-mcp's initialize result. Ship the memory/knowledge usage prompt there: recall-first, routing, tagging rules, metadata-not-frontmatter.
MCP prompts. Ship soul-context, soul-journal, promote as MCP prompts; hosts surface them natively, replacing slash commands.
Server-side gates. Tag/style/destination gates were Claude Code hooks, so other hosts bypassed them. Move enforcement into the server; hooks become a mirror.

Accepted losses for non-Code hosts: session hooks (journal nudge), project-binding enforcement at spawn, /promote-scan automation.

Token-Efficient Retrieval

Status: done (set as the feature focus 2026-09-06; all eight workstreams merged by PR 431 on 2026-09-08; closed on the roadmap 2026-10-20)

2026-10-20: the plan's eight workstreams (benchmark, body match, section-first reads, lean envelope, hub size gate, promote dedup, budgeted context, document curation) are built and measured; the real-corpus baseline followed in graph evaluation. Tokens per correct answer went from 3,363 to about 1,250 on the live soul. The one budget still missed, calls to evidence 2.5 against 2, is ranking work carried by the graph roadmap's done slices and the use-aware ranking backlog entry in deterministic memory.

Reach the right knowledge with the fewest tokens, measured as tokens per correct answer. Body match as an optional mode of the catalog verb (never a new verb), snippets and section anchors, lean response envelopes, hub size gate, promote dedup in software, a retrieval benchmark that gates every step. Plan: /plans/token-efficient-retrieval.md. Continued Ecosystem Optimization and closed the "semantic recall beyond tags" gap in graph and backends.