chaimi-keep-mcp 3.1.24

package/.env.example

@@ -0,0 +1,26 @@
+# 柴米记账 MCP Server 环境变量配置
+# OAuth 2.0 Device Flow 认证（行业标准方案）
+
+# ========================================
+# 必需配置
+# ========================================
+
+# OAuth 云函数地址
+# 首次启动会自动引导完成授权，Token 存储在 ~/.mcporter/oauth-token.json
+MCP_OAUTH_URL=https://cloud1-2gfe5jhjef06b85d-1412172089.ap-shanghai.app.tcloudbase.com/mcpOAuth
+
+# mcpHub 云函数地址
+MCP_HUB_URL=https://cloud1-2gfe5jhjef06b85d-1412172089.ap-shanghai.app.tcloudbase.com/mcpHub-mcp
+
+# mcpPrompt 云函数地址
+MCP_PROMPT_URL=https://cloud1-2gfe5jhjef06b85d-1412172089.ap-shanghai.app.tcloudbase.com/mcpPrompt
+
+# ========================================
+# 可选配置
+# ========================================
+
+# AI API Key（用于本地解析）
+AI_API_KEY=
+
+# AI 提供商（openai/anthropic/deepseek）
+AI_PROVIDER=deepseek

package/README.md

@@ -0,0 +1,222 @@
+# 柴米AI记账 MCP Server
+
+通过 OpenClaw、WorkBuddy 等 AI 工具直接记账，支持 MCP 协议的 Claude、Cursor 等。
+
+## 系统要求
+
+- Node.js >= 18.0.0
+- 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 全局安装（推荐）
+
+```bash
+# 1. 安装 MCPorter（WorkBuddy/OpenClaw 等 OpenClaw 架构的 Agent 必需）
+npm install -g mcporter
+
+# 2. 安装柴米记账 MCP
+npm install -g chaimi-keep-mcp
+
+# 3. 启动（自动配置 mcporter）
+chaimi-keep-mcp
+```
+
+### 方式二：手动下载安装（开发者）
+
+1. 从 GitHub Releases 下载安装包
+2. 解压后进入目录
+3. 安装依赖：`npm install`
+4. 运行：`node bin/cli.js`（会自动配置 mcporter）
+
+## 首次使用
+
+### 1. 触发授权
+
+在 WorkBuddy/OpenClaw 中输入：
+
+```
+帮我记一笔午餐35元
+```
+
+### 2. 获取验证码
+
+MCP Server 会显示：
+
+```
+╔════════════════════════════════════════════════════════╗
+║  柴米AI记账 MCP Server - 首次使用需要授权              ║
+╠════════════════════════════════════════════════════════╣
+║                                                        ║
+║  验证码：ABCD-EFGH                                     ║
+║                                                        ║
+║  请在"柴米AI记账"小程序中完成授权：                    ║
+║                                                        ║
+║  1. 打开"柴米AI记账"小程序                             ║
+║  2. 点击"我的" → "🤖 Agent 授权"                      ║
+║  3. 输入验证码：ABCD-EFGH                              ║
+║                                                        ║
+╚════════════════════════════════════════════════════════╝
+```
+
+### 3. 小程序授权
+
+打开"柴米AI记账"小程序 → 点击"我的" → "🤖 Agent 授权" → 输入上述验证码
+
+### 4. 完成
+
+授权成功后，AI 会自动完成记账。
+
+## 环境变量（可选）
+
+如需自定义云函数地址，可设置以下环境变量：
+
+```bash
+export MCP_OAUTH_URL="你的授权服务地址"
+export MCP_HUB_URL="你的Hub服务地址"
+export MCP_PROMPT_URL="你的Prompt服务地址"
+```
+
+> 默认使用柴米AI记账官方云服务，一般无需修改。
+
+## 常见问题
+
+**Q: 提示 "command not found: chaimi-keep-mcp"**
+
+A: npm 全局安装后需要重启终端，或检查 npm 全局路径是否加入环境变量。
+
+**Q: 验证码无效**
+
+A: 验证码 30 分钟内有效，过期需要重新获取。
+
+**Q: 需要每次都授权吗**
+
+A: 不需要。Token 会自动刷新，除非超过 30 天未使用。
+
+**Q: 如何更新到最新版本**
+
+A: `npm update -g chaimi-keep-mcp`
+
+## 技术支持
+
+- 微信：solinxia
+- 邮箱：songyangx@gmail.com
+- npm 包地址：https://www.npmjs.com/package/chaimi-keep-mcp
+
+## 功能说明
+
+### 支持的记账类型
+
+| 工具 | 用途 | 示例 |
+|------|------|------|
+| `save_expense` | 单商品支出 | "午餐 35 元" |
+| `save_receipt` | 小票/多商品 | "超市购物：牛奶 10 元，面包 15 元" |
+| `save_income` | **收入记录** | "工资到账 8000 元" |
+| `get_expenses` | 查询记录 | "查看本月消费" |
+| `get_statistics` | 消费统计 | "本月花了多少" |
+
+### 收入记账示例
+
+在 WorkBuddy/OpenClaw 中输入：
+
+```
+记录工资收入 8000 元
+```
+
+或：
+
+```
+今天收到奖金 3000
+```
+
+AI 会自动调用 `save_income` 工具记录收入。
+
+## 更新日志
+
+### v3.1.23 (2026-04-13)
+- **安全** 新增请求签名验证，防止 Agent 直接 curl 访问云函数
+- **安全** Token 加密存储（AES-256-CBC），绑定机器标识
+- **安全** URL 加密存储，防止明文暴露
+- **新增** SKILL.md 定义安全约束和触发规则
+- **优化** 授权提示文案，增加 AUTH_JUST_COMPLETED 标记
+
+### v3.1.22 (2026-04-12)
+- **修复** fillDefaults 金额计算逻辑（根据 price × quantity 计算 amount）
+- **修复** 解决辣可可小票价格显示为0元的问题
+
+### v3.1.21 (2026-04-12)
+- **修复** 版本号同步更新
+
+### v3.1.20 (2026-04-12)
+- **修复** 返回已过期验证码的问题（在 getToken 中添加过期检查）
+
+### v3.1.19 (2026-04-12)
+- **恢复** `submit_feedback` 反馈功能（从 npm 3.1.0 恢复丢失代码）
+- **新增** 反馈参数校验（content 非空、长度限制、type 枚举校验）
+- **优化** 客服消息内容截断长度改为 150 字符
+- **新增** Agent 字符限制提示（反馈内容不要超过150字符）
+
+### v3.1.2 (2026-04-11)
+- **修复** 启动界面版本号显示问题
+- **修复** 首次安装验证码显示问题
+- **优化** 内部测试流程
+
+### v3.1.0 (2026-04-11)
+- **移除** Python 版本 (`server.py`)，统一使用 Node.js 版本
+- **安全** 删除包含敏感 token 的 `config.yaml`，新增 `config.example.yaml` 模板
+- **安全** 更新 `.gitignore` 和 `.npmignore`，排除敏感文件
+- **优化** 项目结构，清理不必要的文件
+
+### v3.0.3 (2026-04-10)
+- **新增** `get_parse_prompt` 工具，首次实现将云函数 Prompt 模板完整返回给 Agent
+- **优化** `mcpHub`：新增 `receiptNo` 自动生成逻辑（强制生成唯一 ID）
+- **优化** `mcpHub`：优化 `actualAmount` 计算 fallback 逻辑
+- **优化** `mcpPrompt`：升级 Prompt 版本到 2.0.2，强化支付金额字段提取
+- **优化** `mcpPrompt`：优化 `date` 字段描述，要求 ISO 8601 完整时间格式
+
+### v3.0.0 (2026-04-09)
+- **新增** `submit_feedback` 工具，支持用户提交反馈
+- **新增** 反馈双通道：数据库保存 + 小程序客服消息推送
+- **优化** 小票记账功能，完善字段提取逻辑
+
+### v2.3.4 (2026-04-08)
+- **简化** `save_expense` 工具，只保留 `name` 和 `amount` 为必填参数
+- **优化** 其他参数使用默认值，简化 Agent 调用
+
+### v2.3.3 (2026-04-08)
+- **修正** 版本号统一为 v2.3.3（包含 v2.3.2 的所有修复）
+
+### v2.3.2 (2026-04-08)
+- **修复** `server.js` 中 `CURRENT_VERSION` 未定义错误，统一使用 `MCP_VERSION`
+- **修复** 所有工具的 `userMessage` 添加默认值，防止显示 `undefined`
+
+### v2.3.1 (2026-04-08)
+- **修复** `bin/cli.js` 版本号显示问题，改为动态读取 package.json
+- **优化** OAuth 授权流程，轮询间隔缩短为 2 秒
+
+### v2.3.0 (2026-04-08)
+- **修复** `save_receipt` 的 `items` 参数解析 bug，支持 JSON 字符串自动转换
+- **优化** `source` 字段规范：`save_expense`→`mcp_txt_expense`、`save_income`→`mcp_txt_income`、`save_receipt`→`mcp_receipt`
+- **新增** `mcp_version` 字段追踪，便于版本监控
+- **注释** `quick_book` 工具（暂时下线，待优化后重新开放）
+
+### v2.2.0 (2026-04-05)
+- **新增收入记账功能** (`save_income`)
+- 支持工资、奖金、红包、投资收益等收入类型
+- 支出和收入统一存储，便于统计分析
+
+### v2.1.0 (2026-04-03)
+- 升级 OAuth 2.0 Device Flow 认证
+- 支持 npm 全局安装
+- 支持多种 AI 工具（OpenClaw、WorkBuddy），理论支持 Claude
+- 自动 Token 刷新

