feat: chat with local Claude Code via MCP endpoint

[tkuhn]

First slices of the design in docs/claude-code-chat.md (the "Tier 2" option of #434): a chat page backed by the user's local Claude Code installation, which can act on Nanodash through an MCP endpoint. Uses the user's existing Claude plan login — no API keys, no operator cost. Off by default; intended for locally running instances only.

What's included

• Docked chat panel on every page — ClaudeChatPanel, rendered from the NanodashPage base markup: a corner 💬 button when collapsed, a docked panel when expanded (state in NanodashSession). The conversation lives server-side, so it stays open across open_page navigations — Claude can show you a nanopub while the chat remains in the corner. Per-kind message styling (user / assistant / tool activity / error); assistant messages render as markdown (commonmark), sanitized with the existing OWASP policy. The 2s poll only re-renders the chat box when messages or the busy state changed. /claudechat offers the same panel as a full page.
• ClaudeChatService / ClaudeSession — one persistent headless claude --print --input-format stream-json --output-format stream-json subprocess per Wicket session; ANTHROPIC_API_KEY/AUTH_TOKEN/BASE_URL scrubbed from the child env so usage stays on the plan login; 10-min idle reaping; working directory pinned to ~/.nanodash/claude-chat so the CLI doesn't pick up the server directory's CLAUDE.md.
• /mcp endpoint — hand-rolled MCP server (JSON-RPC 2.0 over POST, stateless streamable-HTTP JSON mode), guarded by a startup-random bearer token injected into the subprocess's --mcp-config. Hand-rolled rather than the official MCP Java SDK because the SDK's servlet transport targets Servlet 6.0 (dev jetty is 11 / Servlet 5.0).
• Read-only tools — search_nanopubs, get_nanopub, get_latest_version, list_templates, get_template, run_query. Template URIs passed to get_template/prepare_publication are resolved to the latest version server-side (supersedes chains + space-governed resolution), and get_latest_version covers arbitrary nanopub URIs. The subprocess runs with --allowedTools mcp__nanodash* WebFetch only.
• Action tools — prepare_publication builds a /publish?template=...&param_... path with prefilled placeholder values (nothing is signed or published server-side; the user reviews and publishes through the normal flow), and open_page queues an in-app navigation that the chat panel executes in the user's browser; the calling session is identified via an X-Nanodash-Chat-Session header, and paths are validated to be in-app only.
• Domain background + page context — a curated background prompt (classpath resource chat/background.md, passed via --append-system-prompt) teaches Claude nanopub anatomy, version semantics, and pins the meta-templates to use when creating new templates, queries, or views; each chat message invisibly carries the in-app path the user is on, so “this page” / “this nanopub” references resolve without asking.
• Stop button — visible while Claude is working; sends an interrupt over the stream-json control protocol, the turn ends with an (interrupted) marker and the session stays usable.
• Config — claudeChatEnabled / claudeChatBinary / claudeChatModel prefs with NANODASH_CLAUDE_CHAT_* env overrides.

Remote MCP access (per-user tokens) — docs/remote-mcp.md

The /mcp endpoint can now also serve hosted multi-user instances, letting users point their own agents at it (bring-your-own-agent instead of a server-side subprocess):

• mcpRemoteEnabled pref (NANODASH_MCP_REMOTE_ENABLED), independent of claudeChatEnabled — either feature works without the other.
• Personal API tokens (ApiTokenService): created/revoked in a new "🔑 Remote AI access" box on the user's own About tab; ndmcp_-prefixed secrets shown once, stored SHA-256-hashed in ~/.nanopub/nanodash-api-tokens.yml; unit-tested. The one-time reveal includes a ready-to-paste claude mcp add --transport http ... command.
• Dual auth in McpServlet: the existing startup-random chat token, or a user token resolved to the owner's IRI (401s carry WWW-Authenticate). Plus protocol polish: version negotiation (2024-11-05 → 2025-06-18), the domain background served as MCP instructions to every client, real serverInfo.version, explicit 405 on GET/DELETE.
• open_page for remote agents: a McpCaller record routes navigations either to the chat-session queue (unchanged) or to per-user queues (RemoteAgentService); pages of the logged-in user poll every 3s only while their agent was active in the last 30 minutes (render-time gate, self-stopping) — no background polling for anyone else.
• background.md split into a client-neutral core (served as instructions) + local-chat addendum (--append-system-prompt).
• Repeatable-row prefill: prepare_publication accepts JSON-array param values and emits the publish form's indexed convention (param_x, param_x__1, ...), so agents can fully prefill repeatable template statements (e.g. the statement rows of the template meta-template) instead of telling the user to add them by hand.

OAuth 2.1 (what claude.ai custom connectors need) is documented as a follow-up in docs/remote-mcp.md.

Try it

NANODASH_CLAUDE_CHAT_ENABLED=true ./mvnw jetty:run

then open http://localhost:37373/claudechat (needs a logged-in claude CLI on the PATH). Try: "I want to publish a nanopub saying X relates to Y. Find a suitable template, prefill it, and open the form for me."

Verified

End-to-end on an isolated instance, twice: (1) chat message → Claude called search_nanopubs over MCP (401 without the token) → answer rendered in the panel; (2) "pick a template, prepare a publication, open it" → Claude chained list_templates → prepare_publication → open_page and the browser landed on a fully prefilled publish form, with Publish untouched. Later slices verified the same way: page-context question answered without tool calls, superseded-URI resolution through get_latest_version/get_template, WebFetch on an arbitrary domain, and mid-turn interrupt with the session staying usable. The remote slice was verified the same way: token creation/one-time-reveal/revoke in the UI, the curl protocol matrix (versions, instructions, 401/405/202), open_page steering a logged-in tab within 3s through the user-keyed queue, a real claude mcp add --transport http client resolving a supersedes chain, array params filling both statement rows of the template meta-template (screenshot-checked) with the local docked chat unaffected.

Not yet (follow-ups per the design doc)

• WebSocket/SSE streaming instead of polling
• --resume revival of idle-reaped sessions

🤖 Generated with Claude Code