MCP server, phase 3: query tools (find_notes, backlinks, wikilink)

[srid]

Three read-only MCP tools so a client can navigate the notebook structurally instead of pulling the bulk metadata export on every question. Phase 2 shipped resources; phase 3 plugs the gap noted there — "the model has to read every note's metadata just to ask 'where is X?'" — by adding tools that answer the structural question directly. The tools share the live-model snapshot semantics phase 2 plumbed (IO Model reader, no shared IORef, no caching).

Tools

Tool	Inputs	Returns
find_notes	query (substring), optional limit (1–100, default 20)	{matches: [{path, title, uri}]} — case-insensitive matches on title or source path
get_backlinks	path (e.g. guide/mcp.md)	{backlinks: [{path, title, uri}]} — wraps Model.Graph.modelLookupBacklinks
resolve_wikilink	wikilink (e.g. guide/mcp), optional from for disambiguation	{result: "found" | "missing" | "ambiguous", …} — wraps Model.Link.Resolve.resolveWikiLinkMustExist

Each path is a valid suffix for the emanote://note/{path} resource template phase 2 advertised — chain find_notes into resources/read to load full notes.

Module shape

Mirrors the phase-2 Catalog/Handlers split — pure surface beside MCP-typed wire adapter:

ToolCatalog (pure)  ─▶  Tools (wire)  ─▶  Handlers  ─▶  dpella/mcp
NoteMatch, queries      ToolHandler[]      withTool…       runtime

ToolCatalog has zero dpella/mcp imports — verifiable from the import list — so future MCP wire changes don't ripple into the query layer, and the queries are reusable for any future non-MCP surface.

Structural review

/hickey + /lowy ran on the feature commit and surfaced five findings, each landed as its own commit so the PR history reads as a sequence of structural refinements:

