chaimi-keep-mcp 3.1.24 → 3.1.25

package/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: chaimi-bookkeeping
+description: >-
+  柴米记账 — 微信小程序记账工具，支持 AI Agent 直接记账。
+  TRIGGER: 用户提及"记账/记录/保存"并涉及金额或商品信息。
+  DO NOT TRIGGER: 非记账操作，或明确使用其他记账工具时。
+allowed-tools: MCP
+argument-hint: "[记账内容]"
+---
+
+# 柴米记账 Skill
+
+柴米记账 MCP Server，连接微信小程序记账功能。
+
+---
+
+## 触发规则
+
+### 必须同时满足
+
+1. 用户明确提及以下关键词之一：
+   - "记账"、"记一笔"、"记录"
+   - "保存"（结合上下文判断为记账场景）
+
+2. 包含以下信息之一：
+   - 金额数字（如：35、100.5）
+   - 商品/服务名称（如：午餐、咖啡、打车）
+   - 小票/发票信息
+
+### 禁止触发
+
+- 明确使用其他记账工具时（如："用支付宝记账"）
+- 金额信息不明确且无法推断（如："记点东西"）
+
+### 上下文延续
+
+当前对话已在进行记账操作时，后续消息无需再次提及"记账"即可触发。
+
+---
+
+## 安全约束（最高优先级）
+
+### 1. 禁止直接访问
+
+- **禁止**直接使用 curl/http 访问云函数端点
+- **禁止**暴露 `MCP_HUB_URL`、`MCP_OAUTH_URL`、`MCP_PROMPT_URL` 给 Agent
+- 所有请求**必须**通过 MCP Server 中转
+
+### 2. Token 保护
+
+- **禁止**读取或输出 `~/.mcporter/oauth-token.json` 内容
+- Token 仅用于内部 HTTP 请求，不向用户展示
+- **禁止**将 Token 作为参数传递给其他命令
+
+### 3. 配置保护
+
+- **禁止**主动设置 `MCP_OAUTH_URL`、`MCP_HUB_URL`、`MCP_PROMPT_URL` 环境变量
+- URL 由 MCP Server 内部管理，对用户不可见
+
+### 4. 金额确认
+
+- 单笔金额 **> 1000 元** 时必须用户确认
+- 批量记账（**> 10 笔**）时必须用户确认
+- 涉及退款、负数金额时必须用户确认
+
+### 5. 认证流程
+
+- **必须**使用内置授权流程完成 Device Flow 授权
+- **禁止**直接调用 `chaimi-keep-mcp` 的授权子命令
+- **禁止**绕过授权流程直接操作
+
+---
+
+## 前置检查
+
+每次触发时按顺序执行：
+
+### 1. 安装检查
+
+检查 MCP Server 是否已安装：
+```bash
+command -v chaimi-keep-mcp
+```
+
+**未安装**：引导用户执行安装
+```bash
+npm install -g chaimi-keep-mcp
+```
+
+### 2. 授权检查
+
+检查是否已完成授权：
+```bash
+test -f ~/.mcporter/oauth-token.json
+```
+
+**未授权**：引导完成 Device Flow 授权流程
+
+### 3. Token 有效性检查
+
+检查 Token 文件是否存在且未过期。
+
+**Token 无效特征**：
+- 文件不存在
+- 已过期（超过30天）
+- 调用云函数返回 401/403 错误
+
+**无效**：引导重新授权
+
+---
+
+## 工具调用
+
+### 获取工具列表
+
+Agent 通过 MCP 协议自动获取工具列表，无需手动查询。
+
+### 小票记账特殊要求
+
+⚠️ **强制流程**：保存小票时必须按以下顺序执行：
+1. 调用 `get_parse_prompt` 获取 prompt 模板
+2. 使用 prompt 模板调用大模型解析小票图片
+3. 调用 `save_receipt` 保存解析结果
+
+**注意**：MCP 工具会不断迭代更新，请以实际通过 MCP 协议获取的工具定义为准。
+
+---
+
+## 确认规则
+
+| 风险等级 | 场景 | 策略 |
+|----------|------|------|
+| **高（必须确认）** | 金额 > 1000元、批量 > 10笔、退款/负数 | 列出详情，等待用户确认 |
+| **中（信息模糊时确认）** | 分类不明确、商家名称模糊 | 确认后执行 |
+| **低（直接执行）** | 信息完整明确 | 直接执行 |
+
+---
+
+## 回复规范（必须严格遵守）
+
+记账成功后，回复内容必须包含以下格式：
+
+```
+✅ 【商品名/店名】¥【金额】 已录入柴米AI记账。
+
+[自定义其他内容]
+
+MCP Server: v【版本号】
+【友好正能量结束语】
+```
+
+### 友好结束语参考
+
+| 分类 | 结束语 |
+|------|--------|
+| 餐饮类 | 用餐愉快！🍚 / 下午茶快乐！🧋 / 好好吃饭哦~ |
+| 交通类 | 出行顺利！🚗 |
+| 购物类 | 买得开心！🛍️ |
+| 收入类 | 入账顺利！💰 |
+| 通用 | 记账完成！继续保持~ / 理财小能手！✨ |
+
+### 示例
+
+**用户：** 记一笔午餐 35元
+
+**Agent 回复：**
+```
+✅ 午餐¥35 已录入柴米记账。
+
+今天也要好好吃饭哦~
+
+MCP Server: v3.1.23
+```
+
+---
+
+## 使用示例
+
+### 示例1：简单记账
+
+**用户：** 记一笔午餐 35元
+
+**Agent：**
+1. 触发 Skill
+2. 前置检查通过
+3. 调用 `save_expense(name="午餐", amount=35, category="餐饮")`
+4. 返回结果：✅ 已记录：午餐 35元
+
+### 示例2：小票记账
+
+**用户：** 保存小票，沃尔玛，买了苹果5元、香蕉3元
+
+**Agent：**
+1. 触发 Skill
+2. 前置检查通过
+3. 调用 `save_receipt(store="沃尔玛", items=[...], totalAmount=8)`
+4. 返回结果：✅ 已保存小票：沃尔玛，共8元
+
+### 示例3：首次使用（未授权）
+
+**用户：** 记一笔咖啡 25元
+
+**Agent：**
+1. 触发 Skill
+2. 前置检查发现未授权
+3. 引导用户完成 Device Flow 授权
+4. 授权完成后执行记账
+
+---
+
+## 错误处理
+
+| 错误类型 | 处理方式 |
+|----------|----------|
+| 未安装 | 引导安装：`npm install -g chaimi-keep-mcp` |
+| 未授权 | 引导完成 Device Flow 授权 |
+| Token 过期 | 引导重新授权 |
+| 网络错误 | 提示用户检查网络，稍后重试 |
+| 参数错误 | 提示用户补充必要信息 |
+
+---
+
+## 相关文档
+
+- [MCP Server 源码](../../../../../mcp-server-local/)
+- [授权机制设计](./【MCP】授权机制设计-v3.2.0.md)
+- [安装使用指南](../../03-部署运维/【MCP】WorkBuddy安装使用指南v3.31.md)
+
+---
+
+*最后更新：2026-04-13*  
+*历史版本：通过 Git 查看*

