soul.demarkus.io/plans/mcp-resources-prompts.md/v1 draft reader meta

Plan: MCP resources + prompts — attach-without-turns

Status: drafted 2026-07-05 · Repo: demarkus (demarkus-mcp client) · Decisions D1–D4 open (recommendations inline) · Follow-up phase named by /plans/mcp-client-ergonomics.md.

Problem

Everything an agent gets from demarkus today costs a tool turn, and the result lands as tool output rather than first-class context. MCP has two primitives built for exactly this gap, and demarkus-mcp implements neither:

  • Resources — client-attachable context. In Claude Desktop the user picks a resource and attaches it; in Claude Code resources can be referenced and read without the model spending a turn deciding to fetch. A demarkus doc as a resource = "put this doc in context" as a UI action, zero turns.
  • Prompts — server-vended workflows that surface as slash commands (/mcp__<server>__<prompt> in Claude Code, prompt picker in Desktop). The orientation strategy the ergonomics phase encoded into tool descriptions can be a first-class command instead of prose the model must remember to follow.

mcp-go v0.44 supports both natively (AddResource, AddResourceTemplate with RFC 6570 URI templates, AddPrompt with typed arguments); capability advertisement is automatic on registration.

Workstreams

R1 — resources (attach a doc without a turn)

  • Resource template mark://<host>/{+path} registered at startup (host known from -host; without -host, template over {host}/{+path}). Read handler: parse URI → FETCH → TextResourceContents with text/markdown. Reuses the ergonomics conventions: a #anchor fragment in the resource URI attaches just that section (mdoutline.Section).
  • Concrete resources (what shows in resources/list): the index hub (/index.md) and the agent manifest (/.well-known/agent-manifest.md) registered statically — the two entry points every demarkus server has.
  • Errors map to MCP resource errors (not-found etc.), never empty content.

R2 — prompts (workflows as slash commands)

V1 set (small, matching what the ergonomics tools already teach):

  • orient (arg: url, required) — vends messages instructing: mark_explore the url, then fetch the #sections that matter; answer with a neighborhood summary. The ≤2-turn orientation flow as a command.
  • recall (arg: subject, required) — lookup-first recall: mark_lookup the subject, explore the best match, fetch sections; report with mark:// refs.

R3 — polish

  • Tool/resource descriptions cross-reference ("attach via resources for zero-turn context; fetch via tools for programmatic access").
  • README/docs note for Desktop users (resources are the Desktop-native way in).

Decisions to settle

  • D1 — resource listing shape. (a) static well-known set + template (recommended — no startup network dependency, unbounded docs reachable via template, resources/list stays honest); (b) dynamic list from a startup LIST crawl (richer picker UX, but couples MCP server startup to host availability and goes stale mid-session); (c) both, with a lazy background refresh (complexity — only if Desktop picker UX proves to matter).
  • D2 — resource read shape for large docs. (a) always full body (recommended) — attaching is a deliberate act, outline-gating an explicit attach would surprise; #anchor URIs give section-sized attach; (b) outline over 8KB like mark_fetch (consistent but wrong ergonomics for attach).
  • D3 — v1 prompt set. (a) orient + recall (recommended); (b) add whats-new (recent-changes digest via LOOKUP modified-after) — defer unless wanted now; (c) soul-specific prompts (journal etc.) stay in the plugin, not the generic client.
  • D4 — broker parity timing. (a) defer (recommended) — ship client-side, prove the shape, then flip the gateway (its plan explicitly excludes resources/prompts and a capabilities test PINS their absence — that test flip is the marker of the follow-up); (b) same phase — bigger PR, and Desktop-attach matters most for knowledge-system users, but auth
    • multi-world resource URIs (mark://{world}/{+path}) deserve their own design pass.

Acceptance

  • In Claude Code against the soul: /mcp__soul__orient <url> runs the orientation flow; a resource read of mark://soul.demarkus.io/index.md returns the hub as markdown; a #section resource URI returns just the section.
  • In Claude Desktop: the soul's index + manifest appear in the resource picker; attaching one adds the doc to context with zero tool turns.
  • initialize advertises resources + prompts capabilities; broker gateway capabilities UNCHANGED (D4a).

Pickup notes

  • mcp-go v0.44: AddResource(mcp.NewResource(uri, name, opts), handler); AddResourceTemplate(mcp.NewResourceTemplate(uriTemplate, name, opts), handler) — uritemplate matching is built in; handlers return []mcp.ResourceContents. AddPrompt(mcp.NewPrompt(name, WithArgument("url", RequiredArgument(), ArgumentDescription(...))), handler) returns *mcp.GetPromptResult (messages). Capabilities auto-advertise on first Add*.
  • Code: client/cmd/demarkus-mcp/ — add resources.go + prompts.go beside explore.go; wire in main() after tool registration. Reuse handler.resolveURL/resolveToken, mdoutline.Section.
  • The broker gateway (tools/demarkus-broker/internal/broker/) asserts in TestMCPGatewayInitializeHandshake that resources/prompts capabilities are ABSENT — leave that test intact under D4a; flipping it is the start of the broker follow-up.
  • Gate: bash pre-commit.sh; never commit — Fritz commits. Feature branch.
trail
  1. soul.demarkus.io v1