calculator-mcp-server

---

概述

由 math.js 驱动的计算器。通过一个工具验证数值结果、化简代数表达式并计算符号导数。

工具

工具	描述
calculate	计算数学表达式、化简代数表达式或计算符号导数。

资源

资源	描述
calculator://help	可用函数、运算符、常量和语法参考。

功能参考

calculate _工具

• 每次调用处理一个 expression。operation 可选择 evaluate（默认）、simplify 或 derivative；求导时需要提供 variable（例如 "x"）。
• 可计算算术、三角函数、对数、统计、矩阵、复数、单位和组合数学；通过 scope 赋值数值变量，例如 { "x": 5 }。
• numericType 可选择 number、BigNumber（64 位有效数字，适用于超出 64 位浮点数范围的值）或 Fraction（精确有理数）。当结果没有精确的有理数值（sqrt(2)）、表达式调用了 Fraction 模式无法计算的函数（sqrt(4)、5!），或使用了 Fraction 模式仅以舍入浮点数形式保存的值（pi、2^(1/2)）时，Fraction 模式会返回 fraction_unsupported，并提示更改数值类型。
• precision 设置数值结果的 1–16 位有效数字。空白的可选 variable 和 precision 值会被视为未提供；scope 和 precision 不影响符号运算。
• 化简包括代数和三角恒等式（2x + 3x → 5 * x）；unchanged: true 表示化简器无法进一步化简表达式，包括多项式因式分解和有理式约分的情况。
• 返回结果字符串、结果类型、原始表达式和操作。验证失败时会提供带类型的原因和恢复提示。

---

calculator://help _资源

• 函数、运算符、常量、单位和表达式语法的 Markdown 参考；无需参数。
• 示例涵盖 scope、矩阵、复数、精度和全部三种操作。
• 可使用公共范围（cacheHint）缓存 24 小时——这是运行时不会改变的静态内容。

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并提供结构化日志和可选的 OpenTelemetry 跟踪。

计算器专属功能：

• 强化的 math.js v15 实例——禁用危险函数，并在 vm 超时限制下运行计算
• 无需身份验证——所有操作均为只读且无状态
• 输入验证：限制表达式长度并拒绝多条语句；矩阵行分隔符和字符串内容仍然有效
• 结果验证：屏蔽特定结果类型（函数、解析器、结果集），并可配置结果大小上限
• 大小限制：按次调用限制根据大小、乘积、广播、索引或精度参数构建矩阵或字符串的函数；每次计算还有总元素预算；超出限制的请求会快速失败并返回 result_too_large
• scope 清理：仅允许数值，防止原型污染（屏蔽 __proto__、constructor 等）

面向 Agent 的输出：

• 有效调用回显——每个响应都会回显表达式和操作，以及应用了哪些 scope 变量和精度，以便 Agent 验证实际计算内容
• 可区分的输出约定——simplify 中的 unchanged: true 会标明结果没有变化，而不是静默地返回相同表达式
• 带类型的错误原因——验证和计算失败时会附带带类型的 reason（例如 fraction_unsupported、evaluation_timeout、disallowed_result_type）及可执行的恢复提示，而非原始异常

入门

公共托管实例

可使用公共实例 https://calculator.caseyjhand.com/mcp，无需安装。该实例提供 Streamable HTTP；每种客户端都有各自的配置格式。

对于 Claude Code：

claude mcp add --transport http calculator-mcp-server https://calculator.caseyjhand.com/mcp

对于 Cline（cline_mcp_settings.json）：

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

对于 Cursor（mcp.json）：

{
  "mcpServers": {
    "calculator-mcp-server": {
      "url": "https://calculator.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在“设置”→“连接器”下添加远程服务。

自托管 / 本地

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

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

或者使用 npx（无需 Bun）：

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

或者使用 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"
      ]
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动构建后的服务：

MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本

安装

1. 克隆仓库：

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

2. 进入目录：

cd calculator-mcp-server

3. 安装依赖：

bun install

配置

变量	说明	默认值
CALC_MAX_EXPRESSION_LENGTH	允许的最大表达式字符串长度（10–10,000）。	1000
CALC_EVALUATION_TIMEOUT_MS	最大求值时间（毫秒，100–30,000）。	5000
CALC_MAX_RESULT_LENGTH	结果字符串的最大长度（字符数，1,000–1,000,000）。	100000
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_HOST	HTTP 服务的主机名。	127.0.0.1
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_HTTP_ENDPOINT_PATH	HTTP MCP 端点的路径。	/mcp
MCP_HTTP_MAX_BODY_BYTES	入站 HTTP 请求的最大大小；0 表示不设限制。	1048576
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_SESSION_MODE	auto、stateful 或 stateless。服务在代码中声明为 stateless，因此每种启动方式都会解析为相同模式；设置此项会覆盖该声明。	stateless
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info

有关可选的会话、可恢复性、日志记录和遥测设置，请参阅 .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

该镜像默认使用端口 3010 上的 Streamable HTTP、无状态会话，并将日志写入 /var/log/calculator-mcp-server。默认会安装 OpenTelemetry 依赖；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖。

项目结构

目录	用途
src/mcp-server/tools/	工具定义（*.tool.ts）。
src/mcp-server/resources/	资源定义（*.resource.ts）。
src/services/	领域服务集成（MathService）。
src/config/	使用 Zod 解析和验证环境变量。
docs/	生成的目录树。
tests/	计算、配置和响应契约测试。

开发指南

开发指南和架构规则请参阅 AGENTS.md 或 CLAUDE.md。简要概括如下：

• 处理器抛出异常，框架捕获异常——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志
• 在 src/index.ts 中注册新工具和资源

贡献

欢迎提交问题。提交前请运行检查：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。