MCP 计算器服务器

一个功能完整的基于 Model Context Protocol (MCP) 的计算器服务器，提供丰富的数学运算功能，包括基础算术、根式运算、三角函数、对数运算、统计学、组合数学、数论、复数运算、矩阵运算、数值分析、金融计算、单位转换和几何计算等 13 个专业数学模块。

📦 安装

通过 npm 安装（推荐）

bash

全局安装

npm install -g mcp-calculator

或者本地安装

npm install mcp-calculator

从源码安装

bash

克隆项目

git clone https://github.com/proflulab/mcp-calculator.git
cd mcp-calculator

安装依赖

npm install

构建并启动

npm start

🚀 快速开始

全局安装后使用

bash

直接启动服务器

calculator

本地安装后使用

bash

使用 npx 运行

npx mcp-calculator

或者通过 npm scripts

npm start

🧮 功能特性

📊 13 个专业数学模块

1. 基础数学 (Basic Math)

• ✅ 加法运算 - 两个数字相加
• ✅ 减法运算 - 两个数字相减
• ✅ 乘法运算 - 两个数字相乘
• ✅ 除法运算 - 两个数字相除（包含除零错误处理）
• ✅ 求余运算 - 计算两个数的余数
• ✅ 幂运算 - 计算 a 的 b 次方

2. 根式运算 (Root Operations)

• ✅ 平方根 - 计算数字的平方根
• ✅ 立方根 - 计算数字的立方根
• ✅ 开多次方 - 计算数字的 n 次方根
• ✅ 绝对值 - 计算数字的绝对值

3. 三角函数 (Trigonometry)

• ✅ 基本三角函数 - sin, cos, tan
• ✅ 反三角函数 - asin, acos, atan
• ✅ 双曲函数 - sinh, cosh, tanh
• ✅ 角度弧度转换 - 度数与弧度互转

4. 对数函数 (Logarithms)

• ✅ 自然对数 - ln(x)
• ✅ 常用对数 - log₁₀(x)
• ✅ 任意底数对数 - log_b(x)
• ✅ 指数函数 - e^x, 10^x, a^x

5. 统计学 (Statistics)

• ✅ 描述统计 - 平均值、中位数、众数
• ✅ 离散度量 - 标准差、方差、范围
• ✅ 极值统计 - 最大值、最小值
• ✅ 聚合运算 - 求和、乘积

6. 组合数学 (Combinatorics)

• ✅ 阶乘运算 - n!
• ✅ 排列组合 - P(n,r), C(n,r)
• ✅ 斐波那契数列 - 第 n 项斐波那契数
• ✅ 卡塔兰数 - 第 n 个卡塔兰数

7. 数论 (Number Theory)

• ✅ 最大公约数 - GCD 计算
• ✅ 最小公倍数 - LCM 计算
• ✅ 素数判断 - 质数检测
• ✅ 质因数分解 - 素因子分解
• ✅ 欧拉函数 - φ(n) 计算
• ✅ 完全数判断 - 完全数检测
• ✅ 因子统计 - 因子个数和列表

8. 复数运算 (Complex Numbers)

• ✅ 基本运算 - 加减乘除
• ✅ 复数属性 - 模长、共轭、幅角
• ✅ 极坐标形式 - r∠θ 表示

9. 矩阵运算 (Matrix Operations)

• ✅ 矩阵运算 - 加法、减法、乘法
• ✅ 矩阵属性 - 行列式、转置、逆矩阵
• ✅ 向量运算 - 点积、叉积、模长

10. 数值分析 (Numerical Analysis)

• ✅ 数值积分 - 梯形法则、辛普森法则
• ✅ 数值微分 - 数值求导
• ✅ 方程求根 - 牛顿法、二分法
• ✅ 插值计算 - 拉格朗日插值

11. 金融计算 (Financial)

• ✅ 复利计算 - 投资收益计算

• ✅ 年金计算 - 现值和未来值

• ✅ 贷款计算 - 月供计算

• ✅ 投资分析 - NPV、IRR 计算

• ✅ 债券定价 - 债券价格计算#### 12. 单位转换 (Conversions)

