Create `packages/mcp` server with run-data tools

[williamthorsen]

Parent

Part of #74 (MCP server for run data + v3 event-sourced format) — PR 2 of 4.

Dependencies

• Blocked by Create packages/run-data shared types package #84 (packages/run-data must exist first)

Scope

Create packages/mcp/ as a custom MCP server providing domain-specific tools for run data management. The orchestrator calls these instead of Read/Edit/Write on JSON files.

Deliverables

1. Package scaffolding — package.json (@codeassembly/mcp), tsconfig.json, vitest.config.ts, CLI entry point
2. 5 MCP tools:
   • init_run — generate run ID, create artifact directory, write v3 header, emit run_initialized
   • emit_event — validate event against Zod schema, append timestamped JSONL line
   • register_artifact — validate artifact entry, emit artifact_written event
   • complete_run — emit run_completed, stamp completedAt on header
   • get_run_state — read header + fold events → CanonicalRunStatus
3. Server implementation — @modelcontextprotocol/sdk with stdio transport
4. MCP registration — add to .claude/settings.json
5. Build-on-install — prepare script to compile on pnpm install

Acceptance criteria

• Server starts via node packages/mcp/dist/esm/cli.js without errors
• Each tool handler tested with mock file system
• JSONL append produces valid, parseable lines
• Validation errors return descriptive messages (not silent failures)
• get_run_state round-trips correctly: init → emit events → get_run_state matches expected state
• Integration test: full lifecycle (init → events → artifacts → complete → get_state)
• init_run failure is loud and immediate (fail-early design for MCP unavailability)

See #74 implementation plan, Step 2 for full details.

[williamthorsen]

Insight: Vite 7 SSR resolve conditions for workspace packages

When using Vitest 4 + Vite 7 in a pnpm monorepo, workspace packages that import other workspace packages via exports fields need special configuration to resolve from TypeScript source during testing (before dist/ exists from a build step).

The problem

CI runs check:strict (which includes tests) before build. Workspace package @codeassembly/mcp imports @codeassembly/run-core, whose exports field points to ./dist/esm/index.js. Since dist/ doesn't exist yet during testing, Vite fails with:

Error: Failed to resolve entry for package "@codeassembly/run-core".
The package may have incorrect main/module/exports specified in its package.json.

Root cause

In Vite 7, resolve.conditions only applies to the client environment. When Vitest runs tests with environment: 'node', it uses an SSR-like environment that has its own ssr.resolve.conditions — defaulting to ['module', 'node', 'development|production'] without any custom conditions.

This means adding resolve.conditions: ['source'] to the Vite/Vitest config is not sufficient — the SSR environment ignores it entirely.

The fix (two parts)

1. Add a "source" condition to the provider package's exports (run-core/package.json):

"exports": {
  ".": {
    "source": "./src/index.ts",   // ← listed BEFORE "import" so it wins
    "import": "./dist/esm/index.js",
    "types": "./src/index.ts"
  }
}

2. Set the condition in BOTH client and SSR environments (config/vitest.config.ts):

export const baseConfig = defineConfig({
  resolve: {
    conditions: ['source'],        // client environment
  },
  ssr: {
    resolve: {
      conditions: ['source'],      // SSR/node environment (used by Vitest)
    },
  },
});

How to verify

Rename packages/run-core/dist → dist.bak, run pnpm --filter @codeassembly/mcp run ws test, confirm all 30 tests pass, then restore dist.

Key takeaway

Any future workspace package that (a) uses exports pointing to compiled output and (b) is consumed by tests in another workspace package will automatically benefit from this base config change — no per-package configuration needed.