Wire MCP server support via completion({ mcp })

[codeswithroh]

What this changes

Wires QVAC to Model Context Protocol servers via completion({ mcp }), alongside (not
replacing) the existing v0 JSON-action protocol.

Closes #16

A blocker worth stating up front

@tetherto/wdk-mcp-toolkit — the 35-tool wallet server this issue names — is still a
reserved placeholder on npm (0.0.0, no code) as of this PR. I checked the published
tarball directly: it's a 54-byte package.json and nothing else. So "wire the official
package" isn't literally possible yet.

What's here instead: src/mcp.mjs wires any MCP server generically over stdio, using the
same protocol QVAC's own mcp-websearch example (@qvac/sdk@0.14.1) uses. The moment
@tetherto/wdk-mcp-toolkit ships, pointing mcp.json's command/args at it works with
zero code changes here.

Relationship to #15

#16 names #15 (native tool-calling via completion({ tools })) as its precursor, and #77
is mid-review for that. I did not touch #77's territory — no changes to the tools-based
native tool-calling path, dispatchToolCall, or useNativeTools. completion({ mcp }) is
a separate QVAC parameter with its own tool-call loop (stream → collect calls → invoke →
push assistant/tool turns → re-complete), so this PR implements that loop only for the
MCP path — it doesn't touch or duplicate #77's tools path.

Changes

• src/mcp.mjs (new) — loadMcpConfig() reads an optional mcp.json (same
  optional-file / NAD_*-override pattern as policy.json / address-book.json): a list
  of MCP servers to spawn over stdio. connectMcpServers() connects each with the official
  @modelcontextprotocol/sdk, best-effort — a server that fails to start is skipped and
  reported via onWarn, not fatal (same rule as a failed model load: the rest of the agent
  still works). summarizeMcpToolResult() turns an arbitrary MCP tool result into a bounded
  string for history/terminal.

• src/agent.mjs — completeWithMcp(): streams text, collects tool calls via
  run.final, invokes them, pushes { role: "assistant" } then { role: "tool" } turns
  back into history, and re-completes — until the model stops calling tools or a finite
  maxToolRounds (default 8) is hit. Never throws on a model-side error (same rule as
  complete()); returns { text, rounds, toolErrors, limitReached } so the caller decides
  how to report a stopped model, a tool error, or a hit round limit. Takes an injectable
  runCompletion so the loop is unit-testable without a live model.

• src/cli.mjs — when MCP servers are configured and connected, natural-language turns
  route through completeWithMcp() instead of the v0 path. Every tool call is gated behind
  the same confirm + mainnet-ack prompt every wallet write already goes through: the tool
  catalog is discovered at runtime from an arbitrary server, so there's no reliable way to
  tell a read from a write the way isWrite() does for the built-in actions — asking every
  time is the safe default here, not a guess. Tool errors and a hit round limit are printed
  and, in scripted mode, flip the exit code — not swallowed.

• .env.example / .gitignore / README.md / CLAUDE.md updated to document mcp.json,
  NAD_MCP_CONFIG, and the actual state of the @tetherto/wdk-mcp-toolkit dependency.

• package.json — added @modelcontextprotocol/sdk (pure JS, no native deps, bundles fine
  under esbuild — verified by npm run build).

How I tested it

• npm run build succeeds
• npm run doctor passes
• npm test — 312 tests pass, 17 new:
  • test/mcp.test.mjs — loadMcpConfig() validation (malformed JSON, unknown keys,
    missing name/command, non-string args/env, duplicate names), summarizeMcpToolResult()
    shape handling and truncation, and connectMcpServers()'s best-effort failure handling
    driven against the real @modelcontextprotocol/sdk (a nonexistent binary is skipped
    and reported, not thrown; one bad server doesn't block another).
  • test/agent-mcp.test.mjs — drives completeWithMcp()'s loop end-to-end through an
    injected fake runCompletion (the actual { events, final } shape completion()
    returns): follow-up turns after a tool call, multi-call rounds invoked in order,
    toolError events surfaced rather than swallowed, round-limit enforcement, and
    stream-error tolerance. This exercises the loop itself, not just that a function exists.
• Real gasless send / interactive MCP session: I couldn't get a model to load in this
  environment (@qvac/llm-llamacpp native module isn't resolving here — looks like a
  sandbox/prebuild issue, unrelated to this change) so I could not do an end-to-end
  interactive run against a live MCP server. Everything above is verified without the model.

Model / platform tested on: none (see above) — npm test + npm run build + npm run doctor
only, in a Linux/macOS CI-like sandbox without a working QVAC model runtime.

Scope check

• This stays within v0 scope, OR
• This grows the scope: adds an opt-in MCP tool-calling path. Off by default (no
  mcp.json = byte-identical behavior to before); on only when a user writes one.

Conventions

• I used npm (not pnpm/yarn) and did not add a global sodium-native override.
• I did not commit .env, seeds, keys, or model weights.

[codeswithroh]

@portdeveloper After #15 is closed will make the necessary changes as required

[portdeveloper]

Thanks for taking this on. There is one secret-handling blocker in src/mcp.mjs:112-116: every MCP child receives { ...process.env, ...s.env }. In the normal agent process that includes WDK_SEED, PIMLICO_API_KEY, and any other wallet credentials, so an arbitrary configured server or npx package can read them before the first tool confirmation.

Please start from the MCP SDK's minimal/default child environment and add only the variables explicitly listed in that server's env config. Add a regression that places sentinel wallet secrets in process.env, constructs the transport options through an injectable seam, and proves those values are absent unless the operator explicitly configured them for that server.

[codeswithroh]

@portdeveloper Fixed in dd3a77f.

The child no longer gets process.env at all. buildStdioTransportOptions(server) (new, exported from src/mcp.mjs) starts from @modelcontextprotocol/sdk's own getDefaultEnvironment(), the SDK's minimal safe allowlist (HOME/LOGNAME/PATH/SHELL/TERM/USER on POSIX) and layers on only whatever that server's own env block in mcp.json explicitly names. connectMcpServers() now goes through that function instead of inlining the merge.

test/mcp.test.mjs has the regression you asked for: it plants sentinel values for WDK_SEED/PIMLICO_API_KEY in process.env before each test, then proves buildStdioTransportOptions() never forwards them unless the operator names them explicitly for that server once with an injected getDefaultEnv seam (fast, no SDK dependency) and once against the real SDK's own default-env function, plus a third case confirming explicit opt-in still works when a secret is named.

315 tests pass, npm run build succeeds.

[portdeveloper]

looks good, thanks