MCP Playground

一个全面的Python工具包，用于与远程模型上下文协议（MCP）端点进行交互。当前支持服务器发送事件（SSE），并计划支持可流式传输的HTTP协议。

🎯 项目重点

MCP Playground 特别设计用于远程MCP客户端能力，提供强大的工具，通过网络协议连接到并与MCP服务器进行交互：

• ✅ 服务器发送事件（SSE） - 完整实现，实时流式传输
• 🔄 可流式传输的HTTP - 计划在未来版本中支持
• 🤖 LLM集成 - 基于AI的工具选择和执行
• 🧪 交互测试 - 全面的测试环境

🚀 快速开始

几分钟内启动运行：

# 克隆仓库
git clone https://github.com/zanetworker/mcp-playground.git
cd mcp-playground

# 安装包
pip install -e .

# 尝试交互式的Streamlit应用
cd mcp-streamlit-app
pip install -r requirements.txt
streamlit run app.py

🚨 重要提示： 连接到MCP服务器时，请始终使用以/sse结尾的URL。 示例：http://localhost:8000/sse（而不是http://localhost:8000）

环境变量

为了方便起见，您可以通过环境变量设置API密钥和OpenRouter配置：

# 对于LLM提供商是必需的
export OPENAI_API_KEY="your-openai-key"
export ANTHROPIC_API_KEY="your-anthropic-key"
export OPENROUTER_API_KEY="your-openrouter-key"

# 可选的OpenRouter配置，以便更好地排名
export OPENROUTER_SITE_URL="https://your-site.com"
export OPENROUTER_SITE_NAME="Your App Name"

Streamlit界面突出显示了对/sse URL的要求，并提供了有用的提示和验证。

🛠️ 支持的协议

当前支持

• 服务器发送事件（SSE） - 实时流式传输通信与MCP服务器
• HTTP/HTTPS - 标准请求-响应模式

计划支持

• 可流式传输的HTTP - 增强的HTTP流式传输能力
• WebSocket - 双向实时通信
• gRPC流式传输 - 高性能流式传输协议

🤖 LLM提供商支持

MCP Playground集成了多个LLM提供商，用于智能工具选择：

• OpenAI: GPT-4o, GPT-4, GPT-3.5-Turbo
• Anthropic: Claude 3 Opus, Claude 3 Sonnet, Claude 3 Haiku
• Ollama: Llama 3, Mistral，以及其他本地托管模型
• OpenRouter: 通过统一API访问100多种模型

📋 核心功能

1. 远程MCP客户端

轻松连接到任何远程MCP端点并与可用工具进行交互：

import asyncio
from mcp_playground import MCPClient

async def main():
    # 使用可选超时和重试设置连接到远程MCP端点
    # 重要提示：URL必须以/sse结尾，用于服务器发送事件
    client = MCPClient(
        "http://localhost:8000/sse",  # 注意/sse后缀！
        timeout=30.0,      # 连接超时时间（秒）
        max_retries=3      # 最大重试次数
    )
    
    # 列出可用工具
    tools = await client.list_tools()
    print(f"找到 {len(tools)} 个工具")
    
    # 调用计算器工具
    result = await client.invoke_tool(
        "calculator", 
        {"x": 10, "y":  5, "operation": "add"}
    )
    print(f"结果: {result.content}")  # 输出: 结果: 15
    print(f"成功: {result.error_code == 0}")

asyncio.run(main())

2. 基于LLM的工具选择

让AI根据自然语言查询选择正确的工具：

import os
from mcp_playground import MCPClient, OpenAIBridge

# 连接到MCP端点并创建LLM桥接器
client = MCPClient("http://localhost:8000/sse")
bridge = OpenAIBridge(
    client,
    api_key=os.environ.get("OPENAI_API_KEY"),
    model="gpt-4o"
)

# 处理自然语言查询
result = await bridge.process_query(
    "将此PDF转换为文本: https://example.com/document.pdf"
)

# LLM自动选择适当的工具和参数
if result["tool_call"]:
    print(f"工具: {result['tool_call']['name']}")
    print(f"结果: {result['tool_result'].content}")

3. 命令行接口

该包包括一个强大的CLI工具，用于交互式测试和分析：

# 运行CLI工具（注意端点URL中的/sse后缀）
python -m mcp_playground.examples.llm_example --provider openai --endpoint http://localhost:8000/sse

配置选项：

usage: llm_example.py [-h] [--provider {openai,anthropic,ollama}]
                     [--openai-model {gpt-4o,gpt-4-turbo,gpt-4,gpt-3.5-turbo}]
                     [--anthropic-model {claude-3-opus-20240229,claude-3-sonnet-20240229,claude-3-haiku-20240307}]
                     [--ollama-model OLLAMA_MODEL] [--ollama-host OLLAMA_HOST]
                     [--endpoint ENDPOINT] [--openai-key OPENAI_KEY]
                     [--anthropic-key ANTHROPIC_KEY]

4. 交互测试环境

包含的Streamlit应用提供了一个全面的测试界面：

关键特性：

