From a3161163e6282b3082b49396da0da4f6ec22bea1 Mon Sep 17 00:00:00 2001 From: Minoru Mizutani Date: Tue, 29 Apr 2025 14:50:03 +0900 Subject: [PATCH] Update README and proxy.ts: Replace example server URLs with a specific remote MCP server address, enhance configuration instructions for MCP clients, and clarify environment variable usage for VPN connections. --- README.md | 52 +++++++++++++++++++++++++++++++++++++++------- README.original.md | 18 ++++++++-------- src/proxy.ts | 26 ++++------------------- 3 files changed, 58 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index a5cf5d0..0680796 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ If you have cloned the repository, you can use the predefined Deno task: deno task proxy:start # Example: -deno task proxy:start https://your-remote-mcp-server.com +deno task proxy:start https://remote.mcp.server.example.com # Specify a custom local port for OAuth redirects: deno task proxy:start [callback-port] @@ -43,7 +43,7 @@ deno task proxy:start 8080 deno task proxy:start [callback-port] --header "Header-Name: Header-Value" --header "Another: Value" # Example with headers: -deno task proxy:start https://your-remote-mcp-server.com 3334 --header "Authorization: Bearer mytoken" --header "X-Custom-ID: 12345" +deno task proxy:start https://remote.mcp.server.example.com 3334 --header "Authorization: Bearer mytoken" --header "X-Custom-ID: 12345" ``` **Arguments:** @@ -64,10 +64,10 @@ DENO_PERMISSIONS="--allow-env --allow-read --allow-sys=homedir --allow-run=open deno run $DENO_PERMISSIONS src/proxy.ts [callback-port] # Example: -deno run $DENO_PERMISSIONS src/proxy.ts https://your-mcp-server.com +deno run $DENO_PERMISSIONS src/proxy.ts https://remote.mcp.server.example.com # Example with custom port and headers: -deno run $DENO_PERMISSIONS src/proxy.ts https://your-mcp-server.com 8080 --header "Authorization: Bearer mytoken" +deno run $DENO_PERMISSIONS src/proxy.ts https://remote.mcp.server.example.com 8080 --header "Authorization: Bearer mytoken" ``` *Note: Using `deno task proxy:start` is simpler as it automatically applies the correct permissions defined in `deno.json`.* @@ -80,12 +80,12 @@ You can also use the library programmatically in your Deno projects: import { startProxy, runProxy } from "jsr:@mmizutani/mcp-remote-deno@^100.1"; // Using the wrapped function -await startProxy("https://your-mcp-server.com", 3334, { +await startProxy("https://remote.mcp.server.example.com", 3334, { "Authorization": "Bearer token" }); // Or using the direct import from mcp-use -await runProxy("https://your-mcp-server.com", 3334, { +await runProxy("https://remote.mcp.server.example.com", 3334, { "Authorization": "Bearer token" }); ``` @@ -94,7 +94,7 @@ await runProxy("https://your-mcp-server.com", 3334, { ```bash # Run in development mode with auto-reload -deno task dev https://your-mcp-server.com +deno task dev https://remote.mcp.server.example.com # Check types deno check mod.ts cli.ts @@ -190,6 +190,44 @@ sequenceDiagram If either the client or the server disconnects, the proxy ensures the other connection is also terminated gracefully. +## MCP Server Configuration + +You can configure your local MCP client (such as Cursor IDE) to use this proxy by adding an entry to your MCP configuration file. + +For Cursor, edit `~/.cursor/mcp.json` (or create it if it doesn't exist) and add the following configuration: + +```json +{ + "mcpServers": { + "${mcpServerName}": { + "type": "stdio", + "command": "deno", + "args": [ + "run", + "--allow-env", + "--allow-read", + "--allow-sys=homedir", + "--allow-run=open", + "--allow-write=\"$HOME/.mcp-auth\"", + "--allow-net=0.0.0.0,127.0.0.1,localhost,remote.mcp.server.example.com", + "jsr:@mmizutani/mcp-remote-deno", + "https://remote.mcp.server.example.com/sse" + ] + } + } +} +``` + +Replace `${mcpServerName}` with a unique name for your remote MCP server, and update the URL in the last argument to point to your actual remote MCP server endpoint. + ## License MIT - See the [LICENSE](LICENSE) file for details. + +## Acknowledgements + +This project would not be possible without these excellent open source projects: + +- [mcp-remote](https://www.npmjs.com/package/mcp-remote) - The original NPM package that this Deno wrapper is based on. Created by Glen Maddern (@geelen), mcp-remote pioneered the approach of connecting local stdio-based MCP clients (like Cursor, Claude Desktop, and Windsurf) to remote MCP servers over HTTP+SSE. It handles the complex OAuth authentication flow and bidirectional proxying between different transport protocols, forming the foundational architecture that this Deno implementation builds upon. + +- [@yamanoku/baseline-mcp-server](https://jsr.io/@yamanoku/baseline-mcp-server) - Developed by Okuto Oyama (@yamanoku), this project provided inspiration for implementing an MCP server within Deno's secure runtime environment. Its clean architecture and approach to permission management exemplifies how to properly leverage Deno's sandbox security model while maintaining full compatibility with the MCP specification. diff --git a/README.original.md b/README.original.md index c7f9e73..e3d190d 100644 --- a/README.original.md +++ b/README.original.md @@ -25,7 +25,7 @@ All the most popular MCP clients (Claude Desktop, Cursor & Windsurf) use the fol "command": "npx", "args": [ "mcp-remote", - "https://remote.mcp.server/sse" + "https://remote.mcp.server.example.com/sse" ] } } @@ -43,7 +43,7 @@ To bypass authentication, or to emit custom headers on all requests to your remo "command": "npx", "args": [ "mcp-remote", - "https://remote.mcp.server/sse", + "https://remote.mcp.server.example.com/sse", "--header", "Authorization: Bearer ${AUTH_TOKEN}" ] @@ -62,7 +62,7 @@ To bypass authentication, or to emit custom headers on all requests to your remo // rest of config... "args": [ "mcp-remote", - "https://remote.mcp.server/sse", + "https://remote.mcp.server.example.com/sse", "--header", "Authorization:${AUTH_HEADER}" // note no spaces around ':' ] @@ -81,7 +81,7 @@ To bypass authentication, or to emit custom headers on all requests to your remo "args": [ "-y" "mcp-remote", - "https://remote.mcp.server/sse" + "https://remote.mcp.server.example.com/sse" ] ``` @@ -90,7 +90,7 @@ To bypass authentication, or to emit custom headers on all requests to your remo ```json "args": [ "mcp-remote@latest", - "https://remote.mcp.server/sse" + "https://remote.mcp.server.example.com/sse" ] ``` @@ -99,7 +99,7 @@ To bypass authentication, or to emit custom headers on all requests to your remo ```json "args": [ "mcp-remote", - "https://remote.mcp.server/sse", + "https://remote.mcp.server.example.com/sse", "9696" ] ``` @@ -170,7 +170,7 @@ Then restarting your MCP client. ### Check your Node version -Make sure that the version of Node you have installed is [18 or +Make sure that the version of Node you have installed is [18 or higher](https://modelcontextprotocol.io/quickstart/server). Claude Desktop will use your system version of Node, even if you have a newer version installed elsewhere. @@ -192,7 +192,7 @@ this might look like: "command": "npx", "args": [ "mcp-remote", - "https://remote.mcp.server/sse" + "https://remote.mcp.server.example.com/sse" ], "env": { "NODE_EXTRA_CA_CERTS": "{your CA certificate file path}.pem" @@ -225,7 +225,7 @@ You can run `rm -rf ~/.mcp-auth` to clear any locally stored state and tokens. Run the following on the command line (not from an MCP server): ```shell -npx -p mcp-remote@latest mcp-remote-client https://remote.mcp.server/sse +npx -p mcp-remote@latest mcp-remote-client https://remote.mcp.server.example.com/sse ``` This will run through the entire authorization flow and attempt to list the tools & resources at the remote URL. Try this after running `rm -rf ~/.mcp-auth` to see if stale credentials are your problem, otherwise hopefully the issue will be more obvious in these logs than those in your MCP client. diff --git a/src/proxy.ts b/src/proxy.ts index 60616e9..d148b53 100644 --- a/src/proxy.ts +++ b/src/proxy.ts @@ -107,7 +107,7 @@ async function runProxy( ) { log(`You may be behind a VPN! -If you are behind a VPN, you can try setting the NODE_EXTRA_CA_CERTS environment variable to point +If you are behind a VPN, you can try setting the DENO_CERT environment variable to point to the CA certificate file. If using claude_desktop_config.json, this might look like: { @@ -122,29 +122,11 @@ to the CA certificate file. If using claude_desktop_config.json, this might look "--allow-run=open", "--allow-write=\"$HOME/.mcp-auth/mcp-remote-deno-0.0.1\"", "--allow-net=0.0.0.0,127.0.0.1,localhost", - "src/proxy.ts", - "https://remote.mcp.server/sse" + "jsr:@mmizutani/mcp-remote-deno", + "https://remote.mcp.server.example.com/sse" ], "env": { - "NODE_EXTRA_CA_CERTS": "\${your CA certificate file path}.pem" - } - } - } -} - -Alternatively, you can use the predefined task from deno.json: - -{ - "mcpServers": { - "\${mcpServerName}": { - "command": "deno", - "args": [ - "task", - "proxy:start", - "https://remote.mcp.server/sse" - ], - "env": { - "NODE_EXTRA_CA_CERTS": "\${your CA certificate file path}.pem" + "DENO_CERT": "\${your CA certificate file path}.pem" } } }