package/bin/cli.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+
+/**
+ * 柴米记账 MCP Server CLI 入口
+ * 智能创建/更新多个 Agent 配置，保护用户已有配置
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const { spawn } = require('child_process');
+
+// 读取 package.json 获取版本号
+const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+const CURRENT_VERSION = packageJson.version;
+
+// 获取 server.js 的绝对路径
+const serverPath = path.join(__dirname, '..', 'server.js');
+
+// 默认的柴米记账配置
+const DEFAULT_CHAIMI_CONFIG = {
+  command: 'chaimi-keep-mcp',
+  description: '柴米记账 MCP Server - 支持 AI 工具直接记账',
+  env: {
+    MCP_OAUTH_URL: 'https://cloud1-2gfe5jhjef06b85d-1412172089.ap-shanghai.app.tcloudbase.com/mcpOAuth',
+    MCP_HUB_URL: 'https://cloud1-2gfe5jhjef06b85d-1412172089.ap-shanghai.app.tcloudbase.com/mcpHub-mcp',
+    MCP_PROMPT_URL: 'https://cloud1-2gfe5jhjef06b85d-1412172089.ap-shanghai.app.tcloudbase.com/mcpPrompt'
+  },
+  // 首次授权时需要常驻运行，等待用户授权（3分钟轮询）
+  // 授权成功后进程自动退出，下次调用时 mcporter 会重新启动
+  lifecycle: 'keep-alive'
+};
+
+// 支持的 Agent 列表
+const SUPPORTED_AGENTS = [
+  {
+    name: 'MCPorter (WorkBuddy/OpenClaw)',
+    configPath: path.join(os.homedir(), '.mcporter', 'mcporter.json'),
+    format: 'json'
+  },
+  {
+    name: 'WorkBuddy (Windows)',
+    configPath: path.join(os.homedir(), 'workbuddy', 'mcp.json'),
+    format: 'json',
+    platform: 'win32'
+  },
+  {
+    name: 'Claude Desktop',
+    configPath: path.join(os.homedir(), 'Library/Application Support/Claude/claude_desktop_config.json'),
+    format: 'json',
+    platform: 'darwin'
+  },
+  {
+    name: 'Claude Desktop (Windows)',
+    configPath: path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json'),
+    format: 'json',
+    platform: 'win32'
+  },
+  {
+    name: 'Cursor',
+    configPath: path.join(os.homedir(), '.cursor', 'mcp.json'),
+    format: 'json'
+  },
+  {
+    name: 'Cursor (Windows)',
+    configPath: path.join(os.homedir(), '.cursor', 'mcp.json'),
+    format: 'json',
+    platform: 'win32'
+  },
+  {
+    name: 'Windsurf',
+    configPath: path.join(os.homedir(), '.codeium', 'windsurf', 'mcp_config.json'),
+    format: 'json'
+  }
+];
+
+/**
+ * 安全读取 JSON 文件
+ */
+function readJSON(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * 安全写入 JSON 文件
+ */
+function writeJSON(filePath, data) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8');
+}
+
+/**
+ * 为单个 Agent 安装配置
+ * 原则：只添加缺失的配置，绝不覆盖用户已有配置
+ */
+function installToAgent(agent) {
+  try {
+    // 平台检查
+    if (agent.platform && agent.platform !== os.platform()) {
+      return { success: false, reason: 'platform-not-supported' };
+    }
+
+    // 检查 Agent 是否已安装（配置文件目录是否存在）
+    const configDir = path.dirname(agent.configPath);
+    const isAgentInstalled = fs.existsSync(configDir);
+
+    // 读取现有配置
+    let config = readJSON(agent.configPath);
+    let isNewFile = false;
+
+    if (!config) {
+      config = { mcpServers: {} };
+      isNewFile = true;
+    }
+
+    if (!config.mcpServers) {
+      config.mcpServers = {};
+    }
+
+    // 检查是否已存在柴米记账配置
+    if (config.mcpServers['柴米记账']) {
+      return { 
+        success: true, 
+        action: 'skipped', 
+        reason: 'already-configured',
+        agentInstalled: isAgentInstalled
+      };
+    }
+
+    // 添加柴米记账配置
+    config.mcpServers['柴米记账'] = JSON.parse(JSON.stringify(DEFAULT_CHAIMI_CONFIG));
+
+    // 写入配置
+    writeJSON(agent.configPath, config);
+
+    return { 
+      success: true, 
+      action: isNewFile ? 'created' : 'updated',
+      agentInstalled: isAgentInstalled
+    };
+
+  } catch (error) {
+    return { 
+      success: false, 
+      reason: 'error', 
+      error: error.message 
+    };
+  }
+}
+
+/**
+ * 配置所有支持的 Agent
+ * 注意：所有输出使用 console.error，避免污染 stdout（MCP 协议通信使用 stdout）
+ */
+function configureAllAgents() {
+  console.error('🔧 正在检测并配置 AI Agent...\n');
+
+  const results = [];
+
+  for (const agent of SUPPORTED_AGENTS) {
+    const result = installToAgent(agent);
+    results.push({ agent: agent.name, ...result });
+
+    // 显示结果（使用 stderr）
+    if (result.success) {
+      if (result.action === 'skipped') {
+        console.error(`✓ ${agent.name}: 配置已存在，已保留`);
+      } else if (result.action === 'created') {
+        console.error(`✓ ${agent.name}: 已创建配置`);
+      } else {
+        console.error(`✓ ${agent.name}: 已添加配置`);
+      }
+    } else {
+      if (result.reason === 'platform-not-supported') {
+        // 静默跳过不支持的平台的 Agent
+      } else {
+        console.error(`✗ ${agent.name}: 配置失败 (${result.error})`);
+      }
+    }
+  }
+
+  // 统计
+  const configured = results.filter(r => r.success && r.action !== 'skipped').length;
+  const skipped = results.filter(r => r.success && r.action === 'skipped').length;
+  const failed = results.filter(r => !r.success).length;
+
+  console.error('\n📊 配置统计:');
+  console.error(`   新增配置: ${configured} 个`);
+  console.error(`   已存在: ${skipped} 个`);
+  if (failed > 0) {
+    console.error(`   失败: ${failed} 个`);
+  }
+  console.error('');
+
+  return results;
+}
+
+/**
+ * 显示欢迎信息
+ * 注意：使用 console.error，避免污染 stdout（MCP 协议通信使用 stdout）
+ */
+function showWelcome() {
+  console.error('╔════════════════════════════════════════════════════════╗');
+  console.error('║                                                        ║');
+  console.error(`║           柴米记账 MCP Server v${CURRENT_VERSION}                   ║`);
+  console.error('║                                                        ║');
+  console.error('║   支持: OpenClaw | WorkBuddy | Claude | Cursor        ║');
+  console.error('║                                                        ║');
+  console.error('╚════════════════════════════════════════════════════════╝');
+  console.error('');
+}
+
+// 主程序
+showWelcome();
+configureAllAgents();
+
+// 启动 server.js - 使用当前 Node.js 可执行文件路径，解决跨平台兼容性问题
+const child = spawn(process.execPath, [serverPath], {
+  stdio: 'inherit',
+  env: process.env
+});
+
+child.on('exit', (code) => {
+  process.exit(code);
+});

