pursr 0.8.0 → 0.8.1

package/README.md

@@ -33,7 +33,7 @@
 Most teams need **five separate tools** to do visual QA: a screenshot CLI, a regression diff runner, an accessibility auditor, a way to share captures with an AI assistant, and a way to **turn all of that into a PDF report** for stakeholders. **pursr is all five** - built as a single Node.js package with:
 
 - **A unified CLI** (`pursr`) for every capture, diff, sweep, and audit.
-- **An agent-grade MCP stdio server** (`pursr-mcp`) with persistent tabs, direct image responses, rendered-state inspection, actions, diagnostics, screenshots, sweeps, and resources.
+- **An agent-grade MCP stdio server** (`pursr-mcp`) built on the official Model Context Protocol SDK, with persistent tabs, direct image responses, rendered-state inspection, actions, diagnostics, screenshots, sweeps, and resources.
 - **A library API** with 23 subpath modules, so you can embed the browser and QA primitives in your own tooling.
 - **A plugin system** for custom viewports, sweep ops, and capture hooks.
 - **PDF reports + AI diff summaries** built in - render a sweep to a styled PDF or ask a vision LLM to describe the regression in plain language.
@@ -96,7 +96,7 @@ pursr sweep ./plan.json   # see plans/ for an example
 | HAR capture | HAR 1.2 spec, written next to your shot | `--har ./req.har.json` |
 | Auth state | Playwright storageState, reuse logged-in sessions | `--auth-state admin` |
 | Plugins | custom viewports, sweep ops, before/after hooks | `pursr-plugin-*` |
-| MCP server | 16 tools + resources/list & resources/read for Claude/Cursor | `npx pursr-mcp` |
+| MCP server | Official MCP SDK transport, 16 tools, and resources for Claude/Cursor/Codex | `npx pursr-mcp` |
 | PDF report | render sweep.json to a styled, embedded-PNG A4 PDF | `pursr report --sweep ./sweep.json` |
 | AI diff summary | vision LLM describes the diff in plain language | `pursr diff ... --ai` |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pursr",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "private": false,
   "description": "pursr — Visual QA, audit, and MCP for the browser. One CLI + one MCP server for screenshots, sweeps, baselines, diffs, axe-core a11y audits, HAR capture, and auth state — with parallel sweep workers, auto-healing selectors, and a plugin system. Zero browser bundled: drives your system Chrome via Playwright.",
   "homepage": "https://github.com/0xheycat/pursr",
@@ -12,8 +12,8 @@
   "funding": "https://github.com/sponsors/0xheycat",
   "type": "module",
   "bin": {
-    "pursr": "./bin/pursr.mjs",
-    "pursr-mcp": "./bin/pursr-mcp.mjs"
+    "pursr": "bin/pursr.mjs",
+    "pursr-mcp": "bin/pursr-mcp.mjs"
   },
   "main": "./src/index.js",
   "exports": {
@@ -77,10 +77,12 @@
   ],
   "license": "MIT",
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "axe-core": "^4.12.1",
     "pdfkit": "^0.19.1",
     "pixelmatch": "^5.3.0",
-    "pngjs": "^7.0.0"
+    "pngjs": "^7.0.0",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "playwright-core": "*"

package/src/mcp.js

@@ -1,8 +1,7 @@
 //  pursr — MCP stdio server (Model Context Protocol).
 //
-// Implements JSON-RPC 2.0 over stdio with Content-Length framing.
-// Exposes every pursr capability as an MCP tool for use by
-// Claude Code, Cursor, Continue, and any other MCP host.
+// Uses the official Model Context Protocol SDK over stdio and exposes every
+// pursr capability to Claude Code, Cursor, Codex, and other MCP hosts.
 //
 // Config via PURSR_MCP_CONFIG env or ~/./mcp-config.json:
 //   { "plugins": ["./my-plugin.js"], "defaultOutDir": "./mcp-output" }
@@ -25,12 +24,20 @@ import { makeOut, nowIso } from "./util.js";
 import { listResources, readResource, recordResource } from "./mcp-resources.js";
 import { createRequire } from "node:module";
 import { BrowserSessionManager } from "./session.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
 
 const __require = createRequire(import.meta.url);
 let _pkg = { version: "0.1.0" };
 try { _pkg = __require("../package.json"); } catch {}
 
-const MCP_VERSION = "0.1.0";
+const MCP_VERSION = _pkg.version || "0.1.0";
 
 // ─── Config ──────────────────────────────────────────────────────────────
 
