MCP Calculator Server

MCP Calculator Server

一个带有基础计算器工具的 Model Context Protocol（MCP）服务实现。此服务可部署在 Smithery 中，并通过 REST API 提供算术运算。

功能

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

安装

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

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. 安装依赖：

pip install -r requirements.txt

运行服务

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

直接使用 uvicorn 以纯 HTTP 模式运行服务：

# Set environment variable to ensure only HTTP mode runs
export MCP_HTTP_MODE=1  # On Windows: set MCP_HTTP_MODE=1
uvicorn server:app --host 0.0.0.0 --port 8000

或者使用提供的脚本：

# On Unix/Linux/Mac
./start-container.sh

# On Windows
start-container.bat

此模式推荐用于：

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

Smithery 模式（本地工具集成）

要将 Smithery 集成为本地工具，请使用 stdio 模式：

# Set environment variable to ensure only stdio mode runs
export MCP_STDIO_MODE=1  # On Windows: set MCP_STDIO_MODE=1
python server.py

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

# On Unix/Linux/Mac
./start-smithery.sh

# On Windows
start-smithery.bat

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

IMPORTANT：未设置环境变量时，切勿使用 python server.py，因为这会同时启动 HTTP 和 stdio 模式，可能导致冲突或超时。

双模式（仅用于开发）

如需同时开发和测试两个接口：

# No environment variables set - runs both modes
python server.py

这会同时启动 HTTP 服务和 stdio 处理程序，但如果标准输入关闭，进程可能会提前退出。不建议在生产环境或 Smithery 集成中使用此模式。

API 端点

标准端点

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

Smithery 集成端点

• POST /mcp：专用于 Smithery 集成的兼容 MCP 的 JSON-RPC 端点
• /mcp 处的 WebSocket：专用于 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 模式，并采用所需的日志配置：

# Set environment variables for stdio mode and logging
export MCP_STDIO_MODE=1  # On Windows: set MCP_STDIO_MODE=1
export LOGGING_CONFIG=stdio  # On Windows: set LOGGING_CONFIG=stdio

# Run the server
python server.py

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

# On Unix/Linux/Mac
./start-smithery.sh

# On Windows
start-smithery.bat

用于 Smithery 集成的 Docker 容器

要在容器中集成 Smithery，请使用专用的 Smithery Dockerfile：

# Build the Smithery-specific container
docker build -t mcp-calculator-smithery -f Dockerfile.smithery .

# Run the container with stdio mode
docker run -i -e MCP_STDIO_MODE=1 -e LOGGING_CONFIG=stdio mcp-calculator-smithery

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

# On Unix/Linux/Mac
./run-smithery-container.sh

# On Windows
run-smithery-container.bat

此容器专为 Smithery 集成配置，以 stdio 模式运行，并采用所需的日志配置。

Smithery 配置

将 Smithery 配置为使用此服务器作为本地工具：

{
  "name": "calculator",
  "description": "A basic calculator that can perform arithmetic operations",
  "command": ["python", "server.py"],
  "env": {
    "MCP_STDIO_MODE": "1",
    "LOGGING_CONFIG": "stdio"
  },
  "type": "local"
}

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

IMPORTANT：对于本地工具集成，必须使用 stdio 模式（MCP_STDIO_MODE=1）和 LOGGING_CONFIG 环境变量。HTTP 模式无法用于本地工具集成。

远程工具集成（HTTP 模式）

若要将 Smithery 集成为远程工具（例如，在容器中），请使用 HTTP 模式和专用的 MCP 端点：

{
  "name": "calculator",
  "description": "A basic calculator that can perform arithmetic operations",
  "url": "http://your-container-host:8000/mcp",
  "type": "remote"
}

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

为了在容器环境中获得最可靠的运行效果，请在部署配置中直接使用 uvicorn：

{
  "name": "calculator",
  "description": "A basic calculator that can perform arithmetic operations",
  "command": ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8000"],
  "env": {
    "MCP_HTTP_MODE": "1"
  },
  "type": "remote"
}

这样可确保在容器环境中正确处理信号，并实现更可靠的启动。