interceptpilot-mcp 0.1.0

package/src/daemon.js

@@ -0,0 +1,312 @@
+import { WebSocketServer } from 'ws'
+
+import {
+  BRIDGE_HOST,
+  BRIDGE_PORT,
+  MESSAGE_TYPES,
+  createClientHelloAckMessage,
+  createCommandMessage,
+  createHelloAckMessage,
+  createPingMessage,
+  isAllowedCommand,
+  isCommandResponse,
+  parseBridgeMessage,
+  validateClientHelloMessage,
+  validateHelloMessage
+} from './protocol.js'
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 5000
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 20000
+const DEFAULT_MAX_PENDING_REQUESTS = 25
+const NOT_CONNECTED_MESSAGE = 'InterceptPilot extension is not connected. Open InterceptPilot settings and start an AI Bridge session.'
+const TIMEOUT_MESSAGE = 'InterceptPilot did not respond in time.'
+const DISCONNECTED_MESSAGE = 'InterceptPilot extension disconnected.'
+const COMMAND_NOT_ALLOWED_MESSAGE = 'Command is not allowed.'
+const TOO_MANY_PENDING_MESSAGE = 'Too many pending InterceptPilot requests.'
+
+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) {
+  if (!socket || socket.closed) return
+  socket.send(JSON.stringify(message))
+}
+
+function createClientError(id, code, message) {
+  return {
+    id,
+    type: MESSAGE_TYPES.clientError,
+    ok: false,
+    error: { code, message }
+  }
+}
+
+export function createInterceptPilotDaemon(options = {}) {
+  const {
+    WebSocketServerCtor = WebSocketServer,
+    port = BRIDGE_PORT,
+    expectedKey = '',
+    requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
+    heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS,
+    maxPendingRequests = DEFAULT_MAX_PENDING_REQUESTS,
+    idGenerator,
+    logger = createDefaultLogger(),
+    setTimeoutFn = setTimeout,
+    clearTimeoutFn = clearTimeout,
+    setIntervalFn = setInterval,
+    clearIntervalFn = clearInterval
+  } = options
+
+  const expectedConnectionKey = String(expectedKey || '')
+  const clients = new Set()
+  const pending = new Map()
+  const host = BRIDGE_HOST
+  let server = null
+  let extensionSocket = null
+  let extensionConnected = false
+  let requestSeq = 0
+  let heartbeatTimer = null
+
+  function nextRequestId() {
+    if (idGenerator) return idGenerator()
+    requestSeq += 1
+    return `daemon_req_${requestSeq}`
+  }
+
+  function isExtensionConnected() {
+    return Boolean(extensionSocket && extensionConnected)
+  }
+
+  function startHeartbeat() {
+    if (heartbeatTimer) return
+    heartbeatTimer = setIntervalFn(() => {
+      if (isExtensionConnected()) sendJson(extensionSocket, createPingMessage())
+    }, heartbeatIntervalMs)
+    heartbeatTimer?.unref?.()
+  }
+
+  function stopHeartbeat() {
+    if (!heartbeatTimer) return
+    clearIntervalFn(heartbeatTimer)
+    heartbeatTimer = null
+  }
+
+  function rejectPendingForClient(clientSocket) {
+    for (const [extensionRequestId, request] of pending) {
+      if (request.clientSocket !== clientSocket) continue
+      clearTimeoutFn(request.timer)
+      pending.delete(extensionRequestId)
+    }
+  }
+
+  function rejectAllPending(message) {
+    for (const [extensionRequestId, request] of pending) {
+      clearTimeoutFn(request.timer)
+      pending.delete(extensionRequestId)
+      sendJson(request.clientSocket, createClientError(
+        request.clientRequestId,
+        'EXTENSION_DISCONNECTED',
+        message
+      ))
+    }
+  }
+
+  function detachExtension(socket) {
+    if (socket !== extensionSocket) return
+    extensionSocket = null
+    extensionConnected = false
+    stopHeartbeat()
+    rejectAllPending(DISCONNECTED_MESSAGE)
+    logger.info('Extension disconnected.')
+  }
+
+  function detachClient(socket) {
+    if (!clients.has(socket)) return
+    clients.delete(socket)
+    rejectPendingForClient(socket)
+    logger.info('MCP client disconnected.')
+  }
+
+  function acceptExtension(socket, message) {
+    const validation = validateHelloMessage(message, { expectedKey: expectedConnectionKey })
+    if (!validation.ok) {
+      logger.warn(validation.error)
+      socket.close()
+      return
+    }
+
+    if (extensionSocket && extensionSocket !== socket) {
+      const previousSocket = extensionSocket
+      detachExtension(previousSocket)
+      previousSocket.close()
+    }
+
+    extensionSocket = socket
+    extensionConnected = true
+    sendJson(socket, createHelloAckMessage())
+    startHeartbeat()
+    logger.info('Extension connected.')
+  }
+
+  function acceptClient(socket, message) {
+    const validation = validateClientHelloMessage(message, { expectedKey: expectedConnectionKey })
+    if (!validation.ok) {
+      logger.warn(validation.error)
+      socket.close()
+      return
+    }
+
+    clients.add(socket)
+    sendJson(socket, createClientHelloAckMessage())
+    logger.info('MCP client connected.')
+  }
+
+  function sendClientError(socket, id, code, message) {
+    sendJson(socket, createClientError(id, code, message))
+  }
+
+  function handleExtensionResponse(message) {
+    if (!isCommandResponse(message)) return
+    const request = pending.get(message.id)
+    if (!request) return
+    pending.delete(message.id)
+    clearTimeoutFn(request.timer)
+
+    if (message.type === MESSAGE_TYPES.commandError || message.ok === false) {
+      sendClientError(
+        request.clientSocket,
+        request.clientRequestId,
+        String(message.error?.code || 'COMMAND_FAILED'),
+        String(message.error?.message || 'InterceptPilot command failed.')
+      )
+      return
+    }
+
+    sendJson(request.clientSocket, {
+      id: request.clientRequestId,
+      type: MESSAGE_TYPES.clientResult,
+      ok: true,
+      result: message.result
+    })
+  }
+
+  function handleClientCommand(socket, message) {
+    const clientRequestId = String(message?.id || '')
+    const command = String(message?.command || '')
+    if (!clientRequestId) return
+
+    if (!isAllowedCommand(command)) {
+      sendClientError(socket, clientRequestId, 'COMMAND_NOT_ALLOWED', COMMAND_NOT_ALLOWED_MESSAGE)
+      return
+    }
+
+    if (!isExtensionConnected()) {
+      sendClientError(socket, clientRequestId, 'EXTENSION_NOT_CONNECTED', NOT_CONNECTED_MESSAGE)
+      return
+    }
+
+    if (pending.size >= maxPendingRequests) {
+      sendClientError(socket, clientRequestId, 'TOO_MANY_PENDING_REQUESTS', TOO_MANY_PENDING_MESSAGE)
+      return
+    }
+
+    const extensionRequestId = nextRequestId()
+    const timer = setTimeoutFn(() => {
+      pending.delete(extensionRequestId)
+      sendClientError(socket, clientRequestId, 'COMMAND_TIMEOUT', TIMEOUT_MESSAGE)
+    }, requestTimeoutMs)
+    timer?.unref?.()
+    pending.set(extensionRequestId, { clientSocket: socket, clientRequestId, timer, command })
+    sendJson(extensionSocket, createCommandMessage(
+      extensionRequestId,
+      command,
+      message.payload && typeof message.payload === 'object' ? message.payload : {}
+    ))
+  }
+
+  function handleSocketMessage(socket, raw) {
+    const message = parseBridgeMessage(raw)
+    if (!message) {
+      logger.warn('Ignoring invalid bridge message.')
+      return
+    }
+
+    if (message.type === MESSAGE_TYPES.hello) {
+      acceptExtension(socket, message)
+      return
+    }
+
+    if (message.type === MESSAGE_TYPES.clientHello) {
+      acceptClient(socket, message)
+      return
+    }
+
+    if (socket === extensionSocket && extensionConnected) {
+      if (message.type === MESSAGE_TYPES.pong) return
+      handleExtensionResponse(message)
+      return
+    }
+
+    if (clients.has(socket)) {
+      if (message.type === MESSAGE_TYPES.clientCommand) handleClientCommand(socket, message)
+      return
+    }
+  }
+
+  function handleSocket(socket) {
+    addSocketListener(socket, 'message', raw => handleSocketMessage(socket, raw))
+    addSocketListener(socket, 'close', () => {
+      detachExtension(socket)
+      detachClient(socket)
+    })
+    addSocketListener(socket, 'error', () => {
+      detachExtension(socket)
+      detachClient(socket)
+    })
+  }
+
+  function start() {
+    if (server) return server
+    server = new WebSocketServerCtor({ host, port })
+    server.on('connection', handleSocket)
+    server.on('listening', () => logger.info(`Shared daemon listening on ${host}:${port}.`))
+    server.on('error', () => logger.error('Shared daemon WebSocket error.'))
+    return server
+  }
+
+  async function close() {
+    stopHeartbeat()
+    rejectAllPending(DISCONNECTED_MESSAGE)
+    if (extensionSocket) extensionSocket.close()
+    for (const client of Array.from(clients)) client.close()
+    extensionSocket = null
+    extensionConnected = false
+    clients.clear()
+    if (server && typeof server.close === 'function') {
+      await new Promise(resolve => server.close(resolve))
+    }
+    server = null
+  }
+
+  return {
+    start,
+    close,
+    handleSocket,
+    isExtensionConnected,
+    getClientCount: () => clients.size,
+    getPendingCount: () => pending.size
+  }
+}