@@ -60,140 +67,68 @@ class McpError extends Error {
 
 // ─── Server ──────────────────────────────────────────────────────────────
 
-class PursrMCPServer {
+class PursrMCPServer {
   constructor(config = {}) {
-    this.config = config;
-    this._buffer = Buffer.alloc(0);
-    this._contentLength = -1;
-    this._initialized = false;
+    this.config = config;
     this._verbose = !!config.verbose;
     this.sessions = new BrowserSessionManager({ outputDir: config.defaultOutDir || process.cwd() });
-  }
+    this.sdk = new McpServer(
+      { name: "pursr", version: MCP_VERSION },
+      {
+        capabilities: { tools: {}, resources: {} },
+        instructions: "Use a persistent pursr session for iterative visual work: open, snapshot, act, screenshot, inspect, diagnose, then close.",
+      },
+    );
+    this.server = this.sdk.server;
+    this.transport = null;
+    this._registerSdkHandlers();
+  }
 
   log(...args) {
     if (this._verbose) console.error("[pursr-mcp]", ...args);
   }
 
-  async start() {
+  async start() {
     if (this.config.plugins?.length) {
       await loadPlugins(this.config.plugins);
     }
-    this.log("server started, plugins:", listPlugins());
-
-    process.stdin.on("data", (chunk) => {
-      this._buffer = Buffer.concat([this._buffer, chunk]);
-      this._processBuffer();
-    });
-    process.stdin.on("end", () => {
-      this.log("stdin closed");
+    this.transport = new StdioServerTransport();
+    this.transport.onclose = () => {
+      this.log("stdio transport closed");
       this.sessions.closeAll().catch(() => {});
+    };
+    await this.sdk.connect(this.transport);
+    this.log("server started with official MCP SDK, plugins:", listPlugins());
+  }
+
+  async close() {
+    await this.sessions.closeAll();
+    await this.sdk.close();
+  }
+
+  _registerSdkHandlers() {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: this._toolDefs() }));
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      try {
+        const content = await this._callTool(request.params.name, request.params.arguments || {});
+        return { content };
+      } catch (error) {
+        this.log("tool error:", error.stack || error.message);
+        return {
+          isError: true,
+          content: [{ type: "text", text: JSON.stringify({ error: error.message, code: error.code || -32603 }, null, 2) }],
+        };
+      }
     });
-
-    process.on("uncaughtException", (err) => {
-      console.error("[pursr-mcp] uncaught:", err.message);
-    });
-  }
-
-  // ── Buffer framing ──────────────────────────────────────────────────
-
-  _processBuffer() {
-    while (true) {
-      if (this._contentLength < 0) {
-        const idx = this._buffer.indexOf(Buffer.from("\r\n\r\n"));
-        if (idx === -1) break;
-        const header = this._buffer.slice(0, idx).toString("utf8");
-        const m = header.match(/Content-Length:\s*(\d+)/i);
-        if (m) this._contentLength = parseInt(m[1], 10);
-        this._buffer = this._buffer.slice(idx + 4);
-      }
-      if (this._contentLength > 0 && this._buffer.length >= this._contentLength) {
-        const raw = this._buffer.slice(0, this._contentLength).toString("utf8");
-        this._buffer = this._buffer.slice(this._contentLength);
-        this._contentLength = -1;
-        try {
-          const msg = JSON.parse(raw);
-          this._handleMessage(msg);
-        } catch (e) {
-          console.error("[pursr-mcp] invalid JSON:", e.message);
-        }
-      } else break;
-    }
-  }
-
-  _send(msg) {
-    const json = JSON.stringify(msg);
-    const bytes = Buffer.from(json, "utf8");
-    const header = `Content-Length: ${bytes.length}\r\n\r\n`;
-    process.stdout.write(header);
-    process.stdout.write(bytes);
-  }
-
-  // ── JSON-RPC dispatcher ─────────────────────────────────────────────
-
-  async _handleMessage(msg) {
-    if (!msg || msg.jsonrpc !== "2.0" || !msg.method) {
-      console.error("[pursr-mcp] skipping non-JSON-RPC message");
-      return;
-    }
-    const { method, id } = msg;
-
-    // Notifications — no id → no response
-    if (method === "notifications/initialized" || method === "notifications/cancelled") {
-      if (method === "notifications/initialized") this._initialized = true;
-      return;
-    }
-    if (id === undefined || id === null) return; // unnamed notification
-
-    try {
-      switch (method) {
-        case "initialize":
-          this._initialized = true;
-          this._send({
-            jsonrpc: "2.0", id,
-            result: {
-              protocolVersion: msg.params?.protocolVersion || "2024-11-05",
-              capabilities: { tools: {} },
-              serverInfo: { name: "pursr", version: MCP_VERSION },
-            },
-          });
-          break;
-
-        case "tools/list":
-          this._send({ jsonrpc: "2.0", id, result: { tools: this._toolDefs() } });
-          break;
-
-        case "resources/list":
-          this._send({ jsonrpc: "2.0", id, result: { resources: listResources().map(this._toMcpResource, this) } });
-          break;
-
-        case "resources/read":
-          if (!msg.params?.uri) throw new McpError(-32602, "Missing uri");
-          const data = readResource(msg.params.uri);
-          if (!data) throw new McpError(-32602, "Resource not found: " + msg.params.uri);
-          this._send({ jsonrpc: "2.0", id, result: { contents: [data] } });
-          break;
-
-        case "tools/call":
-          if (!msg.params?.name) throw new McpError(-32602, "Missing tool name");
-          const result = await this._callTool(msg.params.name, msg.params.arguments || {});
-          this._send({ jsonrpc: "2.0", id, result: { content: result } });
-          break;
-
-        default:
-          this._send({
-            jsonrpc: "2.0", id,
-            error: { code: -32601, message: `Unknown method: ${method}` },
-          });
-      }
-    } catch (e) {
-      if (e instanceof McpError) {
-        this._send({ jsonrpc: "2.0", id, error: { code: e.code, message: e.message } });
-      } else {
-        console.error("[pursr-mcp] handler error:", e.stack || e.message);
-        this._send({ jsonrpc: "2.0", id, error: { code: -32603, message: e.message } });
-      }
-    }
-  }
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+      resources: listResources().map(this._toMcpResource, this),
+    }));
+    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      const data = readResource(request.params.uri);
+      if (!data) throw new Error("Resource not found: " + request.params.uri);
+      return { contents: [data] };
+    });
+  }
 
   // ── Resource shape adapter ─────────────────────────────────────────