Calculator MCP

一个最小但完整的 MCP 服务示例，适合学习和发布到官方 MCP Registry。

它同时演示了三类 MCP 能力：

• tools：calculate、add、subtract、multiply、divide、batch_calculate
• resources：calculator://guide/operators、calculator://guide/examples
• prompts：math-tutor

1. 项目结构

src/
  calculator.js     # 安全表达式解析与计算
  index.js          # MCP server 入口
test/
  calculator.test.js
server.json         # 发布到官方 Registry 的元数据
package.json

2. 本地运行

先把占位符替换成你的真实信息：

• your-github-username
• GitHub 仓库地址
• npm 包名
• mcpName

安装依赖并启动：

npm install
npm start

本地测试：

npm test

3. 在 MCP Client 中配置

以 stdio 方式接入时，客户端一般会配置成类似下面这样：

{
  "mcpServers": {
    "calculator": {
      "command": "npx",
      "args": [
        "-y",
        "@your-github-username/calculator-mcp"
      ]
    }
  }
}

如果你本地调试，也可以直接指向本地 Node：

{
  "mcpServers": {
    "calculator-local": {
      "command": "node",
      "args": [
        "C:/path/to/calculator-mcp/src/index.js"
      ]
    }
  }
}

4. 这个示例学到了什么

Tools

• calculate：直接计算表达式，例如 "(2 + 3) * 4"
• batch_calculate：一次处理多条表达式
• 基础四则运算工具：适合演示结构化参数

Resources

• calculator://guide/operators
• calculator://guide/examples

适合演示“只读知识内容”如何提供给模型。

Prompt

• math-tutor

适合演示如何把一个“可复用的提示模板”通过 MCP 暴露出去。

5. 为什么没有用 eval

这个示例自己实现了一个简单表达式解析器，只支持：

• 数字
• 小数
• 括号
• + - * /

这样更安全，也更适合学习 MCP 工具的业务逻辑该怎么写。

6. 发布到官方 MCP Registry

根据当前官方文档，发布路径是：

1. 先把 npm 包发布到公开 npm。
2. 确保 package.json 里有 mcpName，并且它与 server.json.name 一致。
3. 安装官方 mcp-publisher。
4. 登录 Registry。
5. 执行发布。

参考命令：

npm install
npm test
npm publish --access public

mcp-publisher login github
mcp-publisher publish

如果你用 GitHub 身份认证，server.json.name 必须是：

io.github.<your-github-username>/<server-name>

例如：

io.github.alice/calculator-mcp

7. 推荐的发布顺序

1. 在 GitHub 建仓库
2. 把本项目里的占位符替换为你的真实用户名
3. npm publish --access public
4. mcp-publisher login github
5. mcp-publisher publish
6. 到 Registry 搜索验证

8. 后续你可以怎么扩展

• 增加 power、sqrt、mod 等工具
• 增加 history 资源
• 增加“单位换算器”工具
• 把 stdio 扩展成远程 streamable-http 服务

9. 官方文档

• MCP Registry 说明: https://modelcontextprotocol.io/registry/about
• 发布 Quickstart: https://modelcontextprotocol.io/registry/quickstart
• 认证方式: https://modelcontextprotocol.io/registry/authentication
• 版本规范: https://modelcontextprotocol.io/registry/versioning