JinDaGe - mcpproxy MCP Details

article

README

🚀 MCP SSE 代理服务器

MCP SSE 代理服务器基于 SSE（Server-Sent Events）协议实现 MCP 协议代理服务。它支持共享与独立会话模式，具备灵活配置选项，还能集成 CURSOR 环境，为用户提供高效、安全的代理服务。

🚀 快速开始

安装

pip install mcp-sse-server

启动服务器

python3 -m mcp.sse_server.run_sse_server --listen "127.0.0.1" --port 8000 --auth_key your_auth_key_here

✨ 主要特性

基本功能：提供 MCP 协议的代理服务器功能，支持 SSE（Server-Sent Events）传输协议。
架构模式：
- 共享会话模式：多个客户端可共享同一份上下文数据。
- 独立会话模式：每个客户端拥有独立的上下文数据。
动态配置：
- 支持通过 URL 参数传递环境变量。
- 提供简单易用的配置方式。
连接能力：
- 直接连接到工具执行环境。
- 支持 CURSOR 协议集成。
安全特性：
- 身份验证：支持基于 URL 参数的认证机制，可扩展插件式认证模块。
- 数据保护：数据传输采用 SSL 加密，默认启用，且有灵活的安全策略配置选项。

📦 安装指南

本地安装

pip install mcp-sse-server

高级安装

# 示例：使用虚拟环境进行安装
python3 -m venv mcp_env && \
source mcp_env/bin/activate && \
pip install mcp-sse-server

💻 使用示例

基础用法

# 示例：本地运行MCP SSE服务器
python3 -m mcp.sse_server.run_sse_server --listen "::1" --port 8000 --auth_key your_auth_key_here

高级用法

工具执行

# 示例：配置并启动带有指定工具的MCP服务器
python3 -m mcp.sse_server.run_sse_server \
    --listen "0.0.0.0" \
    --port 8000 \
    --auth_key your_auth_key_here \
    --tools 'echo,cat,ls'

CURSOR 集成

# 示例：配置 CURSOR 环境的MCP服务器
python3 -m mcp.sse_server.run_sse_server \
    --listen "127.0.0.1" \
    --port 8000 \
    --auth_key your_auth_key_here \
    --cursor_mode enable

📚 详细文档

配置示例

{
    "server_name": "my_mcp_server",
    "listen_address": "0.0.0.0",
    "port_number": 8000,
    "auth_key": "your_auth_key_here",
    "tools_list": ["echo", "cat", "ls"],
    "cursor_mode": true
}

配置选项

| 参数名称 | 描述 | 默认值 | | ---- | ---- | ---- | | listen_address | 监听地址 | "127.0.0.1" | | port_number | 监听端口 | 8000 | | auth_key | 认证密钥 | None | | tools_list | 支持的工具列表 | [] | | cursor_mode | 是否启用 CURSOR 模式 | False |

连接方式

# 示例：使用curl连接服务器
curl -X POST "http://127.0.0.1:8000/api" \
    --header "Content-Type: application/json" \
    --data-raw '{"command": "echo", "args": ["hello"]}'

使用日志

启用日志记录

# 示例：启用调试级别的日志记录
python3 -m mcp.sse_server.run_sse_server \
    --listen "127.0.0.1" \
    --port 8000 \
    --auth_key your_auth_key_here \
    --log_level debug

日志格式

# 示例：自定义日志输出格式
python3 -m mcp.sse_server.run_sse_server \
    --listen "127.0.0.1" \
    --port 8000 \
    --auth_key your_auth_key_here \
    --log_format "%(asctime)s - %(levelname)s - %(message)s"

错误处理

常见错误

认证失败：未正确配置或传递有效的认证密钥。
端口占用：目标端口已被其他程序占用。
工具缺失：指定的工具不存在于系统中。

退出状态码

| 状态码 | 描述 | | ---- | ---- | | 0 | 成功 | | 1 | 通用错误 | | 2 | 认证失败 | | 3 | 资源 unavailable |

错误日志格式

LEVEL TIMESTAMP - MSG

使用限制

最大连接数：默认支持 20 个并发连接，可配置扩展。
工具限制：仅支持预设的工具列表。

贡献指南

代码仓库：GitHub 仓库地址
问题反馈：请在 Issues 区提交问题和建议。

项目信息

许可证：MIT License
贡献指南：欢迎通过 GitHub 提出 Pull Request。
问题反馈：请在 Issues 区提交问题。
版本信息：1.0.0

发展计划

未来功能

扩展插件支持
多协议兼容性
高级安全特性

日志示例

启动日志

INFO: Server started on port 8000 at address ::1
DEBUG: Loaded tools: ['echo', 'cat', 'ls']

请求日志

INFO: Received request from 127.0.0.1:55556
DEBUG: Command received: echo, arguments: ["hello"]
INFO: Completed command execution in 0.002 seconds

错误日志

ERROR: Authentication failed for request from 192.168.1.1:45678
CRITICAL: Server shutting down due to repeated authentication failures

开发指南

开发环境

Python 版本：3.8+
依赖管理：使用 poetry 或 pipenv。
代码风格：遵循 PEP8 规范。

贡献流程

Fork 仓库到个人账号。
创建功能分支。
提交代码并 Push 到远程仓库。
提出 Pull Request。

测试指南

单元测试

pytest tests/unit/ -v

集成测试

pytest tests/integration/ -v

性能测试

loadtest.py -c 100 -p 8000

部署指南

生产环境配置

反向代理：建议使用 Nginx 或 Apache。
SSL 证书：必须启用 HTTPS。
日志管理：配置集中化日志收集服务。

监控方案

状态监控：定期检查服务运行状态。
性能指标：监控 CPU、内存使用情况。
错误警报：设置错误阈值触发告警。

⚠️ 重要提示

所有请求均需包含有效的认证密钥，建议在生产环境中启用 SSL 证书。

💡 使用建议

若遇到认证失败问题，请检查传递的认证密钥是否正确；若端口被占用，请确保目标端口未被其他程序占用；若工具不可用，请确认指定的工具已正确安装并可执行。