package/src/import-bundle-schema.js

@@ -0,0 +1,221 @@
+export const IMPORT_BUNDLE_SCHEMA_VERSION = 1
+export const IMPORT_BUNDLE_TYPES = ['interceptpilot.rule', 'interceptpilot.collection']
+
+export const IMPORT_BUNDLE_ALLOWED_VALUES = {
+  matchType: ['contains', 'equals', 'regex', 'glob'],
+  method: ['ANY', 'GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+  resourceType: ['ANY', 'XHR', 'Fetch', 'Document', 'Script', 'Image', 'Stylesheet', 'Other'],
+  actionType: ['mockResponse', 'failRequest', 'delayOnly', 'passThrough'],
+  failReason: [
+    'Failed',
+    'Aborted',
+    'TimedOut',
+    'AccessDenied',
+    'ConnectionClosed',
+    'ConnectionRefused',
+    'ConnectionReset',
+    'InternetDisconnected',
+    'NameNotResolved'
+  ]
+}
+
+const baseMatchShape = {
+  urlPattern: 'string',
+  matchType: 'contains | equals | regex | glob',
+  method: 'ANY | GET | POST | PUT | PATCH | DELETE | OPTIONS',
+  resourceType: 'ANY | XHR | Fetch | Document | Script | Image | Stylesheet | Other'
+}
+
+const baseActionShape = {
+  type: 'mockResponse | failRequest | delayOnly | passThrough',
+  statusCode: 'number optional, 100-599 for mockResponse',
+  statusText: 'string optional',
+  contentType: 'string optional',
+  responseBody: 'string optional; JSON responses must be stringified JSON',
+  responseHeaders: 'string optional; for redirects include a Location header such as "Location: /new-path"',
+  delayMs: 'number optional, milliseconds',
+  failReason: 'Failed | Aborted | TimedOut | AccessDenied | ConnectionClosed | ConnectionRefused | ConnectionReset | InternetDisconnected | NameNotResolved'
+}
+
+export function getImportBundleSchema() {
+  return {
+    schemaVersion: IMPORT_BUNDLE_SCHEMA_VERSION,
+    supportedTypes: [...IMPORT_BUNDLE_TYPES],
+    ruleBundleShape: {
+      schemaVersion: IMPORT_BUNDLE_SCHEMA_VERSION,
+      type: 'interceptpilot.rule',
+      exportedAt: 'ISO date string',
+      rule: {
+        id: 'string optional',
+        collectionId: 'string optional',
+        name: 'string',
+        enabled: 'boolean',
+        priority: 'number',
+        match: { ...baseMatchShape },
+        action: { ...baseActionShape }
+      }
+    },
+    collectionBundleShape: {
+      schemaVersion: IMPORT_BUNDLE_SCHEMA_VERSION,
+      type: 'interceptpilot.collection',
+      exportedAt: 'ISO date string',
+      collection: {
+        id: 'string optional',
+        name: 'string',
+        description: 'string optional',
+        enabled: 'boolean',
+        order: 'number optional'
+      },
+      rules: ['array of rule objects using the same rule shape as ruleBundleShape.rule']
+    },
+    allowedValues: {
+      matchType: [...IMPORT_BUNDLE_ALLOWED_VALUES.matchType],
+      method: [...IMPORT_BUNDLE_ALLOWED_VALUES.method],
+      resourceType: [...IMPORT_BUNDLE_ALLOWED_VALUES.resourceType],
+      actionType: [...IMPORT_BUNDLE_ALLOWED_VALUES.actionType],
+      failReason: [...IMPORT_BUNDLE_ALLOWED_VALUES.failReason]
+    },
+    guidance: [
+      'Prefer resourceType "ANY" unless the user explicitly asks for a specific type.',
+      'Use matchType "contains" for most endpoint path matching unless the user needs exact, regex or glob matching.',
+      'Use mockResponse for HTTP status codes from 100 to 599, including 4xx and 5xx.',
+      'Use failRequest only for network-level failures where there is no HTTP response.',
+      'Use delayOnly only to add latency without changing the response.',
+      'Use passThrough to allow the request to continue unchanged.',
+      'responseBody must be a string. If it contains JSON, stringify and escape it correctly.',
+      'For redirects such as 301 or 302, use mockResponse and include a Location header when appropriate.',
+      'Importing a bundle only creates a pending proposal; the user must confirm it in the Full App before anything is applied.'
+    ]
+  }
+}
+
+function createRuleBundle({ name, urlPattern, action, method = 'GET', priority = 100 }) {
+  return {
+    schemaVersion: IMPORT_BUNDLE_SCHEMA_VERSION,
+    type: 'interceptpilot.rule',
+    exportedAt: '2026-01-01T00:00:00.000Z',
+    rule: {
+      name,
+      enabled: true,
+      priority,
+      match: {
+        urlPattern,
+        matchType: 'contains',
+        method,
+        resourceType: 'ANY'
+      },
+      action
+    }
+  }
+}
+
+export function getImportBundleExamples() {
+  return [
+    {
+      name: 'Single rule mock 200',
+      description: 'Example of a single rule bundle that mocks a JSON success response.',
+      bundle: createRuleBundle({
+        name: 'Mock example success',
+        urlPattern: '/api/example',
+        action: {
+          type: 'mockResponse',
+          statusCode: 200,
+          statusText: 'OK',
+          contentType: 'application/json',
+          responseBody: '{"ok":true,"source":"interceptpilot"}'
+        }
+      })
+    },
+    {
+      name: 'Single rule HTTP 500',
+      description: 'Example of an HTTP error response. Use mockResponse for HTTP 4xx and 5xx statuses.',
+      bundle: createRuleBundle({
+        name: 'Mock checkout server error',
+        urlPattern: '/api/checkout',
+        action: {
+          type: 'mockResponse',
+          statusCode: 500,
+          statusText: 'Internal Server Error',
+          contentType: 'application/json',
+          responseBody: '{"error":"temporary_failure"}'
+        }
+      })
+    },
+    {
+      name: 'Single rule network timeout',
+      description: 'Example of a network-level failure where no HTTP response should exist.',
+      bundle: createRuleBundle({
+        name: 'Simulate checkout timeout',
+        urlPattern: '/api/checkout',
+        action: {
+          type: 'failRequest',
+          failReason: 'TimedOut'
+        }
+      })
+    },
+    {
+      name: 'Single rule delay only',
+      description: 'Example of adding latency without changing the response.',
+      bundle: createRuleBundle({
+        name: 'Delay profile response',
+        urlPattern: '/api/user/profile',
+        action: {
+          type: 'delayOnly',
+          delayMs: 1200
+        }
+      })
+    },
+    {
+      name: 'Collection with multiple rules',
+      description: 'Example of a collection bundle grouping related checkout scenarios.',
+      bundle: {
+        schemaVersion: IMPORT_BUNDLE_SCHEMA_VERSION,
+        type: 'interceptpilot.collection',
+        exportedAt: '2026-01-01T00:00:00.000Z',
+        collection: {
+          name: 'Checkout examples',
+          description: 'Safe generic checkout scenarios',
+          enabled: true
+        },
+        rules: [
+          {
+            name: 'Checkout success',
+            enabled: true,
+            priority: 100,
+            match: {
+              urlPattern: '/api/checkout',
+              matchType: 'contains',
+              method: 'POST',
+              resourceType: 'ANY'
+            },
+            action: {
+              type: 'mockResponse',
+              statusCode: 200,
+              statusText: 'OK',
+              contentType: 'application/json',
+              responseBody: '{"ok":true,"orderId":"example-order"}'
+            }
+          },
+          {
+            name: 'Checkout unavailable',
+            enabled: true,
+            priority: 110,
+            match: {
+              urlPattern: '/api/checkout',
+              matchType: 'contains',
+              method: 'POST',
+              resourceType: 'ANY'
+            },
+            action: {
+              type: 'mockResponse',
+              statusCode: 503,
+              statusText: 'Service Unavailable',
+              contentType: 'application/json',
+              responseBody: '{"ok":false,"error":"service_unavailable"}'
+            }
+          }
+        ]
+      }
+    }
+  ]
+}

package/src/index.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'node:url'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+
+import { BRIDGE_PORT } from './protocol.js'
+import { createDaemonClientBridge } from './daemon-client.js'
+import { createInterceptPilotDaemon } from './daemon.js'
+import { createMcpServer } from './mcp-server.js'
+
+export function parseCliArgs(argv = []) {
+  const options = {
+    mode: 'adapter',
+    port: BRIDGE_PORT,
+    key: '',
+    daemonHost: '127.0.0.1',
+    daemonAutostart: true
+  }
+
+  const args = [...argv]
+  if (args[0] === 'daemon') {
+    options.mode = 'daemon'
+    args.shift()
+  }
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]
+    if (arg === '--port' && args[i + 1]) {
+      options.port = Number(args[i + 1]) || BRIDGE_PORT
+      i += 1
+    } else if (arg === '--key' && args[i + 1]) {
+      options.key = String(args[i + 1] || '')
+      i += 1
+    } else if (arg === '--no-daemon-autostart') {
+      options.daemonAutostart = false
+    }
+  }
+
+  return options
+}
+
+function createStderrLogger() {
+  return {
+    info: message => console.error(`[interceptpilot-mcp] ${message}`),
+    warn: message => console.error(`[interceptpilot-mcp] ${message}`),
+    error: message => console.error(`[interceptpilot-mcp] ${message}`)
+  }
+}
+
+export async function createRuntime(options, factories = {}) {
+  const {
+    createDaemonClientBridge: createDaemonClientBridgeFn = createDaemonClientBridge,
+    createInterceptPilotDaemon: createInterceptPilotDaemonFn = createInterceptPilotDaemon,
+    createMcpServer: createMcpServerFn = createMcpServer,
+    StdioServerTransportCtor = StdioServerTransport,
+    logger = createStderrLogger()
+  } = factories
+
+  if (options.mode === 'daemon') {
+    const daemon = createInterceptPilotDaemonFn({
+      port: options.port,
+      expectedKey: options.key,
+      logger
+    })
+    daemon.start()
+    return {
+      mode: 'daemon',
+      daemon,
+      close: () => daemon.close()
+    }
+  }
+
+  const bridge = createDaemonClientBridgeFn({
+    port: options.port,
+    expectedKey: options.key,
+    daemonAutostart: options.daemonAutostart,
+    logger
+  })
+  await bridge.start()
+
+  const server = createMcpServerFn({ bridge })
+  const transport = new StdioServerTransportCtor()
+  await server.connect(transport)
+
+  return {
+    mode: 'adapter',
+    bridge,
+    server,
+    close: async () => {
+      await bridge.close?.()
+      await server.close?.()
+    }
+  }
+}
+
+export async function main(argv = process.argv.slice(2), factories = {}) {
+  const runtime = await createRuntime(parseCliArgs(argv), factories)
+
+  process.on('SIGINT', async () => {
+    await runtime.close()
+    process.exit(0)
+  })
+
+  return runtime
+}
+
+const currentFile = fileURLToPath(import.meta.url)
+if (process.argv[1] === currentFile) {
+  main().catch(error => {
+    console.error(`[interceptpilot-mcp] ${String(error?.message || 'Failed to start InterceptPilot MCP server.')}`)
+    process.exit(1)
+  })
+}