• 多种聊天模式：
  • 自动模式：LLM自动决定何时使用工具
  • 聊天模式：直接对话，不使用MCP工具
  • 工具模式：总是尝试使用MCP工具
• 多LLM支持：OpenAI、Anthropic、Ollama和OpenRouter集成
• 动态配置：连接到任何MCP端点并实时状态
• 工具发现：自动检测并显示可用工具
• 美观的响应格式化：特殊格式化结构化数据
• 错误处理：具有清晰错误消息的强大连接管理

要运行Streamlit应用：

cd mcp-streamlit-app
pip install -r requirements.txt
streamlit run app.py

📦 安装

从源码安装

git clone https://github.com/zanetworker/mcp-playground.git
cd mcp-playground
pip install -e .

使用pip安装（一旦发布）

pip install mcp-playground

🔧 API参考

MCPClient

client = MCPClient(endpoint, timeout=30.0, max_retries=3)

参数：

• endpoint：MCP端点URL（必须是http或https，并且以/sse结尾）
• timeout：连接超时时间（秒，默认值：30.0）
• max_retries：最大重试次数（默认值：3）

⚠️ URL要求：

• 端点URL必须以/sse结尾，用于服务器发送事件通信
• 正确的URL示例：
  • http://localhost:8000/sse
  • https://my-mcp-server.com/sse
  • http://192.168.1.100:3000/sse

方法

async list_tools() -> List[ToolDef]

列出来自MCP端点的可用工具。

async invoke_tool(tool_name: str, kwargs: Dict[str, Any]) -> ToolInvocationResult

调用特定工具及其参数。

async check_connection() -> bool

检查MCP端点是否可达。

get_endpoint_info() -> Dict[str, Any]

获取有关已配置端点的信息。

错误处理

客户端包括具有特定异常类型的强大错误处理：

from mcp_playground import MCPClient, MCPConnectionError, MCPTimeoutError

try:
    client = MCPClient("http://localhost:8000/sse")
    tools = await client.list_tools()
except MCPConnectionError as e:
    print(f"连接失败: {e}")
except MCPTimeoutError as e:
    print(f"操作超时: {e}")

LLM桥接器

OpenAIBridge

bridge = OpenAIBridge(mcp_client, api_key, model="gpt-4o")

AnthropicBridge

bridge = AnthropicBridge(mcp_client, api_key, model="claude-3-opus-20240229")

OllamaBridge

bridge = OllamaBridge(mcp_client, model="llama3", host=None)

OpenRouterBridge

bridge = OpenRouterBridge(mcp_client, api_key, model="anthropic/claude-3-opus")

🔄 高级功能

重试逻辑和弹性

客户端包括带有指数退避的自动重试逻辑：

# 配置自定义重试行为
client = MCPClient(
    "http://localhost:8000/sse",
    timeout=60.0,     # 更长的超时时间，适用于慢速服务器
    max_retries=5     # 更多的重试次数
)

# 客户端自动重试失败的操作
# 指数退避：1s, 2s, 4s, 8s, 16s

连接健康监控

# 在操作之前检查端点是否可达
if await client.check_connection():
    tools = await client.list_tools()
else:
    print("服务器不可达")

# 获取详细的端点信息
info = client.get_endpoint_info()
print(f"连接到: {info['hostname']}:{info['port']}")

📋 要求

• Python 3.8+
• mcp>=0.1.0（模型上下文协议库）
• pydantic>=2.0.0（数据验证）
• openai>=1.70.0（用于OpenAI集成）
• anthropic>=0.15.0（用于Anthropic集成）
• ollama>=0.1.7（用于Ollama集成）
• streamlit（用于交互式测试应用）

🐛 故障排除

常见问题

“任务组中的未处理错误”错误： 这通常发生在asyncio兼容性问题上。Streamlit应用会自动处理这种情况，但对于自定义实现，请确保正确管理异步上下文。

连接超时：

• 增加超时参数：MCPClient(endpoint, timeout=60.0)
• 检查MCP服务器是否正在运行并且可以访问
• 验证端点URL是否正确并以/sse结尾

导入错误：

• 确保安装了所有依赖项：pip install -e .
• 检查Python版本兼容性（3.8+）

LLM集成问题：

• 验证API密钥设置是否正确
• 检查模型名称是否匹配支持的版本
• 对于Ollama，确保服务在本地运行

🚀 发展路线图

即将推出的功能

• 可流式传输的HTTP支持 - 增强的HTTP流式传输能力
• WebSocket集成 - 实时双向通信
• 连接池 - 多个连接的性能改进
• 高级缓存 - 工具定义和结果的智能缓存
• 监控仪表板 - MCP连接的实时监控
• 插件系统 - 自定义协议的可扩展架构

🤝 开发

关于开发设置、贡献指南和可用的make命令，请参阅DEVELOPMENT.md。

📄 许可

本项目采用MIT许可 - 详情请参阅LICENSE文件。

🙏 致谢

• 模型上下文协议（MCP）规范和社区
• OpenAI、Anthropic和Ollama提供的LLM API访问
• Streamlit提供的交互式测试框架