v0.7.0 — MCP server (any AI client can use AgentMark)

[rrader26]

Summary

Wraps every public surface — web browser, PDF documents, AcroForm filling, OCR — as a Model Context Protocol server. Any MCP client (Claude Desktop, Cursor, Claude Code, custom agents) can use AgentMark through one configuration entry. No SDK install, no language commitment.

Stacked on top of #5 (v0.6 AcroForm). Merge #2 → #3 → #4 → #5 → this PR.

One-line install for any MCP client

```json
{
"mcpServers": {
"agentmark": {
"command": "npx",
"args": ["-y", "@thinkfleet/agentmark", "agentmark-mcp"]
}
}
}
```

15 tools exposed

Surface	Tools
Browser	`browser_open` / `browser_close` / `browser_save_session`
Page	`page_open` / `page_navigate` / `page_snapshot` / `page_execute` / `page_close`
PDF	`pdf_open` (file path OR `data:` URI) / `pdf_close` / `pdf_snapshot` / `pdf_execute` / `pdf_save` (with `flatten?`) / `pdf_reset`
Meta	`list_sessions`

Each tool ships with a full JSON Schema for inputs — clients see usage hints, parameter docs, and validation automatically through MCP's `tools/list`.

Architecture

• `tool-defs.ts` — declarative tool catalog
• `dispatcher.ts` — pure dispatch function (name + args → result). Stateless except for the session registries it receives. Tested directly without transport.
• `server.ts` — MCP Server wiring + StdioServerTransport + SIGINT/SIGTERM cleanup.
• `cli.ts` — `#!/usr/bin/env node` entry; npm installs as `agentmark-mcp` on PATH.

The dispatcher / server split means tests can drive the full protocol without spawning subprocesses.

Stateful session model

Long-lived browsers + pages + opened PDFs held server-side, keyed by opaque IDs returned from `_open` calls. Agents can drive multiple parallel surfaces from one connection. All resources auto-released on shutdown.

Tests (223 total, 18 new for MCP)

• 14 dispatcher tests — tool registry shape, error semantics (unknown tool / missing args / unknown session / AgentMark error code surfacing), PDF round-trip with real file I/O, reset, data-URI loading, list_sessions, disposeAll.
• 4 wire-level handshake tests via `InMemoryTransport` — exercises the full MCP protocol (handshake, ListTools, CallTool, error responses) without spawning a subprocess.

Optional peer dependency

`@modelcontextprotocol/sdk` is an optional peer dep. Library callers who don't run the MCP server pay no install cost; SDK users still get the full library.

Test plan

• Merge v0.3.0 — production-ready SDK surface + action executor #2 → v0.4.0 — PDF support + spec v0.2 (kind: document) #3 → v0.5.0 — OCR + render-backend pipeline (100% on insurance corpus) #4 → v0.6.0 — AcroForm extraction + PdfDocument fill/save SDK #5 first (in order)
• `npm install && npm test` — all 213 unit + benchmark tests pass
• Smoke-test the bin: `npx -y @thinkfleet/agentmark agentmark-mcp` runs without errors (will hang waiting for MCP input — that's correct)
• Configure in Claude Desktop `claude_desktop_config.json` and verify the tools appear
• Drive a PDF from Claude Desktop end-to-end: open file → snapshot → execute → save → verify filled PDF on disk
• Drive a web page from Claude Desktop end-to-end: open browser → navigate → snapshot → execute (e.g. fill a search box) → close
• Verify SIGINT cleanup: `Ctrl-C` after opening browsers/PDFs releases all resources

🤖 Generated with Claude Code