Metadata-Version: 2.4
Name: mcp-http-transport
Version: 0.1.0
Summary: HTTP/SSE transport for MCP servers with hot reload support
Project-URL: Homepage, https://github.com/stephanejouve/mcp-http-transport
Project-URL: Documentation, https://github.com/stephanejouve/mcp-http-transport#readme
Project-URL: Repository, https://github.com/stephanejouve/mcp-http-transport
Project-URL: Issues, https://github.com/stephanejouve/mcp-http-transport/issues
Author-email: Stéphane Jouve <stephane@example.com>
License: MIT
License-File: LICENSE
Keywords: claude,hot-reload,http,mcp,model-context-protocol,server-sent-events,sse,transport
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: mcp>=1.0.0
Requires-Dist: starlette>=0.27.0
Requires-Dist: uvicorn>=0.23.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# mcp-http-transport

**HTTP/SSE transport for MCP servers with hot reload support**

[![PyPI version](https://badge.fury.io/py/mcp-http-transport.svg)](https://badge.fury.io/py/mcp-http-transport)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🎯 Problem Solved

When developing MCP servers, **every code change requires restarting Claude Desktop**. This breaks:
- ❌ Your conversation context
- ❌ Your development flow
- ❌ Your productivity (>1 minute per iteration)

**With `mcp-http-transport`:**
- ✅ Hot reload without Claude Desktop restart
- ✅ Automatic reconnection on server restart
- ✅ Development cycle < 5 seconds
- ✅ Zero modification to your MCP handlers

## 🚀 Quick Start

### Installation

```bash
pip install mcp-http-transport
```

### Basic Usage

```python
import os
from mcp.server import Server
from mcp_http_transport import MCPTransportManager

# Your existing MCP server
server = Server("my-mcp-server")

@server.list_tools()
async def list_tools():
    return [...]  # Your tools

@server.call_tool()
async def call_tool(name, arguments):
    return [...]  # Your handlers

# Add transport layer (NO changes to handlers!)
async def main():
    transport = MCPTransportManager(
        server=server,
        transport_mode=os.getenv("MCP_TRANSPORT", "stdio"),
        host=os.getenv("MCP_HTTP_HOST", "localhost"),
        port=int(os.getenv("MCP_HTTP_PORT", "3000")),
    )
    await transport.start()

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())
```

### Configuration

**`.env` file:**
```bash
# Transport mode: "stdio" (default) or "http"
MCP_TRANSPORT=http
MCP_HTTP_HOST=localhost
MCP_HTTP_PORT=3000
```

**Claude Desktop config:**
```json
{
  "mcpServers": {
    "my-server": {
      "url": "http://localhost:3000/sse"
    }
  }
}
```

**That's it!** Now when you modify your code:
1. Watchdog detects change → restarts server
2. Claude Desktop reconnects automatically
3. **No manual restart needed!**

## 📚 Documentation

### Transport Modes

| Mode | Use Case | Pros | Cons |
|------|----------|------|------|
| **stdio** (default) | Production | Simple, minimal overhead | No hot reload |
| **http** | Development | Hot reload, auto-reconnect | Requires port |

### Environment Variables

- `MCP_TRANSPORT`: `"stdio"` or `"http"` (default: `"stdio"`)
- `MCP_HTTP_HOST`: HTTP server host (default: `"localhost"`)
- `MCP_HTTP_PORT`: HTTP server port (default: `3000`)

### With Watchdog (Hot Reload)

**Install watchdog:**
```bash
pip install watchdog
```

**Create wrapper script** (`mcp-server-wrapper.sh`):
```bash
#!/bin/bash
cd /path/to/your/project

if [ "$MCP_DEV_MODE" = "1" ]; then
    echo "[MCP] Dev mode - auto-reload enabled"
    exec python -m watchdog.watchmedo auto-restart \
        -d your_package \
        -p "*.py" \
        -R \
        --interval 1.0 \
        --debounce-interval 0.5 \
        -- python -m your_package.mcp_server
else
    exec python -m your_package.mcp_server
fi
```

**Claude Desktop config:**
```json
{
  "mcpServers": {
    "my-server": {
      "command": "/path/to/mcp-server-wrapper.sh",
      "env": {
        "MCP_DEV_MODE": "1",
        "MCP_TRANSPORT": "http",
        "MCP_HTTP_PORT": "3000"
      }
    }
  }
}
```

## 🏗️ Architecture

```
┌─────────────────┐
│ Claude Desktop  │
└────────┬────────┘
         │
         ├─── stdio (default)
         │    └─> stdin/stdout pipes
         │
         └─── http (dev)
              ├─> GET /sse (Server-Sent Events)
              └─> POST /messages/ (JSON-RPC)
```

**HTTP/SSE Flow:**
1. Client: `GET http://localhost:3000/sse` → establishes SSE stream
2. Client: `POST http://localhost:3000/messages/` → sends JSON-RPC requests
3. Server: responds via SSE stream
4. Watchdog restarts server → Client reconnects automatically

## 🔧 Advanced Usage

### Multiple MCP Servers

Run multiple MCP servers on different ports:

```json
{
  "mcpServers": {
    "server-1": {
      "url": "http://localhost:3000/sse"
    },
    "server-2": {
      "url": "http://localhost:3001/sse"
    }
  }
}
```

### Custom Host/Port

```python
transport = MCPTransportManager(
    server=server,
    transport_mode="http",
    host="0.0.0.0",  # Listen on all interfaces
    port=8080,
)
```

### Switching Back to Stdio

Just remove or change the environment variable:

```bash
# Back to stdio (production)
MCP_TRANSPORT=stdio
```

Or omit it entirely (defaults to stdio).

## 🧪 Testing

```bash
# Install dev dependencies
pip install mcp-http-transport[dev]

# Run tests
pytest

# With coverage
pytest --cov=mcp_http_transport
```

## 🤝 Contributing

Contributions welcome! This package was extracted from a real-world MCP server to benefit the community.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🙏 Credits

- Built for [MCP (Model Context Protocol)](https://modelcontextprotocol.io/)
- Inspired by real-world pain points in MCP development
- Uses [Starlette](https://www.starlette.io/) and [Uvicorn](https://www.uvicorn.org/)

## 🐛 Troubleshooting

### Port Already in Use

```bash
# Find process using port
lsof -ti:3000

# Kill process
lsof -ti:3000 | xargs kill -9

# Or use different port
MCP_HTTP_PORT=3001
```

### Claude Desktop Not Reconnecting

**Cause:** SSE retry delay (2-5s is normal)

**Solution:** Wait a few seconds after server restart. Claude Desktop will show "Reconnecting..." then connect automatically.

### HTTP Mode Not Working

**Check:**
1. Server logs: `tail -f /tmp/mcp-server-debug.log`
2. Test endpoint: `curl http://localhost:3000/sse`
3. Verify Claude Desktop config has correct URL

## 📊 Comparison

| Feature | stdio | http |
|---------|-------|------|
| **Setup** | Simple | Medium |
| **Hot Reload** | ❌ | ✅ |
| **Auto-Reconnect** | ❌ | ✅ |
| **Production Ready** | ✅ | ⚠️ Dev only |
| **Multi-client** | ❌ | ✅ |
| **Overhead** | Minimal | Very Low |

---

**Made with ❤️ for the MCP community**

If this package saves you time, consider ⭐ starring the repo!
