MCP 计算器服务器

一个实现了模型上下文协议 (MCP) 的服务器，带有一个基本的计算器工具。此服务器可以部署在 Smithery 中，并通过 REST API 提供算术运算。

功能特性

• 基本算术运算（加、减、乘、除）
• 符合 MCP 协议的 API 端点
• JSON 模式验证
• 错误处理
• 多种通信模式（HTTP、WebSocket、stdio）
• 针对不同部署场景的专用入口点

安装

1. 创建一个虚拟环境（推荐）：

python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

2. 安装依赖项：

pip install -r requirements.txt

运行服务器

HTTP 模式（推荐用于生产环境和容器）

直接使用 uvicorn 在纯 HTTP 模式下运行服务器：

# 设置环境变量以确保仅运行 HTTP 模式
export MCP_HTTP_MODE=1  # 在 Windows 上：set MCP_HTTP_MODE=1
uvicorn server:app --host 0.0.0.0 --port 8000

或者使用提供的脚本：

# 在 Unix/Linux/Mac 上
./start-container.sh

# 在 Windows 上
start-container.bat

此模式推荐用于：

• 生产环境部署
• 容器环境
• 任何需要可靠 HTTP 端点的场景

Smithery 模式（本地工具集成）

对于作为本地工具的 Smithery 集成，请使用 stdio 模式：

# 设置环境变量以确保仅运行 stdio 模式
export MCP_STDIO_MODE=1  # 在 Windows 上：set MCP_STDIO_MODE=1
python server.py

或者使用提供的便捷脚本：

# 在 Unix/Linux/Mac 上
./start-smithery.sh

# 在 Windows 上
start-smithery.bat

此模式专门为 Smithery 的本地工具集成而设计，并通过标准输入/输出进行通信。

重要提示：请勿在未设置环境变量的情况下使用 python server.py，因为它会同时启动 HTTP 和 stdio 模式，这可能会导致冲突或超时。

双模式（仅用于开发）

为了同时进行开发和测试两个接口：

# 不设置环境变量 - 运行两种模式
python server.py

这将同时启动 HTTP 服务器和 stdio 处理程序，但如果 stdin 关闭，可能会过早退出。不建议将此模式用于生产环境或 Smithery 集成。

API 端点

标准端点

• GET /health: 健康检查端点
• GET /tools: 列出可用工具及其模式
• POST /: 用于 MCP 协议的 JSON-RPC 端点
• WebSocket at /: 用于 MCP 协议的 WebSocket 端点

Smithery 集成端点

• POST /mcp: 专用于 Smithery 集成的 MCP 兼容 JSON-RPC 端点
• WebSocket at /mcp: 专用于 Smithery 集成的 MCP 兼容 WebSocket 端点

这些专用的 MCP 端点专门为 Smithery 集成而设计，并自动处理初始化和工具列表，而无需显式初始化步骤。

使用计算器工具

REST API

到 /tools 端点的示例请求：

curl -X GET http://localhost:8000/tools

JSON-RPC (HTTP)

到 JSON-RPC 端点的示例请求：

curl -X POST http://localhost:8000/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "execute", "params": {"function_calls": [{"name": "calculator", "parameters": {"operation": "add", "numbers": [1, 2, 3, 4]}}]}, "id": 1}'

可用操作：

• add: 将所有数字相加
• subtract: 从第一个数字中减去后续数字
• multiply: 将所有数字相乘
• divide: 将第一个数字除以所有后续数字

错误处理

服务器为以下情况提供清晰的错误消息：

• 无效操作
• 除以零
• 操作数数量不足
• 无效的参数类型
• JSON-RPC 协议错误

部署

Docker 容器

构建并运行 Docker 容器：

docker build -t mcp-calculator-server .
docker run -p 8000:8000 mcp-calculator-server

该容器直接使用 uvicorn 以确保 HTTP 服务器以正确的信号处理可靠地启动，从而使 API 端点可以在 http://localhost:8000 访问。

Smithery 集成

本地工具集成（stdio 模式）

对于作为本地工具的 Smithery 集成，您必须使用带有必需日志记录配置的 stdio 模式：

# 设置 stdio 模式和日志记录的环境变量
export MCP_STDIO_MODE=1  # 在 Windows 上：set MCP_STDIO_MODE=1
export LOGGING_CONFIG=stdio  # 在 Windows 上：set LOGGING_CONFIG=stdio

# 运行服务器
python server.py

或者使用提供的便捷脚本：

# 在 Unix/Linux/Mac 上
./start-smithery.sh

# 在 Windows 上
start-smithery.bat

用于 Smithery 集成的 Docker 容器

对于容器中的 Smithery 集成，请使用专用的 Smithery Dockerfile：

# 构建特定于 Smithery 的容器
docker build -t mcp-calculator-smithery -f Dockerfile.smithery .

# 使用 stdio 模式运行容器
docker run -i -e MCP_STDIO_MODE=1 -e LOGGING_CONFIG=stdio mcp-calculator-smithery

或者使用提供的便捷脚本：

# 在 Unix/Linux/Mac 上
./run-smithery-container.sh

# 在 Windows 上
run-smithery-container.bat

此容器专门为 Smithery 集成而配置，并在 stdio 模式下运行，并具有所需的日志记录配置。

Smithery 配置

配置 Smithery 以将服务器用作本地工具：

{
  "name": "calculator",
  "description": "一个可以执行算术运算的基本计算器",
  "command": ["python", "server.py"],
  "env": {
    "MCP_STDIO_MODE": "1",
    "LOGGING_CONFIG": "stdio"
  },
  "type": "local"
}

此配置确保服务器在由 Smithery 作为本地工具运行时通过 stdio 进行通信，并正确配置日志记录系统。

重要提示：对于本地工具集成，您必须使用带有 LOGGING_CONFIG 环境变量的 stdio 模式 (MCP_STDIO_MODE=1)。 HTTP 模式不适用于本地工具集成。

远程工具集成（HTTP 模式）

对于作为远程工具（例如，在容器中）的 Smithery 集成，请使用带有专用 MCP 端点的 HTTP 模式：

{
  "name": "calculator",
  "description": "一个可以执行算术运算的基本计算器",
  "url": "http://your-container-host:8000/mcp",
  "type": "remote"
}

此配置确保 Smithery 可以使用专用的 MCP 兼容端点通过 HTTP 访问该工具的 API 端点。

为了在容器环境中获得最可靠的操作，请在您的部署配置中直接使用 uvicorn：

{
  "name": "calculator",
  "description": "一个可以执行算术运算的基本计算器",
  "command": ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8000"],
  "env": {
    "MCP_HTTP_MODE": "1"
  },
  "type": "remote"
}

这确保了正确的信号处理以及在容器环境中更可靠的启动。