@diegoaltoworks/localize-remote-mcp-server 1.0.1 → 1.0.2

package/README.md

@@ -1,40 +1,60 @@
 # @diegoaltoworks/localize-remote-mcp-server
 
-Proxy a remote HTTP MCP server to localhost.
+Bridge any remote HTTP MCP server into Claude Desktop.
 
 ## Why
 
-Claude Desktop currently only supports connecting to local MCP servers. If your MCP server is hosted remotely over HTTP, Claude Desktop can't reach it directly. This project bridges that gap — it runs a lightweight local proxy that forwards all MCP traffic to your remote server, letting Claude Desktop (and any other client with the same limitation) work with remote MCP servers as if they were local.
+Claude Desktop only supports MCP servers that run locally as commands (stdio transport). It cannot connect to remote MCP servers over HTTP. This package bridges that gap — you configure it in Claude Desktop's config file, Claude launches it automatically, and it translates between stdio and your remote server's HTTP endpoint. You never run this yourself.
 
-## Usage
+## Setup
 
-```bash
-npx @diegoaltoworks/localize-remote-mcp-server --port 6969 https://example.com/mcp
+1. Open your Claude Desktop config file `claude_desktop_config.json`:
+   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+2. Add your remote MCP server to the `mcpServers` section. Replace the URL with your remote server's MCP endpoint:
+
+```json
+{
+  "mcpServers": {
+    "my-remote-server": {
+      "command": "npx",
+      "args": [
+        "@diegoaltoworks/localize-remote-mcp-server",
+        "https://my-remote-server.example.com/mcp"
+      ]
+    }
+  }
+}
 ```
 
-This starts a local server at `http://localhost:6969/mcp` that proxies all MCP requests to the remote server.
+3. Restart Claude Desktop.
 
-## Options
+That's it. Claude Desktop will launch the bridge process in the background and your remote server's tools will appear in Claude.
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `-p, --port` | Local port to listen on | `3000` |
-| `-h, --help` | Show help message | |
+## How it works
 
-## Example
+When Claude Desktop starts, it runs the `npx` command from your config. The bridge process:
 
-```bash
-# Proxy a remote MCP server to localhost:6969
-npx @diegoaltoworks/localize-remote-mcp-server --port 6969 https://london-toll-checker.diegoalto.app/mcp
+1. Receives JSON-RPC messages from Claude Desktop over stdin
+2. Forwards them as HTTP POST requests to your remote MCP server
+3. Parses the response (JSON or SSE) and writes it back to stdout
 
-# Proxying https://london-toll-checker.diegoalto.app/mcp -> http://localhost:6969/mcp
+Claude Desktop sees it as a normal local MCP server. Your remote server receives normal HTTP MCP requests. Neither side knows about the bridge.
+
+## HTTP proxy mode
+
+If you need a local HTTP proxy instead of stdio (for other MCP clients), you can run it directly with `--port`:
+
+```bash
+npx @diegoaltoworks/localize-remote-mcp-server --port 6969 https://my-remote-server.example.com/mcp
 ```
 
-Then point your MCP client at `http://localhost:6969/mcp` instead of the remote URL.
+This is not needed for Claude Desktop.
 
 ## What it does
 
-- Proxies POST and GET requests to the remote MCP server
-- Streams SSE responses back to the client
+- Bridges stdio and HTTP MCP transports
+- Parses SSE responses from remote servers
 - Forwards authorization headers and MCP session IDs
 - Zero dependencies — just Node.js

package/bin/cli.js

@@ -1,11 +1,10 @@
 #!/usr/bin/env node
 
 import { parseArgs } from "node:util";
