mcp-streamable-proxy 0.2.7

Streamable HTTP proxy implementation for MCP protocol using rmcp 3.1
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

# MCP Streamable HTTP Proxy

**[English](README.md)** | **[简体中文](README_zh-CN.md)**

---

# MCP Streamable HTTP Proxy

Streamable HTTP proxy implementation for MCP using rmcp 0.12 with stateful session management.

## Overview

This module provides a proxy implementation for MCP (Model Context Protocol) using Streamable HTTP transport with stateful session management.

## Features

- **Streamable HTTP Support**: Uses rmcp with Streamable HTTP transport
- **Stateful Sessions**: Custom SessionManager with backend version tracking
- **Backend isolation**:
  - **URL backends** default to **per-session** connections (connect on `initialize`, RAII drop)
  - **Stdio backends** default to **shared** single child process + notification fan-out
- **Hot Swap**: Supports backend connection replacement for shared isolation
- **Version Control**: Invalidates sessions when a shared backend reconnects
- **High-level Client API**: Simple connection interface hiding transport details

## Architecture

```text
Client → Streamable HTTP → ProxyAwareSessionManager → ProxyHandler → Backend MCP Service

URL (per-session):
  each factory() → new ProxyHandler → initialize → connect() → Drop closes backend

Stdio (shared):
  one backend Arc shared by cloned handlers + UpstreamPeerRegistry fan-out
```

### Builder knobs

```rust,ignore
StreamServerBuilder::new(BackendConfig::Url { url, headers: None })
    .stateful(true)
    .backend_isolation(BackendIsolation::PerSession) // default for URL
    .max_sessions(32)
    .connect_timeout(Duration::from_secs(30))
    .build()
    .await?;
```

Stdio + `PerSession` is rejected in this release.
## Installation

Add to `Cargo.toml`:

```toml
[dependencies]
mcp-streamable-proxy = { version = "0.1.5", path = "../mcp-streamable-proxy" }
```

## Usage

### Server

```rust
use mcp_streamable_proxy::{McpServiceConfig, run_stream_server};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = McpServiceConfig::new("my-service".to_string());

    run_stream_server(config).await?;

    Ok(())
}
```

### Client

```rust
use mcp_streamable_proxy::{StreamClientConnection, McpClientConfig};

// Connect to an MCP server
let config = McpClientConfig::new("http://localhost:8080/mcp");
let conn = StreamClientConnection::connect(config).await?;

// List available tools
let tools = conn.list_tools().await?;
```

## Session Management

The `ProxyAwareSessionManager` provides:
- Backend version tracking using DashMap
- Automatic session invalidation on backend reconnect
- Concurrent-safe session operations

## Development

```bash
# Build
cargo build -p mcp-streamable-proxy

# Test
cargo test -p mcp-streamable-proxy
```

## License

MIT OR Apache-2.0