@silver886/mcp-proxy 0.1.1 → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leonard Liu
+
+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

@@ -1,178 +1,178 @@
-# MCP Proxy
-
-MCP proxy bridge that forwards [Model Context Protocol](https://modelcontextprotocol.io/) requests across network boundaries via [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/).
-
-Works with any MCP client (Claude Code, Cursor, Windsurf, Cline, etc.) and any OS.
-
-## Why
-
-MCP servers that need local resources (Chrome browser, filesystem, GPU, etc.) can't run inside containers or remote environments. This proxy bridges the gap:
-
-```
-MCP Client (container/remote)
-    |  stdio
-Proxy Server (same machine as client)
-    |  HTTP via Cloudflare Tunnel
-Host Agent (machine with the resources)
-    |  stdio
-Real MCP Servers (chrome-devtools, filesystem, etc.)
-```
-
-## Quick start
-
-### 1. Start the host agent
-
-On the machine where your MCP servers run:
-
-```bash
-npx -p @silver886/mcp-proxy host --config config.json --tunnel
-```
-
-Example `config.json`:
-
-```json
-{
-  "servers": {
-    "chrome-devtools": {
-      "command": "npx",
-      "args": ["-y", "chrome-devtools-mcp@latest"],
-      "shell": true
-    },
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
-      "shell": true
-    }
-  }
-}
-```
-
-The host agent prints a tunnel URL and auth token. Keep it running.
-
-### 2. Configure your MCP client
-
-Add the proxy as a stdio MCP server. The client launches it automatically.
-
-**Claude Code** (`claude mcp add` or `.claude.json`):
-
-```json
-{
-  "mcpServers": {
-    "chrome-devtools": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "-p", "@silver886/mcp-proxy", "proxy"]
-    }
-  }
-}
-```
-
-**Cursor / Windsurf / other MCP clients** — same pattern, add as a stdio server with `npx -p @silver886/mcp-proxy proxy` as the command.
-
-### 3. Pair
-
-When the MCP client spawns the proxy, the proxy prints a setup URL to stderr:
-
-```
-Configure at: https://mcp-proxy.pages.dev/setup.html#code=...&key=...
-```
-
-Open the URL in a browser. Enter the tunnel URL and auth token from step 1, discover servers, and select tools. The proxy picks up the config automatically and starts forwarding MCP requests.
-
-## Architecture
-
-### Components
-
-| Component | Role | Runs on |
-|-----------|------|---------|
-| **Host Agent** (`host`) | HTTP-to-stdio bridge. Spawns MCP servers, manages sessions, serves MCP Streamable HTTP. | Machine with resources |
-| **Proxy Server** (`proxy`) | Stdio MCP server that forwards requests to the host agent via tunnel. | Machine with MCP client |
-| **Config Page** (Cloudflare Pages) | Device-code pairing. Stores encrypted config in KV with 15-min TTL. | Cloudflare edge |
-
-### Pairing flow
-
-```
-1. MCP client spawns the proxy (stdio)
-2. Proxy generates pairing code + encryption key, polls Pages RPC
-3. User opens setup URL in browser (code + key in URL hash, never sent to server)
-4. User enters tunnel URL + auth token, discovers servers, selects tools
-5. Setup page encrypts config client-side, stores ciphertext in KV via RPC
-6. Proxy polls, decrypts config, discovers servers, starts forwarding
-```
-
-### Protocol
-
-- **Client <-> Proxy**: stdio (JSON-RPC, newline-delimited)
-- **Proxy <-> Host Agent**: HTTP via Cloudflare Tunnel (MCP Streamable HTTP)
-- **Host Agent <-> MCP Servers**: stdio (JSON-RPC, newline-delimited)
-- **Session management**: `Mcp-Session-Id` header between proxy and host agent
-
-## Configuration
-
-### Host agent config
-
-```json
-{
-  "servers": {
-    "server-name": {
-      "command": "node",
-      "args": ["path/to/server.js"],
-      "env": { "API_KEY": "..." },
-      "shell": false
-    }
-  },
-  "host": "127.0.0.1",
-  "port": 6270
-}
-```
-
-| Field | Default | Description |
-|-------|---------|-------------|
-| `servers` | _(required)_ | Map of server name to spawn config |
-| `servers.*.command` | _(required)_ | Executable to spawn |
-| `servers.*.args` | `[]` | Command arguments |
-| `servers.*.env` | `{}` | Extra environment variables |
-| `servers.*.shell` | `false` | Use shell for PATH resolution (set `true` for `npx`, etc.) |
-| `host` | `127.0.0.1` | Listen address |
-| `port` | `6270` | Listen port |
-
-### CLI
-
-**Host agent:**
-
-```
-host [options]
-
---config <path>    Config file (default: config.json)
---tunnel           Start a Cloudflare quick tunnel
---timeout <ms>     MCP request timeout (default: 120000)
-```
-
-**Proxy server:**
-
-```
-proxy [options]
-
---pages-url <url>   Config page URL (default: https://mcp-proxy.pages.dev)
-```
-
-Also reads `MCP_PROXY_PAGES_URL` environment variable.
-
-## Error codes
-
-| Code | Name | Meaning |
-|------|------|---------|
-| `-32603` | `INTERNAL` | Unhandled server error |
-| `-32001` | `PROXY_NOT_CONFIGURED` | Proxy hasn't been paired yet |
-| `-32002` | `HOST_UNREACHABLE` | Can't reach host agent via tunnel |
-| `-32003` | `PROCESS_EXITED` | MCP server child process died |
-| `-32004` | `PROCESS_NOT_RUNNING` | Child process isn't running |
-| `-32005` | `REQUEST_TIMEOUT` | MCP server didn't respond in time |
-
-## Development
-
-```bash
-pnpm install
-pnpm run build
-pnpm publish --access public --no-git-checks
-```
+# MCP Proxy
+
+MCP proxy bridge that forwards [Model Context Protocol](https://modelcontextprotocol.io/) requests across network boundaries via [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/).
+
+Works with any MCP client (Claude Code, Cursor, Windsurf, Cline, etc.) and any OS.
+
+## Why
+
+MCP servers that need local resources (Chrome browser, filesystem, GPU, etc.) can't run inside containers or remote environments. This proxy bridges the gap:
+
+```
+MCP Client (container/remote)
+    |  stdio
+Proxy Server (same machine as client)
+    |  HTTP via Cloudflare Tunnel
+Host Agent (machine with the resources)
+    |  stdio
+Real MCP Servers (chrome-devtools, filesystem, etc.)
+```
+
+## Quick start
+
+### 1. Start the host agent
+
+On the machine where your MCP servers run:
+
+```bash
+npx -p @silver886/mcp-proxy host --config config.json --tunnel
+```
+
+Example `config.json`:
+
+```json
+{
+  "servers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest"],
+      "shell": true
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
+      "shell": true
+    }
+  }
+}
+```
+
+The host agent prints a tunnel URL and auth token. Keep it running.
+
+### 2. Configure your MCP client
+
+Add the proxy as a stdio MCP server. The client launches it automatically.
+
+**Claude Code** (`claude mcp add` or `.claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "-p", "@silver886/mcp-proxy", "proxy"]
+    }
+  }
+}
+```
+
+**Cursor / Windsurf / other MCP clients** — same pattern, add as a stdio server with `npx -p @silver886/mcp-proxy proxy` as the command.
+
+### 3. Pair
+
+When the MCP client spawns the proxy, the proxy prints a setup URL to stderr:
+
+```
+Configure at: https://mcp-proxy.pages.dev/setup.html#code=...&key=...
+```
+
+Open the URL in a browser. Enter the tunnel URL and auth token from step 1, discover servers, and select tools. The proxy picks up the config automatically and starts forwarding MCP requests.
+
+## Architecture
+
+### Components
+
+| Component | Role | Runs on |
+|-----------|------|---------|
+| **Host Agent** (`host`) | HTTP-to-stdio bridge. Spawns MCP servers, manages sessions, serves MCP Streamable HTTP. | Machine with resources |
+| **Proxy Server** (`proxy`) | Stdio MCP server that forwards requests to the host agent via tunnel. | Machine with MCP client |
+| **Config Page** (Cloudflare Pages) | Device-code pairing. Stores encrypted config in KV with 15-min TTL. | Cloudflare edge |
+
+### Pairing flow
+
+```
+1. MCP client spawns the proxy (stdio)
+2. Proxy generates pairing code + encryption key, polls Pages RPC
+3. User opens setup URL in browser (code + key in URL hash, never sent to server)
+4. User enters tunnel URL + auth token, discovers servers, selects tools
+5. Setup page encrypts config client-side, stores ciphertext in KV via RPC
+6. Proxy polls, decrypts config, discovers servers, starts forwarding
+```
+
+### Protocol
+
+- **Client <-> Proxy**: stdio (JSON-RPC, newline-delimited)
+- **Proxy <-> Host Agent**: HTTP via Cloudflare Tunnel (MCP Streamable HTTP)
+- **Host Agent <-> MCP Servers**: stdio (JSON-RPC, newline-delimited)
+- **Session management**: `Mcp-Session-Id` header between proxy and host agent
+
+## Configuration
+
+### Host agent config
+
+```json
+{
+  "servers": {
+    "server-name": {
+      "command": "node",
+      "args": ["path/to/server.js"],
+      "env": { "API_KEY": "..." },
+      "shell": false
+    }
+  },
+  "host": "127.0.0.1",
+  "port": 6270
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `servers` | _(required)_ | Map of server name to spawn config |
+| `servers.*.command` | _(required)_ | Executable to spawn |
+| `servers.*.args` | `[]` | Command arguments |
+| `servers.*.env` | `{}` | Extra environment variables |
+| `servers.*.shell` | `false` | Use shell for PATH resolution (set `true` for `npx`, etc.) |
+| `host` | `127.0.0.1` | Listen address |
+| `port` | `6270` | Listen port |
+
+### CLI
+
+**Host agent:**
+
+```
+host [options]
+
+--config <path>    Config file (default: config.json)
+--tunnel           Start a Cloudflare quick tunnel
+--timeout <ms>     MCP request timeout (default: 120000)
+```
+
+**Proxy server:**
+
+```
+proxy [options]
+
+--pages-url <url>   Config page URL (default: https://mcp-proxy.pages.dev)
+```
+
+Also reads `MCP_PROXY_PAGES_URL` environment variable.
+
+## Error codes
+
+| Code | Name | Meaning |
+|------|------|---------|
+| `-32603` | `INTERNAL` | Unhandled server error |
+| `-32001` | `PROXY_NOT_CONFIGURED` | Proxy hasn't been paired yet |
+| `-32002` | `HOST_UNREACHABLE` | Can't reach host agent via tunnel |
+| `-32003` | `PROCESS_EXITED` | MCP server child process died |
+| `-32004` | `PROCESS_NOT_RUNNING` | Child process isn't running |
+| `-32005` | `REQUEST_TIMEOUT` | MCP server didn't respond in time |
+
+## Development
+
+```bash
+pnpm install
+pnpm run build
+pnpm publish --access public --no-git-checks
+```

package/mcp/dist/proxy.js

@@ -111,37 +111,75 @@ class ProxyServer {
             return;
         }
         const id = parsed.id ?? null;
+        // Handle client notifications (no id)
         if (id === null)
             return;
-        if (!this.config) {
-            process.stdout.write((0, protocol_js_1.jsonRpcError)(protocol_js_1.ErrorCode.PROXY_NOT_CONFIGURED, `Visit ${this.setupUrl}`, id) + "\n");
-            return;
-        }
         switch (parsed.method) {
+            // initialize always succeeds — proxy is a valid server even before pairing
             case "initialize":
                 this.sendResult(id, {
-                    protocolVersion: "2024-11-05",
-                    capabilities: { tools: {} },
+                    protocolVersion: protocol_js_1.MCP_PROTOCOL_VERSION,
+                    capabilities: { tools: { listChanged: true }, prompts: {}, logging: {} },
                     serverInfo: { name: protocol_js_1.PACKAGE_NAME, version: protocol_js_1.PACKAGE_VERSION },
                 });
                 return;
+            // tools/list returns configure tool before pairing, real tools after
             case "tools/list":
+                if (!this.config) {
+                    this.sendResult(id, { tools: [{
+                                name: "configure",
+                                description: "Set up or reconfigure the MCP proxy connection. Returns the setup URL.",
+                                inputSchema: { type: "object", properties: {} },
+                            }] });
+                    return;
+                }
                 if (!this.initialized)
                     await this.discoverServers();
                 this.sendResult(id, { tools: this.getFilteredTools() });
                 return;
-            case "tools/call":
+            // prompts/list always available
+            case "prompts/list":
+                this.sendResult(id, { prompts: [{
+                            name: "configure",
+                            description: "Set up or reconfigure the MCP proxy connection",
+                        }] });
+                return;
+            case "prompts/get": {
+                const promptName = parsed.params?.name;
+                if (promptName === "configure") {
+                    const text = await this.handleConfigure();
+                    this.sendResult(id, {
+                        messages: [{ role: "user", content: { type: "text", text } }],
+                    });
+                }
+                else {
+                    this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, `Unknown prompt: ${promptName}`, id);
+                }
+                return;
+            }
+            case "tools/call": {
+                const toolName = parsed.params?.name;
+                if (toolName === "configure") {
+                    const text = await this.handleConfigure();
+                    this.sendResult(id, { content: [{ type: "text", text }] });
+                    return;
+                }
+                if (!this.config) {
+                    this.sendError(protocol_js_1.ErrorCode.PROXY_NOT_CONFIGURED, `Visit ${this.setupUrl}`, id);
+                    return;
+                }
                 await this.handleToolCall(id, parsed.params);
                 return;
+            }
             default:
-                process.stdout.write((0, protocol_js_1.jsonRpcError)(-32601, `Method not found: ${parsed.method}`, id) + "\n");
+                this.sendError(protocol_js_1.ErrorCode.METHOD_NOT_FOUND, parsed.method, id);
         }
     }
     async handleToolCall(id, params) {
         const prefixedName = params.name;
         const serverName = this.toolRoute.get(prefixedName);
         if (!serverName) {
-            process.stdout.write((0, protocol_js_1.jsonRpcError)(-32602, `Unknown tool: ${prefixedName}`, id) + "\n");
+            this.sendError(protocol_js_1.ErrorCode.INVALID_PARAMS, `Unknown tool: ${prefixedName}`, id);
             return;
         }
         const originalName = prefixedName.slice(serverName.length + TOOL_SEPARATOR.length);
@@ -164,7 +202,7 @@ class ProxyServer {
                 process.stdout.write(responseBody + "\n");
         }
         catch (err) {
-            process.stdout.write((0, protocol_js_1.jsonRpcError)(protocol_js_1.ErrorCode.HOST_UNREACHABLE, err.message, id) + "\n");
+            this.sendError(protocol_js_1.ErrorCode.HOST_UNREACHABLE, err.message, id);
         }
     }
     getFilteredTools() {
@@ -230,7 +268,7 @@ class ProxyServer {
                     id: `init-${name}`,
                     method: "initialize",
                     params: {
-                        protocolVersion: "2024-11-05",
+                        protocolVersion: protocol_js_1.MCP_PROTOCOL_VERSION,
                         capabilities: {},
                         clientInfo: { name: protocol_js_1.PACKAGE_NAME, version: protocol_js_1.PACKAGE_VERSION },
                     },
@@ -261,6 +299,19 @@ class ProxyServer {
     sendResult(id, result) {
         process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n");
     }
+    sendError(code, detail, id) {
+        process.stdout.write((0, protocol_js_1.jsonRpcError)(code, detail, id) + "\n");
+    }
+    sendNotification(method) {
+        process.stdout.write(JSON.stringify({ jsonrpc: "2.0", method }) + "\n");
+    }
+    async handleConfigure() {
+        if (this.config) {
+            await this.startPairing();
+            this.sendNotification("notifications/tools/list_changed");
+        }
+        return `Open this URL in your browser to set up the MCP Proxy:\n\n${this.setupUrl}\n\nThe proxy will connect automatically once setup is complete.`;
+    }
     async startPairing() {
         if (this.pollTimer)
             clearInterval(this.pollTimer);
@@ -290,6 +341,8 @@ class ProxyServer {
         this.pollTimer = setInterval(() => this.pollConfig(), POLL_INTERVAL);
     }
     async pollConfig() {
+        if (this.config)
+            return; // Already paired — guard against overlapping async polls
         try {
             const { aesKey, codeId, authHash } = await this.ensureDerivedKeys();
             const result = await rpc(this.pagesUrl, codeId, authHash, "read");
@@ -304,6 +357,7 @@ class ProxyServer {
                     this.pollTimer = null;
                     process.stderr.write(`  Paired! tunnel=${data.tunnelUrl}\n`);
                     await this.discoverServers();
+                    this.sendNotification("notifications/tools/list_changed");
                 }
             }
         }

package/mcp/dist/shared/generated.d.ts

@@ -1,2 +1,2 @@
 export declare const PACKAGE_NAME = "@silver886/mcp-proxy";
-export declare const PACKAGE_VERSION = "0.1.1";
+export declare const PACKAGE_VERSION = "0.1.3";

package/mcp/dist/shared/generated.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PACKAGE_VERSION = exports.PACKAGE_NAME = void 0;
 exports.PACKAGE_NAME = "@silver886/mcp-proxy";
-exports.PACKAGE_VERSION = "0.1.1";
+exports.PACKAGE_VERSION = "0.1.3";

package/mcp/dist/shared/protocol.d.ts

@@ -1,9 +1,12 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 export { PACKAGE_NAME, PACKAGE_VERSION } from "./generated.js";
+export declare const MCP_PROTOCOL_VERSION = "2024-11-05";
 export declare const DEFAULT_HOST = "127.0.0.1";
 export declare const DEFAULT_PORT = 6270;
 export declare const DEFAULT_PAGES_URL = "https://mcp-proxy.pages.dev";
 export declare const ErrorCode: {
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
     readonly INTERNAL: -32603;
     readonly PROXY_NOT_CONFIGURED: -32001;
     readonly HOST_UNREACHABLE: -32002;
@@ -12,6 +15,8 @@ export declare const ErrorCode: {
     readonly REQUEST_TIMEOUT: -32005;
 };
 export declare const ErrorMessage: {
+    readonly [-32601]: "Method not found";
+    readonly [-32602]: "Invalid params";
     readonly [-32603]: "Internal error";
     readonly [-32001]: "Proxy not configured";
     readonly [-32002]: "Host agent unreachable";

package/mcp/dist/shared/protocol.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LineBuffer = exports.ErrorMessage = exports.ErrorCode = exports.DEFAULT_PAGES_URL = exports.DEFAULT_PORT = exports.DEFAULT_HOST = exports.PACKAGE_VERSION = exports.PACKAGE_NAME = void 0;
+exports.LineBuffer = exports.ErrorMessage = exports.ErrorCode = exports.DEFAULT_PAGES_URL = exports.DEFAULT_PORT = exports.DEFAULT_HOST = exports.MCP_PROTOCOL_VERSION = exports.PACKAGE_VERSION = exports.PACKAGE_NAME = void 0;
 exports.jsonRpcError = jsonRpcError;
 exports.readBody = readBody;
 exports.getArg = getArg;
@@ -9,11 +9,14 @@ const node_http_1 = require("node:http");
 var generated_js_1 = require("./generated.js");
 Object.defineProperty(exports, "PACKAGE_NAME", { enumerable: true, get: function () { return generated_js_1.PACKAGE_NAME; } });
 Object.defineProperty(exports, "PACKAGE_VERSION", { enumerable: true, get: function () { return generated_js_1.PACKAGE_VERSION; } });
+exports.MCP_PROTOCOL_VERSION = "2024-11-05";
 exports.DEFAULT_HOST = "127.0.0.1";
 exports.DEFAULT_PORT = 6270;
 exports.DEFAULT_PAGES_URL = "https://mcp-proxy.pages.dev";
-// JSON-RPC error codes (-32000 to -32099 = server-defined, -32603 = spec internal error)
+// JSON-RPC error codes: -32600..-32603 = spec-defined, -32000..-32099 = server-defined
 exports.ErrorCode = {
+    METHOD_NOT_FOUND: -32601, // JSON-RPC spec: method not found
+    INVALID_PARAMS: -32602, // JSON-RPC spec: invalid params
     INTERNAL: -32603, // JSON-RPC spec: internal error
     PROXY_NOT_CONFIGURED: -32001, // Proxy has not been paired yet
     HOST_UNREACHABLE: -32002, // Cannot reach the host agent via tunnel
@@ -22,6 +25,8 @@ exports.ErrorCode = {
     REQUEST_TIMEOUT: -32005, // MCP server did not respond in time
 };
 exports.ErrorMessage = {
+    [exports.ErrorCode.METHOD_NOT_FOUND]: "Method not found",
+    [exports.ErrorCode.INVALID_PARAMS]: "Invalid params",
     [exports.ErrorCode.INTERNAL]: "Internal error",
     [exports.ErrorCode.PROXY_NOT_CONFIGURED]: "Proxy not configured",
     [exports.ErrorCode.HOST_UNREACHABLE]: "Host agent unreachable",

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@silver886/mcp-proxy",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "MCP proxy bridge: forward MCP requests across network boundaries via Cloudflare tunnel",
-  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/silver886/mcp-proxy.git"
+  },
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -13,6 +16,15 @@
     "wsl",
     "docker"
   ],
+  "author": {
+    "name": "L",
+    "email": "11664880+silver886@users.noreply.github.com"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/silver886/mcp-proxy/issues"
+  },
+  "homepage": "https://github.com/silver886/mcp-proxy#readme",
   "bin": {
     "host": "mcp/dist/host.js",
     "proxy": "mcp/dist/proxy.js"