proxy-mcp

Instructions

Implementation Reference

• src/tools/lifecycle.ts:12-25 (registration)

  The tool 'proxy_start' is registered here.

  server.tool(
    "proxy_start",
    "Start the HTTPS MITM proxy. Auto-generates a CA certificate. Returns port, URL, cert fingerprint, and setup instructions for the target device.",
    {
      port: z.number().optional().describe("Port to listen on (0 = random available port)"),
      persistence_enabled: z.boolean().optional().default(false)
        .describe("Enable persistent on-disk session capture (default: false)"),
      session_name: z.string().optional().describe("Optional name for the session when persistence is enabled"),
      capture_profile: z.enum(["preview", "full"]).optional().default("preview")
        .describe("Capture profile for persisted sessions: preview (body previews) or full (full bodies)"),
      storage_dir: z.string().optional().describe("Custom session storage directory"),
      max_disk_mb: z.number().optional().default(1024)
        .describe("Per-session disk cap in MB (writes are dropped once exceeded)"),
    },

• src/tools/lifecycle.ts:26-60 (handler)

  The handler for 'proxy_start' which calls proxyManager.start.

  async ({ port, persistence_enabled, session_name, capture_profile, storage_dir, max_disk_mb }) => {
    try {
      const result = await proxyManager.start(port, {
        persistenceEnabled: persistence_enabled ?? false,
        sessionName: session_name,
        captureProfile: capture_profile,
        storageDir: storage_dir,
        maxDiskMb: max_disk_mb,
      });
      const localIP = getLocalIP();
      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            status: "success",
            port: result.port,
            url: result.url,
            certFingerprint: result.cert.fingerprint,
            persistence: proxyManager.getSessionStatus(),
            setup: {
              proxyHost: localIP,
              proxyPort: result.port,
              instructions: [
                `1. Set device Wi-Fi proxy to ${localIP}:${result.port}`,
                "2. Install the CA certificate on the device (use proxy_get_ca_cert)",
                `3. Or use env vars: HTTP_PROXY=http://${localIP}:${result.port} HTTPS_PROXY=http://${localIP}:${result.port}`,
              ],
            },
          }),
        }],
      };
    } catch (e) {
      return { content: [{ type: "text", text: JSON.stringify({ status: "error", error: String(e) }) }] };
    }
  },