calc_mcp

通过 stdio 提供加、减、乘、除四种运算的计算器 MCP 服务。

使用 官方 MCP Python SDK 的 FastMCP API，依赖限定在 1.x，避免跨主要版本升级导致接口变化。

可用工具

所有工具都接收两个必填数值参数 a、b，支持整数、小数和负数。

成功调用的 structuredContent 为 {"result": 数值}，并提供兼容的文本内容。工具不读写文件、不访问网络。

错误以 MCP 工具结果的 isError: true 返回，不会中断服务：

• 除数为 0 或 -0.0：Cannot divide by zero.

• 参数为 NaN 或无穷大：Operands must be finite numbers.

• 结果溢出为无穷大：Result exceeds the supported finite number range.

• 缺少参数或传入无法解析的数值：由 SDK 返回参数校验错误。

运算使用 Python 双精度浮点数，存在通常的浮点舍入误差，例如 0.1 + 0.2 可能返回 0.30000000000000004。不用于需要十进制精确计算的场景；本版本不支持表达式求值。

目录结构

calc_mcp/
├── pyproject.toml          # 项目、依赖和命令行入口
├── uv.lock                 # 依赖版本锁定
├── README.md
├── .gitignore
├── src/calc_mcp/
│   ├── __init__.py
│   ├── __main__.py         # python -m calc_mcp 入口
│   ├── server.py           # MCP 实例和 stdio 启动
│   └── tools.py            # 四则运算、边界检查和工具注册
└── tests/
    └── test_server.py      # 算术单元测试和 stdio 集成测试

安装与启动

需要 Python 3.10+ 和 uv。在本项目目录执行：

uv sync
uv run calc-mcp

也可以通过模块入口启动：

uv run python -m calc_mcp

服务通过标准输入/输出与 MCP 客户端通信，不提供网页。直接启动后等待客户端消息属于正常现象。不要向 stdout 打印调试信息；日志应写入 stderr。

MCP 客户端配置示例

以下适用于使用 mcpServers JSON 配置格式的客户端，请根据实际客户端调整：

{
  "mcpServers": {
    "calc-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/lifang/product/0826/calc_mcp",
        "run",
        "calc-mcp"
      ]
    }
  }
}

如果客户端找不到 uv，将 command 改为 uv 可执行文件的绝对路径。移动项目后需更新目录路径。

验证

uv run python -m unittest discover -s tests -v

测试覆盖四则运算、负数、小数、零、非法参数、非有限数和溢出，并启动真实 stdio 子进程，检查 MCP 初始化、工具发现、工具调用以及错误后的正常调用。

后续扩展位置

在 src/calc_mcp/tools.py 中添加工具定义，并将函数加入 register_tools() 的注册列表。server.py 的 create_server() 会统一注册工具。