Plan: MCP client ergonomics — cheaper turns, cheaper tokens

Status: drafted 2026-07-04 · Repo: demarkus (demarkus-mcp client) + demarkus-memory plugin · Decisions D1–D4 open (recommendations inline)

Problem

The main consumers of the soul and the knowledge system are MCP agents (Claude Code, Claude Desktop). For them the unit of cost is not the QUIC round-trip — it is the model turn per tool call and the context tokens per result. Today:

• Orientation costs a chain of turns: lookup → fetch → backlinks → fetch…
• mark_fetch always returns the whole body. Append-heavy status docs grow unbounded (the library roadmap is the live example — one fetch is a five- figure token spend), and agents usually need one section.
• Agents re-fetch unchanged docs across a long session; every re-read pays full price.
• 14 tools per joined surface × several surfaces = schema budget + verb choice-paralysis.

Measured constraint (journal 2026-06-21): the link graph is hub-and-spoke (73% leaves) — computed graph queries (paths, centrality, communities) mostly re-derive the index tree, so the pre-made graph is NOT where client headroom is. Turns and tokens are.

Workstreams (priority order)

W1 — mark_fetch outline/section mode (token economy)

• url#<heading-anchor> returns just that section (client slices the fetched markdown; no protocol change).
• Outline mode returns the heading tree + opening paragraph + doc stats (version, modified, size, tags) with a "fetch url#section for detail" hint.
• Client caches the full body per session, so section follow-ups are free.

W2 — mark_explore composite (turn economy)

One tool call returns a neighborhood card for a URL: outline-mode head of the doc + backlinks (titles) + outbound links (titles) + sibling listing, each entry one line. Composes FETCH/LOOKUP/graph client-side. Caps per section (~10) with honest "+N more". Replaces the common 3–4-turn orientation chain.

W3 — session etag/version dedup

Re-fetch of an unchanged doc returns unchanged since v<N> (fetched earlier this session) instead of the body. Changed docs return the body plus a version delta note. Per-process cache; a force param overrides.

W4 — polish (cheap, alongside)

• Tool descriptions teach the strategy: lookup-first, filters, explore for orientation, #section fetches, when NOT to fetch full bodies.
• Plugin session-start injection stays the primary orientation channel (the index hubs ARE the map — Leiden finding); keep hub injection current.

Deferred / non-goals

• Client graph queries (path, common-neighbors, centrality): re-test when the knowledge system develops reciprocal cross-reference density (journal 2026-06-21's trigger). Not now.
• Server-side FTS / semantic search: real, but a server lane — separate plan when picked up.
• MCP resources + prompts (Desktop attach-without-turns): nice follow-up after W1–W3; needs demarkus-mcp resource support end-to-end.
• Lean tool profile (consumer vs authoring subsets): only if schema budget shows up as real pain; Claude Code already defers tool loading.

Decisions to settle

• D1 — outline default. Options: (a) opt-in param only; (b) outline by default for all; (c) size-adaptive: full body under ~8KB, outline above, always overridable (recommended — small docs keep today's behavior, monsters stop flooding context, no consumer breaks silently: the outline says how to get the rest).
• D2 — explore card contents. Recommended: outline head + backlinks + outbound + siblings, 10/section cap. Open: include lookup-by-shared-tags? (lean no for v1 — tag noise.)
• D3 — dedup scope. Recommended: per-process session, version+etag keyed, force override; no cross-session persistence (staleness risk > saving).
• D4 — where W1 slicing lives. Recommended: demarkus-mcp only (client slices); the library's open librarian tool adopts the same convention separately if wanted. Alternative: a shared client/markdown package in demarkus both consume.

Acceptance

A scripted orientation scenario ("what is project X, what phase, who decided") run before/after: tool turns and result tokens both drop materially (target: orientation ≤2 turns; no full-body fetch of an append-heavy status doc unless forced). Existing skills/hook flows (session-start, /promote, journal appends) unchanged.

Order

W1 → W3 (both inside mark_fetch's path, ship together) → W2 → W4 tool- description pass → then MCP resources/prompts as the follow-up phase.

SETTLED (2026-07-04, Fritz — all four on recommendation)

• D1: size-adaptive — full body under ~8KB, outline above, always overridable.
• D2: doc + backlinks + outbound + siblings, 10/section cap (no same-tag section in v1).
• D3: per-session dedup — version+etag keyed, force override, no cross-session persistence.
• D4: shared package in demarkus (client-side markdown outline/section slicing) — demarkus-mcp consumes now, the library's librarian open adopts later.

Build order stands: W1 (+W3 together) → W2 → W4. Work lives in the demarkus repo (demarkus-mcp + a shared client markdown package).