calc-mcp-server 0.1.0

package/docs/plans/2025-02-24-mcp-calculator-design.md

@@ -0,0 +1,344 @@
+# MCP Server 计算器设计文档
+
+**日期**: 2025-02-24
+**状态**: 已批准
+**方案**: 自研解析器架构
+
+---
+
+## 概述
+
+为 AI 助手提供计算能力的 MCP Server，支持四则运算和程序员计算功能。采用自研解析器架构，使用 `decimal.js` 处理四则运算精度，`BigInt` 处理程序员计算大数运算。
+
+## 功能范围
+
+### 优先级
+1. **四则运算** - 基础加减乘除、括号优先级
+2. **程序员计算** - 进制转换、位运算、ASCII 码、字节序、编码转换
+
+### 使用场景
+- AI 助手增强 - 为 Claude/AI 助手提供精确计算能力
+
+---
+
+## 架构设计
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    MCP Server                           │
+├─────────────────────────────────────────────────────────┤
+│  ┌─────────────────────────────────────────────────┐    │
+│  │              工具层 (MCP Tools)                  │    │
+│  │  • basic_calculate(expression)                  │    │
+│  │  • programmer_calculate(expression)             │    │
+│  │  • convert_number(value, from, to)              │    │
+│  │  • ascii_encode(text) / ascii_decode(code)      │    │
+│  └─────────────────┬───────────────────────────────┘    │
+│  ┌─────────────────▼───────────────────────────────┐    │
+│  │              表达式解析层                        │    │
+│  │  ┌─────────────┐    ┌─────────────────────┐     │    │
+│  │  │  Lexer      │───▶│    Parser           │     │    │
+│  │  │  (词法)     │    │    (语法/AST)        │     │    │
+│  │  └─────────────┘    └──────────┬──────────┘     │    │
+│  └──────────────────────────────────┼────────────────┘    │
+│  ┌──────────────────────────────────▼────────────────┐    │
+│  │              计算引擎层                            │    │
+│  │  ┌─────────────────────┐  ┌─────────────────────┐ │    │
+│  │  │  DecimalEngine      │  │  ProgrammerEngine   │ │    │
+│  │  │  (四则运算)          │  │  (程序员计算)        │ │    │
+│  │  │  • decimal.js       │  │  • BigInt           │ │    │
+│  │  └─────────────────────┘  └─────────────────────┘ │    │
+│  └─────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 核心设计原则
+- **工具分类**: 按功能类型暴露不同的 MCP 工具
+- **表达式驱动**: 每个工具接受表达式字符串，返回计算结果
+- **双引擎架构**: Decimal 引擎处理四则运算，BigInt 引擎处理程序员计算
+- **统一解析**: 共享 Lexer 和 Parser，不同引擎处理 AST
+
+---
+
+## MCP 工具定义
+
+| 工具名 | 功能描述 | 示例输入 |
+|--------|----------|----------|
+| `basic_calculate` | 四则运算表达式计算 | `"2.5 * 3 + (10 - 4) / 2"` |
+| `programmer_calculate` | 程序员计算表达式（位运算、大数） | `"0xFF & 0x0F \| 0x10"` |
+| `convert_base` | 进制转换（2/8/10/16） | `{ value: "255", from: 10, to: 16 }` |
+| `bit_operation` | 单独的位运算操作 | `{ op: "and", a: "0xFF", b: "0x0F" }` |
+| `ascii_encode` | 文本转 ASCII 码 | `"Hello"` |
+| `ascii_decode` | ASCII 码转文本 | `"72 101 108 108 111"` |
+| `endian_convert` | 字节序转换 | `{ value: "0x12345678", from: "big", to: "little" }` |
+| `number_encoding` | 浮点数编码（IEEE 754） | `{ value: 3.14, format: "float32" }` |
+
+### 返回格式（成功）
+```json
+{
+  "success": true,
+  "result": "结果值（字符串形式）",
+  "details": {
+    "expression": "原始表达式",
+    "steps": ["计算步骤（可选）"]
+  }
+}
+```
+
+### 返回格式（错误）
+```json
+{
+  "success": false,
+  "error": {
+    "type": "SyntaxError | DivisionByZero | InvalidBase | ...",
+    "message": "人类可读错误信息",
+    "position": { "start": 5, "end": 8 },
+    "suggestion": "修复建议"
+  }
+}
+```
+
+---
+
+## 表达式语法设计
+
+### 支持的字面量
+
+| 类型 | 语法示例 | 说明 |
+|------|----------|------|
+| 十进制整数 | `42` | 普通整数 |
+| 十进制小数 | `3.14`, `0.5` | 浮点数 |
+| 十六进制 | `0xFF`, `0x1a3` | `0x` 前缀 |
+| 二进制 | `0b1011`, `0B1100` | `0b` 前缀 |
+| 八进制 | `0o77`, `0O755` | `0o` 前缀 |
+| ASCII 字符 | `'A'`, `'\n'` | 单引号字符 |
+
+### 运算符优先级（从高到低）
+
+| 优先级 | 运算符 | 说明 |
+|--------|--------|------|
+| 1 | `()` | 括号 |
+| 2 | `~`, `!` | 位非、逻辑非 |
+| 3 | `*`, `/`, `%` | 乘、除、取模 |
+| 4 | `+`, `-` | 加、减 |
+| 5 | `<<`, `>>`, `>>>` | 左移、右移、无符号右移 |
+| 6 | `&` | 位与 |
+| 7 | `^` | 位异或 |
+| 8 | `\|` | 位或 |
+| 9 | `&&`, \|\| | 逻辑与、逻辑或 |
+
+### 表达式示例
+
+```
+# 四则运算
+"2 + 3 * 4"           # → 14
+"(10 - 3) * 2"        # → 14
+"0.1 + 0.2"           # → 0.3 (Decimal 精度)
+
+# 程序员计算
+"0xFF & 0x0F"         # → 15
+"0b1010 << 2"         # → 40
+"~0x00"               # → -1
+"0xFF | 0x0F0"        # → 255
+
+# 混合（建议分开，但语法支持）
+"0xFF + 0b10"         # → 257
+```
+
+---
+
+## 核心组件
+
+### 4.1 Lexer（词法分析器）
+
+```typescript
+type TokenType =
+  | 'NUMBER' | 'HEX' | 'BINARY' | 'OCTAL'
+  | 'OPERATOR' | 'LPAREN' | 'RPAREN'
+  | 'CHAR_LITERAL' | 'WHITESPACE' | 'EOF';
+
+interface Token {
+  type: TokenType;
+  value: string;
+  position: { start: number; end: number };
+}
+
+class Lexer {
+  tokenize(expression: string): Token[];
+}
+```
+
+**职责**: 将表达式字符串转换为 Token 流，支持所有字面量格式。
+
+### 4.2 Parser（语法分析器）
+
+```typescript
+type ASTNode =
+  | BinaryOpNode | UnaryOpNode | LiteralNode
+  | GroupNode | FunctionNode;
+
+interface BinaryOpNode {
+  type: 'BinaryOp';
+  operator: string;
+  left: ASTNode;
+  right: ASTNode;
+}
+
+class Parser {
+  parse(tokens: Token[]): ASTNode;
+
+  private parseExpression(): ASTNode;
+  private parseTerm(): ASTNode;
+  private parseFactor(): ASTNode;
+}
+```
+
+**职责**: 根据运算符优先级构建 AST，捕获语法错误并提供位置信息。
+
+### 4.3 DecimalEngine（四则运算引擎）
+
+```typescript
+import { Decimal } from 'decimal.js';
+
+class DecimalEngine {
+  evaluate(ast: ASTNode): Decimal;
+
+  private visitBinaryOp(node: BinaryOpNode): Decimal;
+  private visitUnaryOp(node: UnaryOpNode): Decimal;
+  private visitLiteral(node: LiteralNode): Decimal;
+}
+```
+
+**职责**: 遍历 AST，使用 `decimal.js` 执行四则运算，处理除零等错误。
+
+### 4.4 ProgrammerEngine（程序员计算引擎）
+
+```typescript
+class ProgrammerEngine {
+  evaluate(ast: ASTNode): bigint;
+
+  private bitAnd(a: bigint, b: bigint): bigint;
+  private bitOr(a: bigint, b: bigint): bigint;
+  private bitXor(a: bigint, b: bigint): bigint;
+  private bitNot(value: bigint): bigint;
+  private shiftLeft(value: bigint, amount: bigint): bigint;
+
+  private parseLiteral(token: Token): bigint;
+}
+```
+
+**职责**: 遍历 AST，使用 `BigInt` 执行位运算和进制转换。
+
+### 4.5 ErrorHandler（错误处理器）
+
+```typescript
+type ErrorType =
+  | 'SyntaxError' | 'DivisionByZero' | 'InvalidNumber'
+  | 'OverflowError' | 'InvalidBase' | 'UnmatchedParen';
+
+class ErrorHandler {
+  createError(type: ErrorType, message: string, position?: Position): ErrorResponse;
+
+  syntaxError(message: string, start: number, end: number): ErrorResponse;
+  runtimeError(type: ErrorType, message: string): ErrorResponse;
+}
+```
+
+**职责**: 统一生成结构化错误，包含位置信息和修复建议。
+
+---
+
+## 项目结构
+
+```
+calculator/
+├── docs/
+│   └── plans/
+│       └── 2025-02-24-mcp-calculator-design.md
+├── src/
+│   ├── mcp/
+│   │   ├── server.ts          # MCP Server 入口
+│   │   └── tools/             # MCP 工具实现
+│   │       ├── basic.ts
+│   │       ├── programmer.ts
+│   │       ├── conversion.ts
+│   │       ├── ascii.ts
+│   │       └── encoding.ts
+│   ├── parser/
+│   │   ├── lexer.ts
+│   │   ├── parser.ts
+│   │   └── ast.ts
+│   ├── engines/
+│   │   ├── decimal.ts
+│   │   └── programmer.ts
+│   ├── errors/
+│   │   ├── handler.ts
+│   │   └── types.ts
+│   └── index.ts
+├── test/
+│   ├── unit/
+│   │   ├── lexer.test.ts
+│   │   ├── parser.test.ts
+│   │   ├── decimal-engine.test.ts
+│   │   └── programmer-engine.test.ts
+│   └── integration/
+│       └── mcp-tools.test.ts
+├── package.json
+├── tsconfig.json
+├── vite.config.ts
+└── README.md
+```
+
+---
+
+## 测试策略
+
+### 单元测试（Vitest）
+
+- **Lexer**: Token 化正确性，所有字面量类型
+- **Parser**: 运算符优先级，AST 结构，语法错误捕获
+- **DecimalEngine**: 计算精度（0.1 + 0.2 = 0.3），除零错误
+- **ProgrammerEngine**: 位运算正确性，大数处理
+- **ErrorHandler**: 错误类型，位置信息
+
+### 集成测试
+
+- MCP 工具端到端测试
+- 结构化成功/错误响应验证
+- 边界情况处理
+
+### 边界情况覆盖
+
+- 精度边界：极大/极小数
+- 大数边界：BigInt 溢出
+- 错误边界：空输入、不匹配括号、非法字符
+- 进制边界：非法前缀、非法进制字符
+
+### 测试覆盖目标
+
+| 组件 | 目标覆盖率 |
+|------|------------|
+| Lexer | 100% |
+| Parser | 95%+ |
+| DecimalEngine | 90%+ |
+| ProgrammerEngine | 95%+ |
+| ErrorHandler | 90%+ |
+
+---
+
+## 依赖库
+
+- `decimal.js` - 高精度十进制运算
+- `@modelcontextprotocol/sdk` - MCP Server SDK
+- `vitest` - 测试框架
+- `typescript` - 类型系统
+
+---
+
+## 非目标（明确不实现）
+
+- 变量赋值和存储
+- 函数定义和调用（除内置转换函数外）
+- 复杂的数学函数（sin/cos/log 等）
+- 历史记录功能
+- 图形化界面