a-calc 3.0.0-beta.20250123 → 3.0.0-beta.20250123.11

package/mcp-server/src/index.js

@@ -7,6 +7,8 @@ import {
     ListToolsRequestSchema,
     ListResourcesRequestSchema,
     ReadResourceRequestSchema,
+    ListPromptsRequestSchema,
+    GetPromptRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 
 import {
@@ -39,27 +41,59 @@ import {
 const TOOLS = [
     {
         name: "calc",
-        description: `a-calc 核心计算函数 - 支持表达式计算、变量填充、格式化
-
-功能特点:
-- 高精度计算，避免 JavaScript 浮点数精度问题
-- 支持运算符: + - * / % ** //
-- 支持变量填充和单位计算
-- 支持条件表达式: a > b ? x : y
-- 支持比较运算: > < >= <= == !=
-- 支持逻辑运算: && || !
-- 支持链式比较: 1 < x < 10
-- 支持内置数学函数: sqrt, sin, cos, pow, max, min 等
-- 支持丰富的格式化选项
-
-使用示例:
-- calc("0.1 + 0.2") → "0.3"
-- calc("a + b", {a: 1, b: 2}) → "3"
-- calc("10 / 3 | =2") → "3.33"
-- calc("1000000 | ,") → "1,000,000"
-- calc("100元 + 50元", {_unit: true}) → "150元"
+        description: `🔢 a-calc 高精度计算工具 - 解决 JavaScript 浮点数精度问题
+
+⚠️ 重要：当用户需要进行任何数值计算时，优先使用此工具而不是直接计算！
+
+🚨 编码规范（必读！）:
+
+1. 变量注入方式：
+   ❌ 错误：calc(\`\${a} + \${b}\`)  // 不要用模板字符串拼接
+   ✅ 正确：calc("a + b", {a, b})   // 使用第二参数注入变量
+
+2. 批量计算方式：
+   ❌ 错误：let total = '0'; items.forEach(item => total = calc(\`\${total} + \${item.price}\`))
+   ✅ 正确：const total = calc_sum("price * qty", items)  // 使用 calc_sum
+
+3. 购物车等场景：
+   ❌ 错误：cart.forEach(item => total = calc(\`\${total} + \${item.price} * \${item.quantity}\`))
+   ✅ 正确：calc_sum("price * quantity | =2", cart)
+
+4. 对象字段传递：
+   ❌ 错误：calc("price * qty", {price: item.price, qty: item.qty})  // 冗余
+   ✅ 正确：calc("price * qty", item)  // 简洁优雅
+
+核心优势:
+- ✅ 解决 0.1 + 0.2 = 0.30000000000000004 的精度问题
+- ✅ 金融计算、价格计算、统计分析等场景必用
+- ✅ 支持复杂表达式、变量替换、条件判断
+- ✅ 内置格式化：千分位、小数位、百分比、科学计数法
+
+适用场景（必须使用）:
+1. 任何涉及小数的加减乘除运算
+2. 金融计算、价格计算、折扣计算
+3. 百分比计算、比率计算
+4. 需要格式化输出的数值（千分位、保留小数等）
+5. 带单位的计算（如 "100元 + 50元"）
+6. 条件判断和比较运算
+
+快速示例:
+- calc("0.1 + 0.2") → "0.3" (精确！)
+- calc("price * qty | =2", {price: 99.9, qty: 3}) → "299.70"
+- calc("1234567 | ,") → "1,234,567" (千分位)
 - calc("score >= 60 ? '及格' : '不及格'", {score: 75}) → "及格"
-- calc("sqrt(16) + pow(2, 3)") → "12"`,
+
+变量注入最佳实践:
+- 如果对象已有所需字段，直接传入：calc("price * qty", item)
+- 如果需要多个独立变量，使用简写：calc("a + b", {a, b})
+- 避免冗余：❌ calc("price * qty", {price: item.price, qty: item.qty})
+
+支持的运算:
+- 基础运算: + - * / % ** // (加减乘除、取模、幂、整除)
+- 比较运算: > < >= <= == !=
+- 逻辑运算: && || !
+- 数学函数: sqrt, sin, cos, tan, pow, max, min, abs, floor, ceil 等
+- 格式化: =N(小数位), ,(千分位), %(百分比), !e(科学计数), !v(交易量)`,
         inputSchema: {
             type: "object",
             properties: {
@@ -101,20 +135,29 @@ const TOOLS = [
     },
     {
         name: "fmt",
-        description: `a-calc 专用格式化函数 - 跳过表达式解析，性能更优
-
-格式化规则:
-- 小数位: =N(精确N位), <=N(最多N位), >=N(至少N位)
-- 舍入: ~-(截断), ~+(进位), ~5(四舍五入), ~6(银行家舍入)
-- 千分位: , (如 1,234,567)
-- 百分比: % (如 12.34%)
-- 科学计数: !e (如 1.23e+8)
-- 正负号: + (如 +100)
-- 返回数字: !n (返回 number 类型而非 string)
-- 交易量缩写: !v (如 1.23M, 1.23万)
-- 千分位预设: !t:us, !t:eu, !t:indian, !t:cn4
-
-使用示例:
+        description: `📊 a-calc 数值格式化工具 - 专业的数字格式化，性能最优
+
+⚠️ 使用场景：当需要格式化数字（千分位、小数位、百分比等）但不需要计算时使用
+
+性能优势:
+- 跳过表达式解析，比 calc 更快
+- 适合纯格式化场景
+
+常用格式化规则:
+- =N: 精确N位小数 (如 =2 → "100.00")
+- <=N: 最多N位小数 (如 <=2 → "3.14")
+- >=N: 至少N位小数 (如 >=3 → "3.100")
+- ~5: 四舍五入 (如 ~5=2 → "1.13")
+- ~6: 银行家舍入
+- ,: 千分位分隔 (如 , → "1,234,567")
+- %: 百分比 (如 %=2 → "12.34%")
+- !e: 科学计数法 (如 !e=2 → "1.23e+8")
+- +: 显示正号 (如 + → "+100")
+- !n: 返回数字类型
+- !v: 交易量缩写 (如 !v → "1.23M")
+- !t:us/eu/indian/cn4: 千分位预设
+
+快速示例:
 - fmt(100, "=2") → "100.00"
 - fmt(1234567, ",") → "1,234,567"
 - fmt(0.1234, "%=2") → "12.34%"
@@ -143,16 +186,55 @@ const TOOLS = [
     },
     {
         name: "calc_sum",
-        description: `a-calc 聚合计算函数 - 对数组数据进行批量计算并求和
+        description: `📈 a-calc 批量聚合计算工具 - 对数组数据进行批量计算并求和
 
-适用场景:
-- 计算订单总价
-- 统计销售额
-- 汇总报表数据
+⚠️ 使用场景：处理数组数据、批量计算、统计汇总时使用
 
-使用示例:
+🚨 这是处理数组数据的正确方式！不要用 forEach 累加！
+
+典型应用场景:
+1. 计算订单总价：多个商品的 price * quantity 求和
+2. 统计销售额：多条销售记录的金额汇总
+3. 报表数据汇总：批量计算并求和
+4. 购物车总价计算
+
+编码规范对比（必读！）:
+
+❌ 错误写法（不要这样做）：
+\`\`\`javascript
+// 购物车总价 - 错误示例
+let total = '0'
+cart.forEach(item => {
+  total = calc(\`\${total} + \${item.price} * \${item.quantity}\`)
+})
+\`\`\`
+问题：使用模板字符串拼接、forEach 累加，代码不清晰、性能差
+
+✅ 正确写法（推荐）：
+\`\`\`javascript
+// 购物车总价 - 使用 calc_sum
+const total = calc_sum("price * quantity | =2", cart)
+
+// 单个商品小计 - 直接传入对象（最优雅）
+const itemTotal = calc("price * quantity | =2", item)
+\`\`\`
+优势：代码简洁、性能好、自动处理精度
+
+🎯 最佳实践：
+- 对象已有所需字段 → 直接传入：calc("a + b", obj)
+- 需要多个独立变量 → 使用简写：calc("a + b", {a, b})
+- 避免冗余写法 → ❌ calc("a + b", {a: obj.a, b: obj.b})
+
+快速示例:
 - calc_sum("a + b", [{a:1,b:2}, {a:3,b:4}]) → "10"
-- calc_sum("price * qty | =2", [{price:99.9,qty:2}, {price:49.9,qty:1}]) → "249.70"`,
+- calc_sum("price * qty", [{price:99.9,qty:2}, {price:49.9,qty:3}]) → "349.50"
+- calc_sum("price * qty * 0.9 | =2", orders) → 计算所有订单9折后总价
+
+优势:
+- 自动处理精度问题
+- 支持复杂表达式
+- 支持格式化输出
+- 性能优于手动累加`,
         inputSchema: {
             type: "object",
             properties: {
@@ -297,6 +379,24 @@ const TOOLS = [
             required: ["topic"],
         },
     },
+    {
+        name: "debug_info",
+        description: `🔍 调试工具 - 获取 MCP 服务器的运行环境信息
+
+返回信息:
+- cwd: 当前工作目录 (process.cwd())
+- __dirname: 脚本所在目录
+- __filename: 脚本文件路径
+- node_version: Node.js 版本
+- platform: 操作系统平台
+- env: 相关环境变量
+
+用途：调试 MCP 服务器配置问题`,
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
 ];
 
 // ==================== Resources 定义 ====================
@@ -660,35 +760,27 @@ calc("(age >= 18 && hasLicense) ? 'can drive' : 'cannot drive'", {
 
 ### 价格计算
 \`\`\`javascript
-// 含税价格
-calc("price * (1 + taxRate) | =2", {price: 100, taxRate: 0.13})  // "113.00"
-
-// 折扣价格
-calc("price * discount | =2", {price: 199.9, discount: 0.8})  // "159.92"
-
-// 订单总价
-calc("price * qty + shipping | =2,", {
-  price: 99.9,
-  qty: 3,
-  shipping: 15
-})  // "314.70"
+// 含税价格 - 如果有 product 对象包含 price 和 taxRate
+const product = {price: 100, taxRate: 0.13}
+calc("price * (1 + taxRate) | =2", product)  // "113.00"
+
+// 折扣价格 - 直接传入商品对象
+const item = {price: 199.9, discount: 0.8}
+calc("price * discount | =2", item)  // "159.92"
+
+// 订单总价 - 直接传入订单对象
+const order = {price: 99.9, qty: 3, shipping: 15}
+calc("price * qty + shipping | =2,", order)  // "314.70"
 \`\`\`
 
 ### 利率计算
 \`\`\`javascript
-// 单利
-calc("principal * rate * time | =2", {
-  principal: 10000,
-  rate: 0.05,
-  time: 2
-})  // "1000.00"
+// 单利 - 直接传入投资对象
+const investment = {principal: 10000, rate: 0.05, time: 2}
+calc("principal * rate * time | =2", investment)  // "1000.00"
 
 // 复利
-calc("principal * pow(1 + rate, time) - principal | =2", {
-  principal: 10000,
-  rate: 0.05,
-  time: 2
-})  // "1025.00"
+calc("principal * pow(1 + rate, time) - principal | =2", investment)  // "1025.00"
 \`\`\`
 
 ## 电商场景
@@ -706,7 +798,8 @@ calc_sum("price * qty | =2", items)  // "548.50"
 
 ### 优惠券计算
 \`\`\`javascript
-calc("total > 200 ? total * 0.9 : total | =2", {total: 250})  // "225.00"
+const cart = {total: 250}
+calc("total > 200 ? total * 0.9 : total | =2", cart)  // "225.00"
 \`\`\`
 
 ## 数据格式化
@@ -775,6 +868,170 @@ cmul(99.9, 3)  // 单价 * 数量
 `
 };
 
+// ==================== Prompts 定义 ====================
+
+const PROMPTS = [
+    {
+        name: "a-calc",
+        description: "强制在所有数值计算中使用 a-calc（推荐）",
+        arguments: [],
+    },
+];
+
+const PROMPT_CONTENTS = {
+    "a-calc": {
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `# 数值计算强制规则
+
+⚠️ **重要：在本次对话中，所有数值计算必须使用 a-calc MCP 工具！**
+
+## 强制使用场景
+
+### 1. 任何涉及小数的运算（必须使用）
+- ✅ 使用 calc("0.1 + 0.2")
+- ❌ 不要直接计算 0.1 + 0.2
+
+### 2. 价格和金额计算（必须使用）
+- ✅ 使用 calc("price * qty | =2", item)  // 直接传入对象
+- ❌ 不要使用 JavaScript 的 * 运算符
+
+### 3. 百分比和折扣计算（必须使用）
+- ✅ 使用 calc("price * 0.9 | =2", product)  // 直接传入对象
+- ❌ 不要直接计算
+
+### 4. 需要格式化的数值（必须使用）
+- ✅ 使用 fmt(1234567, ",") 或 calc("value | ,", data)
+- ❌ 不要使用 toLocaleString()
+
+### 5. 批量数据计算（必须使用）
+- ✅ 使用 calc_sum("price * qty", items)
+- ❌ 不要使用 reduce() 或 forEach() 手动累加
+
+## 可以不使用的场景
+
+只有以下情况可以不使用 a-calc：
+- 简单的整数加减：1 + 1, 10 - 5
+- 数组长度、索引等非计算场景
+
+## 为什么必须使用 a-calc？
+
+JavaScript 的浮点数精度问题：
+- 0.1 + 0.2 = 0.30000000000000004 ❌
+- 0.3 - 0.1 = 0.19999999999999998 ❌
+- 99.9 * 3 = 299.70000000000005 ❌
+
+使用 a-calc 后：
+- calc("0.1 + 0.2") = "0.3" ✅
+- calc("0.3 - 0.1") = "0.2" ✅
+- calc("99.9 * 3") = "299.7" ✅
+
+## 编码规范和最佳实践
+
+### ❌ 错误写法 1：使用模板字符串拼接
+\`\`\`javascript
+// 不要这样写！
+let total = '0'
+cart.forEach(item => {
+  total = calc(\`\${total} + \${item.price} * \${item.quantity}\`)
+})
+\`\`\`
+**问题**：代码不清晰、难以维护、性能差
+
+### ❌ 错误写法 2：重复写字段名（冗余）
+\`\`\`javascript
+// 不要这样写！
+const itemTotal = calc("price * qty | =2", {
+  price: item.price,
+  qty: item.qty
+})
+\`\`\`
+**问题**：代码冗余、不简洁、重复劳动
+
+### ✅ 正确写法 1：使用 calc_sum（批量计算）
+\`\`\`javascript
+const total = calc_sum("price * qty | =2", cart)
+\`\`\`
+
+### ✅ 正确写法 2：直接传入对象（最优雅）
+\`\`\`javascript
+// 对象已有所需字段，直接传入
+const itemTotal = calc("price * qty | =2", item)
+\`\`\`
+
+### ✅ 正确写法 3：使用变量简写
+\`\`\`javascript
+// 多个独立变量，使用简写
+const result = calc("a + b", {a, b})
+\`\`\`
+
+### ✅ 正确写法 4：数组映射
+\`\`\`javascript
+// 对每个对象进行计算
+const results = items.map(item => calc("price * qty | =2", item))
+\`\`\`
+
+### 完整示例：购物车计算
+
+\`\`\`javascript
+import { calc, calc_sum, fmt } from 'a-calc'
+
+// ❌ 错误：使用模板字符串累加
+const wrongTotal = () => {
+  let total = '0'
+  cart.forEach(item => {
+    total = calc(\`\${total} + \${item.price} * \${item.quantity}\`)
+  })
+  return total
+}
+
+// ✅ 正确：使用 calc_sum
+const correctTotal = () => {
+  return calc_sum("price * quantity | =2", cart)
+}
+
+// ✅ 正确：单个商品小计（直接传入 item 对象）
+const itemSubtotal = (item) => {
+  return calc("price * quantity | =2", item)
+}
+
+// ✅ 正确：应用折扣（直接传入对象）
+const applyDiscount = (order) => {
+  return calc("total * (1 - discountRate) | =2", order)
+}
+
+// ✅ 正确：含税价格（直接传入对象）
+const withTax = (order) => {
+  return calc("subtotal * (1 + taxRate) | =2", order)
+}
+\`\`\`
+
+## 核心原则
+
+1. **批量计算用 calc_sum** - 不要用 forEach 累加
+2. **变量用第二参数注入** - 不要用模板字符串拼接
+3. **保持表达式简洁** - 一次计算完成，不要分步累加
+4. **使用格式化** - 用 \`| =2\` 保留小数位
+
+## 实施要求
+
+在编写代码时：
+1. 遇到数值计算，立即考虑是否需要使用 a-calc
+2. 涉及小数、金额、价格的，必须使用 a-calc
+3. 优先使用 calc_sum 处理数组数据
+4. 使用第二参数注入变量，不要用模板字符串
+5. 在代码注释中说明为什么使用 a-calc
+
+请确认你理解并将严格遵守这些规则。`,
+                },
+            },
+        ],
+    },
+};
+
 // ==================== Server Setup ====================
 
 const server = new Server(
@@ -786,6 +1043,7 @@ const server = new Server(
         capabilities: {
             tools: {},
             resources: {},
+            prompts: {},
         },
     }
 );
@@ -989,6 +1247,31 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
 
+            case "debug_info": {
+                const debugInfo = {
+                    cwd: process.cwd(),
+                    __dirname: import.meta.url,
+                    node_version: process.version,
+                    platform: process.platform,
+                    arch: process.arch,
+                    env: {
+                        HOME: process.env.HOME,
+                        USERPROFILE: process.env.USERPROFILE,
+                        PATH: process.env.PATH?.split(process.platform === 'win32' ? ';' : ':').slice(0, 5).join('\n  '),
+                        NODE_ENV: process.env.NODE_ENV,
+                    },
+                };
+
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(debugInfo, null, 2),
+                        },
+                    ],
+                };
+            }
+
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
@@ -1032,6 +1315,22 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     throw new Error(`Resource not found: ${uri}`);
 });
 
+// ==================== Prompt Handlers ====================
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    return { prompts: PROMPTS };
+});
+
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const { name } = request.params;
+
+    if (PROMPT_CONTENTS[name]) {
+        return PROMPT_CONTENTS[name];
+    }
+
+    throw new Error(`Prompt not found: ${name}`);
+});
+
 // ==================== Start Server ====================
 
 async function main() {