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

package/README.md

@@ -1,10 +1,18 @@
-# @diegoaltoworks/localize-remote-mcp-server
+# Localize Remote MCP Server
 
 Bridge any remote HTTP MCP server into Claude Desktop.
 
-## Why
+## The problem
 
-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.
+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:
+
+![The broken approach — Claude Desktop cannot connect directly to a remote HTTP/SSE MCP server](docs/mcp_broken_approach.svg)
+
+## 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
 

package/bin/cli.js

@@ -1,46 +1,48 @@
 #!/usr/bin/env node
 
-import { parseArgs } from "node:util";
-
-const { values, positionals } = parseArgs({
-  options: {
-    port: { type: "string", short: "p" },
-    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 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 for HTTP proxy mode
-  -h, --help         Show this help message
-
-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);
+"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];
+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);
+}
 
-if (values.port) {
-  const { createProxy } = await import("../src/proxy.js");
-  createProxy({ remoteUrl, port: parseInt(values.port, 10) });
+if (port) {
+  var proxy = require("../src/proxy");
+  proxy.createProxy({ remoteUrl: remoteUrl, port: port });
 } else {
-  const { createStdioBridge } = await import("../src/stdio.js");
-  createStdioBridge({ remoteUrl });
+  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.2",
+  "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

@@ -1,85 +1,110 @@
-import { createInterface } from "node:readline";
+"use strict";
 
-export function createStdioBridge({ remoteUrl }) {
-  let sessionId = null;
-  let pending = 0;
-  let stdinClosed = false;
+var readline = require("readline");
+var https = require("https");
+var http = require("http");
+var url = require("url");
 
-  const rl = createInterface({ input: process.stdin });
+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", async (line) => {
+  rl.on("line", function (line) {
     if (!line.trim()) return;
 
-    let message;
+    var message;
     try {
       message = JSON.parse(line);
-    } catch {
+    } catch (e) {
       return;
     }
 
     pending++;
 
-    const headers = {
+    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) {
-      headers["mcp-session-id"] = sessionId;
+      reqHeaders["mcp-session-id"] = sessionId;
     }
 
-    try {
-      const response = await fetch(remoteUrl, {
-        method: "POST",
-        headers,
-        body: line,
-      });
+    var reqOpts = {
+      hostname: parsed.hostname,
+      port: parsed.port,
+      path: parsed.path,
+      method: "POST",
+      headers: reqHeaders,
+    };
 
-      // Capture session ID from response
-      const newSessionId = response.headers.get("mcp-session-id");
+    var req = mod.request(reqOpts, function (res) {
+      var newSessionId = res.headers["mcp-session-id"];
       if (newSessionId) {
         sessionId = newSessionId;
       }
 
-      const contentType = response.headers.get("content-type") || "";
+      var contentType = res.headers["content-type"] || "";
+      var chunks = [];
 
-      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");
+      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");
+          }
         }
-      } 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 = {
+
+        pending--;
+        maybeExit();
+      });
+    });
+
+    req.on("error", function (err) {
+      var errorResponse = {
         jsonrpc: "2.0",
-        error: { code: -32000, message: `Proxy error: ${err.message}` },
-        id: message.id ?? null,
+        error: { code: -32000, message: "Proxy error: " + err.message },
+        id: message.id != null ? message.id : null,
       };
       process.stdout.write(JSON.stringify(errorResponse) + "\n");
-    } finally {
       pending--;
       maybeExit();
-    }
+    });
+
+    req.write(line);
+    req.end();
   });
 
-  rl.on("close", () => {
+  rl.on("close", function () {
     stdinClosed = true;
     maybeExit();
   });
 }
+
+exports.createStdioBridge = createStdioBridge;