phoenix-oss/mcp-remote
0
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

Polish README

Browse source
This commit is contained in:
Minoru Mizutani 2025-04-29 13:31:50 +09:00
parent 00da599d79
commit 4522dc41a6
No known key found for this signature in database
1 changed files with 101 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

119
README.md
View file

@ -15,37 +15,68 @@ A Deno wrapper for the [mcp-use](https://github.com/geelen/mcp-remote) proxy ser
## Installation ## Installation
No installation is needed! You can run the CLI directly using Deno: No installation is needed if you have Deno installed. You can run the proxy directly.
```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 <server-url> [callback-port]
# Or clone the repository and run locally
git clone https://github.com/yourusername/mcp-deno.git
cd mcp-deno
deno task start <server-url> [callback-port]
```
## Usage ## 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 ```bash
# Basic usage with default callback port (3334) # Basic usage: Connects to the server and listens on default port 3334
deno task start https://your-mcp-server.com deno task proxy:start <server-url>
# Specify a custom callback port # Example:
deno task start https://your-mcp-server.com 8080 deno task proxy:start https://your-remote-mcp-server.com
# Include custom HTTP headers # Specify a custom local callback port:
deno task start https://your-mcp-server.com --header "Authorization: Bearer token" --header "X-Custom: Value" deno task proxy:start <server-url> [callback-port]
# Example with custom port 8080:
deno task proxy:start <server-url> 8080
# Include custom HTTP headers for the connection to the remote server:
deno task proxy:start <server-url> [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:**
- `<server-url>`: (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 <server-url> [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 ## API
You can also use the library programmatically in your Deno projects: You can also use the library programmatically in your Deno projects:
```typescript ```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 // Using the wrapped function
await startProxy("https://your-mcp-server.com", 3334, { 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. 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 `<server-url>` 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, <server-url>, 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 ## License
MIT - See the [LICENSE](LICENSE) file for details. MIT - See the [LICENSE](LICENSE) file for details.