MCP Calculator

一个功能强大的 MCP (Model Context Protocol) Server 计算器，提供基础算术运算和程序员计算功能。

项目简介

MCP Calculator 是一个使用 TypeScript 实现的计算器服务器，通过 MCP 协议提供各种计算功能。它支持高精度十进制运算和程序员级整数运算（包括位运算），以及进制转换和 ASCII 字符转换。

功能特性

基础计算器 (basic_calculate)

• 支持四则运算：加 (+)、减 (-)、乘 (*)、除 (/)、取余 (%)
• 支持括号优先级
• 使用 Decimal.js 实现高精度计算
• 自动处理浮点数精度问题（如 0.1 + 0.2 = 0.3）

程序员计算器 (programmer_calculate)

• 整数算术运算
• 位运算：按位与 (&)、按位或 (|)、按位异或 (^)、按位取反 (~)
• 位移运算：左移 (<<)、右移 (>>)、无符号右移 (>>>)
• 支持多种字面量格式：
  • 十进制：42
  • 十六进制：0xFF
  • 二进制：0b1010
  • 八进制：0o755
  • 字符字面量：'A' (自动转换为 ASCII 值)

进制转换 (convert_base)

• 支持进制：2（二进制）、8（八进制）、10（十进制）、16（十六进制）
• 双向转换，任意进制互转

ASCII 转换 (ascii_to_number, number_to_ascii, multiple_ascii_to_number)

• ASCII 字符转数值
• 数值转 ASCII 字符
• 批量 ASCII 字符串转数值数组

安装方法

# 克隆仓库
git clone <repository-url>
cd calculator

# 安装依赖
npm install

# 构建项目
npm run build

使用方法

作为 MCP Server 配置

在 MCP 客户端配置文件中添加：

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

直接运行

# 开发模式（监听文件变化）
npm run dev

# 构建生产版本
npm run build

可用工具列表

1. basic_calculate

基础算术表达式计算

参数：

• expression (string): 要计算的算术表达式

示例：

basic_calculate("2 + 3 * 4")        // 返回: "14"
basic_calculate("(10 - 4) / 2")     // 返回: "3"
basic_calculate("0.1 + 0.2")        // 返回: "0.3"
basic_calculate("15 % 4")           // 返回: "3"

2. programmer_calculate

程序员计算器表达式计算

参数：

• expression (string): 要计算的程序员表达式

示例：

programmer_calculate("0xA + 0x5")           // 返回: "15" (十进制)
programmer_calculate("0b1010 & 0b1100")     // 返回: "8"
programmer_calculate("'A' + 1")             // 返回: "66" (ASCII 'B')
programmer_calculate("255 << 2")            // 返回: "1020"
programmer_calculate("~0")                  // 返回: "-1"

3. convert_base

数字进制转换

参数：

• value (string): 要转换的数值
• from (number): 源进制 (2, 8, 10, 16)
• to (number): 目标进制 (2, 8, 10, 16)

示例：

convert_base("1010", 2, 10)    // 返回: { value: "10", representation: "0b1010 = 10" }
convert_base("FF", 16, 2)      // 返回: { value: "11111111", representation: "0xFF = 0b11111111" }
convert_base("10", 10, 16)     // 返回: { value: "A", representation: "10 = 0xA" }

4. ascii_to_number

ASCII 字符转数值

参数：

• char (string): 单个 ASCII 字符

示例：

ascii_to_number("A")    // 返回: { char: "A", value: 65, binary: "0b1000001", hex: "0x41" }

5. number_to_ascii

数值转 ASCII 字符

参数：

• number (number): 数值 (0-255)

示例：

number_to_ascii(65)     // 返回: { number: 65, char: "A", description: "Letter A" }

6. multiple_ascii_to_number

批量 ASCII 字符串转数值数组

参数：

• text (string): ASCII 字符串

示例：

multiple_ascii_to_number("ABC")    // 返回: { text: "ABC", values: [65, 66, 67] }

开发指南

项目结构

calculator/
├── src/
│   ├── index.ts              # MCP Server 入口
│   ├── mcp/
│   │   ├── server.ts         # MCP Server 实现
│   │   └── tools/            # MCP 工具实现
│   │       ├── basic.ts      # 基础计算工具
│   │       ├── programmer.ts # 程序员计算工具
│   │       ├── conversion.ts # 进制转换工具
│   │       └── ascii.ts      # ASCII 转换工具
│   ├── engines/
│   │   ├── decimal.ts        # 高精度十进制引擎
│   │   └── programmer.ts     # 程序员计算引擎
│   ├── parser/
│   │   ├── lexer.ts          # 词法分析器
│   │   ├── parser.ts         # 语法分析器
│   │   └── ast.ts            # 抽象语法树定义
│   └── errors/
│       ├── types.ts          # 错误类型定义
│       └── handler.ts        # 错误处理器
├── test/
│   ├── unit/                 # 单元测试
│   └── integration/          # 集成测试
└── dist/                     # 编译输出

可用命令

# 构建项目
npm run build

# 开发模式（监听文件变化）
npm run dev

# 运行测试
npm run test

# 运行测试（带 UI）
npm run test:ui

# 运行测试覆盖率
npm run test:coverage

# 类型检查
npm run typecheck

# 代码检查
npm run lint

添加新工具

1. 在 src/mcp/tools/ 创建新的工具文件
2. 实现工具函数，遵循现有工具的模式
3. 在 src/mcp/server.ts 中注册新工具
4. 添加相应的测试

返回格式说明

所有工具的返回值均为 JSON 格式：

成功响应

{
  "content": [
    {
      "type": "text",
      "text": "计算结果或错误信息"
    }
  ]
}

basic_calculate 返回格式

{
  "result": "计算结果字符串",
  "expression": "原始表达式"
}

programmer_calculate 返回格式

{
  "result": "计算结果字符串",
  "decimal": "十进制表示",
  "hex": "十六进制表示",
  "binary": "二进制表示"
}

convert_base 返回格式

{
  "value": "转换后的值",
  "representation": "完整表示"
}

ASCII 工具返回格式

{
  "char": "字符",
  "value": 数值,
  "binary": "二进制表示",
  "hex": "十六进制表示"
}

测试覆盖

项目包含全面的单元测试和集成测试：

• 测试文件: 9 个
• 测试用例: 229 个
• 代码覆盖率: 70.09% 语句覆盖
• 分支覆盖: 88.66%

运行测试：

npm run test:coverage

依赖项

运行时依赖

• @modelcontextprotocol/sdk: ^1.0.4 - MCP SDK
• decimal.js: ^10.4.3 - 高精度十进制运算库

开发依赖

• typescript: ^5.3.3 - TypeScript 编译器
• vitest: ^1.2.0 - 测试框架
• @vitest/coverage-v8: ^1.2.0 - 代码覆盖率工具
• @types/node: ^20.11.0 - Node.js 类型定义
• eslint: ^8.56.0 - 代码检查工具

错误处理

计算器实现了完善的错误处理机制：

• 除零错误: 清晰提示除数为零
• 语法错误: 指出表达式中的语法问题位置
• 无效字符: 识别并报告表达式中的非法字符
• 无效进制: 验证进制转换的参数有效性
• 数值溢出: 检测整数运算溢出

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

作者

MCP Calculator Development Team