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

package/README.md

@@ -1,40 +1,68 @@
-# @diegoaltoworks/localize-remote-mcp-server
+# Localize Remote MCP Server
 
-Proxy a remote HTTP MCP server to localhost.
+Bridge any remote HTTP MCP server into Claude Desktop.
 
-## Why
+## The problem
 
-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. The two transports are fundamentally incompatible:
 
-## Usage
+![The broken approach — Claude Desktop cannot connect directly to a remote HTTP/SSE MCP server](docs/mcp_broken_approach.svg)
 
-```bash
-npx @diegoaltoworks/localize-remote-mcp-server --port 6969 https://example.com/mcp
+## The solution
+
+This package bridges the 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 — Claude does.
+
+![The working solution — localize-remote-mcp-server acts as a local stdio bridge](docs/mcp_working_solution.svg)
+
+## 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"
+      ]
+    }
+  }
+}
 ```
 
-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
+
+Claude Desktop sees it as a normal local MCP server. Your remote server receives normal HTTP MCP requests. Neither side knows about the bridge.
 
-# Proxying https://london-toll-checker.diegoalto.app/mcp -> http://localhost:6969/mcp
+## 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,33 +1,48 @@
 #!/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" },
-    help: { type: "boolean", short: "h", default: false },
-  },
-  allowPositionals: true,
-});
-
-if (values.help || positionals.length === 0) {
-  console.log(`
-Usage: localize-remote-mcp-server [options] <remote-url>
-
-Proxy a remote HTTP MCP server to localhost.
-
-Options:
-  -p, --port <port>  Local port to listen on (default: 3000)
-  -h, --help         Show this help message
-
-Example:
-  npx @diegoaltoworks/localize-remote-mcp-server --port 6969 https://example.com/mcp
-`);
-  process.exit(values.help ? 0 : 1);
+"use strict";
+
+var args = process.argv.slice(2);
+var port = null;
+var remoteUrl = null;
+var help = false;
+
+for (var i = 0; i < args.length; i++) {
+  if (args[i] === "-h" || args[i] === "--help") {
+    help = true;
+  } else if (args[i] === "-p" || args[i] === "--port") {
+    port = parseInt(args[++i], 10);
+  } else if (!remoteUrl) {
+    remoteUrl = args[i];
+  }
 }
 
-const remoteUrl = positionals[0];
-const port = parseInt(values.port, 10);
+if (help || !remoteUrl) {
+  console.log("");
+  console.log("Usage: localize-remote-mcp-server [options] <remote-url>");
+  console.log("");
+  console.log("Proxy a remote HTTP MCP server for local use.");
+  console.log("");
+  console.log("Modes:");
+  console.log("  Default (stdio)    Bridges stdin/stdout to the remote server.");
+  console.log("                     Use this with Claude Desktop.");
+  console.log("  --port <port>      Runs a local HTTP proxy server instead.");
+  console.log("");
+  console.log("Options:");
+  console.log("  -p, --port <port>  Local port for HTTP proxy mode");
+  console.log("  -h, --help         Show this help message");
+  console.log("");
+  console.log("Examples:");
+  console.log("  npx @diegoaltoworks/localize-remote-mcp-server https://my-server.example.com/mcp");
+  console.log("  npx @diegoaltoworks/localize-remote-mcp-server --port 6969 https://my-server.example.com/mcp");
+  console.log("");
+  process.exit(help ? 0 : 1);
+}
 
-createProxy({ remoteUrl, port });
+if (port) {
+  var proxy = require("../src/proxy");
+  proxy.createProxy({ remoteUrl: remoteUrl, port: port });
+} else {
+  var stdio = require("../src/stdio");
+  stdio.createStdioBridge({ remoteUrl: remoteUrl });
+}

package/package.json

@@ -1,16 +1,22 @@
 {
   "name": "@diegoaltoworks/localize-remote-mcp-server",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Proxy a remote HTTP MCP server to localhost",
   "bin": {
     "localize-remote-mcp-server": "./bin/cli.js"
   },
-  "type": "module",
   "license": "MIT",
+  "engines": {
+    "node": ">=12"
+  },
   "files": [
-    "bin",
-    "src"
+    "bin/cli.js",
+    "src/proxy.js",
+    "src/stdio.js"
   ],
+  "scripts": {
+    "test": "node --test src/*.test.js bin/*.test.js"
+  },
   "keywords": [
     "mcp",
     "proxy",

package/src/proxy.js

@@ -1,84 +1,88 @@
-import { createServer } from "node:http";
+"use strict";
 
-export function createProxy({ remoteUrl, port }) {
-  const remote = new URL(remoteUrl);
-  const localPath = remote.pathname;
+var http = require("http");
+var https = require("https");
+var url = require("url");
 
-  const server = createServer(async (req, res) => {
-    // Only proxy requests to the MCP path
+function createProxy(opts) {
+  var remoteUrl = opts.remoteUrl;
+  var port = opts.port;
+  var parsed = url.parse(remoteUrl);
+  var localPath = parsed.pathname;
+  var mod = parsed.protocol === "https:" ? https : http;
+
+  var server = http.createServer(function (req, res) {
     if (req.url !== localPath) {
       res.writeHead(404, { "content-type": "text/plain" });
-      res.end(`Not found. MCP endpoint is at ${localPath}\n`);
+      res.end("Not found. MCP endpoint is at " + localPath + "\n");
       return;
     }
 
-    // MCP Streamable HTTP uses POST and GET
     if (req.method !== "POST" && req.method !== "GET") {
       res.writeHead(405, { "content-type": "text/plain" });
       res.end("Method not allowed.\n");
       return;
     }
 
-    try {
-      const body = req.method === "POST" ? await readBody(req) : undefined;
+    var bodyChunks = [];
+
+    req.on("data", function (chunk) {
+      bodyChunks.push(chunk);
+    });
+
+    req.on("end", function () {
+      var body = Buffer.concat(bodyChunks);
 
-      // Forward all relevant headers
-      const headers = {};
+      var reqHeaders = {
+        accept:
+          req.headers["accept"] || "application/json, text/event-stream",
+      };
       if (req.headers["content-type"]) {
-        headers["content-type"] = req.headers["content-type"];
+        reqHeaders["content-type"] = req.headers["content-type"];
       }
-      // MCP Streamable HTTP requires accepting both JSON and SSE
-      headers["accept"] =
-        req.headers["accept"] || "application/json, text/event-stream";
       if (req.headers["authorization"]) {
-        headers["authorization"] = req.headers["authorization"];
+        reqHeaders["authorization"] = req.headers["authorization"];
       }
       if (req.headers["mcp-session-id"]) {
-        headers["mcp-session-id"] = req.headers["mcp-session-id"];
+        reqHeaders["mcp-session-id"] = req.headers["mcp-session-id"];
+      }
+      if (req.method === "POST") {
+        reqHeaders["content-length"] = body.length;
       }
 
-      const response = await fetch(remoteUrl, {
+      var reqOpts = {
+        hostname: parsed.hostname,
+        port: parsed.port,
+        path: parsed.path,
         method: req.method,
-        headers,
-        body,
+        headers: reqHeaders,
+      };
+
+      var proxyReq = mod.request(reqOpts, function (proxyRes) {
+        res.writeHead(proxyRes.statusCode, proxyRes.headers);
+        proxyRes.pipe(res);
       });
 
-      // Forward status and headers back
-      const responseHeaders = {};
-      for (const [key, value] of response.headers) {
-        responseHeaders[key] = value;
-      }
-      res.writeHead(response.status, responseHeaders);
+      proxyReq.on("error", function (err) {
+        console.error("Proxy error:", err.message);
+        res.writeHead(502, { "content-type": "text/plain" });
+        res.end("Bad gateway: " + err.message + "\n");
+      });
 
-      // Stream the response body back
-      if (response.body) {
-        const reader = response.body.getReader();
-        while (true) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          res.write(value);
-        }
+      if (req.method === "POST") {
+        proxyReq.write(body);
       }
-      res.end();
-    } catch (err) {
-      console.error("Proxy error:", err.message);
-      res.writeHead(502, { "content-type": "text/plain" });
-      res.end(`Bad gateway: ${err.message}\n`);
-    }
+      proxyReq.end();
+    });
   });
 
-  server.listen(port, () => {
-    console.log(`Proxying ${remoteUrl} → http://localhost:${port}${localPath}`);
+  server.listen(port, function () {
+    console.log(
+      "Proxying " + remoteUrl + " → http://localhost:" + port + localPath
+    );
   });
 
   return server;
 }
 
-function readBody(req) {
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    req.on("data", (chunk) => chunks.push(chunk));
-    req.on("end", () => resolve(Buffer.concat(chunks)));
-    req.on("error", reject);
-  });
-}
+exports.createProxy = createProxy;

package/src/stdio.js

@@ -0,0 +1,110 @@
+"use strict";
+
+var readline = require("readline");
+var https = require("https");
+var http = require("http");
+var url = require("url");
+
+function createStdioBridge(opts) {
+  var remoteUrl = opts.remoteUrl;
+  var sessionId = null;
+  var pending = 0;
+  var stdinClosed = false;
+
+  var rl = readline.createInterface({ input: process.stdin });
+
+  function maybeExit() {
+    if (stdinClosed && pending === 0) process.exit(0);
+  }
+
+  rl.on("line", function (line) {
+    if (!line.trim()) return;
+
+    var message;
+    try {
+      message = JSON.parse(line);
+    } catch (e) {
+      return;
+    }
+
+    pending++;
+
+    var parsed = url.parse(remoteUrl);
+    var mod = parsed.protocol === "https:" ? https : http;
+
+    var reqHeaders = {
+      "content-type": "application/json",
+      accept: "application/json, text/event-stream",
+      "content-length": Buffer.byteLength(line),
+    };
+    if (sessionId) {
+      reqHeaders["mcp-session-id"] = sessionId;
+    }
+
+    var reqOpts = {
+      hostname: parsed.hostname,
+      port: parsed.port,
+      path: parsed.path,
+      method: "POST",
+      headers: reqHeaders,
+    };
+
+    var req = mod.request(reqOpts, function (res) {
+      var newSessionId = res.headers["mcp-session-id"];
+      if (newSessionId) {
+        sessionId = newSessionId;
+      }
+
+      var contentType = res.headers["content-type"] || "";
+      var chunks = [];
+
+      res.on("data", function (chunk) {
+        chunks.push(chunk);
+      });
+
+      res.on("end", function () {
+        var body = Buffer.concat(chunks).toString();
+
+        if (contentType.indexOf("text/event-stream") !== -1) {
+          var lines = body.split("\n");
+          for (var i = 0; i < lines.length; i++) {
+            if (lines[i].indexOf("data: ") === 0) {
+              var data = lines[i].slice(6).trim();
+              if (data) {
+                process.stdout.write(data + "\n");
+              }
+            }
+          }
+        } else {
+          if (body.trim()) {
+            process.stdout.write(body.trim() + "\n");
+          }
+        }
+
+        pending--;
+        maybeExit();
+      });
+    });
+
+    req.on("error", function (err) {
+      var errorResponse = {
+        jsonrpc: "2.0",
+        error: { code: -32000, message: "Proxy error: " + err.message },
+        id: message.id != null ? message.id : null,
+      };
+      process.stdout.write(JSON.stringify(errorResponse) + "\n");
+      pending--;
+      maybeExit();
+    });
+
+    req.write(line);
+    req.end();
+  });
+
+  rl.on("close", function () {
+    stdinClosed = true;
+    maybeExit();
+  });
+}
+
+exports.createStdioBridge = createStdioBridge;