Polish README
This commit is contained in:
Minoru Mizutani
parent
00da599d79
commit
4522dc41a6
1 changed files with 101 additions and 18 deletions
119
README.md
119
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 <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]
|
||||
```
|
||||
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 <server-url>
|
||||
|
||||
# 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 <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
|
||||
|
||||
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 `<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
|
||||
|
||||
MIT - See the [LICENSE](LICENSE) file for details.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue