Roadmap: MCP and agent surface

The MCP tool surface agents see and the host-agnostic layer planned 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: planned (added 2026-08-27)

Claude Desktop (and any non-Claude-Code host) gets 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 (currently absent). Ship the memory/knowledge usage prompt there: recall-first, routing, tagging rules, metadata-not-frontmatter. Largest win, one field.
MCP prompts. The prompts capability is advertised but empty. Ship soul-context, soul-journal, promote as MCP prompts; hosts surface them natively, replacing slash commands.
Server-side gates. Tag/style/destination gates are Claude Code hooks today, so other hosts bypass them. Move enforcement (or warn-in-response) into demarkus-server/broker; hooks become redundant.

Optional: package demarkus-mcp as a Desktop extension (.mcpb) for one-click install.

Accepted losses for non-Code hosts: session hooks (journal nudge), project-binding enforcement at spawn, /promote-scan automation. Server-side gates cover the integrity-critical part.

Token-Efficient Retrieval

Status: active (set as the next feature focus 2026-09-06)

Reach the right knowledge with the fewest tokens, measured as tokens per correct answer. Search as an external sidecar over the protocol (never a verb), surfaced as one MCP tool returning 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. Continues Ecosystem Optimization and closes the "semantic recall beyond tags" gap in graph and backends.