mcpproxy 0.2.1

# MCP Proxy

A local stdin/stdout MCP (Model Context Protocol) server that proxies requests to a remote MCP server over HTTP.

## Overview

This tool acts as a bridge between MCP clients that expect a local stdin/stdout interface and remote MCP servers that communicate over HTTP. It reads JSON-RPC requests from stdin, forwards them to the configured remote server, and writes the responses back to stdout.

## Features

- **Local MCP Interface**: Provides standard stdin/stdout JSON-RPC interface expected by MCP clients
- **Remote HTTP Proxy**: Forwards all requests to a remote MCP server via HTTP POST
- **Multiple Response Formats**: Supports both JSON and Server-Sent Events (text/event-stream) responses
- **Authentication Support**: Optional Bearer token authentication for remote servers
- **Error Handling**: Proper JSON-RPC error responses for network failures and parsing errors
- **Logging**: Debug information written to stderr (doesn't interfere with JSON-RPC communication)

## Installation

### Option 1: npm Package (Recommended)

```bash
# Global installation
npm install -g @agentdb/mcpproxy

# Or use with npx (no installation required)
npx @agentdb/mcpproxy --url https://your-server.com/mcp
```

### Option 2: Cargo Install

```bash
cargo install mcpproxy
```

### Option 3: Build from Source

```bash
cargo build --release
```

## Usage

### Basic Usage

```bash
./target/release/mcpproxy --url https://your-remote-mcp-server.com/mcp
```

### With Authentication

```bash
./target/release/mcpproxy --url https://your-remote-mcp-server.com/mcp --token your-auth-token
```

### Command Line Options

- `--url, -u`: Remote MCP server URL to proxy to (required)
- `--token, -t`: Optional authentication token for the remote server

## How It Works

1. **Input**: Reads JSON-RPC requests from stdin (one per line)
2. **Forward**: Sends each request to the remote server via HTTP POST with headers:
   - `Content-Type: application/json`
   - `Accept: application/json, text/event-stream`
   - `Authorization: Bearer <token>` (if token provided)
3. **Response Handling**:
   - **JSON Response**: Single JSON-RPC response written to stdout
   - **Event Stream Response**: Multiple JSON-RPC responses from Server-Sent Events, each written to stdout
4. **Logging**: Debug information goes to stderr

## Response Format Support

### JSON Responses
Standard single JSON-RPC response from the remote server.

### Server-Sent Events (Event Stream)
When the remote server responds with `Content-Type: text/event-stream`, the proxy:
1. Parses the event stream format (`data: ...` lines)
2. Extracts JSON-RPC responses from each event
3. Outputs each response as a separate line to stdout
4. Handles multiple responses from a single request

## JSON-RPC Protocol

The proxy handles standard JSON-RPC 2.0 messages:

### Request Format
```json
{
  "jsonrpc": "2.0",
  "method": "method_name",
  "params": {...},
  "id": 1
}
```

### Response Format
```json
{
  "jsonrpc": "2.0",
  "result": {...},
  "id": 1
}
```

### Error Format
```json
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": "Additional error details"
  },
  "id": 1
}
```

## Error Codes

- `-32700`: Parse error (invalid JSON)
- `-32603`: Internal error (network or server errors)
- HTTP status codes are passed through as error codes for remote server errors

## Example Usage with MCP Client

```bash
# Using npm package
npx @agentdb/mcpproxy --url https://api.example.com/mcp --token abc123

# Or if globally installed
mcpproxy --url https://api.example.com/mcp --token abc123

# Test with a simple request
echo '{"jsonrpc":"2.0","method":"ping","id":1}' | npx @agentdb/mcpproxy --url https://api.example.com/mcp
```

## Claude Desktop Configuration

### Using npx (No Installation Required)
```json
{
  "mcpServers": {
    "agentdb-remote": {
      "command": "npx",
      "args": [
        "-y", "@agentdb/mcpproxy",
        "--url", "https://your-agentdb-server.com/mcp",
        "--token", "your-auth-token"
      ]
    }
  }
}
```

### Using Global Installation
```json
{
  "mcpServers": {
    "agentdb-remote": {
      "command": "mcpproxy",
      "args": [
        "--url", "https://your-agentdb-server.com/mcp",
        "--token", "your-auth-token"
      ]
    }
  }
}
```

## Development

### Building
```bash
cargo build
```

### Running Tests
```bash
cargo test
```

### Running with Debug Logging
```bash
RUST_LOG=debug cargo run -- --url https://your-server.com/mcp
```

## Dependencies

- `tokio`: Async runtime
- `reqwest`: HTTP client with streaming support
- `serde`/`serde_json`: JSON serialization
- `clap`: Command line argument parsing
- `anyhow`: Error handling
- `futures-util`: Stream processing for event streams
- `tokio-util`: Additional utilities for async I/O

## License

This project is licensed under the MIT License.