calculator-mcp-server

公共托管服务器： https://calculator.caseyjhand.com/mcp

工具

一个工具即可完成所有数学运算：

calculate

一个工具即可覆盖服务器的全部用途。operation 参数默认为 evaluate，因此常见用法只需 { expression: "..." }。

• 求值（Evaluate） — 算术、三角函数、对数、统计、矩阵、复数、单位换算、组合数学

• 化简（Simplify） — 以符号方式化简代数表达式（例如 2x + 3x -> 5 * x）。支持代数和三角恒等式

• 求导（Derivative） — 计算符号导数（例如 3x^2 + 2x + 1 -> 6 * x + 2）

• 通过 scope 参数设置变量作用域：{ "x": 5, "y": 3 }

• 数值结果精度可配置

• 基于表单的 MCP 客户端传入的空白可选 variable 和 precision 值将被视为未提供

Related MCP server: math-mcp

资源

特性

基于 @cyanheads/mcp-ts-core 构建：

• 声明式工具定义 — 每个工具一个文件，框架负责注册和验证

• 所有工具统一错误处理

• 结构化日志，支持可选的 OpenTelemetry 追踪

• 本地运行（stdio/HTTP）或 Docker 运行

计算器专属特性：

• 加固的 math.js v15 实例 — 禁用危险函数，通过 vm.runInNewContext() 在沙箱中求值并设置超时

• 无需认证 — 所有操作均为只读且无状态

• 输入验证：表达式长度限制、拒绝表达式分隔符（分号和换行）、仅允许数值型作用域值

• 结果验证：阻止危险结果类型（函数、解析器、结果集），可配置最大结果大小

• 作用域净化：仅允许数值型值，防止原型污染（阻止 __proto__、constructor 等）

快速开始

公共托管实例

公共实例位于 https://calculator.caseyjhand.com/mcp — 无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该地址：

{
  "mcpServers": {
    "calculator-mcp-server": {
      "type": "streamable-http",
      "url": "https://calculator.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地

将以下配置之一添加到您的 MCP 客户端配置文件中：

{
  "mcpServers": {
    "calculator-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/calculator-mcp-server@latest"]
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "calculator-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/calculator-mcp-server@latest"]
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "calculator-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/calculator-mcp-server:latest"
      ]
    }
  }
}

前置要求

• Bun v1.3.0 或更高版本

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/calculator-mcp-server.git

2. 进入目录：

cd calculator-mcp-server

3. 安装依赖：

bun install

配置

有关可选的会话、可恢复性、日志和遥测设置，请参阅 .env.example。

运行服务器

本地开发

• 构建并运行生产版本：

  bun run build
  bun run start:http   # or start:stdio

• 运行检查和测试：

  bun run devcheck     # Lints, formats, type-checks
  bun run test         # Runs test suite

Docker

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

该镜像默认以 Streamable HTTP 模式运行在端口 3010 上，使用无状态会话，日志输出到 /var/log/calculator-mcp-server。

项目结构

开发指南

有关开发指南和架构规则，请参阅 AGENTS.md 或 CLAUDE.md。简要说明：

• 处理器抛出异常，框架负责捕获 — 工具逻辑中不使用 try/catch

• 使用 ctx.log 记录日志

• 在 src/index.ts 中注册新工具和资源

贡献

欢迎提交 Issue 和 Pull Request。提交前请先运行检查：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。