calc-mcp-server 0.1.0

package/openspec/changes/archive/2026-02-24-simplify-ascii-tools/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-24

package/openspec/changes/archive/2026-02-24-simplify-ascii-tools/design.md

@@ -0,0 +1,46 @@
+## Context
+
+当前 ASCII 转换工具有三个：
+- `ascii_to_number`: 文本 → 逗号分隔的代码字符串
+- `number_to_ascii`: 单个代码 → 字符
+- `multiple_ascii_to_number`: 代码数组 → 文本（命名方向错误）
+
+项目使用 TypeScript + MCP Server 架构，工具层在 `src/mcp/tools/ascii.ts`，注册在 `src/mcp/server.ts`。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 修复 `multiple_ascii_to_number` 的命名问题
+- 简化 API，用单一工具覆盖单个和批量转换场景
+- 保持与现有 `ascii_to_number` 的功能对称性
+
+**Non-Goals:**
+- 不改变现有工具的输出格式
+- 不新增额外的工具
+
+## Decisions
+
+**合并而非重命名**
+- 将 `multiple_ascii_to_number` 的功能合并到 `number_to_ascii`
+- 理由: 减少工具数量，API 更简洁
+- 替代方案考虑过: 重命名为 `multiple_number_to_ascii`（会增加工具数量）
+
+**输入参数设计**
+```typescript
+{
+  code?: number,     // 单个代码
+  codes?: number[]   // 代码数组
+}
+// 两个参数都是可选，调用者选择其中一个
+```
+- 理由: 允许灵活的单/批量调用，不破坏现有单代码调用
+- 替代方案考虑过: 使用联合类型 `code: number | number[]`（但 JSON Schema 不支持）
+
+**删除而非重命名函数**
+- 直接删除 `multipleAsciiToNumber` 函数
+- 理由: 不需要向后兼容，简化代码
+
+## Risks / Trade-offs
+
+**参数验证复杂度** → 需要同时检查 `code` 和 `codes` 参数，确保恰好提供一个
+**JSON Schema 限制** → 无法使用 TypeScript 联合类型，但通过可选参数模式解决

package/openspec/changes/archive/2026-02-24-simplify-ascii-tools/proposal.md

@@ -0,0 +1,21 @@
+## Why
+
+当前 MCP 工具中的 `multiple_ascii_to_number` 命名与实际功能不匹配。该工具接受 `codes: number[]` 参数并返回文本字符串，实际转换方向是 Number → ASCII，但名字暗示相反方向。这会导致用户混淆。
+
+## What Changes
+
+- **删除** 工具 `multiple_ascii_to_number`
+- **扩展** 工具 `number_to_ascii` 同时支持单个数字和数字数组输入
+  - 单个数字: `code: number` → 字符串
+  - 数字数组: `codes: number[]` → 合并字符串
+
+## Capabilities
+
+### Modified Capabilities
+- `ascii-conversion`: ASCII 转换工具的行为变更，`number_to_ascii` 将接受数组输入
+
+## Impact
+
+- `src/mcp/tools/ascii.ts`: 删除 `multipleAsciiToNumber` 函数，扩展 `numberToAscii` 函数
+- `src/mcp/server.ts`: 删除 `multiple_ascii_to_number` 工具注册，修改 `number_to_ascii` 输入 schema
+- 测试文件: 更新相关测试用例

package/openspec/changes/archive/2026-02-24-simplify-ascii-tools/specs/ascii-conversion/spec.md

@@ -0,0 +1,22 @@
+## 修改的需求
+
+### 需求: 数字转 ASCII 字符
+系统必须将 ASCII/Unicode 码位转换为对应的字符。
+
+#### 场景: 单个码位转换
+- **当** 调用者提供 `code` 参数（单个数值）
+- **则** 系统返回对应的字符字符串
+
+#### 场景: 多个码位转换
+- **当** 调用者提供 `codes` 参数（数值数组）
+- **则** 系统返回所有对应字符拼接的字符串
+
+#### 场景: 无效码位
+- **当** 调用者提供的码位超出有效范围（BMP 范围为 0-65535）
+- **则** 系统返回错误并附带描述信息
+
+## 移除的需求
+
+### 需求: 多个 ASCII 转数字工具
+**原因**: 功能已合并到 `number_to_ascii` 工具以简化 API
+**迁移**: 使用 `number_to_ascii` 的 `codes` 参数代替

package/openspec/changes/archive/2026-02-24-simplify-ascii-tools/tasks.md

