npm package: @neosamon/calc-mcp-server
Description: MCP Server for calculator with basic and programmer operations
Latest version: 0.1.0

# 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 字符串转数值数组

## 安装方法

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

# 安装依赖
npm install

# 构建项目
npm run build
```

## 使用方法

### 作为 MCP Server 配置

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

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

### 直接运行

```bash
# 开发模式（监听文件变化）
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/                     # 编译输出
```

### 可用命令

```bash
# 构建项目
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 格式：

### 成功响应
```json
{
  "content": [
    {
      "type": "text",
      "text": "计算结果或错误信息"
    }
  ]
}
```

### basic_calculate 返回格式
```json
{
  "result": "计算结果字符串",
  "expression": "原始表达式"
}
```

### programmer_calculate 返回格式
```json
{
  "result": "计算结果字符串",
  "decimal": "十进制表示",
  "hex": "十六进制表示",
  "binary": "二进制表示"
}
```

### convert_base 返回格式
```json
{
  "value": "转换后的值",
  "representation": "完整表示"
}
```

### ASCII 工具返回格式
```json
{
  "char": "字符",
  "value": 数值,
  "binary": "二进制表示",
  "hex": "十六进制表示"
}
```

## 测试覆盖

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

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

运行测试：
```bash
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