@simplysm/mcp-playwright 13.0.72 → 13.0.74

package/README.md

@@ -0,0 +1,135 @@
+# @simplysm/mcp-playwright
+
+Simplysm MCP server — multi-session Playwright proxy.
+
+Wraps [`@playwright/mcp`](https://github.com/microsoft/playwright-mcp) and adds **session isolation**: every Playwright tool call requires a `sessionId` argument that routes the request to a dedicated browser instance. Multiple sessions can exist concurrently without interfering with each other.
+
+## Installation
+
+```bash
+pnpm add -g @simplysm/mcp-playwright
+```
+
+Or run directly with npx/pnpm dlx:
+
+```bash
+pnpm dlx @simplysm/mcp-playwright
+```
+
+## MCP Configuration
+
+Add the server to your MCP client configuration (e.g., Claude Desktop's `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "pnpm",
+      "args": ["dlx", "@simplysm/mcp-playwright"]
+    }
+  }
+}
+```
+
+The server communicates over **stdio** using the Model Context Protocol.
+
+## How It Works
+
+- The server starts a single MCP process.
+- Each call to a Playwright tool must include a `sessionId` string.
+- On the first call with a given `sessionId`, the server launches a dedicated headless browser (isolated Playwright context).
+- Subsequent calls with the same `sessionId` reuse that browser context.
+- Sessions are automatically cleaned up after **5 minutes of inactivity**.
+- Output files (screenshots, traces, etc.) are written to `.tmp/playwright/`.
+
+## Session Management Tools
+
+### `session_list`
+
+Returns all currently active session IDs.
+
+**Input:** _(none)_
+
+**Output:** JSON array of session ID strings.
+
+```json
+// Example response content
+["session-a", "session-b"]
+```
+
+### `session_close`
+
+Closes a specific browser session and releases its resources.
+
+**Input:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `sessionId` | `string` | Yes | ID of the session to close |
+
+**Output:** Confirmation text: `Session '<sessionId>' closed.`
+
+## Playwright Proxy Tools
+
+All tools from `@playwright/mcp` are forwarded by this server. Each forwarded tool has a `sessionId` field **prepended** to its original input schema.
+
+**Every proxied tool requires:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `sessionId` | `string` | Yes | Session ID for browser isolation |
+| _(original fields)_ | — | — | Same as the original `@playwright/mcp` tool |
+
+If an error occurs during a proxied tool call, the session is automatically destroyed to avoid leaving a browser in a broken state.
+
+## Server Internals
+
+### `SessionManager`
+
+Internal class that manages the lifecycle of per-session Playwright MCP clients.
+
+**Constructor**
+
+```ts
+new SessionManager(config: Record<string, unknown>, timeoutMs?: number)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `config` | `Record<string, unknown>` | — | Configuration passed to `@playwright/mcp`'s `createConnection` |
+| `timeoutMs` | `number` | `300000` (5 min) | Inactivity timeout before a session is auto-cleaned |
+
+**Methods**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getOrCreate` | `(sessionId: string) => Promise<Client>` | Returns an existing MCP client for the session, or creates a new one. Updates the last-used timestamp on each call. |
+| `destroy` | `(sessionId: string) => Promise<void>` | Closes and removes a single session. No-op if the session does not exist. |
+| `disposeAll` | `() => Promise<void>` | Closes all sessions and stops the cleanup interval. Called on `SIGINT`/`SIGTERM`. |
+| `list` | `() => string[]` | Returns an array of all currently active session IDs. |
+
+### `injectSessionId`
+
+Internal utility that adds the `sessionId` field to a Playwright tool's input schema before the tool is registered on the proxy server.
+
+```ts
+function injectSessionId(tool: Tool): Tool
+```
+
+- Prepends `sessionId` to `inputSchema.properties`.
+- Ensures `sessionId` appears first in the `required` array.
+- Deduplicates `sessionId` if it is already present in `required`.
+- Returns a new tool object; the original is not mutated.
+
+### `registerProxiedTools`
+
+Internal function that wires up all Playwright tools and the two session management tools (`session_list`, `session_close`) to an MCP `Server` instance.
+
+```ts
+async function registerProxiedTools(
+  server: Server,
+  sessionManager: SessionManager,
+): Promise<void>
+```
+
+At startup it creates a temporary bootstrap session to discover the tool list from `@playwright/mcp`, then destroys it before serving real requests.

package/dist/index.js

@@ -1,26 +1,29 @@
 #!/usr/bin/env node
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {} from "@playwright/mcp";
+import { createRequire } from "node:module";
 import { SessionManager } from "./session-manager.js";
 import { registerProxiedTools } from "./tool-proxy.js";
+const _require = createRequire(import.meta.url);
+const { version } = _require("../package.json");
 const config = {
   browser: { isolated: true, launchOptions: { headless: true } },
   outputDir: ".tmp/playwright"
 };
 const server = new Server(
-  { name: "mcp-playwright", version: "1.0.0" },
+  { name: "mcp-playwright", version },
   {
     capabilities: { tools: {} },
     instructions: "Multi-session Playwright MCP server. Each tool requires a 'sessionId' for browser isolation.\nOutput directory: .tmp/playwright"
   }
 );
-const sessionManager = new SessionManager(config);
+const sessionManager = new SessionManager(config, void 0, version);
 await registerProxiedTools(server, sessionManager);
 const transport = new StdioServerTransport();
 await server.connect(transport);
 async function shutdown() {
   await sessionManager.disposeAll();
+  await server.close();
   process.exit(0);
 }
 process.on("SIGINT", () => void shutdown());

package/dist/index.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../src/index.ts"],
-  "mappings": ";AAEA,SAAS,cAAc;AACvB,SAAS,4BAA4B;AACrC,eAAsC;AACtC,SAAS,sBAAsB;AAC/B,SAAS,4BAA4B;AAErC,MAAM,SAA8D;AAAA,EAClE,SAAS,EAAE,UAAU,MAAM,eAAe,EAAE,UAAU,KAAK,EAAE;AAAA,EAC7D,WAAW;AACb;AAEA,MAAM,SAAS,IAAI;AAAA,EACjB,EAAE,MAAM,kBAAkB,SAAS,QAAQ;AAAA,EAC3C;AAAA,IACE,cAAc,EAAE,OAAO,CAAC,EAAE;AAAA,IAC1B,cAAc;AAAA,EAChB;AACF;AAEA,MAAM,iBAAiB,IAAI,eAAe,MAAM;AAEhD,MAAM,qBAAqB,QAAQ,cAAc;AAEjD,MAAM,YAAY,IAAI,qBAAqB;AAC3C,MAAM,OAAO,QAAQ,SAAS;AAE9B,eAAe,WAA0B;AACvC,QAAM,eAAe,WAAW;AAChC,UAAQ,KAAK,CAAC;AAChB;AAEA,QAAQ,GAAG,UAAU,MAAM,KAAK,SAAS,CAAC;AAC1C,QAAQ,GAAG,WAAW,MAAM,KAAK,SAAS,CAAC;",
+  "mappings": ";AAEA,SAAS,cAAc;AACvB,SAAS,4BAA4B;AAErC,SAAS,qBAAqB;AAC9B,SAAS,sBAAsB;AAC/B,SAAS,4BAA4B;AAErC,MAAM,WAAW,cAAc,YAAY,GAAG;AAC9C,MAAM,EAAE,QAAQ,IAAI,SAAS,iBAAiB;AAE9C,MAAM,SAA8D;AAAA,EAClE,SAAS,EAAE,UAAU,MAAM,eAAe,EAAE,UAAU,KAAK,EAAE;AAAA,EAC7D,WAAW;AACb;AAEA,MAAM,SAAS,IAAI;AAAA,EACjB,EAAE,MAAM,kBAAkB,QAAQ;AAAA,EAClC;AAAA,IACE,cAAc,EAAE,OAAO,CAAC,EAAE;AAAA,IAC1B,cAAc;AAAA,EAChB;AACF;AAEA,MAAM,iBAAiB,IAAI,eAAe,QAAQ,QAAW,OAAO;AAEpE,MAAM,qBAAqB,QAAQ,cAAc;AAEjD,MAAM,YAAY,IAAI,qBAAqB;AAC3C,MAAM,OAAO,QAAQ,SAAS;AAE9B,eAAe,WAA0B;AACvC,QAAM,eAAe,WAAW;AAChC,QAAM,OAAO,MAAM;AACnB,UAAQ,KAAK,CAAC;AAChB;AAEA,QAAQ,GAAG,UAAU,MAAM,KAAK,SAAS,CAAC;AAC1C,QAAQ,GAAG,WAAW,MAAM,KAAK,SAAS,CAAC;",
   "names": []
 }

package/dist/session-manager.d.ts

@@ -1,11 +1,14 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { createConnection as CreateConnectionFn } from "@playwright/mcp";
 export declare class SessionManager {
     private readonly config;
     private readonly timeoutMs;
+    private readonly version;
     private readonly _sessions;
     private readonly _pending;
     private readonly _cleanupInterval;
-    constructor(config: Record<string, unknown>, timeoutMs?: number);
+    private _cleanupRunning;
+    constructor(config: NonNullable<Parameters<typeof CreateConnectionFn>[0]>, timeoutMs?: number, version?: string);
     getOrCreate(sessionId: string): Promise<Client>;
     destroy(sessionId: string): Promise<void>;
     disposeAll(): Promise<void>;

package/dist/session-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAQnE,qBAAa,cAAc;IAMvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAN5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;IAChE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAiC;gBAG/C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,SAAgB;IAOtC,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmB/C,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQzC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC,IAAI,IAAI,MAAM,EAAE;YAIF,cAAc;YASd,QAAQ;CAQvB"}
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGnE,OAAO,KAAK,EAAE,gBAAgB,IAAI,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAY9E,qBAAa,cAAc;IAOvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAR1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;IAChE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAiC;IAClE,OAAO,CAAC,eAAe,CAAS;gBAGb,MAAM,EAAE,WAAW,CAAC,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,EAC7D,SAAS,SAAgB,EACzB,OAAO,SAAU;IAO9B,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmB/C,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASzC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC,IAAI,IAAI,MAAM,EAAE;YAIF,cAAc;YAcd,QAAQ;CAevB"}

package/dist/session-manager.js

@@ -1,10 +1,14 @@
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { createConnection } from "@playwright/mcp";
+import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
+import { createRequire } from "node:module";
+const _require = createRequire(import.meta.url);
+const { createConnection } = _require("@playwright/mcp");
 class SessionManager {
-  constructor(config, timeoutMs = 5 * 60 * 1e3) {
+  constructor(config, timeoutMs = 5 * 60 * 1e3, version = "0.0.0") {
     this.config = config;
     this.timeoutMs = timeoutMs;
+    this.version = version;
     this._cleanupInterval = setInterval(() => {
       void this._cleanup();
     }, 3e4);
@@ -12,6 +16,7 @@ class SessionManager {
   _sessions = /* @__PURE__ */ new Map();
   _pending = /* @__PURE__ */ new Map();
   _cleanupInterval;
+  _cleanupRunning = false;
   async getOrCreate(sessionId) {
     let session = this._sessions.get(sessionId);
     if (session == null) {
@@ -35,6 +40,7 @@ class SessionManager {
     if (session != null) {
       this._sessions.delete(sessionId);
       await session.client.close();
+      await session.innerServer.close();
     }
   }
   async disposeAll() {
@@ -49,16 +55,26 @@ class SessionManager {
     const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
     const innerServer = await createConnection(this.config);
     await innerServer.connect(serverTransport);
-    const client = new Client({ name: "mcp-playwright-proxy", version: "1.0.0" });
-    await client.connect(clientTransport);
-    return { client, lastUsed: Date.now() };
+    const client = new Client({ name: "mcp-playwright-proxy", version: this.version });
+    try {
+      await client.connect(clientTransport);
+    } catch (err) {
+      await innerServer.close();
+      throw err;
+    }
+    return { client, innerServer, lastUsed: Date.now() };
   }
   async _cleanup() {
-    const now = Date.now();
-    for (const [id, session] of this._sessions) {
-      if (now - session.lastUsed > this.timeoutMs) {
+    if (this._cleanupRunning) return;
+    this._cleanupRunning = true;
+    try {
+      const now = Date.now();
+      const expired = [...this._sessions.entries()].filter(([, s]) => now - s.lastUsed > this.timeoutMs).map(([id]) => id);
+      for (const id of expired) {
         await this.destroy(id);
       }
+    } finally {
+      this._cleanupRunning = false;
     }
   }
 }

package/dist/session-manager.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../src/session-manager.ts"],
-  "mappings": "AAAA,SAAS,yBAAyB;AAClC,SAAS,cAAc;AACvB,SAAS,wBAAwB;AAO1B,MAAM,eAAe;AAAA,EAK1B,YACmB,QACA,YAAY,IAAI,KAAK,KACtC;AAFiB;AACA;AAEjB,SAAK,mBAAmB,YAAY,MAAM;AACxC,WAAK,KAAK,SAAS;AAAA,IACrB,GAAG,GAAM;AAAA,EACX;AAAA,EAXiB,YAAY,oBAAI,IAAqB;AAAA,EACrC,WAAW,oBAAI,IAA8B;AAAA,EAC7C;AAAA,EAWjB,MAAM,YAAY,WAAoC;AACpD,QAAI,UAAU,KAAK,UAAU,IAAI,SAAS;AAC1C,QAAI,WAAW,MAAM;AACnB,UAAI,UAAU,KAAK,SAAS,IAAI,SAAS;AACzC,UAAI,WAAW,MAAM;AACnB,kBAAU,KAAK,eAAe,EAAE,KAAK,CAAC,MAAM;AAC1C,eAAK,UAAU,IAAI,WAAW,CAAC;AAC/B,iBAAO;AAAA,QACT,CAAC,EAAE,QAAQ,MAAM;AACf,eAAK,SAAS,OAAO,SAAS;AAAA,QAChC,CAAC;AACD,aAAK,SAAS,IAAI,WAAW,OAAO;AAAA,MACtC;AACA,gBAAU,MAAM;AAAA,IAClB;AACA,YAAQ,WAAW,KAAK,IAAI;AAC5B,WAAO,QAAQ;AAAA,EACjB;AAAA,EAEA,MAAM,QAAQ,WAAkC;AAC9C,UAAM,UAAU,KAAK,UAAU,IAAI,SAAS;AAC5C,QAAI,WAAW,MAAM;AACnB,WAAK,UAAU,OAAO,SAAS;AAC/B,YAAM,QAAQ,OAAO,MAAM;AAAA,IAC7B;AAAA,EACF;AAAA,EAEA,MAAM,aAA4B;AAChC,kBAAc,KAAK,gBAAgB;AACnC,UAAM,MAAM,CAAC,GAAG,KAAK,UAAU,KAAK,CAAC;AACrC,UAAM,QAAQ,IAAI,IAAI,IAAI,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC,CAAC;AAAA,EACrD;AAAA,EAEA,OAAiB;AACf,WAAO,CAAC,GAAG,KAAK,UAAU,KAAK,CAAC;AAAA,EAClC;AAAA,EAEA,MAAc,iBAAmC;AAC/C,UAAM,CAAC,iBAAiB,eAAe,IAAI,kBAAkB,iBAAiB;AAC9E,UAAM,cAAc,MAAM,iBAAiB,KAAK,MAAe;AAC/D,UAAM,YAAY,QAAQ,eAAe;AACzC,UAAM,SAAS,IAAI,OAAO,EAAE,MAAM,wBAAwB,SAAS,QAAQ,CAAC;AAC5E,UAAM,OAAO,QAAQ,eAAe;AACpC,WAAO,EAAE,QAAQ,UAAU,KAAK,IAAI,EAAE;AAAA,EACxC;AAAA,EAEA,MAAc,WAA0B;AACtC,UAAM,MAAM,KAAK,IAAI;AACrB,eAAW,CAAC,IAAI,OAAO,KAAK,KAAK,WAAW;AAC1C,UAAI,MAAM,QAAQ,WAAW,KAAK,WAAW;AAC3C,cAAM,KAAK,QAAQ,EAAE;AAAA,MACvB;AAAA,IACF;AAAA,EACF;AACF;",
+  "mappings": "AAAA,SAAS,yBAAyB;AAClC,SAAS,cAAc;AACvB,SAAS,UAAU,iBAAiB;AACpC,SAAS,qBAAqB;AAI9B,MAAM,WAAW,cAAc,YAAY,GAAG;AAC9C,MAAM,EAAE,iBAAiB,IAAI,SAAS,iBAAiB;AAQhD,MAAM,eAAe;AAAA,EAM1B,YACmB,QACA,YAAY,IAAI,KAAK,KACrB,UAAU,SAC3B;AAHiB;AACA;AACA;AAEjB,SAAK,mBAAmB,YAAY,MAAM;AACxC,WAAK,KAAK,SAAS;AAAA,IACrB,GAAG,GAAM;AAAA,EACX;AAAA,EAbiB,YAAY,oBAAI,IAAqB;AAAA,EACrC,WAAW,oBAAI,IAA8B;AAAA,EAC7C;AAAA,EACT,kBAAkB;AAAA,EAY1B,MAAM,YAAY,WAAoC;AACpD,QAAI,UAAU,KAAK,UAAU,IAAI,SAAS;AAC1C,QAAI,WAAW,MAAM;AACnB,UAAI,UAAU,KAAK,SAAS,IAAI,SAAS;AACzC,UAAI,WAAW,MAAM;AACnB,kBAAU,KAAK,eAAe,EAAE,KAAK,CAAC,MAAM;AAC1C,eAAK,UAAU,IAAI,WAAW,CAAC;AAC/B,iBAAO;AAAA,QACT,CAAC,EAAE,QAAQ,MAAM;AACf,eAAK,SAAS,OAAO,SAAS;AAAA,QAChC,CAAC;AACD,aAAK,SAAS,IAAI,WAAW,OAAO;AAAA,MACtC;AACA,gBAAU,MAAM;AAAA,IAClB;AACA,YAAQ,WAAW,KAAK,IAAI;AAC5B,WAAO,QAAQ;AAAA,EACjB;AAAA,EAEA,MAAM,QAAQ,WAAkC;AAC9C,UAAM,UAAU,KAAK,UAAU,IAAI,SAAS;AAC5C,QAAI,WAAW,MAAM;AACnB,WAAK,UAAU,OAAO,SAAS;AAC/B,YAAM,QAAQ,OAAO,MAAM;AAC3B,YAAM,QAAQ,YAAY,MAAM;AAAA,IAClC;AAAA,EACF;AAAA,EAEA,MAAM,aAA4B;AAChC,kBAAc,KAAK,gBAAgB;AACnC,UAAM,MAAM,CAAC,GAAG,KAAK,UAAU,KAAK,CAAC;AACrC,UAAM,QAAQ,IAAI,IAAI,IAAI,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC,CAAC;AAAA,EACrD;AAAA,EAEA,OAAiB;AACf,WAAO,CAAC,GAAG,KAAK,UAAU,KAAK,CAAC;AAAA,EAClC;AAAA,EAEA,MAAc,iBAAmC;AAC/C,UAAM,CAAC,iBAAiB,eAAe,IAAI,kBAAkB,iBAAiB;AAC9E,UAAM,cAAc,MAAM,iBAAiB,KAAK,MAAM;AACtD,UAAM,YAAY,QAAQ,eAAe;AACzC,UAAM,SAAS,IAAI,OAAO,EAAE,MAAM,wBAAwB,SAAS,KAAK,QAAQ,CAAC;AACjF,QAAI;AACF,YAAM,OAAO,QAAQ,eAAe;AAAA,IACtC,SAAS,KAAK;AACZ,YAAM,YAAY,MAAM;AACxB,YAAM;AAAA,IACR;AACA,WAAO,EAAE,QAAQ,aAAa,UAAU,KAAK,IAAI,EAAE;AAAA,EACrD;AAAA,EAEA,MAAc,WAA0B;AACtC,QAAI,KAAK,gBAAiB;AAC1B,SAAK,kBAAkB;AACvB,QAAI;AACF,YAAM,MAAM,KAAK,IAAI;AACrB,YAAM,UAAU,CAAC,GAAG,KAAK,UAAU,QAAQ,CAAC,EACzC,OAAO,CAAC,CAAC,EAAE,CAAC,MAAM,MAAM,EAAE,WAAW,KAAK,SAAS,EACnD,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE;AACnB,iBAAW,MAAM,SAAS;AACxB,cAAM,KAAK,QAAQ,EAAE;AAAA,MACvB;AAAA,IACF,UAAE;AACA,WAAK,kBAAkB;AAAA,IACzB;AAAA,EACF;AACF;",
   "names": []
 }

package/dist/tool-proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-proxy.d.ts","sourceRoot":"","sources":["../src/tool-proxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAGL,KAAK,IAAI,EACV,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAahD;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,IAAI,CAAC,CAiEf"}
+{"version":3,"file":"tool-proxy.d.ts","sourceRoot":"","sources":["../src/tool-proxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAGL,KAAK,IAAI,EACV,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI3D,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAahD;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,IAAI,CAAC,CAoFf"}

package/dist/tool-proxy.js

@@ -4,6 +4,7 @@ import {
   CallToolRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import {} from "./session-manager.js";
+const BOOTSTRAP_SESSION_ID = "__bootstrap__";
 function injectSessionId(tool) {
   const existing = tool.inputSchema.required;
   return {
@@ -11,20 +12,20 @@ function injectSessionId(tool) {
     inputSchema: {
       ...tool.inputSchema,
       properties: {
-        sessionId: { type: "string", description: "Session ID for browser isolation" },
-        ...tool.inputSchema.properties ?? {}
+        ...tool.inputSchema.properties ?? {},
+        sessionId: { type: "string", description: "Session ID for browser isolation" }
       },
       required: ["sessionId", ...existing?.filter((r) => r !== "sessionId") ?? []]
     }
   };
 }
 async function registerProxiedTools(server, sessionManager) {
-  const bootstrapClient = await sessionManager.getOrCreate("__bootstrap__");
+  const bootstrapClient = await sessionManager.getOrCreate(BOOTSTRAP_SESSION_ID);
   let playwrightTools;
   try {
     ({ tools: playwrightTools } = await bootstrapClient.listTools());
   } finally {
-    await sessionManager.destroy("__bootstrap__");
+    await sessionManager.destroy(BOOTSTRAP_SESSION_ID);
   }
   const proxiedTools = playwrightTools.map(injectSessionId);
   const allTools = [
@@ -53,7 +54,10 @@ async function registerProxiedTools(server, sessionManager) {
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args = {} } = request.params;
     if (name === "session_close") {
-      const { sessionId: sessionId2 } = args;
+      const sessionId2 = args["sessionId"];
+      if (typeof sessionId2 !== "string" || sessionId2 === "") {
+        throw new Error("Missing required argument: sessionId");
+      }
       await sessionManager.destroy(sessionId2);
       return { content: [{ type: "text", text: `Session '${sessionId2}' closed.` }] };
     }
@@ -72,8 +76,24 @@ async function registerProxiedTools(server, sessionManager) {
     try {
       return await client.callTool({ name, arguments: toolArgs });
     } catch (err) {
-      await sessionManager.destroy(sessionId);
-      throw err;
+      const message = err instanceof Error ? err.message : String(err);
+      try {
+        await client.listTools();
+      } catch {
+        await sessionManager.destroy(sessionId);
+        return {
+          content: [{ type: "text", text: `### Error
+${message}
+
+Session '${sessionId}' was destroyed due to a broken connection.` }],
+          isError: true
+        };
+      }
+      return {
+        content: [{ type: "text", text: `### Error
+${message}` }],
+        isError: true
+      };
     }
   });
 }

package/dist/tool-proxy.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../src/tool-proxy.ts"],
-  "mappings": "AAAA,SAAS,cAAc;AACvB;AAAA,EACE;AAAA,EACA;AAAA,OAEK;AACP,eAAoC;AAE7B,SAAS,gBAAgB,MAAkB;AAChD,QAAM,WAAW,KAAK,YAAY;AAClC,SAAO;AAAA,IACL,GAAG;AAAA,IACH,aAAa;AAAA,MACX,GAAG,KAAK;AAAA,MACR,YAAY;AAAA,QACV,WAAW,EAAE,MAAM,UAAU,aAAa,mCAAmC;AAAA,QAC7E,GAAI,KAAK,YAAY,cAAc,CAAC;AAAA,MACtC;AAAA,MACA,UAAU,CAAC,aAAa,GAAI,UAAU,OAAO,CAAC,MAAM,MAAM,WAAW,KAAK,CAAC,CAAE;AAAA,IAC/E;AAAA,EACF;AACF;AAEA,eAAsB,qBACpB,QACA,gBACe;AAEf,QAAM,kBAAkB,MAAM,eAAe,YAAY,eAAe;AACxE,MAAI;AACJ,MAAI;AACF,KAAC,EAAE,OAAO,gBAAgB,IAAI,MAAM,gBAAgB,UAAU;AAAA,EAChE,UAAE;AACA,UAAM,eAAe,QAAQ,eAAe;AAAA,EAC9C;AAEA,QAAM,eAAe,gBAAgB,IAAI,eAAe;AACxD,QAAM,WAAmB;AAAA,IACvB,GAAG;AAAA,IACH;AAAA,MACE,MAAM;AAAA,MACN,aAAa;AAAA,MACb,aAAa;AAAA,QACX,MAAM;AAAA,QACN,YAAY;AAAA,UACV,WAAW,EAAE,MAAM,UAAU,aAAa,sBAAsB;AAAA,QAClE;AAAA,QACA,UAAU,CAAC,WAAW;AAAA,MACxB;AAAA,IACF;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,aAAa;AAAA,MACb,aAAa;AAAA,QACX,MAAM;AAAA,QACN,YAAY,CAAC;AAAA,MACf;AAAA,IACF;AAAA,EACF;AAEA,SAAO,kBAAkB,wBAAwB,OAAO,EAAE,OAAO,SAAS,EAAE;AAE5E,SAAO,kBAAkB,uBAAuB,OAAO,YAAY;AACjE,UAAM,EAAE,MAAM,WAAW,OAAO,CAAC,EAAE,IAAI,QAAQ;AAE/C,QAAI,SAAS,iBAAiB;AAC5B,YAAM,EAAE,WAAAA,WAAU,IAAI;AACtB,YAAM,eAAe,QAAQA,UAAS;AACtC,aAAO,EAAE,SAAS,CAAC,EAAE,MAAM,QAAiB,MAAM,YAAYA,UAAS,YAAY,CAAC,EAAE;AAAA,IACxF;AAEA,QAAI,SAAS,gBAAgB;AAC3B,YAAM,WAAW,eAAe,KAAK;AACrC,aAAO;AAAA,QACL,SAAS,CAAC,EAAE,MAAM,QAAiB,MAAM,KAAK,UAAU,UAAU,MAAM,CAAC,EAAE,CAAC;AAAA,MAC9E;AAAA,IACF;AAEA,UAAM,YAAY,KAAK,WAAW;AAClC,QAAI,OAAO,cAAc,YAAY,cAAc,IAAI;AACrD,YAAM,IAAI,MAAM,sCAAsC;AAAA,IACxD;AACA,UAAM,EAAE,WAAW,GAAG,GAAG,SAAS,IAAI;AACtC,UAAM,SAAS,MAAM,eAAe,YAAY,SAAS;AACzD,QAAI;AACF,aAAO,MAAM,OAAO,SAAS,EAAE,MAAM,WAAW,SAAS,CAAC;AAAA,IAC5D,SAAS,KAAK;AACZ,YAAM,eAAe,QAAQ,SAAS;AACtC,YAAM;AAAA,IACR;AAAA,EACF,CAAC;AACH;",
+  "mappings": "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",
   "names": ["sessionId"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/mcp-playwright",
-  "version": "13.0.72",
+  "version": "13.0.74",
   "description": "Simplysm MCP server — multi-session Playwright proxy",
   "author": "simplysm",
   "license": "Apache-2.0",

package/src/index.ts

@@ -2,24 +2,28 @@
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { type createConnection } from "@playwright/mcp";
+import type { createConnection } from "@playwright/mcp";
+import { createRequire } from "node:module";
 import { SessionManager } from "./session-manager.js";
 import { registerProxiedTools } from "./tool-proxy.js";
 
+const _require = createRequire(import.meta.url);
+const { version } = _require("../package.json") as { version: string };
+
 const config: NonNullable<Parameters<typeof createConnection>[0]> = {
   browser: { isolated: true, launchOptions: { headless: true } },
   outputDir: ".tmp/playwright",
 };
 
 const server = new Server(
-  { name: "mcp-playwright", version: "1.0.0" },
+  { name: "mcp-playwright", version },
   {
     capabilities: { tools: {} },
     instructions: "Multi-session Playwright MCP server. Each tool requires a 'sessionId' for browser isolation.\nOutput directory: .tmp/playwright",
   },
 );
 
-const sessionManager = new SessionManager(config);
+const sessionManager = new SessionManager(config, undefined, version);
 
 await registerProxiedTools(server, sessionManager);
 
@@ -28,6 +32,7 @@ await server.connect(transport);
 
 async function shutdown(): Promise<void> {
   await sessionManager.disposeAll();
+  await server.close();
   process.exit(0);
 }
 

package/src/session-manager.ts

@@ -1,9 +1,16 @@
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { createConnection } from "@playwright/mcp";
+import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
+import { createRequire } from "node:module";
+import type { createConnection as CreateConnectionFn } from "@playwright/mcp";
+
+// @playwright/mcp ships CJS only — use createRequire for ESM compatibility
+const _require = createRequire(import.meta.url);
+const { createConnection } = _require("@playwright/mcp") as { createConnection: typeof CreateConnectionFn };
 
 interface Session {
   client: Client;
+  innerServer: McpServer;
   lastUsed: number;
 }
 
@@ -11,10 +18,12 @@ export class SessionManager {
   private readonly _sessions = new Map<string, Session>();
   private readonly _pending = new Map<string, Promise<Session>>();
   private readonly _cleanupInterval: ReturnType<typeof setInterval>;
+  private _cleanupRunning = false;
 
   constructor(
-    private readonly config: Record<string, unknown>,
+    private readonly config: NonNullable<Parameters<typeof CreateConnectionFn>[0]>,
     private readonly timeoutMs = 5 * 60 * 1000,
+    private readonly version = "0.0.0",
   ) {
     this._cleanupInterval = setInterval(() => {
       void this._cleanup();
@@ -45,6 +54,7 @@ export class SessionManager {
     if (session != null) {
       this._sessions.delete(sessionId);
       await session.client.close();
+      await session.innerServer.close();
     }
   }
 
@@ -60,19 +70,31 @@ export class SessionManager {
 
   private async _createSession(): Promise<Session> {
     const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
-    const innerServer = await createConnection(this.config as never);
+    const innerServer = await createConnection(this.config);
     await innerServer.connect(serverTransport);
-    const client = new Client({ name: "mcp-playwright-proxy", version: "1.0.0" });
-    await client.connect(clientTransport);
-    return { client, lastUsed: Date.now() };
+    const client = new Client({ name: "mcp-playwright-proxy", version: this.version });
+    try {
+      await client.connect(clientTransport);
+    } catch (err) {
+      await innerServer.close();
+      throw err;
+    }
+    return { client, innerServer, lastUsed: Date.now() };
   }
 
   private async _cleanup(): Promise<void> {
-    const now = Date.now();
-    for (const [id, session] of this._sessions) {
-      if (now - session.lastUsed > this.timeoutMs) {
+    if (this._cleanupRunning) return;
+    this._cleanupRunning = true;
+    try {
+      const now = Date.now();
+      const expired = [...this._sessions.entries()]
+        .filter(([, s]) => now - s.lastUsed > this.timeoutMs)
+        .map(([id]) => id);
+      for (const id of expired) {
         await this.destroy(id);
       }
+    } finally {
+      this._cleanupRunning = false;
     }
   }
 }

package/src/tool-proxy.ts

@@ -6,6 +6,8 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import { type SessionManager } from "./session-manager.js";
 
+const BOOTSTRAP_SESSION_ID = "__bootstrap__";
+
 export function injectSessionId(tool: Tool): Tool {
   const existing = tool.inputSchema.required as string[] | undefined;
   return {
@@ -13,8 +15,8 @@ export function injectSessionId(tool: Tool): Tool {
     inputSchema: {
       ...tool.inputSchema,
       properties: {
-        sessionId: { type: "string", description: "Session ID for browser isolation" },
         ...(tool.inputSchema.properties ?? {}),
+        sessionId: { type: "string", description: "Session ID for browser isolation" },
       },
       required: ["sessionId", ...(existing?.filter((r) => r !== "sessionId") ?? [])],
     },
@@ -26,12 +28,12 @@ export async function registerProxiedTools(
   sessionManager: SessionManager,
 ): Promise<void> {
   // Bootstrap: get tool list from @playwright/mcp (no browser launched)
-  const bootstrapClient = await sessionManager.getOrCreate("__bootstrap__");
+  const bootstrapClient = await sessionManager.getOrCreate(BOOTSTRAP_SESSION_ID);
   let playwrightTools: Tool[];
   try {
     ({ tools: playwrightTools } = await bootstrapClient.listTools());
   } finally {
-    await sessionManager.destroy("__bootstrap__");
+    await sessionManager.destroy(BOOTSTRAP_SESSION_ID);
   }
 
   const proxiedTools = playwrightTools.map(injectSessionId);
@@ -64,7 +66,10 @@ export async function registerProxiedTools(
     const { name, arguments: args = {} } = request.params;
 
     if (name === "session_close") {
-      const { sessionId } = args as { sessionId: string };
+      const sessionId = args["sessionId"];
+      if (typeof sessionId !== "string" || sessionId === "") {
+        throw new Error("Missing required argument: sessionId");
+      }
       await sessionManager.destroy(sessionId);
       return { content: [{ type: "text" as const, text: `Session '${sessionId}' closed.` }] };
     }
@@ -85,8 +90,24 @@ export async function registerProxiedTools(
     try {
       return await client.callTool({ name, arguments: toolArgs });
     } catch (err) {
-      await sessionManager.destroy(sessionId);
-      throw err;
+      const message = err instanceof Error ? err.message : String(err);
+
+      // Check if the underlying connection is still alive
+      try {
+        await client.listTools();
+      } catch {
+        // Connection is broken — destroy the session
+        await sessionManager.destroy(sessionId);
+        return {
+          content: [{ type: "text" as const, text: `### Error\n${message}\n\nSession '${sessionId}' was destroyed due to a broken connection.` }],
+          isError: true,
+        };
+      }
+
+      return {
+        content: [{ type: "text" as const, text: `### Error\n${message}` }],
+        isError: true,
+      };
     }
   });
 }