interceptpilot-mcp 0.1.0 → 0.1.1

package/README.md

@@ -41,6 +41,8 @@ AI client
 
 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.
 
+The daemon exits on its own after 10 minutes with no adapter and no extension connected. When you update the package, the newer adapter asks an older daemon to stop and starts a fresh one, so both always run the same version.
+
 ## Options
 
 | Option | Meaning |
@@ -49,6 +51,7 @@ The MCP client starts the adapter. The adapter starts the local daemon when none
 | `--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>`. |
+| `--version`, `--help` | Print the version or this usage. |
 
 ## Tools
 
@@ -100,6 +103,8 @@ What each tool exposes depends on the permissions you set in the extension. By d
 
 **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.
 
+**"An older interceptpilot-mcp daemon is running on port … and could not be replaced automatically."** A daemon from version 0.1.0 is still running; that version cannot be stopped remotely. End the `node` process that runs `interceptpilot-mcp daemon` (or restart the machine) and start the MCP client again. Later versions replace themselves without this step.
+
 **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "interceptpilot-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local MCP server for InterceptPilot",
   "license": "MIT",
   "type": "module",

package/src/daemon-client.js

@@ -10,9 +10,11 @@ import {
   isClientResponse,
   parseBridgeMessage
 } from './protocol.js'
+import { PACKAGE_VERSION, compareVersions } from './package-version.js'
 import { startDaemonProcess as defaultStartDaemonProcess } from './process-manager.js'
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 5000
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 1500
 const DEFAULT_RETRY_DELAY_MS = 100
 const DEFAULT_MAX_PENDING_REQUESTS = 25
 const DEFAULT_MAX_CONNECT_ATTEMPTS = 30