package/bin/get-auth-code.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+/**
+ * 获取授权验证码（非阻塞模式）
+ * 用于 Agent 自动获取验证码，提示用户去小程序授权
+ */
+
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+// 读取 package.json 获取版本号
+const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+const CURRENT_VERSION = packageJson.version;
+
+// 导入 OAuth 模块
+const { OAuthManager, FileTokenStorage } = require('../oauth.js');
+
+const MCP_OAUTH_URL = process.env.MCP_OAUTH_URL || 'https://cloud1-2gfe5jhjef06b85d-1412172089.ap-shanghai.app.tcloudbase.com/mcpOAuth';
+
+// 检查是否已有有效 Token
+async function checkExistingToken() {
+  const tokenStorage = new FileTokenStorage(
+    path.join(os.homedir(), '.mcporter', 'oauth-token.json')
+  );
+  
+  try {
+    const existingToken = await tokenStorage.load();
+    if (existingToken && existingToken.expiresAt > Date.now()) {
+      return true;
+    }
+  } catch (e) {
+    // 无 Token 或已过期
+  }
+  return false;
+}
+
+// 获取新的授权码
+async function getAuthCode() {
+  const tokenStorage = new FileTokenStorage(
+    path.join(os.homedir(), '.mcporter', 'oauth-token.json')
+  );
+
+  const oauthManager = new OAuthManager({
+    mcpOAuthUrl: MCP_OAUTH_URL,
+    tokenStorage: tokenStorage,
+    onQrCode: (qrData) => {
+      // 输出 JSON 格式，方便 Agent 解析
+      console.log(JSON.stringify({
+        success: true,
+        type: 'auth_required',
+        userCode: qrData.userCode,
+        verificationUri: qrData.verificationUri,
+        message: `请在"柴米AI记账"小程序中完成授权`,
+        steps: [
+          '打开"柴米AI记账"小程序',
+          '点击"我的" → "🤖 Agent 授权"',
+          `输入验证码：${qrData.userCode}`
+        ]
+      }));
+    },
+    onTokenReady: (token) => {
+      console.log(JSON.stringify({
+        success: true,
+        type: 'auth_success',
+        message: '授权成功！现在可以正常使用记账功能了。'
+      }));
+    }
+  });
+
+  try {
+    // 检查是否已有进行中的授权
+    const authState = await oauthManager.loadAuthState();
+    if (authState && !oauthManager.isAuthStateExpired(authState)) {
+      console.log(JSON.stringify({
+        success: true,
+        type: 'auth_pending',
+        userCode: authState.userCode,
+        message: `授权进行中，请使用验证码 ${authState.userCode} 完成授权`,
+        steps: [
+          '打开"柴米AI记账"小程序',
+          '点击"我的" → "🤖 Agent 授权"',
+          `输入验证码：${authState.userCode}`
+        ]
+      }));
+      return;
+    }
+
+    // 启动新的授权流程
+    await oauthManager.startAuthFlow();
+  } catch (err) {
+    console.log(JSON.stringify({

package/config.example.yaml

@@ -0,0 +1,15 @@
+# 柴米记账 MCP Server 配置文件示例
+# 复制此文件为 config.yaml 并填入您的实际配置
+
+chaihuo:
+  # JWT Token（从小程序调用 mcpAuth 云函数获取）
+  # 示例：token: "eyJhbGciOiJIUzI1NiIs..."
+  token: ""
+  
+  # SCF函数URL（部署后获取）
+  # 示例：base_url: "https://mcpServer-xxx.gz.apigw.tencentcs.com"
+  base_url: ""
+
+# 其他配置
+port: 3000
+environment: "production"