• ✅ 长度转换 - 米、英尺、英寸等

• ✅ 重量转换 - 千克、磅、盎司等

• ✅ 温度转换 - 摄氏度、华氏度、开尔文

• ✅ 面积体积 - 各种单位互转

• ✅ 时间转换 - 秒、分钟、小时等

13. 几何计算 (Geometry)

• ✅ 平面几何 - 圆形、矩形、三角形面积周长
• ✅ 立体几何 - 球体、圆柱、圆锥体积表面积
• ✅ 坐标几何 - 点距离、直线方程

🔧 系统特性

• ✅ 参数验证 - 使用 Zod 进行输入验证
• ✅ 错误处理 - 完善的错误处理机制
• ✅ 模块化设计 - 13个独立数学模块
• ✅ 类型安全 - 完整的 TypeScript 类型定义
• ✅ 单元测试 - 266个测试用例，100%覆盖率

安装和使用

1. 安装依赖

bash
npm install

2. 构建项目

bash
npm run build

3. 启动服务器

bash
npm start

或者直接运行构建后的文件：

bash
node build/index.js

4. 测试服务器

详细的测试说明和使用方法请参考：测试文档

快速运行测试：

bash

运行所有测试

npm test

运行单元测试

npm run test:unit

运行集成测试

npm run test:integration

生成覆盖率报告

npm run test:coverage

💡 使用示例

在 MCP 客户端中使用

全局安装配置

如果你已经全局安装了 mcp-calculator，可以这样配置：

json
{
"mcpServers": {
"calculator": {
"command": "calculator"
}
}
}

本地安装配置

如果你是本地安装或从源码构建，可以这样配置：

json
{
"mcpServers": {
"calculator": {
"command": "node",
"args": ["/path/to/mcp_calculator/build/index.js"]
}
}
}

使用 npx 配置

json
{
"mcpServers": {
"calculator": {
"command": "npx",
"args": ["mcp-calculator"]
}
}
}

计算器功能示例

• 基础运算："计算 15 + 27"
• 三角函数："计算 sin(π/4) 的值"
• 对数运算："计算 log₂(16)"
• 开方运算："计算 ∛125"
• 复合运算："计算 2^3 + √16 - ln(e)"

命令行直接使用

bash

启动服务器

node build/index.js

在另一个终端发送请求

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"add","arguments":{"a":10,"b":5}}}' | node build/index.js

安装验证

安装完成后，你可以通过以下方式验证安装是否成功：

bash

检查版本

npm list mcp-calculator

运行测试（如果是从源码安装）

npm run test:all

启动服务器测试

calculator # 全局安装

或

npx mcp-calculator # 本地安装

🔧 可用工具

本项目提供 100+ 个数学工具，按 13 个专业模块组织。以下是各模块的主要工具：

📐 1. 基础数学 (Basic Math)

🔢 2. 根式运算 (Root Operations)

📊 3. 三角函数 (Trigonometry)

📈 4. 对数函数 (Logarithms)

📊 5. 统计学 (Statistics)

🎲 6. 组合数学 (Combinatorics)

🔢 7. 数论 (Number Theory)

🔄 8. 复数运算 (Complex Numbers)

🔢 9. 矩阵运算 (Matrix Operations)

📊 10. 数值分析 (Numerical Analysis)

💰 11. 金融计算 (Financial)

🔄 12. 单位转换 (Conversions)

| 工具名 | 描述 | 示例 ||--------|------|------|
| length_conversion | 长度转换 | 米、英尺、英寸互转 |
| weight_conversion | 重量转换 | 千克、磅、盎司互转 |
| temperature_conversion | 温度转换 | 摄氏度、华氏度、开尔文 |
| area_conversion | 面积转换 | 平方米、英亩等 |
| time_conversion | 时间转换 | 秒、分钟、小时等 |

📐 13. 几何计算 (Geometry)

💡 提示: 每个工具都包含完整的参数验证、错误处理和详细的使用说明。使用 MCP 协议的 tools/list 方法可以获取所有工具的完整定义。

📡 MCP 协议使用

连接服务器

