interceptpilot-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Alpin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# interceptpilot-mcp
+
+Local [MCP](https://modelcontextprotocol.io) server for the InterceptPilot Chrome extension. It lets AI agents (Claude Code, Codex, Cursor and any other MCP client) read the extension's sanitized test context, inspect captured requests, rules and logs, and propose or run actions such as enabling a mock, importing a collection or capturing a tab.
+
+Everything stays on your machine: the server talks to the extension over a local WebSocket on `127.0.0.1`, protected by a session key that the extension generates.
+
+## Setup
+
+1. Open the InterceptPilot Full App, go to **AI Bridge** and click **Start**.
+2. Click **Copy configuration**. You get something like:
+
+   ```json
+   {
+     "mcpServers": {
+       "interceptpilot": {
+         "command": "npx",
+         "args": ["-y", "interceptpilot-mcp", "--port", "37177", "--key", "<SESSION_KEY>"]
+       }
+     }
+   }
+   ```
+
+3. Add it to your MCP client and restart the client:
+   - **Claude Code**: `claude mcp add-json interceptpilot '<the "interceptpilot" object>'`, or paste it into `~/.claude.json`.
+   - **Cursor**: `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global).
+   - **Claude Desktop**: `claude_desktop_config.json`.
+   - **Codex**: `~/.codex/config.toml`, as `[mcp_servers.interceptpilot]` with the same `command` and `args`.
+4. Back in the extension, the AI Bridge status changes to **Connected**.
+
+The key is per session. Regenerating it in the extension invalidates the configuration you copied before. Never paste a real key into issues, logs or documentation.
+
+## How it works
+
+```txt
+AI client
+  -> MCP adapter (this package, stdio)
+  -> shared local daemon (one per port)
+  -> WebSocket connection from the extension
+  -> InterceptPilot
+```
+
+The MCP client starts the adapter. The adapter starts the local daemon when none is listening on the configured port; several adapters (several chats or clients) share one daemon and one key. If the extension disconnects, the daemon stays up and the tools return a safe error until the extension reconnects.
+
+## Options
+
+| Option | Meaning |
+| --- | --- |
+| `--key <KEY>` | Session key shown by the AI Bridge page. Required. |
+| `--port <PORT>` | Local daemon port. Default `37177`. |
+| `--no-daemon-autostart` | Do not start the daemon automatically (debugging). |
+| `daemon` | Run only the daemon: `npx -y interceptpilot-mcp daemon --port <PORT> --key <KEY>`. |
+
+## Tools
+
+What each tool exposes depends on the permissions you set in the extension. By default query-string values, headers, bodies, cookies, `Authorization` values and tab titles are never sent, and every action that changes state opens a proposal you confirm in the Full App. Session permissions let you skip the confirmation for specific groups of actions.
+
+### Reading
+
+| Tool | Use it to |
+| --- | --- |
+| `get_current_test_context` | See capture status and mode, the active tab origin and path, the active collection, rule counts and the AI Bridge status. |
+| `list_captured_requests` | List the requests captured in the active context. |
+| `search_captured_requests` | Search captured requests with safe filters and pagination. |
+| `list_collections` | List collections with rule counts. |
+| `get_active_collection` | Get the active collection. |
+| `list_rules` | List rules with sanitized match and action summaries. |
+| `search_rules` | Search rules by metadata, match, action and diagnostics. |
+| `list_sanitized_logs` | Read recent logs from the active context. |
+| `search_sanitized_logs` | Search logs with safe filters and pagination. |
+| `list_recent_rule_results` | See which rules matched recent requests and what was applied. |
+| `search_rule_results` | Search rule results with safe filters and pagination. |
+| `explain_rule_match` | Compare a rule with a captured request and learn why it matched or not. |
+| `get_import_bundle_schema` | Get the import bundle schema. Works without the extension connected. |
+| `get_import_bundle_examples` | Get safe example bundles. Works without the extension connected. |
+
+### Actions
+
+| Tool | Use it to | Skips confirmation when |
+| --- | --- | --- |
+| `import_bundle` | Propose a rule or collection bundle. | "Apply imports without confirmation" is on. |
+| `request_enable_rule`, `request_disable_rule`, `request_set_only_active_rule`, `request_set_active_collection` | Toggle rules or switch the active collection. | "Rule and collection actions without confirmation" is on. |
+| `request_update_rule`, `request_update_collection` | Edit safe fields of a rule or collection, with a before/after diff. `responseBody` and `responseHeaders` cannot be edited. | "Rule and collection actions without confirmation" is on. |
+| `request_delete_rule`, `request_delete_collection` | Delete a rule or collection. | "Delete rules and collections without confirmation" is on. |
+| `request_reload_captured_tab` | Reload only the captured tab to validate a mock. Never reloads other or internal pages. | "Reload captured tab without confirmation" is on. |
+| `request_start_capture`, `request_restart_capture`, `request_stop_capture`, `request_capture_current_tab`, `request_set_capture_mode` | Control capture on the eligible web tab; modes are `auto`, `full` and `light`. | "Capture control without confirmation" is on. |
+
+## Security
+
+- Local only: the daemon listens on `127.0.0.1`.
+- The session key is required from both the extension and every adapter, and is never echoed in logs, errors or tool results.
+- Sanitized by default; sensitive data is only sent when the matching permission is on.
+- State changes are proposals confirmed by you unless you enable the matching session permission.
+- The daemon accepts an allowlist of commands. There are no tools to clear logs, drive the debugger or reload arbitrary pages.
+
+## Troubleshooting
+
+**Extension not connected.** Open the Full App, go to AI Bridge and click Start. Tools return a safe error until the extension connects.
+
+**Daemon did not start.** Run it by hand to see the error: `npx -y interceptpilot-mcp daemon --port <PORT> --key <KEY>`.
+
+**Port in use.** A healthy daemon on the port is reused by other adapters. If an old process is stuck, stop it or change the port in both the AI Bridge page and the client configuration.
+
+**Invalid or regenerated key.** Copy the configuration again from the AI Bridge page.
+
+**Client using an old configuration.** Update the client configuration and restart the client. Permission changes happen in the extension and do not require a new key.
+
+## Development
+
+```bash
+npm install
+npm test
+```
+
+## License
+
+[MIT](./LICENSE)

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "interceptpilot-mcp",
+  "version": "0.1.0",
+  "description": "Local MCP server for InterceptPilot",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "interceptpilot-mcp": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "interceptpilot",
+    "chrome-extension",
+    "api-mock",
+    "network-interception"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AndersonAlpin/interceptpilot-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AndersonAlpin/interceptpilot-mcp/issues"
+  },
+  "homepage": "https://github.com/AndersonAlpin/interceptpilot-mcp#readme",
+  "scripts": {
+    "start": "node src/index.js",
+    "check": "node --check src/index.js src/import-bundle-schema.js src/mcp-server.js src/protocol.js src/websocket-bridge.js src/daemon.js src/daemon-client.js src/process-manager.js",
+    "test": "node --test tests/*.test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "ws": "8.21.0",
+    "zod": "4.4.3"
+  }
+}

package/src/daemon-client.js

@@ -0,0 +1,281 @@
+import WebSocket from 'ws'
+
+import {
+  BRIDGE_HOST,
+  BRIDGE_PORT,
+  BRIDGE_PROTOCOL_VERSION,
+  MCP_CLIENT_SOURCE,
+  MESSAGE_TYPES,
+  isAllowedCommand,
+  isClientResponse,
+  parseBridgeMessage
+} from './protocol.js'
+import { startDaemonProcess as defaultStartDaemonProcess } from './process-manager.js'
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 5000
+const DEFAULT_RETRY_DELAY_MS = 100
+const DEFAULT_MAX_PENDING_REQUESTS = 25
+const DEFAULT_MAX_CONNECT_ATTEMPTS = 30
+const TIMEOUT_MESSAGE = 'InterceptPilot did not respond in time.'
+const DISCONNECTED_MESSAGE = 'InterceptPilot daemon disconnected.'
+const COMMAND_NOT_ALLOWED_MESSAGE = 'Command is not allowed.'
+const TOO_MANY_PENDING_MESSAGE = 'Too many pending InterceptPilot requests.'
+const DAEMON_NOT_RUNNING_MESSAGE = 'InterceptPilot daemon is not running. Start AI Bridge or run without --no-daemon-autostart.'
+const DAEMON_START_FAILED_MESSAGE = 'Unable to start InterceptPilot daemon.'
+
+function createDefaultLogger() {
+  return {
+    info: message => console.error(`[interceptpilot-mcp] ${message}`),
+    warn: message => console.error(`[interceptpilot-mcp] ${message}`),
+    error: message => console.error(`[interceptpilot-mcp] ${message}`)
+  }
+}
+
+function addSocketListener(socket, event, handler) {
+  if (typeof socket.on === 'function') {
+    socket.on(event, handler)
+    return
+  }
+  socket[`on${event}`] = handler
+}
+
+function sendJson(socket, message) {
+  socket.send(JSON.stringify(message))
+}
+
+function createSafeError(message) {
+  return new Error(message)
+}
+
+function getMessageData(raw) {
+  if (raw && typeof raw === 'object' && 'data' in raw) return raw.data
+  return raw
+}
+
+export function createDaemonClientBridge(options = {}) {
+  const {
+    WebSocketCtor = WebSocket,
+    host = BRIDGE_HOST,
+    port = BRIDGE_PORT,
+    expectedKey = '',
+    daemonAutostart = true,
+    requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
+    maxPendingRequests = DEFAULT_MAX_PENDING_REQUESTS,
+    maxConnectAttempts = DEFAULT_MAX_CONNECT_ATTEMPTS,
+    retryDelayMs = DEFAULT_RETRY_DELAY_MS,
+    idGenerator,
+    clientId = 'interceptpilot-mcp',
+    logger = createDefaultLogger(),
+    startDaemonProcess = defaultStartDaemonProcess,
+    setTimeoutFn = setTimeout,
+    clearTimeoutFn = clearTimeout
+  } = options
+
+  const connectionKey = String(expectedKey || '')
+  const pending = new Map()
+  let socket = null
+  let connected = false
+  let requestSeq = 0
+  let startPromise = null
+
+  function nextRequestId() {
+    if (idGenerator) return idGenerator()
+    requestSeq += 1
+    return `client_req_${requestSeq}`
+  }
+
+  function isConnected() {
+    return Boolean(socket && connected)
+  }
+
+  function rejectPending(message) {
+    for (const [, request] of pending) {
+      clearTimeoutFn(request.timer)
+      request.reject(createSafeError(message))
+    }
+    pending.clear()
+  }
+
+  function handleResponse(message) {
+    if (!isClientResponse(message)) return
+    const request = pending.get(message.id)
+    if (!request) return
+    pending.delete(message.id)
+    clearTimeoutFn(request.timer)
+
+    if (message.type === MESSAGE_TYPES.clientError || message.ok === false) {
+      request.reject(createSafeError(String(message.error?.message || 'InterceptPilot command failed.')))
+      return
+    }
+
+    request.resolve(message.result)
+  }
+
+  function handleSocketClose(activeSocket) {
+    if (socket !== activeSocket) return
+    connected = false
+    socket = null
+    startPromise = null
+    rejectPending(DISCONNECTED_MESSAGE)
+  }
+
+  function schedule(fn) {
+    if (retryDelayMs <= 0) {
+      fn()
+      return
+    }
+    const timer = setTimeoutFn(fn, retryDelayMs)
+    timer?.unref?.()
+  }
+
+  function connectAttempt(resolve, reject, attempt = 1, autostartTried = false) {
+    let settled = false
+    const activeSocket = new WebSocketCtor(`ws://${host}:${port}`)
+    socket = activeSocket
+
+    function failStart(message) {
+      settled = true
+      socket = null
+      connected = false
+      startPromise = null
+      reject(createSafeError(message))
+    }
+
+    function retryAfterAutostart() {
+      schedule(() => connectAttempt(resolve, reject, attempt + 1, true))
+    }
+
+    addSocketListener(activeSocket, 'open', () => {
+      if (settled) return
+      sendJson(activeSocket, {
+        type: MESSAGE_TYPES.clientHello,
+        source: MCP_CLIENT_SOURCE,
+        key: connectionKey,
+        version: BRIDGE_PROTOCOL_VERSION,
+        clientId
+      })
+    })
+
+    addSocketListener(activeSocket, 'message', raw => {
+      const message = parseBridgeMessage(getMessageData(raw))
+      if (!message) return
+
+      if (message.type === MESSAGE_TYPES.clientHelloAck && message.ok === true && Number(message.version) === BRIDGE_PROTOCOL_VERSION) {
+        settled = true
+        connected = true
+        resolve()
+        return
+      }
+
+      handleResponse(message)
+    })
+
+    addSocketListener(activeSocket, 'error', () => {
+      if (connected || settled) return
+      settled = true
+      socket = null
+
+      if (!daemonAutostart) {
+        failStart(DAEMON_NOT_RUNNING_MESSAGE)
+        return
+      }
+
+      if (!autostartTried) {
+        try {
+          startDaemonProcess({ port, key: connectionKey, logger })
+        } catch {
+          failStart(DAEMON_START_FAILED_MESSAGE)
+          return
+        }
+        retryAfterAutostart()
+        return
+      }
+
+      if (attempt < maxConnectAttempts) {
+        retryAfterAutostart()
+        return
+      }
+
+      failStart(DAEMON_START_FAILED_MESSAGE)
+    })
+
+    addSocketListener(activeSocket, 'close', () => {
+      if (!connected && !settled) {
+        settled = true
+        socket = null
+        if (!daemonAutostart) {
+          failStart(DAEMON_NOT_RUNNING_MESSAGE)
+          return
+        }
+        if (!autostartTried) {
+          try {
+            startDaemonProcess({ port, key: connectionKey, logger })
+          } catch {
+            failStart(DAEMON_START_FAILED_MESSAGE)
+            return
+          }
+          retryAfterAutostart()
+          return
+        }
+        failStart(DAEMON_START_FAILED_MESSAGE)
+        return
+      }
+      handleSocketClose(activeSocket)
+    })
+  }
+
+  function start() {
+    if (isConnected()) return Promise.resolve()
+    if (startPromise) return startPromise
+    startPromise = new Promise((resolve, reject) => {
+      connectAttempt(resolve, reject)
+    })
+    return startPromise
+  }
+
+  async function close() {
+    rejectPending(DISCONNECTED_MESSAGE)
+    connected = false
+    startPromise = null
+    if (socket && typeof socket.close === 'function') socket.close()
+    socket = null
+  }
+
+  function callCommand(command, payload = {}) {
+    if (!isAllowedCommand(command)) {
+      return Promise.reject(createSafeError(COMMAND_NOT_ALLOWED_MESSAGE))
+    }
+    if (!isConnected()) {
+      return Promise.reject(createSafeError(DAEMON_NOT_RUNNING_MESSAGE))
+    }
+    if (pending.size >= maxPendingRequests) {
+      return Promise.reject(createSafeError(TOO_MANY_PENDING_MESSAGE))
+    }
+
+    const id = nextRequestId()
+    const message = {
+      id,
+      type: MESSAGE_TYPES.clientCommand,
+      command,
+      payload: payload && typeof payload === 'object' ? payload : {}
+    }
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeoutFn(() => {
+        pending.delete(id)
+        reject(createSafeError(TIMEOUT_MESSAGE))
+      }, requestTimeoutMs)
+      timer?.unref?.()
+      pending.set(id, { resolve, reject, timer })
+      sendJson(socket, message)
+    })
+  }
+
+  return {
+    start,
+    close,
+    callCommand,
+    isConnected,
+    getPendingCount: () => pending.size
+  }
+}