Commit	Finding
553a5c76	Hoist lmlSourcePath from View.Export.JSON → Route.ModelRoute (layering: MCP shouldn't depend on View)
476eccf6	Dedup parseNoteRoute via new Route.mkLMLRouteFromMdOrOrgFilePath
db678c32	Pass Note through noteMatchOf — drop re-lookup and latent title-divergence
349240aa	Derive NoteMatch.uri in ToJSON instance — one place owns uri = noteUriPrefix <> path
971395b1	Split Tools.hs into pure ToolCatalog + wire Tools

/code-police added three elegance refinements: pure instead of Right in do-notation, Data.Scientific.toBoundedInteger for readIntArg (safer than truncate . toRational), and a WHY comment on readTextArgMaybe's empty-string normalisation.

Try it locally

nix run github:srid/emanote/mcp3 -- -L docs run --mcp-port 8079

Then point Claude Code / Codex at http://localhost:8079/mcp and call any of the three tools through the model.

Closes phase 3 of #645. Phase 4 (resource subscriptions) is the next slice.

Generated by /do on Claude Code (model claude-opus-4-7).

[srid]

Hickey/Lowy Analysis

#	Lens	Finding	Disposition
1	Hickey	lmlSourcePath placed in View.Export.JSON — layering miss	Fixed in this PR (553a5c76)
2	Hickey/Lowy	parseNoteRoute duplicated verbatim across two modules	Fixed in this PR (476eccf6)
3	Hickey	noteMatchOf discards in-scope Note, forces re-lookup with latent title divergence	Fixed in this PR (db678c32)
4	Lowy → Hickey cross-validation	NoteMatch.uri bakes URI-scheme volatility into a pure result type	Fixed in this PR (349240aa) — refined to derive uri in the ToJSON instance rather than scatter the concatenation to wire callers
5	Lowy	Tools.hs braids notebook-query and MCP-wire volatility axes	Fixed in this PR (971395b1)

Hickey rationale

Three findings, all narrow:

• Finding A — Duplicated parseNoteRoute. Byte-identical helper in Catalog.hs and Tools.hs. Coupling invariant ("both agree on what counts as a recognised note path") was structural — adding a third LML format would require two updates with nothing forcing them to match.
• Finding B — lmlSourcePath placement. withLmlRoute encodeRoute is a pure route-layer helper with no View or JSON-export concern. Its home was an accident of being the first consumer's module. Phase 3 made the layering inversion visible by adding MCP as a non-View consumer.
• Finding C — noteMatchOf re-lookup. findNotes already held the Note in scope; the helper discarded it, passed the route, and re-derived the title via modelLookupTitle (another IxSet lookup). Worse, the match-key (note._noteTitle) and report-title (modelLookupTitle) were computed via different paths — they agreed today only accidentally.

Lowy rationale

Three findings, all Fix-in-this-PR:

• Finding A — Tools.hs conflates two volatility axes. Pure query functions (findNotes, getBacklinks, resolveWikilink, NoteMatch, ResolveResult) lived alongside MCP wire scaffolding (InputSchema literals, argument parsing, ToolHandler construction). Phase 2 encapsulated the analogous split for resources via Catalog/Handlers; phase 3 collapsed it.
• Finding B — parseNoteRoute dup. Same as Hickey A; hoist into Route.ModelRoute where mkLMLRouteFromKnownFilePath already lives (same volatility axis: LML-format recognition).
• Finding C — NoteMatch.uri bakes URI-scheme volatility into a pure result type. Catalog.NotebookResource doesn't carry URIs — Handlers.toMcpResource assigns them at the wire boundary. Phase 3 inverted this by storing uri = kindToUri ... inside the pure record.

Cross-validation

Each reviewer was then shown the other's findings and asked whether applying them would create a problem its lens would flag. Hickey concurred with Lowy's diagnosis on Finding C but refined the fix: rather than recompute kindToUri at each wire handler (which scatters the concatenation across three callers), drop the uri field entirely and derive it inside a hand-written ToJSON instance — one place owns the rule uri = noteUriPrefix <> path. Lowy returned no cross-validation findings against Hickey's three.

Generated by /do on Claude Code (model claude-opus-4-7).

[srid]

Evidence

Captured against docs/ (the user-docs notebook) via the bundled MCP HTTP transport. Verifies every advertised tool returns the expected wire shape end-to-end, including the two error paths (text-level isError: true for bad input, JSON-RPC -32602 for missing required arguments).

tools/list

[
  {
    "name": "find_notes",
    "description": "Search the notebook for notes whose title or source path contains the query (case-insensitive). Returns up to `limit` matches.",
    "required": [
      "query"
    ]
  },
  {
    "name": "get_backlinks",
    "description": "List notes that backlink to the note at the given source path.",
    "required": [
      "path"
    ]
  },
  {
    "name": "resolve_wikilink",
    "description": "Resolve a wikilink (e.g. \"guide/mcp\") to a note or static file. Optionally relative to a source note for disambiguation; defaults to the notebook index.",
    "required": [
      "wikilink"
    ]
  }
]

find_notes — query="wikilink", limit=3

{
  "matches": [
    {
      "path": "guide/markdown/file-links.md",
      "title": "File WikiLinks",
      "uri": "emanote://note/guide/markdown/file-links.md"
    },
    {
      "path": "guide/wikilinks.md",
      "title": "Wiki Links",
      "uri": "emanote://note/guide/wikilinks.md"
    }
  ]
}

get_backlinks — path="guide/folgezettel.md"

{
  "backlinks": [
    {
      "path": "guide/wikilinks.md",
      "title": "Wiki Links",
      "uri": "emanote://note/guide/wikilinks.md"
    },
    {
      "path": "guide/html-template/uptree.md",
      "title": "Uplink tree",
      "uri": "emanote://note/guide/html-template/uptree.md"
    },
    {
      "path": "guide/html-template/sidebar.md",
      "title": "Sidebar",
      "uri": "emanote://note/guide/html-template/sidebar.md"
    },
    {
      "path": "guide/markdown.md",
      "title": "Markdown ✍️",
      "uri": "emanote://note/guide/markdown.md"
    },
    {
      "path": "guide/folgezettel.md",
      "title": "Folgezettel links",
      "uri": "emanote://note/guide/folgezettel.md"
    },
    {
      "path": "guide/folder-note.md",
      "title": "Folder notes",
      "uri": "emanote://note/guide/folder-note.md"
    },
    {
      "path": "guide/html-template/breadcrumbs.md",
      "title": "Breadcrumbs",
      "uri": "emanote://note/guide/html-template/breadcrumbs.md"
    }
  ]
}

resolve_wikilink — wikilink="guide/mcp"

{
  "kind": "note",
  "note": {
    "path": "guide/mcp.md",
    "title": "MCP server",
    "uri": "emanote://note/guide/mcp.md"
  },
  "result": "found"
}

resolve_wikilink — wikilink="no-such-note"

{
  "result": "missing"
}

get_backlinks — bogus path → isError

{
  "content": [
    {
      "text": "Not a recognised note path: foo.invalid",
      "type": "text"
    }
  ],
  "isError": true
}

get_backlinks — missing required → JSON-RPC -32602

{
  "code": -32602,
  "message": "Missing required arguments: path"
}

Generated by /do on Claude Code (model claude-opus-4-7).

[srid]

/do results

Step	Status	Duration	Verification
sync	✓	1s	git fetch ok; forge=github; noGit=false
research	✓	6m 32s	Mapped phase 2 MCP code, dpella/mcp tool API, and the three model functions to wrap.
branch	✓	9s	On feature branch mcp3 at 214480b (== origin/master, no remote yet — pushed in commit step).
implement	✓	16m 7s	Created Emanote.MCP.Tools, wired into Handlers, advertised ToolsCapability. ToolCatalogSpec covers 12 unit tests; smoke-tested against the docs notebook over JSON-RPC.
check	✓	10s	cabal build all clean.
docs	✓	1m 46s	docs/guide/mcp.md Tools section + extended complexity table; CHANGELOG extended.
fmt	✓	2m 47s	pre-commit (cabal-fmt + fourmolu + hlint + nixpkgs-fmt) all green.
commit	✓	30s	Feature commit e62efd8 pushed to origin/mcp3.
hickey+lowy	✓	45m 55s	3 + 3 findings (1 overlap), cross-validation refined Lowy's uri-field fix. Five Fix commits landed: 553a5c7, 476eccf, db678c3, 349240a, 971395b.
police	✓	15m 14s	/code-police three iterations: Data.Scientific.toBoundedInteger, WHY comment, pure vs Right. Three commits: e6bac32, e712004, 13d4c3a.
test	✓	21s	137 unit tests pass (12 of them new in ToolCatalogSpec).
create-pr	✓	1m 19s	Draft PR #745 with forge-pr description + hickey/lowy analysis comment.
ci	✓	4m 37s	vira ci signed off HEAD (13d4c3a) for aarch64-darwin + x86_64-linux. e2e-static 60/60, e2e-live 79/79, e2e-morph 79/79.
evidence	✓	3m 50s	PR comment under ## Evidence with seven JSON-RPC samples (success paths + both error paths).
Total		99m 43s

Slowest step: hickey+lowy (45m 55s, 46% of total).

Optimization suggestions

• hickey+lowy dominated (46% of total). Each of the five Fix findings ran its own fmt → build → test → commit → push cycle (~5 min each). When sister findings touch the same module — Hickey C (Note-passing) and Lowy C (uri derivation) both modified NoteMatch/noteMatchOf — consider batching them in one commit. PR history loses one entry but saves a full CI lap.
• Research was 6m 32s, mostly spent reading the dpella/mcp source from /nix/store/.../mcp/src. The repo has a dpella-mcp skill that documents the same API; invoking it instead of grep-spelunking the nix store would have cut this step roughly in half.
• The hlint pass at fmt time caught three suggestions (maybeToRight, viaNonEmpty, unused pragma) that hlint would have caught at check time too. Running hlint as part of the check command (or as a pre-commit hook only) would keep the suggestions next to the change that produced them.
• The background-task harness exited with code 144 several times when launching emanote run for smoke tests. The synchronous-launch + & + wait pattern (run inside one Bash invocation) worked reliably; the run_in_background: true path didn't survive the next tool call.

Workflow completed at 2026-05-25.

[srid]