使用说明

项目简介

'mcp-example' 是一个 Model Context Protocol (MCP) 的参考实现，它同时包含了客户端和服务端。本项目主要演示了如何构建一个 MCP 服务器，用于托管和管理工具，并通过标准化的 JSON-RPC over HTTP/WebSocket 协议，为 LLM 应用提供工具调用服务。该示例尤其关注工具调用的本地和远程场景，并展示了与 AWS Bedrock 和 Claude 3.7 集成的潜力。

主要功能点

工具注册与执行: 允许注册各种功能工具（如计算器、文本处理），并通过服务器接口安全地执行这些工具。
远程工具调用: 通过 HTTP API 提供工具的远程调用能力，支持标准的 JSON-RPC 请求和响应格式。
WebSocket 流式处理: 支持 WebSocket 连接，用于处理长时间运行的工具调用，并流式返回结果，适用于需要实时反馈的应用场景。
API 密钥认证: 服务器端实现了简单的 API 密钥认证，保障工具调用的安全性。
结果缓存: 客户端和服务端都支持结果缓存，提升性能并减少不必要的重复计算。
代理工具: 内置代理工具，可以将工具调用转发到其他 MCP 服务器，实现工具链的灵活组合。
工具链: 支持本地工具和远程工具的链式调用，构建更复杂的工作流。

安装步骤

克隆仓库:

git clone https://github.com/iddv/mcp-example.git
cd mcp-example

安装依赖: 推荐使用 Poetry 进行依赖管理，或者使用 venv。

使用 Poetry (推荐):
```
poetry install
```

使用 venv:

python3 -m venv venv
source venv/bin/activate   # Linux/macOS
# venv\Scripts\activate.bat  # Windows
pip install -e .

服务器配置

对于 MCP 客户端，配置连接到此 MCP 服务器，您需要提供以下 JSON 格式的服务器配置信息。以下配置信息描述了如何启动 'mcp-example' 服务器，并允许客户端通过命令行与其建立连接。

{
  "serverName": "mcp-example-server",
  "command": "python",
  "args": [
    "-m",
    "mcp_example.server.main",
    "start",
    "--host", "0.0.0.0",   // 服务器监听地址，0.0.0.0 表示监听所有网络接口
    "--port", "8000"      // 服务器端口号，默认为 8000
    // "--reload",          // (可选) 启用自动重载，方便开发时使用
    // "--log-level", "debug" // (可选) 设置日志级别，默认为 info
  ]
}

基本使用方法

启动服务器: 使用 Poetry 或 venv 启动服务器。

使用 Poetry:

poetry run python -m mcp_example.server.main start --host 0.0.0.0 --port 8000

使用 venv:

python -m mcp_example.server.main start --host 0.0.0.0 --port 8000

服务器默认运行在 'http://127.0.0.1:8000'。您可以通过访问 'http://127.0.0.1:8000/docs' 查看 API 文档。

测试 API (使用 curl):

列出可用工具:

curl http://localhost:8000/api/functions -H "X-API-Key: test-key"

调用计算器工具:

curl -X POST http://localhost:8000/api/functions/call \
  -H "X-API-Key: test-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "calculator", "parameters": {"operation": "add", "a": 5, "b": 3}}'

调用文本转换工具:

curl -X POST http://localhost:8000/api/functions/call \
  -H "X-API-Key: test-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "transform_text", "parameters": {"operation": "uppercase", "text": "hello world"}}'

使用 HTTP 客户端 (Python): 项目提供了 Python HTTP 客户端，方便在 Python 应用中调用 MCP 服务器。示例代码请参考 'README.md' 中的 "Using the HTTP Client" 部分。

关键词

使用说明

信息