@@ -22,6 +24,7 @@ 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.'
+const OUTDATED_DAEMON_MESSAGE = port => `An older interceptpilot-mcp daemon is running on port ${port} and could not be replaced automatically. End that node process (or restart the machine) and start the MCP client again.`
 
 function createDefaultLogger() {
   return {
@@ -63,6 +66,8 @@ export function createDaemonClientBridge(options = {}) {
     maxPendingRequests = DEFAULT_MAX_PENDING_REQUESTS,
     maxConnectAttempts = DEFAULT_MAX_CONNECT_ATTEMPTS,
     retryDelayMs = DEFAULT_RETRY_DELAY_MS,
+    shutdownTimeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS,
+    packageVersion = PACKAGE_VERSION,
     idGenerator,
     clientId = 'interceptpilot-mcp',
     logger = createDefaultLogger(),
@@ -128,8 +133,9 @@ export function createDaemonClientBridge(options = {}) {
     timer?.unref?.()
   }
 
-  function connectAttempt(resolve, reject, attempt = 1, autostartTried = false) {
+  function connectAttempt(resolve, reject, attempt = 1, autostartTried = false, replaceTried = false) {
     let settled = false
+    let replacing = false
     const activeSocket = new WebSocketCtor(`ws://${host}:${port}`)
     socket = activeSocket
 
@@ -142,7 +148,25 @@ export function createDaemonClientBridge(options = {}) {
     }
 
     function retryAfterAutostart() {
-      schedule(() => connectAttempt(resolve, reject, attempt + 1, true))
+      schedule(() => connectAttempt(resolve, reject, attempt + 1, true, replaceTried))
+    }
+
+    // A daemon older than this adapter may not know newer commands. Ask it to
+    // stop and start a fresh one; a daemon too old to understand the request is
+    // kept, with a warning, so the user is not blocked.
+    function replaceOutdatedDaemon(daemonVersion) {
+      replacing = true
+      logger.info(`Replacing daemon ${daemonVersion || '(unknown version)'} with ${packageVersion}.`)
+      sendJson(activeSocket, { type: MESSAGE_TYPES.clientShutdown })
+      const timer = setTimeoutFn(() => {
+        if (settled) return
+        settled = true
+        replacing = false
+        connected = true
+        logger.warn(OUTDATED_DAEMON_MESSAGE(port))
+        resolve()
+      }, shutdownTimeoutMs)
+      timer?.unref?.()
     }
 
     addSocketListener(activeSocket, 'open', () => {
@@ -161,12 +185,20 @@ export function createDaemonClientBridge(options = {}) {
       if (!message) return
 
       if (message.type === MESSAGE_TYPES.clientHelloAck && message.ok === true && Number(message.version) === BRIDGE_PROTOCOL_VERSION) {
+        if (settled || replacing) return
+        const daemonVersion = String(message.packageVersion || '')
+        if (daemonAutostart && !replaceTried && compareVersions(daemonVersion, packageVersion) < 0) {
+          replaceOutdatedDaemon(daemonVersion)
+          return
+        }
         settled = true
         connected = true
         resolve()
         return
       }
 
+      if (message.type === MESSAGE_TYPES.clientShutdownAck) return
+
       handleResponse(message)
     })
 
@@ -200,6 +232,18 @@ export function createDaemonClientBridge(options = {}) {
     })
 
     addSocketListener(activeSocket, 'close', () => {
+      if (replacing && !settled) {
+        settled = true
+        socket = null
+        try {
+          startDaemonProcess({ port, key: connectionKey, logger })
+        } catch {
+          failStart(DAEMON_START_FAILED_MESSAGE)
+          return
+        }
+        schedule(() => connectAttempt(resolve, reject, attempt + 1, true, true))
+        return
+      }
       if (!connected && !settled) {
         settled = true
         socket = null

package/src/daemon.js

@@ -14,9 +14,11 @@ import {
   validateClientHelloMessage,
   validateHelloMessage
 } from './protocol.js'
+import { PACKAGE_VERSION } from './package-version.js'
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 5000
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 20000
+const DEFAULT_IDLE_TIMEOUT_MS = 10 * 60 * 1000
 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.'
@@ -62,6 +64,12 @@ export function createInterceptPilotDaemon(options = {}) {
     requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
     heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS,
     maxPendingRequests = DEFAULT_MAX_PENDING_REQUESTS,
+    // Exit when no MCP client has been connected for this long and the
+    // extension is not connected either. 0 disables it.
+    idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,
+    packageVersion = PACKAGE_VERSION,
+    onIdle = () => {},
+    onShutdown = () => {},
     idGenerator,
     logger = createDefaultLogger(),
     setTimeoutFn = setTimeout,
@@ -79,6 +87,7 @@ export function createInterceptPilotDaemon(options = {}) {
   let extensionConnected = false
   let requestSeq = 0
   let heartbeatTimer = null
+  let idleTimer = null
 
   function nextRequestId() {
     if (idGenerator) return idGenerator()
@@ -104,6 +113,25 @@ export function createInterceptPilotDaemon(options = {}) {
     heartbeatTimer = null
   }
 
+  function clearIdleTimer() {
+    if (!idleTimer) return
+    clearTimeoutFn(idleTimer)
+    idleTimer = null
+  }
+
+  function scheduleIdleCheck() {
+    clearIdleTimer()
+    if (!idleTimeoutMs || clients.size > 0 || isExtensionConnected()) return
+    idleTimer = setTimeoutFn(async () => {
+      idleTimer = null
+      if (clients.size > 0 || isExtensionConnected()) return
+      logger.info('No MCP client or extension connected; shutting down idle daemon.')
+      await close()
+      onIdle()
+    }, idleTimeoutMs)
+    idleTimer?.unref?.()
+  }
+
   function rejectPendingForClient(clientSocket) {
     for (const [extensionRequestId, request] of pending) {
       if (request.clientSocket !== clientSocket) continue
@@ -131,6 +159,7 @@ export function createInterceptPilotDaemon(options = {}) {
     stopHeartbeat()
     rejectAllPending(DISCONNECTED_MESSAGE)
     logger.info('Extension disconnected.')
+    scheduleIdleCheck()
   }
 
   function detachClient(socket) {
@@ -138,6 +167,7 @@ export function createInterceptPilotDaemon(options = {}) {
     clients.delete(socket)
     rejectPendingForClient(socket)
     logger.info('MCP client disconnected.')
+    scheduleIdleCheck()
   }
 
   function acceptExtension(socket, message) {
@@ -156,6 +186,7 @@ export function createInterceptPilotDaemon(options = {}) {
 
     extensionSocket = socket
     extensionConnected = true
+    clearIdleTimer()
     sendJson(socket, createHelloAckMessage())
     startHeartbeat()
     logger.info('Extension connected.')
@@ -170,10 +201,20 @@ export function createInterceptPilotDaemon(options = {}) {
     }
 
     clients.add(socket)
-    sendJson(socket, createClientHelloAckMessage())
+    clearIdleTimer()
+    sendJson(socket, createClientHelloAckMessage(packageVersion))
     logger.info('MCP client connected.')
   }
 
+  // Only a client that passed the key check at hello can ask for this; a newer
+  // adapter uses it to replace an outdated daemon on the same port.
+  async function handleClientShutdown(socket) {
+    logger.info('Shutdown requested by an MCP client; stopping daemon.')
+    sendJson(socket, { type: MESSAGE_TYPES.clientShutdownAck, ok: true })
+    await close()
+    onShutdown()
+  }
+
   function sendClientError(socket, id, code, message) {
     sendJson(socket, createClientError(id, code, message))
   }
@@ -262,6 +303,7 @@ export function createInterceptPilotDaemon(options = {}) {
 
     if (clients.has(socket)) {
       if (message.type === MESSAGE_TYPES.clientCommand) handleClientCommand(socket, message)
+      else if (message.type === MESSAGE_TYPES.clientShutdown) handleClientShutdown(socket)
       return
     }
   }
@@ -284,10 +326,12 @@ export function createInterceptPilotDaemon(options = {}) {
     server.on('connection', handleSocket)
     server.on('listening', () => logger.info(`Shared daemon listening on ${host}:${port}.`))
     server.on('error', () => logger.error('Shared daemon WebSocket error.'))
+    scheduleIdleCheck()
     return server
   }
 
   async function close() {
+    clearIdleTimer()
     stopHeartbeat()
     rejectAllPending(DISCONNECTED_MESSAGE)
     if (extensionSocket) extensionSocket.close()

package/src/index.js

@@ -7,6 +7,22 @@ import { BRIDGE_PORT } from './protocol.js'
 import { createDaemonClientBridge } from './daemon-client.js'
 import { createInterceptPilotDaemon } from './daemon.js'
 import { createMcpServer } from './mcp-server.js'
+import { PACKAGE_VERSION } from './package-version.js'
+
+export const USAGE = `interceptpilot-mcp ${PACKAGE_VERSION}
+
+Usage:
+  interceptpilot-mcp --key <KEY> [--port <PORT>] [--no-daemon-autostart]
+  interceptpilot-mcp daemon --key <KEY> [--port <PORT>]
+
+Options:
+  --key <KEY>             Session key shown by the InterceptPilot AI Bridge page (required)
+  --port <PORT>           Local daemon port (default ${BRIDGE_PORT})
+  --no-daemon-autostart   Do not start the shared daemon automatically
+  --version               Print the package version
+  --help                  Print this help
+
+Copy the ready-made configuration from InterceptPilot > AI Bridge and paste it into your MCP client.`
 
 export function parseCliArgs(argv = []) {
   const options = {
@@ -14,7 +30,9 @@ export function parseCliArgs(argv = []) {
     port: BRIDGE_PORT,
     key: '',
     daemonHost: '127.0.0.1',
-    daemonAutostart: true
+    daemonAutostart: true,
+    help: false,
+    version: false
   }
 
   const args = [...argv]
@@ -33,6 +51,10 @@ export function parseCliArgs(argv = []) {
       i += 1
     } else if (arg === '--no-daemon-autostart') {
       options.daemonAutostart = false
+    } else if (arg === '--help' || arg === '-h') {
+      options.help = true
+    } else if (arg === '--version' || arg === '-v') {
+      options.version = true
     }
   }
 
@@ -53,14 +75,17 @@ export async function createRuntime(options, factories = {}) {
     createInterceptPilotDaemon: createInterceptPilotDaemonFn = createInterceptPilotDaemon,
     createMcpServer: createMcpServerFn = createMcpServer,
     StdioServerTransportCtor = StdioServerTransport,
-    logger = createStderrLogger()
+    logger = createStderrLogger(),
+    exit = code => process.exit(code)
   } = factories
 
   if (options.mode === 'daemon') {
     const daemon = createInterceptPilotDaemonFn({
       port: options.port,
       expectedKey: options.key,
-      logger
+      logger,
+      onIdle: () => exit(0),
+      onShutdown: () => exit(0)
     })
     daemon.start()
     return {
@@ -94,7 +119,21 @@ export async function createRuntime(options, factories = {}) {
 }
 
 export async function main(argv = process.argv.slice(2), factories = {}) {
-  const runtime = await createRuntime(parseCliArgs(argv), factories)
+  const options = parseCliArgs(argv)
+  if (options.help) {
+    console.log(USAGE)
+    return null
+  }
+  if (options.version) {
+    console.log(PACKAGE_VERSION)
+    return null
+  }
+  if (!options.key) {
+    throw new Error(`--key is required.
+
+${USAGE}`)
+  }
+  const runtime = await createRuntime(options, factories)
 
   process.on('SIGINT', async () => {
     await runtime.close()
@@ -106,7 +145,9 @@ export async function main(argv = process.argv.slice(2), factories = {}) {
 
 const currentFile = fileURLToPath(import.meta.url)
 if (process.argv[1] === currentFile) {
-  main().catch(error => {
+  main().then(runtime => {
+    if (!runtime) process.exit(0)
+  }).catch(error => {
     console.error(`[interceptpilot-mcp] ${String(error?.message || 'Failed to start InterceptPilot MCP server.')}`)
     process.exit(1)
   })

package/src/mcp-server.js

@@ -1,4 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { PACKAGE_VERSION } from './package-version.js'
 import { z } from 'zod'
 
 import { getImportBundleExamples, getImportBundleSchema } from './import-bundle-schema.js'
@@ -658,7 +659,7 @@ export function createToolCallHandler({ bridge }) {
 export function createMcpServer({ bridge }) {
   const server = new McpServer({
     name: 'interceptpilot-mcp',
-    version: '0.1.0'
+    version: PACKAGE_VERSION
   })
   const handleToolCall = createToolCallHandler({ bridge })
 

package/src/package-version.js

@@ -0,0 +1,16 @@
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+
+export const PACKAGE_VERSION = String(require('../package.json').version || '0.0.0')
+
+// Numeric semver compare on major.minor.patch; anything unparsable counts as 0.
+export function compareVersions(a, b) {
+  const parse = value => String(value || '').split('.').slice(0, 3).map(part => Number.parseInt(part, 10) || 0)
+  const [left, right] = [parse(a), parse(b)]
+  for (let i = 0; i < 3; i += 1) {
+    const diff = (left[i] || 0) - (right[i] || 0)
+    if (diff !== 0) return diff < 0 ? -1 : 1
+  }
+  return 0
+}

package/src/protocol.js

@@ -15,6 +15,8 @@ export const MESSAGE_TYPES = {
   clientCommand: 'client:command',
   clientResult: 'client:result',
   clientError: 'client:error',
+  clientShutdown: 'client:shutdown',
+  clientShutdownAck: 'client:shutdown:ack',
   ping: 'ping',
   pong: 'pong'
 }
@@ -65,11 +67,12 @@ export function createHelloAckMessage() {
   }
 }
 
-export function createClientHelloAckMessage() {
+export function createClientHelloAckMessage(packageVersion = '') {
   return {
     type: MESSAGE_TYPES.clientHelloAck,
     ok: true,
-    version: BRIDGE_PROTOCOL_VERSION
+    version: BRIDGE_PROTOCOL_VERSION,
+    ...(packageVersion ? { packageVersion: String(packageVersion) } : {})
   }
 }