chaimi-bookkeeping-mcp 3.1.21 → 3.1.22

package/README.md

@@ -8,6 +8,15 @@
 - macOS / Windows / Linux
 - 微信（已安装"柴米AI记账"小程序）
 
+## ⚠️ 重要提示（Agent开发者必读）
+
+**如果您是 AI Agent 开发者，请注意：**
+
+1. **不要缓存工具定义**：MCP 工具定义可能会更新，请在每次调用前通过 `mcporter list` 获取最新定义
+2. **关注版本号**：工具描述中包含版本号（如【v3.1.21】），版本变化时请更新您的 Skill
+3. **save_receipt 工具要求**：items 数组中每个商品必须包含完整的4个字段：`name`、`amount`、`price`、`quantity`
+4. **自动填充字段**：`agentType`、`apiProvider`、`rawInput`、`mcp_version` 为自动填充字段，无需用户输入
+
 ## 快速安装
 
 ### 方式一：npm 全局安装（推荐）
@@ -134,6 +143,10 @@ AI 会自动调用 `save_income` 工具记录收入。
 
 ## 更新日志
 
+### v3.1.22 (2026-04-12)
+- **修复** fillDefaults 金额计算逻辑（根据 price × quantity 计算 amount）
+- **修复** 解决辣可可小票价格显示为0元的问题
+
 ### v3.1.21 (2026-04-12)
 - **修复** 版本号同步更新
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chaimi-bookkeeping-mcp",
-  "version": "3.1.21",
+  "version": "3.1.22",
   "description": "柴米记账 MCP Server - 支持 Claude、Cursor、OpenClaw、WorkBuddy 等 AI 工具直接记账",
   "main": "server.js",
   "bin": {

package/server.js

@@ -118,41 +118,41 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'save_receipt',
-        description: '【图片小票专用】保存购物小票/发票/收据（支持单商品或多商品）。当用户提供图片形式的小票、发票时，无论商品数量多少（1条或多条），都必须使用此接口。可自动识别商家名称、商品明细、金额、优惠等信息。典型场景：超市购物小票、餐厅发票、线上订单截图、手写收据照片等',
+        description: '【v3.1.21】【图片小票专用】保存购物小票/发票/收据。⚠️ 重要：items数组中每个商品必须包含完整的4个字段：name（商品名称）、amount（金额=单价×数量）、price（单价）、quantity（数量）。示例：[{"name":"苹果","amount":5.5,"price":5.5,"quantity":1}]',
         inputSchema: {
           type: 'object',
           properties: {
-            store: { type: 'string', description: '商家名称' },
+            store: { type: 'string', description: '商家名称（必填）' },
             date: { type: 'string', description: '消费时间（ISO 8601 格式，必须包含日期和时间，如：2026-04-10T13:06:21）' },
-            totalAmount: { type: 'number', description: '总金额' },
-            originalAmount: { type: 'number', description: '应付金额' },
+            totalAmount: { type: 'number', description: '总金额（所有商品amount之和）' },
+            originalAmount: { type: 'number', description: '应付金额（优惠前）' },
             discountAmount: { type: 'number', description: '优惠金额' },
-            actualAmount: { type: 'number', description: '实付金额' },
-            paymentMethod: { type: 'string', description: '支付方式' },
+            actualAmount: { type: 'number', description: '实付金额（优惠后）' },
+            paymentMethod: { type: 'string', description: '支付方式，如：微信支付、支付宝' },
             receiptNo: { type: 'string', description: '小票编号' },
             items: {
               type: 'array',
-              description: '商品列表，支持两种格式：1) 直接数组：[{"name":"苹果","amount":5.5}]  2) JSON字符串："[{\"name\":\"苹果\",\"amount\":5.5}]"（部分Agent如Claude Code可能传递JSON字符串）',
+              description: '【必填】商品列表，必须是数组格式。每个商品必须包含：name、amount、price、quantity。⚠️ 注意：amount=price×quantity',
               items: {
                 type: 'object',
                 properties: {
-                  name: { type: 'string', description: '商品名称' },
-                  originalName: { type: 'string', description: '原始商品名称' },
-                  price: { type: 'number', description: '单价' },
-                  quantity: { type: 'number', description: '数量' },
-                  unit: { type: 'string', description: '单位' },
-                  amount: { type: 'number', description: '金额' },
+                  name: { type: 'string', description: '【必填】商品名称' },
+                  originalName: { type: 'string', description: '原始商品名称（含规格）' },
+                  price: { type: 'number', description: '【必填】单价' },
+                  quantity: { type: 'number', description: '【必填】数量' },
+                  unit: { type: 'string', description: '单位，如：斤、个、份' },
+                  amount: { type: 'number', description: '【必填】金额，必须等于 price × quantity' },
                   weight: { type: 'string', description: '重量' },
-                  marketPrice: { type: 'string', description: '市场单价' },
-                  category: { type: 'string', description: '分类' },
+                  marketPrice: { type: 'string', description: '市场单价（元/500g）' },
+                  category: { type: 'string', description: '分类，如：餐饮、食品、购物' },
                 },
                 required: ['name', 'amount', 'price', 'quantity'],
               },
             },
-            agentType: { type: 'string', description: '【推荐自动填充】Agent类型，如：claude-desktop、cursor、openclaw、workbuddy、trae' },
-            apiProvider: { type: 'string', description: '【推荐自动填充】AI服务提供商，如：anthropic、openai、doubao、aliyun' },
-            rawInput: { type: 'string', description: '【推荐自动填充】用户的原始输入内容，用于记录用户原始请求' },
-            mcp_version: { type: 'string', description: 'MCP Server 版本号（自动填充）' },
+            agentType: { type: 'string', description: '【自动填充】Agent类型：claude-desktop、cursor、openclaw、workbuddy、trae' },
+            apiProvider: { type: 'string', description: '【自动填充】AI服务提供商：anthropic、openai、doubao、aliyun' },
+            rawInput: { type: 'string', description: '【自动填充】用户的原始输入内容' },
+            mcp_version: { type: 'string', description: '【自动填充】MCP Server版本号' },
           },
           required: ['store', 'items'],
         },
@@ -418,6 +418,32 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case 'save_receipt': {
+        // 0. 参数格式强制检查 - 确保 items 中每个商品都有完整的字段
+        if (processedArgs.items && Array.isArray(processedArgs.items)) {
+          const invalidItems = [];
+          processedArgs.items.forEach((item, index) => {
+            const missingFields = [];
+            if (!item.hasOwnProperty('name')) missingFields.push('name');
+            if (!item.hasOwnProperty('amount')) missingFields.push('amount');
+            if (!item.hasOwnProperty('price')) missingFields.push('price');
+            if (!item.hasOwnProperty('quantity')) missingFields.push('quantity');
+            
+            if (missingFields.length > 0) {
+              invalidItems.push(`商品${index + 1}(${item.name || '未命名'})缺少字段: ${missingFields.join(', ')}`);
+            }
+          });
+          
+          if (invalidItems.length > 0) {
+            result = {
+              success: false,
+              error: `参数格式错误：${invalidItems.join('; ')}。请更新您的 MCP Skill 或检查 items 数组格式。每个商品必须包含：name, amount, price, quantity`,
+              code: 400
+            };
+            userMessage = `❌ 保存失败\n\n错误：商品数据格式不完整\n\n${invalidItems.join('\n')}\n\n💡 解决方案：\n1. 请更新您的柴米记账 MCP Skill\n2. 确保每个商品包含完整的4个字段：name, amount, price, quantity\n3. amount 必须等于 price × quantity`;
+            break;
+          }
+        }
+        
         // 1. 调用 parseReceipt 重新提取小票信息（覆盖 Agent 传的数据）
         if (processedArgs.rawInput) {
           const parseResult = await callMcpPrompt(