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

CHANGELOG.md

@@ -5,6 +5,59 @@ All notable changes to `@thinkfleet/agentmark` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] — 2026-05-10
+
+MCP server. The entire AgentMark library is now drivable from any MCP
+client (Claude Desktop, Cursor, Claude Code, custom agents) through a
+single config entry.
+
+### Added
+
+- **`agentmark-mcp` CLI** — bin entry in package.json. Configure any
+  MCP client with one line:
+  ```json
+  {
+    "mcpServers": {
+      "agentmark": {
+        "command": "npx",
+        "args": ["-y", "@thinkfleet/agentmark", "agentmark-mcp"]
+      }
+    }
+  }
+  ```
+- **15 MCP tools** covering every public surface:
+  - 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` / `pdf_reset`
+  - Meta: `list_sessions` for debugging stuck connections
+- **Stateful session model.** The server holds long-lived browsers + open
+  PDFs keyed by IDs returned from `_open` calls, so one MCP connection
+  can drive multiple parallel agents.
+- **Programmatic access.** `createMcpServer()` + `startMcpServer()` +
+  `dispatch()` exported for embedding the server in other applications
+  or testing without spinning up stdio.
+- **Graceful shutdown.** SIGINT / SIGTERM disposes all browsers,
+  Tesseract workers, and PDF handles before exit.
+- **`@modelcontextprotocol/sdk` as optional peer dependency.** Library
+  callers who don't run the MCP server pay no install cost; surface a
+  clean error if the SDK is missing.
+
+### Tests
+
+- 14 new dispatcher tests (PDF round-trip, error semantics, data-URI
+  loading, session listing, dispose-all)
+- 4 new wire-level handshake tests using `InMemoryTransport` (full
+  MCP protocol — handshake, ListTools, CallTool, error responses) —
+  proves real MCP clients can connect without spawning a subprocess.
+- Total: 213 unit + 10 real-Chromium integration = 223 (was 199).
+
+### Distribution unlocked
+
+After `npm publish`, anyone can configure AgentMark in any MCP client
+with the snippet above. No code, no language, no setup beyond the
+config file. The full SDK (web + PDF + OCR + form fill/save) becomes
+available as ~15 tools any agent can call.
+
 ## [0.6.0] — 2026-05-10
 
 PDF form support. AcroForm fields become AgentMark actions; the new
@@ -270,6 +323,7 @@ Initial release of `@thinkfleet/agentmark`.
 - In-memory action binding
 - 90 tests, npm provenance auto-publish
 
+[0.7.0]: https://github.com/ThinkfleetAI/agentmark/releases/tag/v0.7.0
 [0.6.0]: https://github.com/ThinkfleetAI/agentmark/releases/tag/v0.6.0
 [0.5.0]: https://github.com/ThinkfleetAI/agentmark/releases/tag/v0.5.0
 [0.4.0]: https://github.com/ThinkfleetAI/agentmark/releases/tag/v0.4.0

README.md

@@ -227,6 +227,44 @@ OCR modes:
 - `'always'` — OCR every page (overrides any extracted text).
 - `'never'` — disable OCR. Same as omitting `ocr` from `convertPdf`.
 
+## MCP server (v0.7+)
+
+AgentMark ships a Model Context Protocol server so any MCP client (Claude Desktop, Cursor, Claude Code, custom agents) can use the entire library — web, PDF, OCR, AcroForm — through one configuration entry. No SDK install, no language commitment.
+
+**Configure once in your MCP client:**
+
+```json
+{
+  "mcpServers": {
+    "agentmark": {
+      "command": "npx",
+      "args": ["-y", "@thinkfleet/agentmark", "agentmark-mcp"]
+    }
+  }
+}
+```
+
+The server exposes ~15 tools, prefixed `agentmark_*`:
+
+| Surface | Tools |
+|---|---|
+| Browser | `agentmark_browser_open`, `agentmark_browser_close`, `agentmark_browser_save_session` |
+| Page | `agentmark_page_open`, `agentmark_page_navigate`, `agentmark_page_snapshot`, `agentmark_page_execute`, `agentmark_page_close` |
+| PDF | `agentmark_pdf_open`, `agentmark_pdf_close`, `agentmark_pdf_snapshot`, `agentmark_pdf_execute`, `agentmark_pdf_save`, `agentmark_pdf_reset` |
+| Meta | `agentmark_list_sessions` |
+
+Each tool is documented in-line via the MCP `list_tools` response — clients see usage hints, JSON schemas, and parameter descriptions automatically.
+
+The server holds long-lived state per connection (browsers, opened PDFs) keyed by IDs returned from `_open` calls — agents can drive multiple parallel surfaces from one connection. Resources auto-release on shutdown via SIGINT/SIGTERM cleanup.
+
+MCP support is opt-in via the optional peer dependency:
+
+```bash
+npm install @modelcontextprotocol/sdk
+```
+
+Library callers who don't run the MCP server pay no install cost.
+
 ## Lower-level APIs
 
 For callers who want direct control over conversion or want to feed AgentMark

package.json

@@ -1,10 +1,13 @@
 {
   "name": "@thinkfleet/agentmark",
-  "version": "0.6.0",
-  "description": "AI browser + document + form library — convert any web page or PDF (text, scanned, printed, or fillable AcroForm) into a compact AgentMark snapshot, then drive it via clean primitives any AI can call.",
+  "version": "0.7.0",
+  "description": "AI browser + document + form library + MCP server — convert any web page or PDF into a compact AgentMark snapshot, then drive it from any MCP client (Claude Desktop, Cursor, Claude Code) or directly via the SDK.",
   "type": "commonjs",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
+  "bin": {
+    "agentmark-mcp": "./dist/src/mcp/cli.js"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -40,6 +43,7 @@
     "tslib": "2.6.2"
   },
   "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "pdf-lib": "^1.17.1",
     "pdfjs-dist": "^4.10.38",
     "playwright-core": ">=1.40.0",
@@ -57,9 +61,13 @@
     },
     "pdf-lib": {
       "optional": true
+    },
+    "@modelcontextprotocol/sdk": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@types/js-yaml": "4.0.9",
     "@types/node": "20.19.9",
     "pdf-lib": "^1.17.1",

src/mcp/cli.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+/**
+ * `agentmark-mcp` CLI — the bin entry referenced by package.json.
+ *
+ * Configure in any MCP client to expose the entire AgentMark library:
+ *
+ *   {
+ *     "mcpServers": {
+ *       "agentmark": {
+ *         "command": "npx",
+ *         "args": ["-y", "@thinkfleet/agentmark", "agentmark-mcp"]
+ *       }
+ *     }
+ *   }
+ *
+ * (Or just `npx -y @thinkfleet/agentmark` once the bin name resolves on $PATH.)
+ */
+
+import { startMcpServer } from './server'
+
+async function main(): Promise<void> {
+    await startMcpServer({
+        name: 'agentmark',
+        // Version is read from package.json at build time; for now hardcoded.
+        version: '0.7.0',
+    })
+    // Stay alive — the MCP transport keeps the event loop busy via stdio.
+}
+
+main().catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error('Failed to start AgentMark MCP server:', err)
+    process.exit(1)
+})