From 4522dc41a6cebf831f0c6b522bc3a74ebd6da567 Mon Sep 17 00:00:00 2001 From: Minoru Mizutani Date: Tue, 29 Apr 2025 13:31:50 +0900 Subject: [PATCH] Polish README --- README.md | 119 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 101 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 78e858b..0432cfa 100644 --- a/README.md +++ b/README.md @@ -15,37 +15,68 @@ A Deno wrapper for the [mcp-use](https://github.com/geelen/mcp-remote) proxy ser ## Installation -No installation is needed! You can run the CLI directly using Deno: - -```bash -# Run from GitHub (replace {VERSION} with the latest version or main) -deno run --allow-net --allow-env --allow-read https://raw.githubusercontent.com/yourusername/mcp-deno/{VERSION}/cli.ts [callback-port] - -# Or clone the repository and run locally -git clone https://github.com/yourusername/mcp-deno.git -cd mcp-deno -deno task start [callback-port] -``` +No installation is needed if you have Deno installed. You can run the proxy directly. ## Usage +The primary way to use this tool is via the command line to start the proxy server. + +### Running with `deno task` (Recommended) + +If you have cloned the repository, you can use the predefined Deno task: + ```bash -# Basic usage with default callback port (3334) -deno task start https://your-mcp-server.com +# Basic usage: Connects to the server and listens on default port 3334 +deno task proxy:start -# Specify a custom callback port -deno task start https://your-mcp-server.com 8080 +# Example: +deno task proxy:start https://your-remote-mcp-server.com -# Include custom HTTP headers -deno task start https://your-mcp-server.com --header "Authorization: Bearer token" --header "X-Custom: Value" +# Specify a custom local callback port: +deno task proxy:start [callback-port] + +# Example with custom port 8080: +deno task proxy:start 8080 + +# Include custom HTTP headers for the connection to the remote server: +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" ``` +**Arguments:** + +- ``: (Required) The URL of the remote MCP server you want to connect to. +- `[callback-port]`: (Optional) The local port the proxy should listen on for connections from your MCP client. Defaults to `3334`. +- `--header "Name: Value"`: (Optional, repeatable) Custom HTTP headers to send to the remote MCP server during the initial connection. + +### Running with `deno run` + +You can also run the proxy script directly using `deno run`. This requires specifying the necessary permissions precisely. + +```bash +# Define permissions based on deno.json task +DENO_PERMISSIONS="--allow-env --allow-read --allow-sys=homedir --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" + +# Basic usage with specific permissions: +deno run $DENO_PERMISSIONS src/proxy.ts [callback-port] + +# Example: +deno run $DENO_PERMISSIONS src/proxy.ts https://your-mcp-server.com + +# Example with custom port and headers: +deno run $DENO_PERMISSIONS src/proxy.ts https://your-mcp-server.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`.* + ## API You can also use the library programmatically in your Deno projects: ```typescript -import { startProxy, runProxy } from "https://raw.githubusercontent.com/yourusername/mcp-deno/{VERSION}/mod.ts"; +import { startProxy, runProxy } from "jsr:@mmizutani/mcp-remote-deno@^100.1"; // Using the wrapped function await startProxy("https://your-mcp-server.com", 3334, { @@ -75,6 +106,58 @@ deno fmt This project uses Deno's NPM compatibility feature to directly import and use the `mcp-use` package without the need for Node.js or a subprocess. It wraps the functionality in a Deno-friendly API with TypeScript type definitions. +### Bidirectional Proxying Explained + +The core functionality relies on establishing two sets of communication channels based on the MCP HTTP+SSE transport specification: + +1. **Client <-> Proxy:** + - The proxy starts an HTTP server locally (defaulting to port 3334, configurable via the `[callback-port]` argument). + - Your local MCP client connects to this server's SSE endpoint to receive messages *from* the proxy. + - The client sends messages *to* the proxy via HTTP POST requests to a specific endpoint provided by the proxy upon connection. +2. **Proxy <-> Server:** + - The proxy makes an initial HTTP connection to the remote MCP server specified by the `` argument to establish an SSE connection. Any custom headers provided via the `--header` flag are sent during this setup. + - The proxy receives messages *from* the remote server via this SSE connection. + - The proxy sends messages *to* the remote server via HTTP POST requests to the endpoint provided by the server during the initial handshake. + +Once both connections are established, the proxy relays messages between them: + +- HTTP POST messages received from the **Client** are forwarded as HTTP POST messages to the **Server**. +- SSE messages received from the **Server** are forwarded as SSE messages to the **Client**. + +This creates a transparent bridge, allowing your local client to communicate with the remote server using the standard MCP HTTP+SSE transport. + +```mermaid +sequenceDiagram + participant Client + participant Proxy as Proxy (mcp-remote-deno) + participant Server + + Client->>+Proxy: GET / (Establish SSE connection, http://localhost:3334) + Proxy-->>-Client: SSE stream opened, provides POST endpoint (/client-post) + + Proxy->>+Server: GET / (Establish SSE connection, , Headers) + Server-->>-Proxy: SSE stream opened, provides POST endpoint (/server-post) + + loop Message Exchange + Client->>Proxy: POST /client-post (MCP Request) + Proxy->>Server: POST /server-post (Forwarded MCP Request) + Server-->>Proxy: SSE event (MCP Response/Notification) + Proxy-->>Client: SSE event (Forwarded MCP Response/Notification) + + Server-->>Proxy: SSE event (MCP Request/Notification) + Proxy-->>Client: SSE event (Forwarded MCP Request/Notification) + Client->>Proxy: POST /client-post (MCP Response) + Proxy->>Server: POST /server-post (Forwarded MCP Response) + end + + Client->>Proxy: Close Connection + Proxy->>Server: Close Connection + Server-->>Proxy: Connection Closed + Proxy-->>Client: Connection Closed +``` + +If either the client or the server disconnects, the proxy ensures the other connection is also terminated gracefully. + ## License MIT - See the [LICENSE](LICENSE) file for details.