MCP server, phase 2: notebook-backed resources

[srid]

The MCP endpoint now exposes the notebook as read-only resources rather than empty inventories. Phase 2 of #645: clients can read the full-notebook JSON metadata, a single-file Markdown dump of every note, or any individual note by its source path — all without touching the filesystem, served straight from Emanote's live in-memory model.

Three URIs under the emanote:// scheme: emanote://export/metadata (JSON, reuses renderJSONExport), emanote://export/content (Markdown, reuses renderContentExport), and emanote://note/{path} for individual notes. resources/list returns the two static exports plus one entry per note; resources/templates/list advertises the {path} template for RFC 6570-aware clients. The architecturally interesting bit is that Ema's Dynamic is push-only — there's no pull-side API to snapshot the current model. Phase 2 adds a new EmanoteConfig field, _emanoteConfigOnModelUpdate :: Maybe (Model -> IO ()) — a subscription hook that Emanote's EmaSite.siteInput calls on the initial model and every subsequent update. Emanote.run owns an IORef and wires writeIORef ref . Just as the hook, so MCP handlers can readIORef the live snapshot. Storage is the caller's concern; the config boundary stays abstract, which keeps the phase-4 refactor (fanout to per-subscriber queues) local to tapModel.

One known gap: a client arriving in the window between Warp's socket bind and Ema's first model snapshot will hit a JSON-RPC 503 "model not yet loaded", not a real resource read. Phase 4 should close this by deferring MCP.run's bind until the initial model is published. Documented in withModel.

Try it locally

nix run github:srid/emanote/feat/mcp-server-phase2 -- run --port 9010 --mcp-port 8079

Then point Claude Code or Codex at http://localhost:8079/mcp (see docs/guide/mcp.md for client setup).

[srid]

Hickey/Lowy Analysis

#	Lens	Finding	Disposition
1	Hickey	URI scheme fragmented — instructions hand-rolled prefix literal	Fixed (6268bdd)
2	Hickey	Static vs dynamic resource partition enforced by convention	No-op — separation clarifies; invariant holds by domain (note paths must have .md/.org extension, can't collide with export/*)
3	Hickey	_emanoteConfigLiveModelRef names the implementation, not the purpose	Fixed — folded into Lowy F1 (73409d8)
4	Lowy	Raw IORef leaks into EmanoteConfig as an implementation detail	Fixed (73409d8)
5	Lowy	tapModel will need fanout in phase 4	Deferred to phase 4 (docstring added in 73409d8)
6	Lowy	withModel 503 is a startup-race artifact, not a real error	Deferred to phase 4 (docstring added in 7ba1a29)
7	Lowy	IORef → TVar blast radius	No-op — contingent on #4; now local to two call sites after fix

Hickey rationale

The only real complecting find was F1: the instructions string hand-rolled the per-note URI prefix as a fourth literal of a fact already captured by noteUriPrefix. Introducing noteUriTemplate (now the single source of truth for the RFC 6570 template, used by both instructions and noteTemplate) resolves it.

F2 (merging staticResources + noteResources) was declined because the separation clarifies intent rather than interleaving concerns — one is a constant, the other is a projection of the model. The disjointness invariant is domain-enforced (note paths require .md/.org extensions), not a silent fragility.

F3 converged with Lowy F1 and was fixed there.

Lowy rationale

F1 (_emanoteConfigLiveModelRef) was the load-bearing fix. Exposing a raw IORef (Maybe Model) in EmanoteConfig conflated what we need (subscribe to model updates) with how we store it (a ref). Replaced with _emanoteConfigOnModelUpdate :: Maybe (Model -> IO ()) — a subscription hook. Emanote.run now owns the IORef privately and injects a one-line writer as the observer; phase 4's fanout refactor becomes local to tapModel and Emanote.run, with no ripple into the config record.

F2 and F3 are both deferred to phase 4 with explicit doc-comments naming the expected refactor. tapModel's comment calls out the fanout transition explicitly so phase 4 implementers don't need to re-derive it; withModel's comment documents that the 503 path exists only because race_ gives no ordering guarantee between Warp's bind and Ema's first snapshot. Phase 4 should remove that path by deferring MCP.run until the first model is published.

F4 becomes a non-concern once F1 is fixed: the IORef → TVar migration is now a 3-line change inside Emanote.run and tapModel, with no impact on EmanoteConfig.

[srid]

/do results

Step	Status	Duration	Verification
sync	✓	0s	git fetch ok; forge=github; noGit=false
research	✓	7m 40s	Architecture: IORef Model tapped in siteInput, shared with MCP handlers. Reuse renderJSONExport/renderContentExport/readNoteContent/generateNoteHeader. URI shape emanote://export/{metadata,content}, emanote://note/{path}. MCP types confirmed in dpella/mcp source.
branch	✓	10s	On feat/mcp-server-phase2
implement	✓	5m 14s	New module Emanote.MCP with 3 resource URIs and a template; IORef (Maybe Model) wired via tapModelRef in Emanote.hs; EmanoteConfig extended with _emanoteConfigLiveModelRef
check	✓	1m 26s	cabal build all clean; smoke-tested all 3 resource URIs + 404 error paths + template listing via curl
docs	✓	1m 35s	Updated docs/guide/mcp.md with resources table + URI template note; refreshed CHANGELOG entry to reflect phase 2; nix build .#docs passes
fmt	✓	49s	fourmolu + hlint + cabal-fmt + nixpkgs-fmt all pass; build still clean after formatting
commit	✓	18s	commit 33bde3b on feat/mcp-server-phase2 pushed to origin
hickey+lowy	✓	7m 4s	Hickey F1 fixed (6268bdd); Lowy F1 + Hickey F3 combined into observer refactor (73409d8); Lowy F3 documented (7ba1a29); Hickey F2 no-op (separation is clarifying); Lowy F2/F4 addressed inline / contingent. Smoke-tested post-refactor.
police	✓	5m 22s	Rules: clean. Fact-check: clean. Elegance: 1 fix (extract readNoteResource, commit 6449a82). 4 findings deferred with rationale (per-request caching is premature at phase 2 scale; DuplicateRecordFields noise is codebase-wide style).
test	—	0s	setup: user skipped
create-pr	✓	1m 21s	Draft PR #649 opened with narrative body; hickey/lowy ledger + rationale posted as comment
ci	✓	1m 32s	vira ci FullBuild: both platforms signed off on 6449a82; HEAD matches
done	✓	0s	Phase 2 complete; draft PR #649 open
Total		35m 16s

Slowest step: research (7m 40s)

Optimization suggestions

• Research (7m 40s) dominated again despite the pre-loaded dpella-mcp skill. The skill saved the MCP-protocol rediscovery, but the main research spend was on Emanote's own layers — EmanoteConfig, Dynamic, export module surfaces. A companion emanote-architecture skill summarizing the renderer/model/exporter seam would pay off starting phase 3.
• Hickey+lowy (7m 4s) is the second-most-expensive step — roughly two minutes of sub-agent wall-clock plus the commit-per-finding cadence. For small phases, consider batching the observer-refactor + doc-comments into two commits rather than three to trim ~30s; diminishing returns beyond that.
• Implement + check + fmt together are 7m 29s — this looked right-sized for the scope (one new module, one config field, one Dynamic tap). No suggestion.
• Phase 3 (query tools) should skip research entirely if the dpella-mcp skill is pre-loaded and include "tools live under the same IORef (Maybe Model) as resources" in the invocation — the MCP tool surface is shaped like emanote/src/Emanote/MCP.hs:readResource dispatch, just with different inputs.

Workflow completed at 2026-04-23.