服务器通过标准输入/输出 (stdio) 进行通信，支持 JSON-RPC 2.0 协议。

获取工具列表

json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}

🛠️ 技术栈

• TypeScript - 主要开发语言，提供类型安全
• @modelcontextprotocol/sdk - MCP 协议实现
• Zod - 运行时类型验证和输入校验
• Node.js - 运行环境

依赖版本

• Node.js >= 16.0.0
• TypeScript >= 5.0.0
• @modelcontextprotocol/sdk ^1.17.4
• Zod ^3.25.76

📁 项目结构

text
mcp-calculator/
├── src/ # 源代码目录
│ ├── index.ts # 主服务器文件
│ ├── types.ts # 类型定义文件
│ └── modules/ # 数学模块目录
│ ├── basicMath.ts # 基础数学运算
│ ├── rootOperations.ts # 根式运算
│ ├── trigonometry.ts # 三角函数
│ ├── logarithm.ts # 对数函数
│ ├── statistics.ts # 统计学函数
│ ├── combinatorics.ts # 组合数学
│ ├── numberTheory.ts # 数论函数
│ ├── complex.ts # 复数运算
│ ├── matrix.ts # 矩阵运算
│ ├── numerical.ts # 数值分析
│ ├── financial.ts # 金融计算
│ ├── conversion.ts # 单位转换
│ └── geometry.ts # 几何计算
├── tests/ # 测试文件目录
│ ├── unit/ # 单元测试
│ │ ├── basicMath.test.ts
│ │ ├── rootOperations.test.ts
│ │ ├── trigonometry.test.ts
│ │ ├── logarithm.test.ts
│ │ ├── statistics.test.ts
│ │ ├── combinatorics.test.ts
│ │ ├── numberTheory.test.ts
│ │ ├── complex.test.ts
│ │ ├── matrix.test.ts
│ │ ├── numerical.test.ts
│ │ ├── financial.test.ts
│ │ ├── conversion.test.ts
│ │ └── geometry.test.ts
│ ├── integration/ # 集成测试
│ ├── performance/ # 性能测试
│ ├── jest.config.cjs # Jest 配置文件
│ ├── setup.ts # 测试环境设置
│ ├── coverage/ # 测试覆盖率报告
│ └── README.md # 测试文档
├── build/ # 编译输出目录
├── package.json # 项目配置和依赖
├── package-lock.json # 锁定依赖版本
├── tsconfig.json # TypeScript 编译配置
├── .gitignore # Git 忽略文件配置
├── LICENSE # MIT 许可证
└── README.md # 项目说明文档

📜 开发脚本

构建和运行- npm run build - 编译 TypeScript 代码

• npm start - 构建并启动服务器
• npm run dev - 开发模式（监听文件变化自动重编译）

🤝 贡献

欢迎提交 Issue 和 Pull Request！

开发流程

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

代码规范

• 使用 TypeScript 进行开发
• 遵循现有的代码风格
• 为新功能添加相应的测试
• 更新文档说明

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情

📋 版本信息

当前版本：v1.0.1

版本历史

• v1.0.1 - 初始发布版本
  • 支持19个数学运算工具
  • 完整的错误处理机制
  • 100%测试覆盖率
  • npm包发布

🔗 相关链接

• npm 包: mcp-calculator
• GitHub 仓库: mcp-calculator
• Model Context Protocol 官方文档
• MCP TypeScript SDK
• Zod 验证库

📊 功能统计

• 100+ 个数学工具
• 13 个专业数学模块
• 266 个测试用例
• 14 个测试套件
• 100% 测试覆盖率
• 100% 测试通过率
• 完整 的错误处理机制
• TypeScript 类型安全
• 模块化设计 架构

🚀 性能特性

• 轻量级: 编译后体积小，启动快速
• 内存高效: 低内存占用，适合长期运行
• 类型安全: 完整的 TypeScript 类型定义
• 错误恢复: 单个计算错误不影响服务器运行

📚 API 参考

模块分类

错误类型

返回格式

所有工具调用都返回统一的格式：

typescript
interface ToolResult {
content: [{
type: "text";
text: string;
}];
isError?: boolean;
}