calc-mcp-server 0.1.0

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

@@ -0,0 +1,2626 @@
+# MCP Server 计算器实施计划
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**目标:** 构建一个为 AI 助手提供计算能力的 MCP Server，支持四则运算（使用 Decimal 精度）和程序员计算（使用 BigInt）功能。
+
+**架构:** 自研递归下降解析器 + 双引擎架构。Decimal 引擎处理四则运算，BigInt 引擎处理程序员计算。共享 Lexer 和 Parser，不同引擎处理 AST。
+
+**技术栈:** TypeScript, decimal.js, @modelcontextprotocol/sdk, vitest
+
+---
+
+## 阶段 1: 项目初始化
+
+### 任务 1: 初始化项目结构和配置
+
+**文件:**
+- 创建: `package.json`
+- 创建: `tsconfig.json`
+- 创建: `vite.config.ts`
+- 创建: `vitest.config.ts`
+- 创建: `.gitignore`
+
+**Step 1: 创建 package.json**
+
+```bash
+cat > package.json << 'EOF'
+{
+  "name": "mcp-calculator",
+  "version": "0.1.0",
+  "description": "MCP Server for calculator with basic and programmer operations",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-calculator": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": ["mcp", "calculator", "typescript"],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "decimal.js": "^10.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@vitest/ui": "^1.2.0",
+    "@vitest/coverage-v8": "^1.2.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0",
+    "eslint": "^8.56.0",
+    "@typescript-eslint/eslint-plugin": "^6.19.0",
+    "@typescript-eslint/parser": "^6.19.0"
+  }
+}
+EOF
+```
+
+**Step 2: 安装依赖**
+
+```bash
+npm install
+```
+
+**Step 3: 创建 tsconfig.json**
+
+```bash
+cat > tsconfig.json << 'EOF'
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}
+EOF
+```
+
+**Step 4: 创建 vitest.config.ts**
+
+```bash
+cat > vitest.config.ts << 'EOF'
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: ['**/node_modules/**', '**/dist/**', '**/test/**'],
+    },
+  },
+});
+EOF
+```
+
+**Step 5: 创建 .gitignore**
+
+```bash
+cat > .gitignore << 'EOF'
+node_modules/
+dist/
+*.log
+.DS_Store
+coverage/
+.nyc_output/
+EOF
+```
+
+**Step 6: 验证配置**
+
+```bash
+npm run typecheck
+```
+
+**Step 7: 初始化 Git 仓库并提交**
+
+```bash
+git init
+git add .
+git commit -m "feat: initialize project with TypeScript and Vitest"
+```
+
+---
+
+## 阶段 2: 错误处理系统
+
+### 任务 2: 定义错误类型和处理器
+
+**文件:**
+- 创建: `src/errors/types.ts`
+- 创建: `src/errors/handler.ts`
+- 测试: `test/unit/error-handler.test.ts`
+
+**Step 1: 编写错误类型定义的测试**
+
+```bash
+mkdir -p src/errors test/unit
+```
+
+```typescript
+// test/unit/error-handler.test.ts
+import { describe, it, expect } from 'vitest';
+import { ErrorHandler, ErrorType } from '../../src/errors/handler.js';
+
+describe('ErrorHandler', () => {
+  it('should create syntax error with position', () => {
+    const handler = new ErrorHandler();
+    const error = handler.syntaxError('Unexpected token', 5, 8);
+
+    expect(error.success).toBe(false);
+    expect(error.error.type).toBe('SyntaxError');
+    expect(error.error.message).toBe('Unexpected token');
+    expect(error.error.position).toEqual({ start: 5, end: 8 });
+  });
+
+  it('should create runtime error', () => {
+    const handler = new ErrorHandler();
+    const error = handler.runtimeError('DivisionByZero', 'Cannot divide by zero');
+
+    expect(error.success).toBe(false);
+    expect(error.error.type).toBe('DivisionByZero');
+    expect(error.error.message).toBe('Cannot divide by zero');
+  });
+
+  it('should include suggestion for known error types', () => {
+    const handler = new ErrorHandler();
+    const error = handler.syntaxError('Unexpected token', 5, 8);
+
+    expect(error.error.suggestion).toBeDefined();
+    expect(typeof error.error.suggestion).toBe('string');
+  });
+});
+```
+
+**Step 2: 运行测试验证失败**
+
+```bash
+npm test -- test/unit/error-handler.test.ts
+```
+
+**Step 3: 实现错误类型**
+
+```typescript
+// src/errors/types.ts
+export type ErrorType =
+  | 'SyntaxError'
+  | 'DivisionByZero'
+  | 'InvalidNumber'
+  | 'OverflowError'
+  | 'InvalidBase'
+  | 'UnmatchedParen'
+  | 'InvalidOperator'
+  | 'EmptyInput';
+
+export interface Position {
+  start: number;
+  end: number;
+}
+
+export interface ErrorDetail {
+  type: ErrorType;
+  message: string;
+  position?: Position;
+  suggestion: string;
+}
+
+export interface SuccessResponse {
+  success: true;
+  result: string;
+  details?: {
+    expression?: string;
+    steps?: string[];
+  };
+}
+
+export interface ErrorResponse {
+  success: false;
+  error: ErrorDetail;
+}
+
+export type CalculationResponse = SuccessResponse | ErrorResponse;
+```
+
+**Step 4: 实现错误处理器**
+
+```typescript
+// src/errors/handler.ts
+import {
+  ErrorType,
+  Position,
+  ErrorDetail,
+  ErrorResponse,
+  CalculationResponse,
+  SuccessResponse,
+} from './types.js';
+
+export class ErrorHandler {
+  private suggestions: Record<ErrorType, string> = {
+    SyntaxError: 'Check your expression syntax. Ensure operators and operands are correctly placed.',
+    DivisionByZero: 'Division by zero is not allowed. Check your denominators.',
+    InvalidNumber: 'The number format is invalid. Check for typos or unsupported formats.',
+    OverflowError: 'The number is too large or too small to process.',
+    InvalidBase: 'Invalid base specified. Supported bases are 2, 8, 10, and 16.',
+    UnmatchedParen: 'Unmatched parenthesis. Ensure every opening parenthesis has a closing one.',
+    InvalidOperator: 'Invalid operator for this operation. Check supported operators.',
+    EmptyInput: 'Expression cannot be empty. Please provide a valid expression.',
+  };
+
+  syntaxError(message: string, start: number, end: number): ErrorResponse {
+    return this.createError('SyntaxError', message, { start, end });
+  }
+
+  runtimeError(type: ErrorType, message: string): ErrorResponse {
+    return this.createError(type, message);
+  }
+
+  createError(
+    type: ErrorType,
+    message: string,
+    position?: Position
+  ): ErrorResponse {
+    return {
+      success: false,
+      error: {
+        type,
+        message,
+        position,
+        suggestion: this.suggestions[type],
+      },
+    };
+  }
+
+  success(result: string, details?: SuccessResponse['details']): SuccessResponse {
+    return {
+      success: true,
+      result,
+      details,
+    };
+  }
+}
+
+export type { ErrorType, Position, ErrorDetail, ErrorResponse, CalculationResponse, SuccessResponse };
+```
+
+**Step 5: 运行测试验证通过**
+
+```bash
+npm test -- test/unit/error-handler.test.ts
+```
+
+**Step 6: 提交**
+
+```bash
+git add src/errors test/unit/error-handler.test.ts
+git commit -m "feat: implement error handling system with structured errors"
+```
+
+---
+
+## 阶段 3: 词法分析器 (Lexer)
+
+### 任务 3: 实现 Token 类型和 Lexer
+
+**文件:**
+- 创建: `src/parser/ast.ts`
+- 创建: `src/parser/lexer.ts`
+- 测试: `test/unit/lexer.test.ts`
+
+**Step 1: 编写 Lexer 测试 - 数字字面量**
+
+```bash
+mkdir -p src/parser
+```
+
+```typescript
+// test/unit/lexer.test.ts
+import { describe, it, expect } from 'vitest';
+import { Lexer } from '../../src/parser/lexer.js';
+import { TokenType } from '../../src/parser/ast.js';
+
+describe('Lexer', () => {
+  describe('Number literals', () => {
+    it('should tokenize decimal integers', () => {
+      const lexer = new Lexer();
+      const tokens = lexer.tokenize('42');
+
+      expect(tokens).toHaveLength(2); // NUMBER + EOF
+      expect(tokens[0].type).toBe('NUMBER');
+      expect(tokens[0].value).toBe('42');
+    });
+
+    it('should tokenize decimal floats', () => {
+      const lexer = new Lexer();
+      const tokens = lexer.tokenize('3.14');
+
+      expect(tokens[0].type).toBe('NUMBER');
+      expect(tokens[0].value).toBe('3.14');
+    });
+
+    it('should tokenize hex literals', () => {
+      const lexer = new Lexer();
+      const tokens = lexer.tokenize('0xFF');
+
+      expect(tokens[0].type).toBe('HEX');
+      expect(tokens[0].value).toBe('0xFF');
+    });
+
+    it('should tokenize binary literals', () => {
+      const lexer = new Lexer();
+      const tokens = lexer.tokenize('0b1011');
+
+      expect(tokens[0].type).toBe('BINARY');
+      expect(tokens[0].value).toBe('0b1011');
+    });
+
+    it('should tokenize octal literals', () => {
+      const lexer = new Lexer();
+      const tokens = lexer.tokenize('0o77');
+
+      expect(tokens[0].type).toBe('OCTAL');
+      expect(tokens[0].value).toBe('0o77');
+    });
+  });
+});
+```
+
+**Step 2: 运行测试验证失败**
+
+```bash
+npm test -- test/unit/lexer.test.ts
+```
+
+**Step 3: 实现 AST 类型定义**
+
+```typescript
+// src/parser/ast.ts
+export type TokenType =
+  | 'NUMBER'
+  | 'HEX'
+  | 'BINARY'
+  | 'OCTAL'
+  | 'OPERATOR'
+  | 'LPAREN'
+  | 'RPAREN'
+  | 'CHAR_LITERAL'
+  | 'WHITESPACE'
+  | 'EOF';
+
+export interface Token {
+  type: TokenType;
+  value: string;
+  position: { start: number; end: number };
+}
+
+export type ASTNode =
+  | BinaryOpNode
+  | UnaryOpNode
+  | LiteralNode
+  | GroupNode;
+
+export interface BinaryOpNode {
+  type: 'BinaryOp';
+  operator: string;
+  left: ASTNode;
+  right: ASTNode;
+  position?: { start: number; end: number };
+}
+
+export interface UnaryOpNode {
+  type: 'UnaryOp';
+  operator: string;
+  operand: ASTNode;
+  position?: { start: number; end: number };
+}
+
+export interface LiteralNode {
+  type: 'Literal';
+  value: string;
+  tokenType: TokenType;
+  position?: { start: number; end: number };
+}
+
+export interface GroupNode {
+  type: 'Group';
+  expression: ASTNode;
+  position?: { start: number; end: number };
+}
+```
+
+**Step 4: 实现 Lexer**
+
+```typescript
+// src/parser/lexer.ts
+import { Token, TokenType } from './ast.js';
+
+export class Lexer {
+  private pos = 0;
+  private input = '';
+  private length = 0;
+
+  tokenize(input: string): Token[] {
+    this.input = input;
+    this.pos = 0;
+    this.length = input.length;
+    const tokens: Token[] = [];
+
+    while (this.pos < this.length) {
+      const char = this.input[this.pos];
+
+      if (this.isWhitespace(char)) {
+        this.skipWhitespace();
+        continue;
+      }
+
+      const token = this.readToken();
+      if (token && token.type !== 'WHITESPACE') {
+        tokens.push(token);
+      }
+    }
+
+    tokens.push({
+      type: 'EOF',
+      value: '',
+      position: { start: this.pos, end: this.pos },
+    });
+
+    return tokens;
+  }
+
+  private readToken(): Token | null {
+    const char = this.input[this.pos];
+    const start = this.pos;
+
+    // Hex literal: 0x or 0X
+    if (char === '0' && this.peek() === 'x') {
+      return this.readHexLiteral(start);
+    }
+
+    // Binary literal: 0b or 0B
+    if (char === '0' && this.peek() === 'b') {
+      return this.readBinaryLiteral(start);
+    }
+
+    // Octal literal: 0o or 0O
+    if (char === '0' && this.peek() === 'o') {
+      return this.readOctalLiteral(start);
+    }
+
+    // Number (decimal or float)
+    if (this.isDigit(char) || (char === '.' && this.isDigit(this.peek()))) {
+      return this.readNumber(start);
+    }
+
+    // Operators
+    if (this.isOperatorChar(char)) {
+      return this.readOperator(start);
+    }
+
+    // Parentheses
+    if (char === '(') {
+      this.advance();
+      return { type: 'LPAREN', value: '(', position: { start, end: this.pos } };
+    }
+
+    if (char === ')') {
+      this.advance();
+      return { type: 'RPAREN', value: ')', position: { start, end: this.pos } };
+    }
+
+    // Char literal
+    if (char === "'") {
+      return this.readCharLiteral(start);
+    }
+
+    // Unknown character
+    this.advance();
+    return null;
+  }
+
+  private readNumber(start: number): Token {
+    let value = '';
+
+    while (this.pos < this.length && (this.isDigit(this.input[this.pos]) || this.input[this.pos] === '.')) {
+      value += this.input[this.pos];
+      this.advance();
+    }
+
+    return { type: 'NUMBER', value, position: { start, end: this.pos } };
+  }
+
+  private readHexLiteral(start: number): Token {
+    this.advance(); // '0'
+    this.advance(); // 'x'
+
+    let value = '0x';
+    while (this.pos < this.length && this.isHexDigit(this.input[this.pos])) {
+      value += this.input[this.pos];
+      this.advance();
+    }
+
+    return { type: 'HEX', value, position: { start, end: this.pos } };
+  }
+
+  private readBinaryLiteral(start: number): Token {
+    this.advance(); // '0'
+    this.advance(); // 'b'
+
+    let value = '0b';
+    while (this.pos < this.length && (this.input[this.pos] === '0' || this.input[this.pos] === '1')) {
+      value += this.input[this.pos];
+      this.advance();
+    }
+
+    return { type: 'BINARY', value, position: { start, end: this.pos } };
+  }
+
+  private readOctalLiteral(start: number): Token {
+    this.advance(); // '0'
+    this.advance(); // 'o'
+
+    let value = '0o';
+    while (this.pos < this.length && this.isOctalDigit(this.input[this.pos])) {
+      value += this.input[this.pos];
+      this.advance();
+    }
+
+    return { type: 'OCTAL', value, position: { start, end: this.pos } };
+  }
+
+  private readOperator(start: number): Token {
+    // Check for multi-char operators: <<, >>, >>>
+    const twoChar = this.input.substring(this.pos, this.pos + 2);
+
+    if (twoChar === '<<' || twoChar === '>>') {
+      // Check for >>>
+      if (twoChar === '>>' && this.peek(1) === '>') {
+        this.pos += 3;
+        return { type: 'OPERATOR', value: '>>>', position: { start, end: this.pos } };
+      }
+      this.pos += 2;
+      return { type: 'OPERATOR', value: twoChar, position: { start, end: this.pos } };
+    }
+
+    // Single char operators
+    const op = this.input[this.pos];
+    this.advance();
+    return { type: 'OPERATOR', value: op, position: { start, end: this.pos } };
+  }
+
+  private readCharLiteral(start: number): Token {
+    this.advance(); // opening '
+
+    let value = "'";
+
+    // Handle escape sequences
+    if (this.input[this.pos] === '\\') {
+      value += this.input[this.pos];
+      this.advance();
+    }
+
+    if (this.pos < this.length) {
+      value += this.input[this.pos];
+      this.advance();
+    }
+
+    if (this.pos < this.length && this.input[this.pos] === "'") {
+      value += this.input[this.pos];
+      this.advance();
+    }
+
+    return { type: 'CHAR_LITERAL', value, position: { start, end: this.pos } };
+  }
+
+  private skipWhitespace(): void {
+    while (this.pos < this.length && this.isWhitespace(this.input[this.pos])) {
+      this.pos++;
+    }
+  }
+
+  private advance(): void {
+    this.pos++;
+  }
+
+  private peek(offset = 1): string {
+    return this.pos + offset < this.length ? this.input[this.pos + offset] : '';
+  }
+
+  private isWhitespace(char: string): boolean {
+    return /\s/.test(char);
+  }
+
+  private isDigit(char: string): boolean {
+    return /[0-9]/.test(char);
+  }
+
+  private isHexDigit(char: string): boolean {
+    return /[0-9a-fA-F]/.test(char);
+  }
+
+  private isOctalDigit(char: string): boolean {
+    return /[0-7]/.test(char);
+  }
+
+  private isOperatorChar(char: string): boolean {
+    return ['+', '-', '*', '/', '%', '&', '|', '^', '~', '!', '<', '>'].includes(char);
+  }
+}
+
+export type { Token, TokenType };
+```
+
+**Step 5: 运行测试验证通过**
+
+```bash
+npm test -- test/unit/lexer.test.ts
+```
+
+**Step 6: 添加更多 Lexer 测试**
+
+```typescript
+// 添加到 test/unit/lexer.test.ts
+
+describe('Operators', () => {
+  it('should tokenize single-char operators', () => {
+    const lexer = new Lexer();
+    const tokens = lexer.tokenize('2+3*4');
+
+    expect(tokens[1].type).toBe('OPERATOR');
+    expect(tokens[1].value).toBe('+');
+    expect(tokens[3].type).toBe('OPERATOR');
+    expect(tokens[3].value).toBe('*');
+  });
+
+  it('should tokenize shift operators', () => {
+    const lexer = new Lexer();
+    const tokens = lexer.tokenize('1 << 2 >> 1 >>> 3');
+
+    expect(tokens[1].value).toBe('<<');
+    expect(tokens[4].value).toBe('>>');
+    expect(tokens[7].value).toBe('>>>');
+  });
+
+  it('should tokenize bitwise operators', () => {
+    const lexer = new Lexer();
+    const tokens = lexer.tokenize('0xFF & 0x0F | 0x10 ^ 0x20');
+
+    expect(tokens[1].value).toBe('&');
+    expect(tokens[3].value).toBe('|');
+    expect(tokens[5].value).toBe('^');
+  });
+});
+
+describe('Parentheses', () => {
+  it('should tokenize parentheses', () => {
+    const lexer = new Lexer();
+    const tokens = lexer.tokenize('(2 + 3)');
+
+    expect(tokens[0].type).toBe('LPAREN');
+    expect(tokens[4].type).toBe('RPAREN');
+  });
+});
+
+describe('Positions', () => {
+  it('should track token positions correctly', () => {
+    const lexer = new Lexer();
+    const tokens = lexer.tokenize('42 + 3');
+
+    expect(tokens[0].position).toEqual({ start: 0, end: 2 });
+    expect(tokens[1].position).toEqual({ start: 3, end: 4 });
+    expect(tokens[2].position).toEqual({ start: 5, end: 6 });
+  });
+});
+```
+
+**Step 7: 运行测试验证通过**
+
+```bash
+npm test -- test/unit/lexer.test.ts
+```
+
+**Step 8: 提交**
+
+```bash
+git add src/parser test/unit/lexer.test.ts
+git commit -m "feat: implement lexer with support for all numeric literals and operators"
+```
+
+---
+
+## 阶段 4: 语法分析器 (Parser)
+
+### 任务 4: 实现 Parser
+
+**文件:**
+- 创建: `src/parser/parser.ts`
+- 测试: `test/unit/parser.test.ts`
+
+**Step 1: 编写 Parser 测试 - 运算符优先级**
+
+```typescript
+// test/unit/parser.test.ts
+import { describe, it, expect } from 'vitest';
+import { Parser } from '../../src/parser/parser.js';
+import { Lexer } from '../../src/parser/lexer.js';
+
+describe('Parser', () => {
+  describe('Operator precedence', () => {
+    it('should respect multiplication over addition', () => {
+      const lexer = new Lexer();
+      const parser = new Parser();
+      const tokens = lexer.tokenize('2 + 3 * 4');
+      const ast = parser.parse(tokens);
+
+      expect(ast.type).toBe('BinaryOp');
+      expect(ast.operator).toBe('+');
+      expect((ast as any).left.type).toBe('Literal');
+      expect((ast as any).left.value).toBe('2');
+      expect((ast as any).right.type).toBe('BinaryOp');
+      expect((ast as any).right.operator).toBe('*');
+    });
+
+    it('should respect parentheses', () => {
+      const lexer = new Lexer();
+      const parser = new Parser();
+      const tokens = lexer.tokenize('(2 + 3) * 4');
+      const ast = parser.parse(tokens);
+
+      expect(ast.type).toBe('BinaryOp');
+      expect(ast.operator).toBe('*');
+      expect((ast as any).left.type).toBe('Group');
+      expect((ast as any).right.type).toBe('Literal');
+    });
+  });
+});
+```
+
+**Step 2: 运行测试验证失败**
+
+```bash
+npm test -- test/unit/parser.test.ts
+```
+
+**Step 3: 实现 Parser**
+
+```typescript
+// src/parser/parser.ts
+import { Token, ASTNode, BinaryOpNode, UnaryOpNode, LiteralNode, GroupNode, TokenType } from './ast.js';
+import { ErrorHandler } from '../errors/handler.js';
+
+// Operator precedence (higher number = higher precedence)
+const PRECEDENCE: Record<string, number> = {
+  '(': 10,
+  ')': 10,
+  '~': 9,
+  '!': 9,
+  '*': 8,
+  '/': 8,
+  '%': 8,
+  '+': 7,
+  '-': 7,
+  '<<': 6,
+  '>>': 6,
+  '>>>': 6,
+  '&': 5,
+  '^': 4,
+  '|': 3,
+  '&&': 2,
+  '||': 1,
+};
+
+export class Parser {
+  private pos = 0;
+  private tokens: Token[] = [];
+  private errorHandler = new ErrorHandler();
+
+  parse(tokens: Token[]): ASTNode {
+    this.tokens = tokens;
+    this.pos = 0;
+
+    if (this.tokens.length === 0 || (this.tokens.length === 1 && this.tokens[0].type === 'EOF')) {
+      throw new Error('Empty input');
+    }
+
+    const ast = this.parseExpression();
+
+    if (this.current()?.type !== 'EOF') {
+      const token = this.current()!;
+      throw this.errorHandler.syntaxError(
+        `Unexpected token: ${token.value}`,
+        token.position.start,
+        token.position.end
+      );
+    }
+
+    return ast;
+  }
+
+  private parseExpression(minPrecedence = 0): ASTNode {
+    let left = this.parseUnary();
+
+    while (true) {
+      const op = this.current();
+      if (!op || op.type !== 'OPERATOR') {
+        break;
+      }
+
+      const precedence = PRECEDENCE[op.value] ?? 0;
+      if (precedence < minPrecedence) {
+        break;
+      }
+
+      this.advance();
+      const right = this.parseExpression(precedence + 1);
+
+      left = {
+        type: 'BinaryOp',
+        operator: op.value,
+        left,
+        right,
+        position: { start: left.position?.start ?? 0, end: right.position?.end ?? 0 },
+      } as BinaryOpNode;
+    }
+
+    return left;
+  }
+
+  private parseUnary(): ASTNode {
+    const token = this.current();
+
+    if (token && token.type === 'OPERATOR' && (token.value === '~' || token.value === '!' || token.value === '-')) {
+      this.advance();
+      const operand = this.parseUnary();
+
+      return {
+        type: 'UnaryOp',
+        operator: token.value,
+        operand,
+        position: { start: token.position.start, end: operand.position?.end ?? token.position.end },
+      } as UnaryOpNode;
+    }
+
+    return this.parsePrimary();
+  }
+
+  private parsePrimary(): ASTNode {
+    const token = this.current();
+
+    if (!token || token.type === 'EOF') {
+      throw new Error('Unexpected end of input');
+    }
+
+    // Parenthesized expression
+    if (token.type === 'LPAREN') {
+      this.advance();
+      const expr = this.parseExpression();
+
+      const closing = this.current();
+      if (!closing || closing.type !== 'RPAREN') {
+        throw this.errorHandler.syntaxError(
+          'Unmatched parenthesis: expected )',
+          token.position.start,
+          token.position.end
+        );
+      }
+      this.advance();
+
+      return {
+        type: 'Group',
+        expression: expr,
+        position: { start: token.position.start, end: closing.position.end },
+      } as GroupNode;
+    }
+
+    // Literal
+    if (this.isLiteral(token)) {
+      this.advance();
+      return {
+        type: 'Literal',
+        value: token.value,
+        tokenType: token.type,
+        position: token.position,
+      } as LiteralNode;
+    }
+
+    throw this.errorHandler.syntaxError(
+      `Unexpected token: ${token.value}`,
+      token.position.start,
+      token.position.end
+    );
+  }
+
+  private isLiteral(token: Token): boolean {
+    return ['NUMBER', 'HEX', 'BINARY', 'OCTAL', 'CHAR_LITERAL'].includes(token.type);
+  }
+
+  private current(): Token | undefined {
+    return this.tokens[this.pos];
+  }
+
+  private advance(): void {
+    this.pos++;
+  }
+}
+```
+
+**Step 4: 运行测试验证通过**
+
+```bash
+npm test -- test/unit/parser.test.ts
+```
+
+**Step 5: 添加更多 Parser 测试**
+
+```typescript
+// 添加到 test/unit/parser.test.ts
+
+describe('Unary operators', () => {
+  it('should parse bitwise NOT', () => {
+    const lexer = new Lexer();
+    const parser = new Parser();
+    const tokens = lexer.tokenize('~0xFF');
+    const ast = parser.parse(tokens);
+
+    expect(ast.type).toBe('UnaryOp');
+    expect((ast as any).operator).toBe('~');
+    expect((ast as any).operand.type).toBe('Literal');
+  });
+
+  it('should parse negation', () => {
+    const lexer = new Lexer();
+    const parser = new Parser();
+    const tokens = lexer.tokenize('-42');
+    const ast = parser.parse(tokens);
+
+    expect(ast.type).toBe('UnaryOp');
+    expect((ast as any).operator).toBe('-');
+  });
+});
+
+describe('Bitwise operators', () => {
+  it('should parse AND', () => {
+    const lexer = new Lexer();
+    const parser = new Parser();
+    const tokens = lexer.tokenize('0xFF & 0x0F');
+    const ast = parser.parse(tokens);
+
+    expect(ast.type).toBe('BinaryOp');
+    expect((ast as any).operator).toBe('&');
+  });
+
+  it('should parse OR', () => {
+    const lexer = new Lexer();
+    const parser = new Parser();
+    const tokens = lexer.tokenize('0xFF | 0x0F');
+    const ast = parser.parse(tokens);
+
+    expect(ast.type).toBe('BinaryOp');
+    expect((ast as any).operator).toBe('|');
+  });
+
+  it('should parse XOR', () => {
+    const lexer = new Lexer();
+    const parser = new Parser();
+    const tokens = lexer.tokenize('0xFF ^ 0x0F');
+    const ast = parser.parse(tokens);
+
+    expect(ast.type).toBe('BinaryOp');
+    expect((ast as any).operator).toBe('^');
+  });
+});
+
+describe('Shift operators', () => {
+  it('should parse left shift', () => {
+    const lexer = new Lexer();
+    const parser = new Parser();
+    const tokens = lexer.tokenize('1 << 4');
+    const ast = parser.parse(tokens);
+
+    expect(ast.type).toBe('BinaryOp');
+    expect((ast as any).operator).toBe('<<');
+  });
+
+  it('should parse right shift', () => {
+    const lexer = new Lexer();
+    const parser = new Parser();
+    const tokens = lexer.tokenize('16 >> 2');
+    const ast = parser.parse(tokens);
+
+    expect(ast.type).toBe('BinaryOp');
+    expect((ast as any).operator).toBe('>>');
+  });
+});
+```
+
+**Step 6: 运行测试验证通过**
+
+```bash
+npm test -- test/unit/parser.test.ts
+```
+
+**Step 7: 提交**
+
+```bash
+git add src/parser/parser.ts test/unit/parser.test.ts
+git commit -m "feat: implement recursive descent parser with operator precedence"
+```
+
+---
+
+## 阶段 5: 四则运算引擎
+
+### 任务 5: 实现 DecimalEngine
+
+**文件:**
+- 创建: `src/engines/decimal.ts`
+- 测试: `test/unit/decimal-engine.test.ts`
+
+**Step 1: 编写 DecimalEngine 测试**
+
+```bash
+mkdir -p src/engines
+```
+
+```typescript
+// test/unit/decimal-engine.test.ts
+import { describe, it, expect } from 'vitest';
+import { DecimalEngine } from '../../src/engines/decimal.js';
+import { Lexer } from '../../src/parser/lexer.js';
+import { Parser } from '../../src/parser/parser.js';
+
+describe('DecimalEngine', () => {
+  const lexer = new Lexer();
+  const parser = new Parser();
+  const engine = new DecimalEngine();
+
+  describe('Basic operations', () => {
+    it('should add two numbers', () => {
+      const tokens = lexer.tokenize('2 + 3');
+      const ast = parser.parse(tokens);
+      const result = engine.evaluate(ast);
+
+      expect(result.toString()).toBe('5');
+    });
+
+    it('should subtract two numbers', () => {
+      const tokens = lexer.tokenize('5 - 3');
+      const ast = parser.parse(tokens);
+      const result = engine.evaluate(ast);
+
+      expect(result.toString()).toBe('2');
+    });
+
+    it('should multiply two numbers', () => {
+      const tokens = lexer.tokenize('4 * 3');
+      const ast = parser.parse(tokens);
+      const result = engine.evaluate(ast);
+
+      expect(result.toString()).toBe('12');
+    });
+
+    it('should divide two numbers', () => {
+      const tokens = lexer.tokenize('10 / 2');
+      const ast = parser.parse(tokens);
+      const result = engine.evaluate(ast);
+
+      expect(result.toString()).toBe('5');
+    });
+  });
+
+  describe('Decimal precision', () => {
+    it('should handle 0.1 + 0.2 correctly', () => {
+      const tokens = lexer.tokenize('0.1 + 0.2');
+      const ast = parser.parse(tokens);
+      const result = engine.evaluate(ast);
+
+      expect(result.toString()).toBe('0.3');
+    });
+
+    it('should handle floating point division', () => {
+      const tokens = lexer.tokenize('1 / 3');
+      const ast = parser.parse(tokens);
+      const result = engine.evaluate(ast);
+
+      expect(parseFloat(result.toString())).toBeCloseTo(0.333, 2);
+    });
+  });
+
+  describe('Operator precedence', () => {
+    it('should respect precedence', () => {
+      const tokens = lexer.tokenize('2 + 3 * 4');
+      const ast = parser.parse(tokens);
+      const result = engine.evaluate(ast);
+
+      expect(result.toString()).toBe('14');
+    });
+
+    it('should respect parentheses', () => {
+      const tokens = lexer.tokenize('(2 + 3) * 4');
+      const ast = parser.parse(tokens);
+      const result = engine.evaluate(ast);
+
+      expect(result.toString()).toBe('20');
+    });
+  });
+
+  describe('Error handling', () => {
+    it('should throw on division by zero', () => {
+      const tokens = lexer.tokenize('1 / 0');
+      const ast = parser.parse(tokens);
+
+      expect(() => engine.evaluate(ast)).toThrow('DivisionByZero');
+    });
+  });
+});
+```
+
+**Step 2: 运行测试验证失败**
+
+```bash
+npm test -- test/unit/decimal-engine.test.ts
+```
+
+**Step 3: 实现 DecimalEngine**
+
+```typescript
+// src/engines/decimal.ts
+import { Decimal } from 'decimal.js';
+import { ASTNode, BinaryOpNode, UnaryOpNode, LiteralNode, GroupNode } from '../parser/ast.js';
+import { ErrorHandler } from '../errors/handler.js';
+
+export class DecimalEngine {
+  private errorHandler = new ErrorHandler();
+
+  evaluate(ast: ASTNode): Decimal {
+    return this.visit(ast);
+  }
+
+  private visit(node: ASTNode): Decimal {
+    switch (node.type) {
+      case 'Literal':
+        return this.visitLiteral(node as LiteralNode);
+      case 'BinaryOp':
+        return this.visitBinaryOp(node as BinaryOpNode);
+      case 'UnaryOp':
+        return this.visitUnaryOp(node as UnaryOpNode);
+      case 'Group':
+        return this.visit((node as GroupNode).expression);
+      default:
+        throw new Error(`Unknown node type: ${(node as any).type}`);
+    }
+  }
+
+  private visitLiteral(node: LiteralNode): Decimal {
+    // Strip prefixes for non-decimal literals
+    const value = node.value.replace(/^(0x|0b|0o)/, '');
+
+    // For literals with non-standard prefixes, parse as if they were decimal
+    // This is a simplification - proper implementation would handle these differently
+    return new Decimal(value);
+  }
+
+  private visitBinaryOp(node: BinaryOpNode): Decimal {
+    const left = this.visit(node.left);
+    const right = this.visit(node.right);
+
+    switch (node.operator) {
+      case '+':
+        return left.plus(right);
+      case '-':
+        return left.minus(right);
+      case '*':
+        return left.times(right);
+      case '/':
+        if (right.isZero()) {
+          throw this.errorHandler.runtimeError('DivisionByZero', 'Cannot divide by zero');
+        }
+        return left.dividedBy(right);
+      case '%':
+        if (right.isZero()) {
+          throw this.errorHandler.runtimeError('DivisionByZero', 'Cannot divide by zero');
+        }
+        return left.modulo(right);
+      default:
+        throw new Error(`Unsupported operator for decimal engine: ${node.operator}`);
+    }
+  }
+
+  private visitUnaryOp(node: UnaryOpNode): Decimal {
+    const operand = this.visit(node.operand);
+
+    switch (node.operator) {
+      case '-':
+        return operand.negated();
+      case '+':
+        return operand;
+      default:
+        throw new Error(`Unsupported unary operator for decimal engine: ${node.operator}`);
+    }
+  }
+}
+```
+
+**Step 4: 运行测试验证通过**
+
+```bash
+npm test -- test/unit/decimal-engine.test.ts
+```
+
+**Step 5: 添加更多测试**
+
+```typescript
+// 添加到 test/unit/decimal-engine.test.ts
+
+describe('Complex expressions', () => {
+  it('should handle multiple operations', () => {
+    const tokens = lexer.tokenize('2.5 * 3 + (10 - 4) / 2');
+    const ast = parser.parse(tokens);
+    const result = engine.evaluate(ast);
+
+    expect(result.toString()).toBe('10.5');
+  });
+
+  it('should handle modulo', () => {
+    const tokens = lexer.tokenize('10 % 3');
+    const ast = parser.parse(tokens);
+    const result = engine.evaluate(ast);
+
+    expect(result.toString()).toBe('1');
+  });
+});
+```
+
+**Step 6: 运行测试验证通过**
+
+```bash
+npm test -- test/unit/decimal-engine.test.ts
+```
+
+**Step 7: 提交**
+
+```bash
+git add src/engines/decimal.ts test/unit/decimal-engine.test.ts
+git commit -m "feat: implement decimal engine with high precision arithmetic"
+```
+
+---
+
+## 阶段 6: 程序员计算引擎
+
+### 任务 6: 实现 ProgrammerEngine
+
+**文件:**
+- 创建: `src/engines/programmer.ts`
+- 测试: `test/unit/programmer-engine.test.ts`
+
+**Step 1: 编写 ProgrammerEngine 测试**
+
+```typescript
+// test/unit/programmer-engine.test.ts
+import { describe, it, expect } from 'vitest';
+import { ProgrammerEngine } from '../../src/engines/programmer.js';
+import { Lexer } from '../../src/parser/lexer.js';
+import { Parser } from '../../src/parser/parser.js';
+
+describe('ProgrammerEngine', () => {
+  const lexer = new Lexer();
+  const parser = new Parser();
+  const engine = new ProgrammerEngine();
+
+  describe('Bitwise AND', () => {
+    it('should perform bitwise AND', () => {
+      const tokens = lexer.tokenize('0xFF & 0x0F');
+      const ast = parser.parse(tokens);
+      const result = engine.evaluate(ast);
+
+      expect(result.toString()).toBe('15');
+    });
+  });
+
+  describe('Bitwise OR', () => {
+    it('should perform bitwise OR', () => {
+      const tokens = lexer.tokenize('0xF0 | 0x0F');
+      const ast = parser.parse(tokens);
+      const result = engine.evaluate(ast);
+
+      expect(result.toString()).toBe('255');
+    });
+  });
+
+  describe('Bitwise XOR', () => {
+    it('should perform bitwise XOR', () => {
+      const tokens = lexer.tokenize('0xFF ^ 0xFF');
+      const ast = parser.parse(tokens);
+      const result = engine.evaluate(ast);
+
+      expect(result.toString()).toBe('0');
+    });
+  });
+
+  describe('Bitwise NOT', () => {
+    it('should perform bitwise NOT', () => {
+      const tokens = lexer.tokenize('~0x00');
+      const ast = parser.parse(tokens);
+      const result = engine.evaluate(ast);
+
+      // ~0 = -1 in two's complement
+      expect(result.toString()).toBe('-1');
+    });
+  });
+
+  describe('Left shift', () => {
+    it('should perform left shift', () => {
+      const tokens = lexer.tokenize('1 << 4');
+      const ast = parser.parse(tokens);
+      const result = engine.evaluate(ast);
+
+      expect(result.toString()).toBe('16');
+    });
+  });
+
+  describe('Right shift', () => {
+    it('should perform right shift', () => {
+      const tokens = lexer.tokenize('16 >> 2');
+      const ast = parser.parse(tokens);
+      const result = engine.evaluate(ast);
+
+      expect(result.toString()).toBe('4');
+    });
+  });
+
+  describe('BigInt support', () => {
+    it('should handle very large numbers', () => {
+      const tokens = lexer.tokenize('0xFFFFFFFFFFFFFFFF + 1');
+      const ast = parser.parse(tokens);
+      const result = engine.evaluate(ast);
+
+      expect(result.toString()).toBe('18446744073709551616');
+    });
+  });
+});
+```
+
+**Step 2: 运行测试验证失败**
+
+```bash
+npm test -- test/unit/programmer-engine.test.ts
+```
+
+**Step 3: 实现 ProgrammerEngine**
+
+```typescript
+// src/engines/programmer.ts
+import { ASTNode, BinaryOpNode, UnaryOpNode, LiteralNode, GroupNode, TokenType } from '../parser/ast.js';
+import { ErrorHandler } from '../errors/handler.js';
+
+export class ProgrammerEngine {
+  private errorHandler = new ErrorHandler();
+
+  evaluate(ast: ASTNode): bigint {
+    return this.visit(ast);
+  }
+
+  private visit(node: ASTNode): bigint {
+    switch (node.type) {
+      case 'Literal':
+        return this.parseLiteral(node as LiteralNode);
+      case 'BinaryOp':
+        return this.visitBinaryOp(node as BinaryOpNode);
+      case 'UnaryOp':
+        return this.visitUnaryOp(node as UnaryOpNode);
+      case 'Group':
+        return this.visit((node as GroupNode).expression);
+      default:
+        throw new Error(`Unknown node type: ${(node as any).type}`);
+    }
+  }
+
+  private parseLiteral(node: LiteralNode): bigint {
+    const { value, tokenType } = node;
+
+    switch (tokenType) {
+      case 'NUMBER':
+        // Decimal integer
+        if (value.includes('.')) {
+          throw this.errorHandler.runtimeError('InvalidNumber', 'Floating point numbers not supported in programmer mode');
+        }
+        return BigInt(value);
+      case 'HEX':
+        return BigInt(value);
+      case 'BINARY':
+        return BigInt(value);
+      case 'OCTAL':
+        return BigInt(value);
+      case 'CHAR_LITERAL':
+        // Parse char literal like 'A' or '\n'
+        const char = value.substring(1, value.length - 1);
+        return BigInt(char.charCodeAt(0));
+      default:
+        throw new Error(`Unsupported literal type: ${tokenType}`);
+    }
+  }
+
+  private visitBinaryOp(node: BinaryOpNode): bigint {
+    const left = this.visit(node.left);
+    const right = this.visit(node.right);
+
+    switch (node.operator) {
+      case '+':
+        return left + right;
+      case '-':
+        return left - right;
+      case '*':
+        return left * right;
+      case '/':
+        if (right === 0n) {
+          throw this.errorHandler.runtimeError('DivisionByZero', 'Cannot divide by zero');
+        }
+        return left / right;
+      case '%':
+        if (right === 0n) {
+          throw this.errorHandler.runtimeError('DivisionByZero', 'Cannot divide by zero');
+        }
+        return left % right;
+      case '&':
+        return left & right;
+      case '|':
+        return left | right;
+      case '^':
+        return left ^ right;
+      case '<<':
+        return left << right;
+      case '>>':
+        return left >> right;
+      case '>>>':
+        // Unsigned right shift - convert to number, shift, back to bigint
+        return BigInt(Number(left) >>> Number(right));
+      default:
+        throw new Error(`Unsupported operator for programmer engine: ${node.operator}`);
+    }
+  }
+
+  private visitUnaryOp(node: UnaryOpNode): bigint {
+    const operand = this.visit(node.operand);
+
+    switch (node.operator) {
+      case '~':
+        return ~operand;
+      case '-':
+        return -operand;
+      case '+':
+        return operand;
+      default:
+        throw new Error(`Unsupported unary operator for programmer engine: ${node.operator}`);
+    }
+  }
+}
+```
+
+**Step 4: 运行测试验证通过**
+
+```bash
+npm test -- test/unit/programmer-engine.test.ts
+```
+
+**Step 5: 添加更多测试**
+
+```typescript
+// 添加到 test/unit/programmer-engine.test.ts
+
+describe('Complex expressions', () => {
+  it('should handle multiple bitwise operations', () => {
+    const tokens = lexer.tokenize('0xFF & 0x0F | 0x10');
+    const ast = parser.parse(tokens);
+    const result = engine.evaluate(ast);
+
+    // (0xFF & 0x0F) | 0x10 = 15 | 16 = 31
+    expect(result.toString()).toBe('31');
+  });
+
+  it('should handle shift with bitwise ops', () => {
+    const tokens = lexer.tokenize('(1 << 4) & 0xFF');
+    const ast = parser.parse(tokens);
+    const result = engine.evaluate(ast);
+
+    // (16) & 255 = 16
+    expect(result.toString()).toBe('16');
+  });
+});
+
+describe('Binary literals', () => {
+  it('should parse binary literals', () => {
+    const tokens = lexer.tokenize('0b1010');
+    const ast = parser.parse(tokens);
+    const result = engine.evaluate(ast);
+
+    expect(result.toString()).toBe('10');
+  });
+
+  it('should perform operations on binary literals', () => {
+    const tokens = lexer.tokenize('0b1010 << 2');
+    const ast = parser.parse(tokens);
+    const result = engine.evaluate(ast);
+
+    expect(result.toString()).toBe('40');
+  });
+});
+
+describe('Octal literals', () => {
+  it('should parse octal literals', () => {
+    const tokens = lexer.tokenize('0o77');
+    const ast = parser.parse(tokens);
+    const result = engine.evaluate(ast);
+
+    expect(result.toString()).toBe('63');
+  });
+});
+```
+
+**Step 6: 运行测试验证通过**
+
+```bash
+npm test -- test/unit/programmer-engine.test.ts
+```
+
+**Step 7: 提交**
+
+```bash
+git add src/engines/programmer.ts test/unit/programmer-engine.test.ts
+git commit -m "feat: implement programmer engine with BigInt and bitwise operations"
+```
+
+---
+
+## 阶段 7: MCP 工具实现
+
+### 任务 7: 实现 basic_calculate 工具
+
+**文件:**
+- 创建: `src/mcp/tools/basic.ts`
+- 创建: `src/mcp/server.ts`
+- 测试: `test/integration/basic-calculate.test.ts`
+
+**Step 1: 编写 basic_calculate 集成测试**
+
+```bash
+mkdir -p src/mcp/tools test/integration
+```
+
+```typescript
+// test/integration/basic-calculate.test.ts
+import { describe, it, expect } from 'vitest';
+import { basicCalculate } from '../../src/mcp/tools/basic.js';
+
+describe('basic_calculate MCP tool', () => {
+  it('should calculate simple addition', () => {
+    const result = basicCalculate({ expression: '2 + 3' });
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('5');
+  });
+
+  it('should calculate with operator precedence', () => {
+    const result = basicCalculate({ expression: '2 + 3 * 4' });
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('14');
+  });
+
+  it('should handle decimal precision', () => {
+    const result = basicCalculate({ expression: '0.1 + 0.2' });
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('0.3');
+  });
+
+  it('should return structured error for invalid syntax', () => {
+    const result = basicCalculate({ expression: '2 + * 3' });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.type).toBe('SyntaxError');
+    expect(result.error?.position).toBeDefined();
+  });
+
+  it('should return structured error for division by zero', () => {
+    const result = basicCalculate({ expression: '1 / 0' });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.type).toBe('DivisionByZero');
+  });
+
+  it('should handle empty input', () => {
+    const result = basicCalculate({ expression: '' });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.type).toBe('EmptyInput');
+  });
+});
+```
+
+**Step 2: 运行测试验证失败**
+
+```bash
+npm test -- test/integration/basic-calculate.test.ts
+```
+
+**Step 3: 实现 basic_calculate 工具**
+
+```typescript
+// src/mcp/tools/basic.ts
+import { Lexer } from '../../parser/lexer.js';
+import { Parser } from '../../parser/parser.js';
+import { DecimalEngine } from '../../engines/decimal.js';
+import { ErrorHandler, CalculationResponse } from '../../errors/handler.js';
+
+export interface BasicCalculateInput {
+  expression: string;
+}
+
+export function basicCalculate(input: BasicCalculateInput): CalculationResponse {
+  const errorHandler = new ErrorHandler();
+  const lexer = new Lexer();
+  const parser = new Parser();
+  const engine = new DecimalEngine();
+
+  const { expression } = input;
+
+  // Validate input
+  if (!expression || expression.trim().length === 0) {
+    return errorHandler.runtimeError('EmptyInput', 'Expression cannot be empty');
+  }
+
+  try {
+    // Tokenize
+    const tokens = lexer.tokenize(expression);
+
+    // Parse
+    const ast = parser.parse(tokens);
+
+    // Evaluate
+    const result = engine.evaluate(ast);
+
+    return errorHandler.success(result.toString(), {
+      expression,
+    });
+  } catch (error) {
+    // Handle structured errors
+    if (typeof error === 'object' && error !== null && 'success' in error) {
+      return error as CalculationResponse;
+    }
+
+    // Handle unexpected errors
+    return errorHandler.runtimeError('InvalidNumber', error instanceof Error ? error.message : 'Unknown error');
+  }
+}
+```
+
+**Step 4: 运行测试验证通过**
+
+```bash
+npm test -- test/integration/basic-calculate.test.ts
+```
+
+**Step 5: 提交**
+
+```bash
+git add src/mcp/tools/basic.ts test/integration/basic-calculate.test.ts
+git commit -m "feat: implement basic_calculate MCP tool with decimal precision"
+```
+
+---
+
+### 任务 8: 实现 programmer_calculate 工具
+
+**文件:**
+- 创建: `src/mcp/tools/programmer.ts`
+- 测试: `test/integration/programmer-calculate.test.ts`
+
+**Step 1: 编写 programmer_calculate 集成测试**
+
+```typescript
+// test/integration/programmer-calculate.test.ts
+import { describe, it, expect } from 'vitest';
+import { programmerCalculate } from '../../src/mcp/tools/programmer.js';
+
+describe('programmer_calculate MCP tool', () => {
+  it('should calculate bitwise AND', () => {
+    const result = programmerCalculate({ expression: '0xFF & 0x0F' });
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('15');
+  });
+
+  it('should calculate bitwise OR', () => {
+    const result = programmerCalculate({ expression: '0xFF | 0x0F' });
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('255');
+  });
+
+  it('should calculate left shift', () => {
+    const result = programmerCalculate({ expression: '1 << 4' });
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('16');
+  });
+
+  it('should handle binary literals', () => {
+    const result = programmerCalculate({ expression: '0b1010 << 2' });
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('40');
+  });
+
+  it('should handle very large numbers', () => {
+    const result = programmerCalculate({ expression: '0xFFFFFFFFFFFFFFFF + 1' });
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('18446744073709551616');
+  });
+
+  it('should return structured error for invalid syntax', () => {
+    const result = programmerCalculate({ expression: '0xFF && 0x0F' });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.type).toBe('SyntaxError');
+  });
+});
+```
+
+**Step 2: 运行测试验证失败**
+
+```bash
+npm test -- test/integration/programmer-calculate.test.ts
+```
+
+**Step 3: 实现 programmer_calculate 工具**
+
+```typescript
+// src/mcp/tools/programmer.ts
+import { Lexer } from '../../parser/lexer.js';
+import { Parser } from '../../parser/parser.js';
+import { ProgrammerEngine } from '../../engines/programmer.js';
+import { ErrorHandler, CalculationResponse } from '../../errors/handler.js';
+
+export interface ProgrammerCalculateInput {
+  expression: string;
+}
+
+export function programmerCalculate(input: ProgrammerCalculateInput): CalculationResponse {
+  const errorHandler = new ErrorHandler();
+  const lexer = new Lexer();
+  const parser = new Parser();
+  const engine = new ProgrammerEngine();
+
+  const { expression } = input;
+
+  // Validate input
+  if (!expression || expression.trim().length === 0) {
+    return errorHandler.runtimeError('EmptyInput', 'Expression cannot be empty');
+  }
+
+  try {
+    // Tokenize
+    const tokens = lexer.tokenize(expression);
+
+    // Parse
+    const ast = parser.parse(tokens);
+
+    // Evaluate
+    const result = engine.evaluate(ast);
+
+    return errorHandler.success(result.toString(), {
+      expression,
+    });
+  } catch (error) {
+    // Handle structured errors
+    if (typeof error === 'object' && error !== null && 'success' in error) {
+      return error as CalculationResponse;
+    }
+
+    // Handle unexpected errors
+    return errorHandler.runtimeError('InvalidNumber', error instanceof Error ? error.message : 'Unknown error');
+  }
+}
+```
+
+**Step 4: 运行测试验证通过**
+
+```bash
+npm test -- test/integration/programmer-calculate.test.ts
+```
+
+**Step 5: 提交**
+
+```bash
+git add src/mcp/tools/programmer.ts test/integration/programmer-calculate.test.ts
+git commit -m "feat: implement programmer_calculate MCP tool with BigInt"
+```
+
+---
+
+### 任务 9: 实现 convert_base 工具
+
+**文件:**
+- 创建: `src/mcp/tools/conversion.ts`
+- 测试: `test/integration/conversion.test.ts`
+
+**Step 1: 编写 convert_base 集成测试**
+
+```typescript
+// test/integration/conversion.test.ts
+import { describe, it, expect } from 'vitest';
+import { convertBase } from '../../src/mcp/tools/conversion.js';
+
+describe('convert_base MCP tool', () => {
+  it('should convert decimal to hex', () => {
+    const result = convertBase({ value: '255', from: 10, to: 16 });
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('ff');
+  });
+
+  it('should convert hex to decimal', () => {
+    const result = convertBase({ value: 'FF', from: 16, to: 10 });
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('255');
+  });
+
+  it('should convert decimal to binary', () => {
+    const result = convertBase({ value: '10', from: 10, to: 2 });
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('1010');
+  });
+
+  it('should convert binary to decimal', () => {
+    const result = convertBase({ value: '1010', from: 2, to: 10 });
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('10');
+  });
+
+  it('should convert hex to binary', () => {
+    const result = convertBase({ value: 'F', from: 16, to: 2 });
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('1111');
+  });
+
+  it('should return error for invalid base', () => {
+    const result = convertBase({ value: '10', from: 10, to: 3 });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.type).toBe('InvalidBase');
+  });
+
+  it('should return error for invalid value', () => {
+    const result = convertBase({ value: 'ZZ', from: 16, to: 10 });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.type).toBe('InvalidNumber');
+  });
+});
+```
+
+**Step 2: 运行测试验证失败**
+
+```bash
+npm test -- test/integration/conversion.test.ts
+```
+
+**Step 3: 实现 convert_base 工具**
+
+```typescript
+// src/mcp/tools/conversion.ts
+import { ErrorHandler, CalculationResponse } from '../../errors/handler.js';
+
+export interface ConvertBaseInput {
+  value: string;
+  from: number;
+  to: number;
+}
+
+export function convertBase(input: ConvertBaseInput): CalculationResponse {
+  const errorHandler = new ErrorHandler();
+  const { value, from, to } = input;
+
+  // Validate bases
+  const validBases = [2, 8, 10, 16];
+  if (!validBases.includes(from)) {
+    return errorHandler.runtimeError('InvalidBase', `Source base ${from} is not supported. Supported bases: ${validBases.join(', ')}`);
+  }
+  if (!validBases.includes(to)) {
+    return errorHandler.runtimeError('InvalidBase', `Target base ${to} is not supported. Supported bases: ${validBases.join(', ')}`);
+  }
+
+  // Validate value
+  if (!value || value.trim().length === 0) {
+    return errorHandler.runtimeError('InvalidNumber', 'Value cannot be empty');
+  }
+
+  try {
+    // Parse from source base
+    const bigintValue = parseValueToBigInt(value, from);
+
+    // Convert to target base
+    const result = bigintValue.toString(to);
+
+    return errorHandler.success(result, {
+      expression: `${value} (base ${from}) → base ${to}`,
+    });
+  } catch (error) {
+    return errorHandler.runtimeError('InvalidNumber', error instanceof Error ? error.message : 'Failed to parse value');
+  }
+}
+
+function parseValueToBigInt(value: string, base: number): bigint {
+  const cleanValue = value.trim().toLowerCase();
+
+  // Remove common prefixes if present
+  let numValue = cleanValue;
+  if (cleanValue.startsWith('0x')) {
+    numValue = cleanValue.substring(2);
+  } else if (cleanValue.startsWith('0b')) {
+    numValue = cleanValue.substring(2);
+  } else if (cleanValue.startsWith('0o')) {
+    numValue = cleanValue.substring(2);
+  }
+
+  // Validate characters for the base
+  const validDigits: Record<number, RegExp> = {
+    2: /^[01]+$/,
+    8: /^[0-7]+$/,
+    10: /^[0-9]+$/,
+    16: /^[0-9a-f]+$/,
+  };
+
+  if (!validDigits[base].test(numValue)) {
+    throw new Error(`Invalid value for base ${base}: ${value}`);
+  }
+
+  return BigInt(`0${base === 16 ? 'x' : ''}${numValue}`);
+}
+```
+
+**Step 4: 运行测试验证通过**
+
+```bash
+npm test -- test/integration/conversion.test.ts
+```
+
+**Step 5: 提交**
+
+```bash
+git add src/mcp/tools/conversion.ts test/integration/conversion.test.ts
+git commit -m "feat: implement convert_base MCP tool"
+```
+
+---
+
+### 任务 10: 实现 ASCII 工具
+
+**文件:**
+- 创建: `src/mcp/tools/ascii.ts`
+- 测试: `test/integration/ascii.test.ts`
+
+**Step 1: 编写 ASCII 工具集成测试**
+
+```typescript
+// test/integration/ascii.test.ts
+import { describe, it, expect } from 'vitest';
+import { asciiEncode, asciiDecode } from '../../src/mcp/tools/ascii.js';
+
+describe('ASCII MCP tools', () => {
+  describe('ascii_encode', () => {
+    it('should encode text to ASCII codes', () => {
+      const result = asciiEncode({ text: 'Hello' });
+
+      expect(result.success).toBe(true);
+      expect(result.result).toBe('72 101 108 108 111');
+    });
+
+    it('should encode single character', () => {
+      const result = asciiEncode({ text: 'A' });
+
+      expect(result.success).toBe(true);
+      expect(result.result).toBe('65');
+    });
+
+    it('should handle empty string', () => {
+      const result = asciiEncode({ text: '' });
+
+      expect(result.success).toBe(true);
+      expect(result.result).toBe('');
+    });
+  });
+
+  describe('ascii_decode', () => {
+    it('should decode ASCII codes to text', () => {
+      const result = asciiDecode({ codes: '72 101 108 108 111' });
+
+      expect(result.success).toBe(true);
+      expect(result.result).toBe('Hello');
+    });
+
+    it('should decode single code', () => {
+      const result = asciiDecode({ codes: '65' });
+
+      expect(result.success).toBe(true);
+      expect(result.result).toBe('A');
+    });
+
+    it('should handle comma-separated codes', () => {
+      const result = asciiDecode({ codes: '72,101,108,108,111' });
+
+      expect(result.success).toBe(true);
+      expect(result.result).toBe('Hello');
+    });
+
+    it('should return error for invalid code', () => {
+      const result = asciiDecode({ codes: '999' });
+
+      expect(result.success).toBe(false);
+      expect(result.error?.type).toBe('InvalidNumber');
+    });
+  });
+});
+```
+
+**Step 2: 运行测试验证失败**
+
+```bash
+npm test -- test/integration/ascii.test.ts
+```
+
+**Step 3: 实现 ASCII 工具**
+
+```typescript
+// src/mcp/tools/ascii.ts
+import { ErrorHandler, CalculationResponse } from '../../errors/handler.js';
+
+export interface AsciiEncodeInput {
+  text: string;
+}
+
+export interface AsciiDecodeInput {
+  codes: string;
+}
+
+export function asciiEncode(input: AsciiEncodeInput): CalculationResponse {
+  const errorHandler = new ErrorHandler();
+  const { text } = input;
+
+  try {
+    const codes = text
+      .split('')
+      .map(char => char.charCodeAt(0))
+      .join(' ');
+
+    return errorHandler.success(codes, {
+      expression: `"${text}" → ASCII codes`,
+    });
+  } catch (error) {
+    return errorHandler.runtimeError('InvalidNumber', error instanceof Error ? error.message : 'Failed to encode text');
+  }
+}
+
+export function asciiDecode(input: AsciiDecodeInput): CalculationResponse {
+  const errorHandler = new ErrorHandler();
+  const { codes } = input;
+
+  if (!codes || codes.trim().length === 0) {
+    return errorHandler.success('', {
+      expression: 'Empty codes → empty text',
+    });
+  }
+
+  try {
+    // Parse codes (support space and comma separated)
+    const codeList = codes
+      .split(/[\s,]+/)
+      .filter(s => s.length > 0)
+      .map(s => parseInt(s, 10));
+
+    // Validate codes
+    for (const code of codeList) {
+      if (isNaN(code) || code < 0 || code > 127) {
+        throw new Error(`Invalid ASCII code: ${code}`);
+      }
+    }
+
+    const text = codeList.map(code => String.fromCharCode(code)).join('');
+
+    return errorHandler.success(text, {
+      expression: `ASCII codes → "${text}"`,
+    });
+  } catch (error) {
+    return errorHandler.runtimeError('InvalidNumber', error instanceof Error ? error.message : 'Failed to decode ASCII codes');
+  }
+}
+```
+
+**Step 4: 运行测试验证通过**
+
+```bash
+npm test -- test/integration/ascii.test.ts
+```
+
+**Step 5: 提交**
+
+```bash
+git add src/mcp/tools/ascii.ts test/integration/ascii.test.ts
+git commit -m "feat: implement ASCII encode/decode MCP tools"
+```
+
+---
+
+### 任务 11: 实现 MCP Server
+
+**文件:**
+- 修改: `src/mcp/server.ts`
+- 创建: `src/index.ts`
+
+**Step 1: 实现 MCP Server**
+
+```typescript
+// src/mcp/server.ts
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { basicCalculate } from './tools/basic.js';
+import { programmerCalculate } from './tools/programmer.js';
+import { convertBase } from './tools/conversion.js';
+import { asciiEncode, asciiDecode } from './tools/ascii.js';
+
+const server = new Server(
+  {
+    name: 'mcp-calculator',
+    version: '0.1.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'basic_calculate',
+        description: 'Calculate basic arithmetic expressions with decimal precision. Supports: +, -, *, /, %, parentheses. Example: "2 + 3 * 4" or "0.1 + 0.2"',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            expression: {
+              type: 'string',
+              description: 'The arithmetic expression to evaluate',
+            },
+          },
+          required: ['expression'],
+        },
+      },
+      {
+        name: 'programmer_calculate',
+        description: 'Calculate programmer-style expressions with BigInt and bitwise operations. Supports: hex (0xFF), binary (0b1010), octal (0o77), &, |, ^, ~, <<, >>, >>>. Example: "0xFF & 0x0F" or "1 << 4"',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            expression: {
+              type: 'string',
+              description: 'The programmer expression to evaluate',
+            },
+          },
+          required: ['expression'],
+        },
+      },
+      {
+        name: 'convert_base',
+        description: 'Convert numbers between different bases (2, 8, 10, 16). Example: { value: "255", from: 10, to: 16 }',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            value: {
+              type: 'string',
+              description: 'The number value to convert',
+            },
+            from: {
+              type: 'number',
+              description: 'Source base (2, 8, 10, or 16)',
+            },
+            to: {
+              type: 'number',
+              description: 'Target base (2, 8, 10, or 16)',
+            },
+          },
+          required: ['value', 'from', 'to'],
+        },
+      },
+      {
+        name: 'ascii_encode',
+        description: 'Encode text to ASCII codes. Example: "Hello" → "72 101 108 108 111"',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            text: {
+              type: 'string',
+              description: 'The text to encode to ASCII codes',
+            },
+          },
+          required: ['text'],
+        },
+      },
+      {
+        name: 'ascii_decode',
+        description: 'Decode ASCII codes to text. Example: "72 101 108 108 111" → "Hello"',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            codes: {
+              type: 'string',
+              description: 'ASCII codes separated by spaces or commas',
+            },
+          },
+          required: ['codes'],
+        },
+      },
+    ],
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  switch (name) {
+    case 'basic_calculate':
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(basicCalculate(args as { expression: string })),
+          },
+        ],
+      };
+
+    case 'programmer_calculate':
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(programmerCalculate(args as { expression: string })),
+          },
+        ],
+      };
+
+    case 'convert_base':
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(convertBase(args as { value: string; from: number; to: number })),
+          },
+        ],
+      };
+
+    case 'ascii_encode':
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(asciiEncode(args as { text: string })),
+          },
+        ],
+      };
+
+    case 'ascii_decode':
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(asciiDecode(args as { codes: string })),
+          },
+        ],
+      };
+
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+});
+
+// Start server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('MCP Calculator server running on stdio');
+}
+
+main().catch((error) => {
+  console.error('Server error:', error);
+  process.exit(1);
+});
+```
+
+**Step 2: 创建入口文件**
+
+```typescript
+// src/index.ts
+export * from './parser/ast.js';
+export * from './parser/lexer.js';
+export * from './parser/parser.js';
+export * from './engines/decimal.js';
+export * from './engines/programmer.js';
+export * from './errors/handler.js';
+export * from './mcp/tools/basic.js';
+export * from './mcp/tools/programmer.js';
+export * from './mcp/tools/conversion.js';
+export * from './mcp/tools/ascii.js';
+
+// Run server if this is the main module
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await import('./mcp/server.js');
+}
+```
+
+**Step 3: 构建并测试**
+
+```bash
+npm run build
+```
+
+**Step 4: 提交**
+
+```bash
+git add src/mcp/server.ts src/index.ts
+git commit -m "feat: implement MCP Server with all tools"
+```
+
+---
+
+## 阶段 8: 最终验证和文档
+
+### 任务 12: 运行完整测试套件
+
+**Step 1: 运行所有测试**
+
+```bash
+npm run test:coverage
+```
+
+**Step 2: 验证覆盖率**
+
+检查每个组件的覆盖率是否达到目标：
+- Lexer: 100%
+- Parser: 95%+
+- DecimalEngine: 90%+
+- ProgrammerEngine: 95%+
+- ErrorHandler: 90%+
+
+**Step 3: 类型检查**
+
+```bash
+npm run typecheck
+```
+
+**Step 4: 构建验证**
+
+```bash
+npm run build
+```
+
+**Step 5: 提交**
+
+```bash
+git add .
+git commit -m "test: ensure full test coverage and type safety"
+```
+
+---
+
+### 任务 13: 创建 README
+
+**文件:**
+- 创建: `README.md`
+
+```bash
+cat > README.md << 'EOF'
+# MCP Calculator
+
+一个为 AI 助手提供计算能力的 MCP Server，支持四则运算和程序员计算功能。
+
+## 功能特性
+
+- **四则运算**: 高精度十进制计算（使用 decimal.js）
+- **程序员计算**: 大整数和位运算（使用 BigInt）
+- **进制转换**: 支持 2/8/10/16 进制互转
+- **ASCII 编码**: 文本与 ASCII 码互转
+
+## 安装
+
+\`\`\`bash
+npm install
+npm run build
+\`\`\`
+
+## 使用方法
+
+### 作为 MCP Server
+
+在 Claude Desktop 的配置文件中添加：
+
+\`\`\`json
+{
+  "mcpServers": {
+    "calculator": {
+      "command": "node",
+      "args": ["/path/to/calculator/dist/index.js"]
+    }
+  }
+}
+\`\`\`
+
+### 可用工具
+
+#### basic_calculate
+
+基础四则运算，支持高精度小数。
+
+\`\`\`typescript
+basic_calculate({ expression: "2 + 3 * 4" })
+// => { success: true, result: "14" }
+
+basic_calculate({ expression: "0.1 + 0.2" })
+// => { success: true, result: "0.3" }
+\`\`\`
+
+#### programmer_calculate
+
+程序员计算，支持位运算和大整数。
+
+\`\`\`typescript
+programmer_calculate({ expression: "0xFF & 0x0F" })
+// => { success: true, result: "15" }
+
+programmer_calculate({ expression: "1 << 4" })
+// => { success: true, result: "16" }
+
+programmer_calculate({ expression: "0xFFFFFFFFFFFFFFFF + 1" })
+// => { success: true, result: "18446744073709551616" }
+\`\`\`
+
+#### convert_base
+
+进制转换。
+
+\`\`\`typescript
+convert_base({ value: "255", from: 10, to: 16 })
+// => { success: true, result: "ff" }
+
+convert_base({ value: "1010", from: 2, to: 10 })
+// => { success: true, result: "10" }
+\`\`\`
+
+#### ascii_encode / ascii_decode
+
+ASCII 编码解码。
+
+\`\`\`typescript
+ascii_encode({ text: "Hello" })
+// => { success: true, result: "72 101 108 108 111" }
+
+ascii_decode({ codes: "72 101 108 108 111" })
+// => { success: true, result: "Hello" }
+\`\`\`
+
+## 开发
+
+\`\`\`bash
+# 开发模式
+npm run dev
+
+# 运行测试
+npm test
+
+# 测试覆盖率
+npm run test:coverage
+
+# 类型检查
+npm run typecheck
+\`\`\`
+
+## 返回格式
+
+### 成功
+
+\`\`\`json
+{
+  "success": true,
+  "result": "结果值（字符串形式）",
+  "details": {
+    "expression": "原始表达式"
+  }
+}
+\`\`\`
+
+### 错误
+
+\`\`\`json
+{
+  "success": false,
+  "error": {
+    "type": "SyntaxError | DivisionByZero | InvalidNumber | ...",
+    "message": "人类可读错误信息",
+    "position": { "start": 5, "end": 8 },
+    "suggestion": "修复建议"
+  }
+}
+\`\`\`
+
+## 许可证
+
+MIT
+EOF
+```
+
+**Step 6: 提交最终版本**
+
+```bash
+git add README.md
+git commit -m "docs: add comprehensive README"
+```
+
+---
+
+## 实施完成检查清单
+
+- [ ] 项目初始化完成（package.json, tsconfig.json, vitest.config.ts）
+- [ ] 错误处理系统实现（ErrorHandler, 结构化错误）
+- [ ] Lexer 实现（所有字面量和运算符）
+- [ ] Parser 实现（递归下降，运算符优先级）
+- [ ] DecimalEngine 实现（高精度四则运算）
+- [ ] ProgrammerEngine 实现（BigInt 和位运算）
+- [ ] basic_calculate 工具实现
+- [ ] programmer_calculate 工具实现
+- [ ] convert_base 工具实现
+- [ ] ASCII 工具实现
+- [ ] MCP Server 实现
+- [ ] 所有测试通过
+- [ ] 测试覆盖率达标
+- [ ] README 文档完成
+
+---
+
+**计划总任务数:** 13 个任务
+**估计时间:** 每个任务 20-40 分钟
+**总计时间:** 约 4-8 小时（取决于经验）