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

package/README.md

@@ -0,0 +1,60 @@
+# @diegoaltoworks/localize-remote-mcp-server
+
+Bridge any remote HTTP MCP server into Claude Desktop.
+
+## Why
+
+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.
+
+## Setup
+
+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"
+      ]
+    }
+  }
+}
+```
+
+3. Restart Claude Desktop.
+
+That's it. Claude Desktop will launch the bridge process in the background and your remote server's tools will appear in Claude.
+
+## How it works
+
+When Claude Desktop starts, it runs the `npx` command from your config. The bridge process:
+
+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
+
+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
+```
+
+This is not needed for Claude Desktop.
+
+## What it does
+
+- 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.0",
+  "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();
+  });
+}