@@ -0,0 +1,24 @@
+## 1. 更新 src/mcp/tools/ascii.ts
+
+- [x] 1.1 删除 `MultipleAsciiToNumberInput` 接口
+- [x] 1.2 删除 `multipleAsciiToNumber` 函数
+- [x] 1.3 扩展 `NumberToAsciiInput` 接口，添加可选的 `codes?: number[]` 参数
+- [x] 1.4 修改 `numberToAscii` 函数逻辑：
+  - 检查 `code` 和 `codes` 参数，确保恰好提供一个
+  - 如果提供 `codes`，遍历数组并拼接字符
+  - 如果提供 `code`，保持原有逻辑
+
+## 2. 更新 src/mcp/server.ts
+
+- [x] 2.1 从导入中删除 `multipleAsciiToNumber`
+- [x] 2.2 在 TOOLS 数组中删除 `multiple_ascii_to_number` 工具定义
+- [x] 2.3 修改 `number_to_ascii` 工具的 inputSchema，添加 `codes` 属性
+- [x] 2.4 在 CallToolRequestSchema 处理器中删除 `multiple_ascii_to_number` case
+- [x] 2.5 更新 `number_to_ascii` case 处理逻辑，支持 `codes` 参数
+
+## 3. 更新测试
+
+- [x] 3.1 删除 `multiple_ascii_to_number` 相关测试
+- [x] 3.2 添加 `number_to_ascii` 批量转换测试用例
+- [x] 3.3 添加参数验证测试（同时提供 code 和 codes 应返回错误）
+- [x] 3.4 运行测试确认通过

package/openspec/config.yaml

@@ -0,0 +1,20 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours

package/openspec/specs/ascii-conversion/spec.md

@@ -0,0 +1,43 @@
+# ASCII Conversion 规范
+
+## Purpose
+
+提供 ASCII/Unicode 码位与字符之间的双向转换功能，支持单个和批量转换。
+
+## Requirements
+
+### 需求: ASCII 字符转数字
+
+系统必须将文本字符串转换为对应的 ASCII/Unicode 码位列表。
+
+#### 场景: 基本文本转换
+- **当** 调用者提供有效的非空文本字符串
+- **则** 系统返回每个字符对应的 ASCII 码位，以逗号分隔
+
+#### 场景: 空文本输入
+- **当** 调用者提供空字符串或 null
+- **则** 系统返回错误并提示文本不能为空
+
+### 需求: 数字转 ASCII 字符
+
+系统必须将 ASCII/Unicode 码位转换为对应的字符。
+
+#### 场景: 单个码位转换
+- **当** 调用者提供 `code` 参数（单个数值）
+- **则** 系统返回对应的字符字符串
+
+#### 场景: 多个码位转换
+- **当** 调用者提供 `codes` 参数（数值数组）
+- **则** 系统返回所有对应字符拼接的字符串
+
+#### 场景: 无效码位
+- **当** 调用者提供的码位超出有效范围（BMP 范围为 0-65535）
+- **则** 系统返回错误并附带描述信息
+
+#### 场景: 参数冲突
+- **当** 调用者同时提供 `code` 和 `codes` 参数
+- **则** 系统返回错误并提示只能提供一个参数
+
+#### 场景: 缺少参数
+- **当** 调用者未提供 `code` 或 `codes` 参数
+- **则** 系统返回错误并提示必须提供一个参数

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "calc-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP Server for calculator with basic and programmer operations",
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "calc-mcp-server": "build/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",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/ui": "^4.0.18",
+    "eslint": "^8.56.0",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.18"
+  }
+}

package/src/engines/decimal.ts

@@ -0,0 +1,69 @@
+import { Decimal } from 'decimal.js';
+import { ASTNode, BinaryOpNode, UnaryOpNode, LiteralNode, GroupNode } from '../parser/ast.js';
+
+export class DecimalEngine {
+
+  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)/, '');
+    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 new Error('DivisionByZero');
+        }
+        return left.dividedBy(right);
+      case '%':
+        if (right.isZero()) {
+          throw new Error('DivisionByZero');
+        }
+        return left.modulo(right);
+      default:
+        throw new Error(`不支持运算符 "${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}`);
+    }
+  }
+}

package/src/engines/programmer.ts

@@ -0,0 +1,112 @@
+import { ASTNode, BinaryOpNode, UnaryOpNode, LiteralNode, GroupNode } from '../parser/ast.js';
+import { ErrorHandler } from '../errors/handler.js';
+
+export class ProgrammerEngine {
+  private errorHandler = new ErrorHandler();
+
+  /**
+   * Evaluates an AST node and returns the result as a bigint.
+   *
+   * @param ast - The AST node to evaluate
+   * @returns The evaluation result as a bigint
+   * @throws {RuntimeError} If division by zero is attempted
+   * @throws {RuntimeError} If floating point numbers are used
+   */
+  evaluate(ast: ASTNode): bigint {
+    return this.visit(ast);
+  }
+
+  private visit(node: ASTNode): bigint {
+    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): 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}`);
+    }
+  }
+}

package/src/errors/handler.ts

@@ -0,0 +1,55 @@
+import {
+  ErrorType,
+  Position,
+  ErrorDetail,
+  ErrorResponse,
+  CalculationResponse,
+  SuccessResponse,
+} from './types.js';
+
+export type { ErrorType, CalculationResponse, ErrorResponse, SuccessResponse };
+
+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,
+    };
+  }
+}

package/src/errors/types.ts

@@ -0,0 +1,37 @@
+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;

package/src/index.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+import { createMCPServer } from './mcp/server.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+async function main() {
+  const server = createMCPServer();
+  const transport = new StdioServerTransport();
+
+  await server.connect(transport);
+
+  // eslint-disable-next-line no-console
+  console.error('MCP Calculator server running on stdio');
+}
+
+main().catch((error) => {
+  // eslint-disable-next-line no-console
+  console.error('Fatal error:', error);
+  process.exit(1);
+});