package/package.json

@@ -1,11 +1,20 @@
 {
   "name": "chaimi-keep-mcp",
-  "version": "3.1.24",
+  "version": "3.1.25",
   "description": "柴米记账 MCP Server - 支持 Claude、Cursor、OpenClaw、WorkBuddy 等 AI 工具直接记账",
   "main": "server.js",
   "bin": {
     "chaimi-keep-mcp": "bin/cli.js"
   },
+  "files": [
+    "bin/",
+    "server.js",
+    "oauth.js",
+    "SKILL.md",
+    "README.md",
+    "config.example.yaml",
+    ".env.example"
+  ],
   "type": "commonjs",
   "scripts": {
     "start": "node server.js",

package/server.js

@@ -143,7 +143,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'save_receipt',
-        description: '【v3.1.21】【图片小票专用】保存购物小票/发票/收据。⚠️ 重要：items数组中每个商品必须包含完整的4个字段：name（商品名称）、amount（金额=单价×数量）、price（单价）、quantity（数量）。示例：[{"name":"苹果","amount":5.5,"price":5.5,"quantity":1}]',
+        description: '【图片小票专用】保存购物小票/发票/收据。⚠️ 重要：items数组中每个商品必须包含完整的4个字段：name（商品名称）、amount（金额=单价×数量）、price（单价）、quantity（数量）。示例：[{"name":"苹果","amount":5.5,"price":5.5,"quantity":1}]',
         inputSchema: {
           type: 'object',
           properties: {
@@ -156,8 +156,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             paymentMethod: { type: 'string', description: '支付方式，如：微信支付、支付宝' },
             receiptNo: { type: 'string', description: '小票编号' },
             items: {
-              type: 'array',
-              description: '【必填】商品列表，必须是数组格式。每个商品必须包含：name、amount、price、quantity。⚠️ 注意：amount=price×quantity',
+              type: ['array', 'string'],
+              description: '【必填】商品列表，支持数组或JSON字符串格式（某些Agent如Claude Code可能传递JSON字符串）。每个商品必须包含：name、amount、price、quantity。⚠️ 注意：amount=price×quantity。示例数组：[{"name":"苹果","amount":5.5,"price":5.5,"quantity":1}]',
               items: {
                 type: 'object',
                 properties: {

package/install.sh

@@ -1,268 +0,0 @@
-#!/bin/bash
-
-# 柴米记账 MCP Server 一键安装脚本
-# 支持 macOS 和 Linux
-# 用法: curl -fsSL https://chaihuo.io/install.sh | bash
-
-set -e
-
-# 颜色定义
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-# 配置
-INSTALL_DIR="$HOME/.chaihuo-mcp"
-WORKBUDDY_DIR="$HOME/WorkBuddy"
-PYTHON_VERSION="3.10"
-SCF_URL="https://1412172089-4wbwsop8pe.ap-shanghai.tencentscf.com"
-
-echo -e "${GREEN}=== 柴米记账 MCP Server 安装脚本 ===${NC}"
-echo ""
-
-# 检测操作系统
-OS="$(uname -s)"
-case "${OS}" in
-    Linux*)     PLATFORM=Linux;;
-    Darwin*)    PLATFORM=Mac;;
-    *)          PLATFORM="UNKNOWN:${OS}"
-esac
-
-echo -e "${YELLOW}检测到操作系统: ${PLATFORM}${NC}"
-
-# 检查并安装 Python 3.10+
-check_python() {
-    echo -e "${YELLOW}检查 Python 版本...${NC}"
-    
-    if command -v python3.10 &> /dev/null; then
-        PYTHON_CMD="python3.10"
-    elif command -v python3.11 &> /dev/null; then
-        PYTHON_CMD="python3.11"
-    elif command -v python3.12 &> /dev/null; then
-        PYTHON_CMD="python3.12"
-    elif command -v python3 &> /dev/null; then
-        PY_VERSION=$(python3 --version 2>&1 | awk '{print $2}' | cut -d. -f1,2)
-        if (( $(echo "$PY_VERSION >= 3.10" | bc -l) )); then
-            PYTHON_CMD="python3"
-        else
-            PYTHON_CMD=""
-        fi
-    else
-        PYTHON_CMD=""
-    fi
-    
-    if [ -z "$PYTHON_CMD" ]; then
-        echo -e "${RED}未检测到 Python 3.10+${NC}"
-        install_python
-    else
-        echo -e "${GREEN}找到 Python: $PYTHON_CMD${NC}"
-    fi
-}
-
-# 安装 Python 3.10
-install_python() {
-    echo -e "${YELLOW}正在安装 Python 3.10...${NC}"
-    
-    if [ "$PLATFORM" == "Mac" ]; then
-        # macOS
-        if command -v brew &> /dev/null; then
-            echo "使用 Homebrew 安装 Python 3.10..."
-            brew install python@3.10
-            PYTHON_CMD="/opt/homebrew/bin/python3.10"
-        else
-            echo -e "${RED}请先安装 Homebrew: https://brew.sh${NC}"
-            exit 1
-        fi
-    elif [ "$PLATFORM" == "Linux" ]; then
-        # Linux
-        if command -v apt-get &> /dev/null; then
-            echo "使用 apt 安装 Python 3.10..."
-            sudo apt-get update
-            sudo apt-get install -y python3.10 python3.10-venv python3.10-pip
-            PYTHON_CMD="python3.10"
-        elif command -v yum &> /dev/null; then
-            echo "使用 yum 安装 Python 3.10..."
-            sudo yum install -y python310
-            PYTHON_CMD="python3.10"
-        else
-            echo -e "${RED}不支持的 Linux 发行版，请手动安装 Python 3.10+${NC}"
-            exit 1
-        fi
-    else
-        echo -e "${RED}不支持的操作系统: ${PLATFORM}${NC}"
-        exit 1
-    fi
-}
-
-# 创建安装目录
-setup_install_dir() {
-    echo -e "${YELLOW}创建安装目录...${NC}"
-    
-    if [ -d "$INSTALL_DIR" ]; then
-        echo -e "${YELLOW}目录已存在，清理旧文件...${NC}"
-        rm -rf "$INSTALL_DIR"
-    fi
-    
-    mkdir -p "$INSTALL_DIR"
-    echo -e "${GREEN}安装目录: $INSTALL_DIR${NC}"
-}
-
-# 创建虚拟环境
-create_venv() {
-    echo -e "${YELLOW}创建 Python 虚拟环境...${NC}"
-    
-    $PYTHON_CMD -m venv "$INSTALL_DIR/venv"
-    source "$INSTALL_DIR/venv/bin/activate"
-    
-    echo -e "${GREEN}虚拟环境创建成功${NC}"
-}
-
-# 安装依赖
-install_dependencies() {
-    echo -e "${YELLOW}安装依赖...${NC}"
-    
-    pip install --upgrade pip
-    pip install fastmcp>=0.4.0 requests
-    
-    echo -e "${GREEN}依赖安装完成${NC}"
-}
-
-# 下载 MCP Server 文件
-download_server() {
-    echo -e "${YELLOW}下载 MCP Server...${NC}"
-    
-    # 复制本地文件（如果是本地安装）
-    if [ -f "server.py" ]; then
-        cp server.py "$INSTALL_DIR/"
-        echo -e "${GREEN}使用本地 server.py${NC}"
-    else
-        # 从远程下载
-        echo "从远程下载..."
-        curl -fsSL -o "$INSTALL_DIR/server.py" "https://raw.githubusercontent.com/chaihuo/mcp-server/main/server.py"
-        echo -e "${GREEN}下载完成${NC}"
-    fi
-}
-
-# 配置 WorkBuddy
-configure_workbuddy() {
-    echo -e "${YELLOW}配置 WorkBuddy...${NC}"
-    
-    if [ ! -d "$WORKBUDDY_DIR" ]; then
-        echo -e "${RED}未找到 WorkBuddy 目录: $WORKBUDDY_DIR${NC}"
-        echo "请确认 WorkBuddy 已安装，或手动配置 MCP"
-        return 1
-    fi
-    
-    # 创建 MCP 配置
-    mkdir -p "$WORKBUDDY_DIR/mcp"
-    
-    # 复制 server.py 到 WorkBuddy 目录
-    cp "$INSTALL_DIR/server.py" "$WORKBUDDY_DIR/mcp/chaihuo-server.py"
-    
-    # 创建配置文件
-    cat > "$WORKBUDDY_DIR/mcp_config.json" << EOF
-{
-  "mcpServers": {
-    "chaihuo": {
-      "command": "$INSTALL_DIR/venv/bin/python",
-      "args": ["$WORKBUDDY_DIR/mcp/chaihuo-server.py"],
-      "env": {
-        "SCF_URL": "$SCF_URL"
-      }
-    }
-  }
-}
-EOF
-    
-    echo -e "${GREEN}WorkBuddy 配置完成${NC}"
-    echo -e "${YELLOW}配置文件: $WORKBUDDY_DIR/mcp_config.json${NC}"
-}
-
-# 生成 JWT Secret
-generate_jwt_secret() {
-    echo -e "${YELLOW}生成 JWT Secret...${NC}"
-    
-    JWT_SECRET=$(openssl rand -base64 32)
-    
-    # 更新配置文件
-    cat > "$WORKBUDDY_DIR/mcp_config.json" << EOF
-{
-  "mcpServers": {
-    "chaihuo": {
-      "command": "$INSTALL_DIR/venv/bin/python",
-      "args": ["$WORKBUDDY_DIR/mcp/chaihuo-server.py"],
-      "env": {
-        "SCF_URL": "$SCF_URL",
-        "JWT_SECRET": "$JWT_SECRET"
-      }
-    }
-  }
-}
-EOF
-    
-    echo -e "${GREEN}JWT Secret 生成成功${NC}"
-    echo -e "${YELLOW}请保存以下密钥（用于生成用户 Token）:${NC}"
-    echo -e "${GREEN}$JWT_SECRET${NC}"
-}
-
-# 测试安装
-test_installation() {
-    echo -e "${YELLOW}测试安装...${NC}"
-    
-    source "$INSTALL_DIR/venv/bin/activate"
-    
-    if python -c "import fastmcp" 2>/dev/null; then
-        echo -e "${GREEN}✓ fastmcp 安装成功${NC}"
-    else
-        echo -e "${RED}✗ fastmcp 安装失败${NC}"
-        return 1
-    fi
-    
-    if [ -f "$INSTALL_DIR/server.py" ]; then
-        echo -e "${GREEN}✓ server.py 存在${NC}"
-    else
-        echo -e "${RED}✗ server.py 不存在${NC}"
-        return 1
-    fi
-    
-    echo -e "${GREEN}安装测试通过！${NC}"
-}
-
-# 打印完成信息
-print_finish() {
-    echo ""
-    echo -e "${GREEN}=== 安装完成！===${NC}"
-    echo ""
-    echo -e "${YELLOW}下一步操作:${NC}"
-    echo "1. 重启 WorkBuddy"
-    echo "2. 在 WorkBuddy 中测试记账功能"
-    echo ""
-    echo -e "${YELLOW}配置信息:${NC}"
-    echo "- 安装目录: $INSTALL_DIR"
-    echo "- 配置文件: $WORKBUDDY_DIR/mcp_config.json"
-    echo "- SCF 地址: $SCF_URL"
-    echo ""
-    echo -e "${YELLOW}如需卸载，运行:${NC}"
-    echo "rm -rf $INSTALL_DIR"
-    echo ""
-}
-
-# 主流程
-main() {
-    echo -e "${GREEN}开始安装柴米记账 MCP Server...${NC}"
-    echo ""
-    
-    check_python
-    setup_install_dir
-    create_venv
-    install_dependencies
-    download_server
-    configure_workbuddy
-    generate_jwt_secret
-    test_installation
-    print_finish
-}
-
-# 运行主流程
-main