# Roadmap: MCP and agent surface

The MCP tool surface agents see and the host-agnostic layer planned above it. Part of the [roadmap hub](/roadmap.md).

## 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](/plans/mcp-client-ergonomics.md) and
[/plans/mcp-resources-prompts.md](/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.

1. 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.
2. 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.
3. 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](/plans/token-efficient-retrieval.md). Continues [Ecosystem Optimization](/plans/ecosystem-optimization.md) and closes the "semantic recall beyond tags" gap in [graph and backends](/roadmap/graph-and-backends.md#semantic-recall-beyond-tags).