-import { createProxy } from "../src/proxy.js";
 
 const { values, positionals } = parseArgs({
   options: {
-    port: { type: "string", short: "p", default: "3000" },
+    port: { type: "string", short: "p" },
     help: { type: "boolean", short: "h", default: false },
   },
   allowPositionals: true,
@@ -15,19 +14,33 @@ if (values.help || positionals.length === 0) {
   console.log(`
 Usage: localize-remote-mcp-server [options] <remote-url>
 
-Proxy a remote HTTP MCP server to localhost.
+Proxy a remote HTTP MCP server for local use.
+
+Modes:
+  Default (stdio)    Bridges stdin/stdout to the remote server.
+                     Use this with Claude Desktop.
+  --port <port>      Runs a local HTTP proxy server instead.
 
 Options:
-  -p, --port <port>  Local port to listen on (default: 3000)
+  -p, --port <port>  Local port for HTTP proxy mode
   -h, --help         Show this help message
 
-Example:
-  npx @diegoaltoworks/localize-remote-mcp-server --port 6969 https://example.com/mcp
+Examples:
+  # stdio mode (for Claude Desktop)
+  npx @diegoaltoworks/localize-remote-mcp-server https://my-remote-server.example.com/mcp
+
+  # HTTP proxy mode
+  npx @diegoaltoworks/localize-remote-mcp-server --port 6969 https://my-remote-server.example.com/mcp
 `);
   process.exit(values.help ? 0 : 1);
 }
 
 const remoteUrl = positionals[0];
-const port = parseInt(values.port, 10);
 
-createProxy({ remoteUrl, port });
+if (values.port) {
+  const { createProxy } = await import("../src/proxy.js");
+  createProxy({ remoteUrl, port: parseInt(values.port, 10) });
+} else {
+  const { createStdioBridge } = await import("../src/stdio.js");
+  createStdioBridge({ remoteUrl });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegoaltoworks/localize-remote-mcp-server",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Proxy a remote HTTP MCP server to localhost",
   "bin": {
     "localize-remote-mcp-server": "./bin/cli.js"

package/src/stdio.js

@@ -0,0 +1,85 @@
+import { createInterface } from "node:readline";
+
+export function createStdioBridge({ remoteUrl }) {
+  let sessionId = null;
+  let pending = 0;
+  let stdinClosed = false;
+
+  const rl = createInterface({ input: process.stdin });
+
+  function maybeExit() {
+    if (stdinClosed && pending === 0) process.exit(0);
+  }
+
+  rl.on("line", async (line) => {
+    if (!line.trim()) return;
+
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      return;
+    }
+
+    pending++;
+
+    const headers = {
+      "content-type": "application/json",
+      accept: "application/json, text/event-stream",
+    };
+    if (sessionId) {
+      headers["mcp-session-id"] = sessionId;
+    }
+
+    try {
+      const response = await fetch(remoteUrl, {
+        method: "POST",
+        headers,
+        body: line,
+      });
+
+      // Capture session ID from response
+      const newSessionId = response.headers.get("mcp-session-id");
+      if (newSessionId) {
+        sessionId = newSessionId;
+      }
+
+      const contentType = response.headers.get("content-type") || "";
+
+      if (contentType.includes("text/event-stream")) {
+        // Parse SSE and extract JSON-RPC messages
+        const text = await response.text();
+        for (const sseLine of text.split("\n")) {
+          if (sseLine.startsWith("data: ")) {
+            const data = sseLine.slice(6).trim();
+            if (data) {
+              process.stdout.write(data + "\n");
+            }
+          }
+        }
+      } else {
+        // Plain JSON response
+        const text = await response.text();
+        if (text.trim()) {
+          process.stdout.write(text.trim() + "\n");
+        }
+      }
+    } catch (err) {
+      // Write JSON-RPC error to stdout
+      const errorResponse = {
+        jsonrpc: "2.0",
+        error: { code: -32000, message: `Proxy error: ${err.message}` },
+        id: message.id ?? null,
+      };
+      process.stdout.write(JSON.stringify(errorResponse) + "\n");
+    } finally {
+      pending--;
+      maybeExit();
+    }
+  });
+
+  rl.on("close", () => {
+    stdinClosed = true;
+    maybeExit();
+  });
+}