mcp-remote 0.0.10-3 → 0.0.11

package/README.md

@@ -16,17 +16,7 @@ That's where `mcp-remote` comes in. As soon as your chosen MCP client supports r
 
 ## Usage
 
-### Claude Desktop
-
-[Official Docs](https://modelcontextprotocol.io/quickstart/user)
-
-In order to add an MCP server to Claude Desktop you need to edit the configuration file located at:
-
-macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-
-Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-
-If it does not exist yet, [you may need to enable it under Settings > Developer](https://modelcontextprotocol.io/quickstart/user#2-add-the-filesystem-mcp-server).
+All the most popular MCP clients (Claude Desktop, Cursor & Windsurf) use the following config format:
 
 ```json
 {
@@ -34,7 +24,6 @@ If it does not exist yet, [you may need to enable it under Settings > Developer]
     "remote-example": {
       "command": "npx",
       "args": [
-        "-y",
         "mcp-remote",
         "https://remote.mcp.server/sse"
       ]
@@ -43,52 +32,75 @@ If it does not exist yet, [you may need to enable it under Settings > Developer]
 }
 ```
 
-Restart Claude Desktop to pick up the changes in the configuration file.
-Upon restarting, you should see a hammer icon in the bottom right corner
-of the input box.
-
-### Cursor
-
-[Official Docs](https://docs.cursor.com/context/model-context-protocol)
+### Flags
 
-Add the following configuration to `~/.cursor/mcp.json`:
+* If `npx` is producing errors, consider adding `-y` as the first argument to auto-accept the installation of the `mcp-remote` package.
 
 ```json
-{
-  "mcpServers": {
-    "remote-example": {
       "command": "npx",
       "args": [
-        "-y",
+        "-y"
         "mcp-remote",
         "https://remote.mcp.server/sse"
       ]
-    }
-  }
-}
 ```
 
-### Windsurf
+* To force `npx` to always check for an updated version of `mcp-remote`, add the `@latest` flag:
 
-[Official Docs](https://docs.codeium.com/windsurf/mcp)
+```json
+      "args": [
+        "mcp-remote@latest",
+        "https://remote.mcp.server/sse"
+      ]
+```
 
-Add the following configuration to `~/.codeium/windsurf/mcp_config.json`:
+* To force `mcp-remote` to ignore any existing access tokens and begin the authorization flow anew, pass `--clean`.
 
 ```json
-{
-  "mcpServers": {
-    "remote-example": {
-      "command": "npx",
       "args": [
-        "-y",
         "mcp-remote",
-        "https://remote.mcp.server/sse"
+        "https://remote.mcp.server/sse",
+        "--clean"
+      ]
+```
+
+* To change which port `mcp-remote` listens for an OAuth redirect (by default `3334`), add an additional argument after the server URL. Note that whatever port you specify, if it is unavailable an open port will be chosen at random.
+
+```json
+      "args": [
+        "mcp-remote",
+        "https://remote.mcp.server/sse",
+        "9696"
       ]
-    }
-  }
-}
 ```
 
+* To ensure that no
+
+### Claude Desktop
+
+[Official Docs](https://modelcontextprotocol.io/quickstart/user)
+
+In order to add an MCP server to Claude Desktop you need to edit the configuration file located at:
+
+* macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+* Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+If it does not exist yet, [you may need to enable it under Settings > Developer](https://modelcontextprotocol.io/quickstart/user#2-add-the-filesystem-mcp-server).
+
+Restart Claude Desktop to pick up the changes in the configuration file.
+Upon restarting, you should see a hammer icon in the bottom right corner
+of the input box.
+
+### Cursor
+
+[Official Docs](https://docs.cursor.com/context/model-context-protocol). The configuration file is located at `~/.cursor/mcp.json`.
+
+As of version `0.48.0`, Cursor supports unauthed SSE servers directly. If your MCP server is using the official MCP OAuth authorization protocol, you still need to add a **"command"** server and call `mcp-remote`.
+
+### Windsurf
+
+[Official Docs](https://docs.codeium.com/windsurf/mcp). The configuration file is located at `~/.codeium/windsurf/mcp_config.json`.
+
 ## Building Remote MCP Servers
 
 For instructions on building & deploying remote MCP servers, including acting as a valid OAuth client, see the following resources:
@@ -106,7 +118,17 @@ For more information about testing these servers, see also:
 
 Know of more resources you'd like to share? Please add them to this Readme and send a PR!
 
-## Debugging
+## Troubleshooting
+
+### Wipe your `~/.mcp-auth` directory
+
+`mcp-remote` stores all the credential information inside `~/.mcp-auth` (or wherever your `MCP_REMOTE_CONFIG_DIR` points to). If you're having persistent issues, try running:
+
+```sh
+rm -rf ~/.mcp-auth
+```
+
+Then restarting your MCP client.
 
 ### Check your Node version
 
@@ -141,3 +163,19 @@ this might look like:
   }
 }
 ```
+
+### Check the logs
+
+[Follow Claude Desktop logs in real-time](https://modelcontextprotocol.io/docs/tools/debugging#debugging-in-claude-desktop)
+
+MacOS / Linux:
+
+`tail -n 20 -F ~/Library/Logs/Claude/mcp*.log`
+
+For bash on WSL:
+
+`tail -n 20 -f "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log"`
+
+or Powershell:
+
+`Get-Content "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log" -Wait -Tail 20`

package/dist/chunk-W4HND3T7.js

@@ -0,0 +1,382 @@
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+
+// src/lib/node-oauth-client-provider.ts
+import open from "open";
+import {
+  OAuthClientInformationSchema,
+  OAuthTokensSchema
+} from "@modelcontextprotocol/sdk/shared/auth.js";
+
+// src/lib/mcp-auth-config.ts
+import crypto from "crypto";
+import path from "path";
+import os from "os";
+import fs from "fs/promises";
+var knownConfigFiles = [
+  "client_info.json",
+  "tokens.json",
+  "code_verifier.txt"
+];
+async function cleanServerConfig(serverUrlHash) {
+  console.error(`Cleaning configuration files for server: ${serverUrlHash}`);
+  for (const filename of knownConfigFiles) {
+    await deleteConfigFile(serverUrlHash, filename);
+  }
+}
+function getConfigDir() {
+  return process.env.MCP_REMOTE_CONFIG_DIR || path.join(os.homedir(), ".mcp-auth");
+}
+async function ensureConfigDir() {
+  try {
+    const configDir = getConfigDir();
+    await fs.mkdir(configDir, { recursive: true });
+  } catch (error) {
+    console.error("Error creating config directory:", error);
+    throw error;
+  }
+}
+function getServerUrlHash(serverUrl) {
+  return crypto.createHash("md5").update(serverUrl).digest("hex");
+}
+function getConfigFilePath(serverUrlHash, filename) {
+  const configDir = getConfigDir();
+  return path.join(configDir, `${serverUrlHash}_${filename}`);
+}
+async function deleteConfigFile(serverUrlHash, filename) {
+  try {
+    const filePath = getConfigFilePath(serverUrlHash, filename);
+    await fs.unlink(filePath);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      console.error(`Error deleting ${filename}:`, error);
+    }
+  }
+}
+async function readJsonFile(serverUrlHash, filename, schema, clean = false) {
+  try {
+    await ensureConfigDir();
+    if (clean) {
+      await deleteConfigFile(serverUrlHash, filename);
+      return void 0;
+    }
+    const filePath = getConfigFilePath(serverUrlHash, filename);
+    const content = await fs.readFile(filePath, "utf-8");
+    return await schema.parseAsync(JSON.parse(content));
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return void 0;
+    }
+    return void 0;
+  }
+}
+async function writeJsonFile(serverUrlHash, filename, data) {
+  try {
+    await ensureConfigDir();
+    const filePath = getConfigFilePath(serverUrlHash, filename);
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2), "utf-8");
+  } catch (error) {
+    console.error(`Error writing ${filename}:`, error);
+    throw error;
+  }
+}
+async function readTextFile(serverUrlHash, filename, errorMessage, clean = false) {
+  try {
+    await ensureConfigDir();
+    if (clean) {
+      await deleteConfigFile(serverUrlHash, filename);
+      throw new Error("File deleted due to clean flag");
+    }
+    const filePath = getConfigFilePath(serverUrlHash, filename);
+    return await fs.readFile(filePath, "utf-8");
+  } catch (error) {
+    throw new Error(errorMessage || `Error reading ${filename}`);
+  }
+}
+async function writeTextFile(serverUrlHash, filename, text) {
+  try {
+    await ensureConfigDir();
+    const filePath = getConfigFilePath(serverUrlHash, filename);
+    await fs.writeFile(filePath, text, "utf-8");
+  } catch (error) {
+    console.error(`Error writing ${filename}:`, error);
+    throw error;
+  }
+}
+
+// src/lib/node-oauth-client-provider.ts
+var NodeOAuthClientProvider = class {
+  /**
+   * Creates a new NodeOAuthClientProvider
+   * @param options Configuration options for the provider
+   */
+  constructor(options) {
+    this.options = options;
+    this.serverUrlHash = getServerUrlHash(options.serverUrl);
+    this.callbackPath = options.callbackPath || "/oauth/callback";
+    this.clientName = options.clientName || "MCP CLI Client";
+    this.clientUri = options.clientUri || "https://github.com/modelcontextprotocol/mcp-cli";
+    if (options.clean) {
+      cleanServerConfig(this.serverUrlHash).catch((err) => {
+        console.error("Error cleaning server config:", err);
+      });
+    }
+  }
+  serverUrlHash;
+  callbackPath;
+  clientName;
+  clientUri;
+  get redirectUrl() {
+    return `http://127.0.0.1:${this.options.callbackPort}${this.callbackPath}`;
+  }
+  get clientMetadata() {
+    return {
+      redirect_uris: [this.redirectUrl],
+      token_endpoint_auth_method: "none",
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      client_name: this.clientName,
+      client_uri: this.clientUri
+    };
+  }
+  /**
+   * Gets the client information if it exists
+   * @returns The client information or undefined
+   */
+  async clientInformation() {
+    return readJsonFile(
+      this.serverUrlHash,
+      "client_info.json",
+      OAuthClientInformationSchema,
+      this.options.clean
+    );
+  }
+  /**
+   * Saves client information
+   * @param clientInformation The client information to save
+   */
+  async saveClientInformation(clientInformation) {
+    await writeJsonFile(this.serverUrlHash, "client_info.json", clientInformation);
+  }
+  /**
+   * Gets the OAuth tokens if they exist
+   * @returns The OAuth tokens or undefined
+   */
+  async tokens() {
+    return readJsonFile(
+      this.serverUrlHash,
+      "tokens.json",
+      OAuthTokensSchema,
+      this.options.clean
+    );
+  }
+  /**
+   * Saves OAuth tokens
+   * @param tokens The tokens to save
+   */
+  async saveTokens(tokens) {
+    await writeJsonFile(this.serverUrlHash, "tokens.json", tokens);
+  }
+  /**
+   * Redirects the user to the authorization URL
+   * @param authorizationUrl The URL to redirect to
+   */
+  async redirectToAuthorization(authorizationUrl) {
+    console.error(`
+Please authorize this client by visiting:
+${authorizationUrl.toString()}
+`);
+    try {
+      await open(authorizationUrl.toString());
+      console.error("Browser opened automatically.");
+    } catch (error) {
+      console.error("Could not open browser automatically. Please copy and paste the URL above into your browser.");
+    }
+  }
+  /**
+   * Saves the PKCE code verifier
+   * @param codeVerifier The code verifier to save
+   */
+  async saveCodeVerifier(codeVerifier) {
+    await writeTextFile(this.serverUrlHash, "code_verifier.txt", codeVerifier);
+  }
+  /**
+   * Gets the PKCE code verifier
+   * @returns The code verifier
+   */
+  async codeVerifier() {
+    return await readTextFile(
+      this.serverUrlHash,
+      "code_verifier.txt",
+      "No code verifier saved for session",
+      this.options.clean
+    );
+  }
+};
+
+// src/lib/utils.ts
+import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import express from "express";
+import net from "net";
+var pid = process.pid;
+function mcpProxy({ transportToClient, transportToServer }) {
+  let transportToClientClosed = false;
+  let transportToServerClosed = false;
+  transportToClient.onmessage = (message) => {
+    console.error("[Local\u2192Remote]", message.method || message.id);
+    transportToServer.send(message).catch(onServerError);
+  };
+  transportToServer.onmessage = (message) => {
+    console.error("[Remote\u2192Local]", message.method || message.id);
+    transportToClient.send(message).catch(onClientError);
+  };
+  transportToClient.onclose = () => {
+    if (transportToServerClosed) {
+      return;
+    }
+    transportToClientClosed = true;
+    transportToServer.close().catch(onServerError);
+  };
+  transportToServer.onclose = () => {
+    if (transportToClientClosed) {
+      return;
+    }
+    transportToServerClosed = true;
+    transportToClient.close().catch(onClientError);
+  };
+  transportToClient.onerror = onClientError;
+  transportToServer.onerror = onServerError;
+  function onClientError(error) {
+    console.error("Error from local client:", error);
+  }
+  function onServerError(error) {
+    console.error("Error from remote server:", error);
+  }
+}
+async function connectToRemoteServer(serverUrl, authProvider, waitForAuthCode) {
+  console.error(`[${pid}] Connecting to remote server: ${serverUrl}`);
+  const url = new URL(serverUrl);
+  const transport = new SSEClientTransport(url, { authProvider });
+  try {
+    await transport.start();
+    console.error("Connected to remote server");
+    return transport;
+  } catch (error) {
+    if (error instanceof UnauthorizedError || error instanceof Error && error.message.includes("Unauthorized")) {
+      console.error("Authentication required. Waiting for authorization...");
+      const code = await waitForAuthCode();
+      try {
+        console.error("Completing authorization...");
+        await transport.finishAuth(code);
+        const newTransport = new SSEClientTransport(url, { authProvider });
+        await newTransport.start();
+        console.error("Connected to remote server after authentication");
+        return newTransport;
+      } catch (authError) {
+        console.error("Authorization error:", authError);
+        throw authError;
+      }
+    } else {
+      console.error("Connection error:", error);
+      throw error;
+    }
+  }
+}
+function setupOAuthCallbackServer(options) {
+  let authCode = null;
+  const app = express();
+  app.get(options.path, (req, res) => {
+    const code = req.query.code;
+    if (!code) {
+      res.status(400).send("Error: No authorization code received");
+      return;
+    }
+    authCode = code;
+    res.send("Authorization successful! You may close this window and return to the CLI.");
+    options.events.emit("auth-code-received", code);
+  });
+  const server = app.listen(options.port, () => {
+    console.error(`OAuth callback server running at http://127.0.0.1:${options.port}`);
+  });
+  const waitForAuthCode = () => {
+    return new Promise((resolve) => {
+      if (authCode) {
+        resolve(authCode);
+        return;
+      }
+      options.events.once("auth-code-received", (code) => {
+        resolve(code);
+      });
+    });
+  };
+  return { server, authCode, waitForAuthCode };
+}
+async function findAvailablePort(preferredPort) {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.on("error", (err) => {
+      if (err.code === "EADDRINUSE") {
+        server.listen(0);
+      } else {
+        reject(err);
+      }
+    });
+    server.on("listening", () => {
+      const { port } = server.address();
+      server.close(() => {
+        resolve(port);
+      });
+    });
+    server.listen(preferredPort || 0);
+  });
+}
+async function parseCommandLineArgs(args, defaultPort, usage) {
+  const cleanIndex = args.indexOf("--clean");
+  const clean = cleanIndex !== -1;
+  if (clean) {
+    args.splice(cleanIndex, 1);
+  }
+  const serverUrl = args[0];
+  const specifiedPort = args[1] ? parseInt(args[1]) : void 0;
+  if (!serverUrl) {
+    console.error(usage);
+    process.exit(1);
+  }
+  const url = new URL(serverUrl);
+  const isLocalhost = (url.hostname === "localhost" || url.hostname === "127.0.0.1") && url.protocol === "http:";
+  if (!(url.protocol == "https:" || isLocalhost)) {
+    console.error(usage);
+    process.exit(1);
+  }
+  const callbackPort = specifiedPort || await findAvailablePort(defaultPort);
+  if (specifiedPort) {
+    console.error(`Using specified callback port: ${callbackPort}`);
+  } else {
+    console.error(`Using automatically selected callback port: ${callbackPort}`);
+  }
+  if (clean) {
+    console.error("Clean mode enabled: config files will be reset before reading");
+  }
+  return { serverUrl, callbackPort, clean };
+}
+function setupSignalHandlers(cleanup) {
+  process.on("SIGINT", async () => {
+    console.error("\nShutting down...");
+    await cleanup();
+    process.exit(0);
+  });
+  process.stdin.resume();
+}
+
+export {
+  __commonJS,
+  NodeOAuthClientProvider,
+  mcpProxy,
+  connectToRemoteServer,
+  setupOAuthCallbackServer,
+  parseCommandLineArgs,
+  setupSignalHandlers
+};

package/dist/{cli/client.js → client.js}

@@ -1,33 +1,98 @@
 #!/usr/bin/env node
 import {
   NodeOAuthClientProvider,
+  __commonJS,
   parseCommandLineArgs,
   setupOAuthCallbackServer,
   setupSignalHandlers
-} from "../chunk-S3VO5IXF.js";
+} from "./chunk-W4HND3T7.js";
 
-// src/cli/client.ts
+// package.json
+var require_package = __commonJS({
+  "package.json"(exports, module) {
+    module.exports = {
+      name: "mcp-remote",
+      version: "0.0.10",
+      description: "Remote proxy for Model Context Protocol, allowing local-only clients to connect to remote servers using oAuth",
+      keywords: [
+        "mcp",
+        "stdio",
+        "sse",
+        "remote",
+        "oauth"
+      ],
+      author: "Glen Maddern <glen@cloudflare.com>",
+      repository: "https://github.com/geelen/remote-mcp",
+      type: "module",
+      files: [
+        "dist",
+        "README.md",
+        "LICENSE"
+      ],
+      main: "dist/index.js",
+      bin: {
+        "mcp-remote": "dist/cli/proxy.js"
+      },
+      scripts: {
+        dev: "tsup --watch",
+        build: "tsup",
+        check: "prettier --check . && tsc"
+      },
+      dependencies: {
+        "@modelcontextprotocol/sdk": "^1.7.0",
+        express: "^4.21.2",
+        open: "^10.1.0"
+      },
+      devDependencies: {
+        "@types/express": "^5.0.0",
+        "@types/node": "^22.13.10",
+        "@types/react": "^19.0.12",
+        prettier: "^3.5.3",
+        react: "^19.0.0",
+        tsup: "^8.4.0",
+        tsx: "^4.19.3",
+        typescript: "^5.8.2"
+      },
+      tsup: {
+        entry: [
+          "src/client.ts",
+          "src/proxy.ts"
+        ],
+        format: [
+          "esm"
+        ],
+        dts: true,
+        clean: true,
+        outDir: "dist",
+        external: [
+          "react"
+        ]
+      }
+    };
+  }
+});
+
+// src/client.ts
 import { EventEmitter } from "events";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { ListResourcesResultSchema, ListToolsResultSchema } from "@modelcontextprotocol/sdk/types.js";
 import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
-async function runClient(serverUrl, callbackPort) {
+async function runClient(serverUrl, callbackPort, clean = false) {
   const events = new EventEmitter();
   const authProvider = new NodeOAuthClientProvider({
     serverUrl,
     callbackPort,
-    clientName: "MCP CLI Client"
+    clientName: "MCP CLI Client",
+    clean
   });
   const client = new Client(
     {
-      name: "mcp-cli",
-      version: "0.1.0"
+      name: "mcp-remote",
+      version: require_package().version
     },
     {
-      capabilities: {
-        sampling: {}
-      }
+      capabilities: {}
     }
   );
   const url = new URL(serverUrl);
@@ -105,8 +170,8 @@ async function runClient(serverUrl, callbackPort) {
   }
   console.log("Listening for messages. Press Ctrl+C to exit.");
 }
-parseCommandLineArgs(process.argv.slice(2), 3333, "Usage: npx tsx client.ts <https://server-url> [callback-port]").then(({ serverUrl, callbackPort }) => {
-  return runClient(serverUrl, callbackPort);
+parseCommandLineArgs(process.argv.slice(2), 3333, "Usage: npx tsx client.ts [--clean] <https://server-url> [callback-port]").then(({ serverUrl, callbackPort, clean }) => {
+  return runClient(serverUrl, callbackPort, clean);
 }).catch((error) => {
   console.error("Fatal error:", error);
   process.exit(1);