不过期助手 MCP Server

物品管理小程序的 MCP Server，支持智能体（Claude、Cursor、Cline、小龙虾等）通过 API Key 管理物品。

✨ 功能特性

🛠️ 可用工具

工具	描述	参数
login	使用 API Key 登录，获取认证 Token	apiKey
add_item	添加新物品，记录名称、位置、过期日期等	name, locationName, expiryDate, ...
scan_add_item	通过扫描条形码添加物品，自动识别信息	barcode, locationName, ...
query_items	查询物品列表，支持关键词、位置、状态筛选	keyword, locationName, status, ...
get_item	获取物品详细信息	id

🎯 核心特性

• 🔐 API Key 认证 - 安全的身份验证机制
• 📦 类型安全 - 完整的 TypeScript 类型定义
• 🔍 智能搜索 - 支持关键词、位置、状态等多维度查询
• 📱 条形码扫描 - 自动识别商品信息
• 🌐 通用兼容 - 支持 Claude Desktop、Cursor、Cline、小龙虾等

📦 安装

方式一：全局安装（推荐）

npm install -g baozhibao-mcp-server
# 或
npx baozhibao-mcp-server

方式二：本地安装

git clone https://github.com/fawaikuangtuzhangfei/baozhibao-mcp-server.git
cd baozhibao-mcp-server
npm install
npm run build

🚀 快速开始（从零配置）

第一步：获取 API Key

1. 打开微信，搜索「不过期助手」小程序
2. 进入小程序后，点击「我的」->「设置」
3. 找到「API Key 管理」，点击「创建 API Key」
4. 输入名称（如 "Claude Code"），点击确认
5. 立即复制 生成的 API Key（格式：sk_xxx），只会显示一次！

第二步：安装 MCP Server

方式 A：全局安装（推荐）

npm install -g baozhibao-mcp-server

方式 B：从源码构建

git clone https://github.com/fawaikuangtuzhangfei/baozhibao-mcp-server.git
cd baozhibao-mcp-server
npm install
npm run build

第三步：配置 Claude Code

1. 找到配置文件位置：

   • Windows: C:\Users\<你的用户名>\.claude\settings.json
   • macOS/Linux: ~/.claude/settings.json

2. 如果文件不存在，手动创建

3. 添加 MCP Server 配置：

{
  "mcpServers": {
    "baozhibao": {
      "command": "node",
      "args": [
        "D:/path/to/baozhibao-mcp-server/dist/index.js"
      ],
      "env": {
        "BAOZHIBAO_API_URL": "https://h1b.site/out_date",
        "BAOZHIBAO_API_KEY": "sk_xxx"
      }
    }
  }
}

注意：

• args 填你实际安装的路径
• BAOZHIBAO_API_URL 填后端服务地址
• BAOZHIBAO_API_KEY 填第一步获取的密钥

第四步：重启 Claude Code

配置完成后，重启 Claude Code 使配置生效。

第五步：验证配置

在 Claude Code 中输入：

帮我看看我有哪些物品

如果返回你的物品列表，说明配置成功！

---

⚙️ 详细配置

环境变量

创建 .env 文件或直接在 MCP 配置的 env 中设置：

# API 服务地址（必填）
BAOZHIBAO_API_URL=https://h1b.site/out_date

# API Key（可选，用于默认登录）
BAOZHIBAO_API_KEY=sk_xxx

参考 .env.example 文件：

cp .env.example .env

🖥️ 其他客户端配置

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)：

{
  "mcpServers": {
    "baozhibao": {
      "command": "node",
      "args": [
        "/path/to/baozhibao-mcp-server/dist/index.js"
      ],
      "env": {
        "BAOZHIBAO_API_URL": "https://h1b.site/out_date",
        "BAOZHIBAO_API_KEY": "sk_xxx"
      }
    }
  }
}

在 Claude Code 中配置

编辑 ~/.claude/settings.json：

{
  "mcpServers": {
    "baozhibao": {
      "command": "node",
      "args": [
        "/path/to/baozhibao-mcp-server/dist/index.js"
      ],
      "env": {
        "BAOZHIBAO_API_URL": "https://h1b.site/out_date",
        "BAOZHIBAO_API_KEY": "sk_xxx"
      }
    }
  }
}

在 Cursor 中配置

编辑 Cursor 设置中的 MCP Servers 配置：

{
  "mcpServers": {
    "baozhibao": {
      "command": "node",
      "args": [
        "/path/to/baozhibao-mcp-server/dist/index.js"
      ],
      "env": {
        "BAOZHIBAO_API_URL": "https://h1b.site/out_date"
      }
    }
  }
}

在 Cline (VSCode) 中配置

在 VSCode 设置中搜索 cline.mcp.servers，添加：

{
  "baozhibao": {
    "command": "node",
    "args": [
      "/path/to/baozhibao-mcp-server/dist/index.js"
    ],
    "env": {
      "BAOZHIBAO_API_URL": "https://h1b.site/out_date"
    }
  }
}

在小龙虾中配置

1. 打开小龙虾设置
2. 添加 MCP Server
3. 输入配置：

{
  "mcpServers": {
    "baozhibao": {
      "command": "node",
      "args": [
        "/path/to/baozhibao-mcp-server/dist/index.js"
      ],
      "env": {
        "BAOZHIBAO_API_URL": "https://h1b.site/out_date"
      }
    }
  }
}

💬 使用示例

以下为真实对话效果，AI 会自动调用工具并以友好的格式呈现结果。

场景一：查询所有物品

用户: 帮我看看我有哪些物品

AI: 你一共有 28 件物品，按状态分类如下：

    ✅ 未过期（有效物品）
    | 物品               | 位置   | 数量 | 过期日期     |
    |--------------------|--------|------|-------------|
    | 苹果               | 冰箱   | 1    | 无保质期     |
    | 尖叫多肽型运动饮料 | 我的家 | 4    | 2026-04-29  |
    | 红枣桂圆枸杞茶     | 我的家 | 1    | 2026-09-08  |
    | 洁柔纸面巾         | 我的家 | 6    | 2028-11-29  |

    ⚠️ 已过期（需注意）
    | 物品         | 数量 | 过期日期     |
    |--------------|------|-------------|
    | 三麟椰子水   | 2    | 2025-06-08  |

    📌 提醒：三麟椰子水已过期将近10个月了，建议处理掉。

AI 会自动分页查询、按状态分类汇总，并主动提醒过期物品。

场景二：按关键词搜索

用户: 我的牛奶放哪了？

AI: 找到 2 件牛奶相关物品：
    - 牛奶 x 2，位于未设置，过期日期 2025-12-31（已过期88天）

    ⚠️ 这批牛奶已经过期了，建议检查是否还能使用。

场景三：添加物品

用户: 帮我记录一下，牛奶放在冰箱里，5月1号过期

AI: ✅ 已添加：牛奶
    - 存放位置：冰箱
    - 过期日期：2025-05-01
    - 数量：1

场景四：扫码添加

用户: 帮我扫码添加这个商品，条形码是 6920459950180，放冰箱，明年3月过期

AI: ✅ 已识别并添加商品
    - 商品名称：蒙牛纯牛奶
    - 存放位置：冰箱
    - 过期日期：2026-03-31
    - 数量：1

场景五：按状态筛选

用户: 有哪些快过期的东西？

AI: 查询到以下临期物品：
    | 物品               | 位置   | 剩余天数 | 过期日期    |
    |--------------------|--------|---------|------------|
    | 尖叫多肽型运动饮料 | 我的家 | 30天    | 2026-04-29 |

    📌 运动饮料还有1个月过期，建议尽快饮用。

场景六：查看物品详情

用户: 帮我看看牛奶的详细信息

AI: 物品详细信息：
    - 名称：牛奶
    - 存放位置：未设置
    - 数量：2
    - 过期日期：2025-12-31
    - 状态：已过期（过期88天）

实用提示

• 分页加载：物品较多时 AI 会自动分页查询（每页 20 条）
• 智能分类：AI 会按"未过期/已过期/已消费"自动归类，不只是罗列数据
• 过期提醒：AI 会主动计算过期天数并给出建议
• 模糊匹配：搜索关键词支持物品名称、品牌等模糊匹配

🛠️ 开发

# 安装依赖
npm install

# 开发模式
npm run dev

# 编译 TypeScript
npm run build

# 监听模式编译
npm run watch

# 调试 MCP Server
npx @modelcontextprotocol/inspector npm run dev

🔑 获取 API Key

1. 打开「不过期助手」小程序
2. 进入「设置」->「API Key 管理」
3. 点击「创建 API Key」
4. 输入名称（如"小龙虾"）
5. 复制生成的 API Key（格式：sk_xxx）

📋 工具参数详解

login - 登录

参数	类型	必填	说明
apiKey	string	✅	API Key，格式为 sk_xxx

add_item - 添加物品

参数	类型	必填	说明
name	string	✅	物品名称
locationId	number	❌	存放位置 ID
locationName	string	❌	存放位置名称，如"冰箱"
expiryDate	string	❌	过期日期，格式 YYYY-MM-DD
quantity	number	❌	数量，默认 1
categoryId	number	❌	分类 ID
categoryName	string	❌	分类名称
description	string	❌	物品描述
brand	string	❌	品牌
specification	string	❌	规格
price	number	❌	价格
remark	string	❌	备注

scan_add_item - 扫码添加

参数	类型	必填	说明
barcode	string	✅	条形码
locationId	number	❌	存放位置 ID
locationName	string	❌	存放位置名称
quantity	number	❌	数量，默认 1
expiryDate	string	❌	过期日期

query_items - 查询物品

参数	类型	必填	说明
keyword	string	❌	搜索关键词
locationId	number	❌	存放位置 ID
locationName	string	❌	存放位置名称
status	number	❌	状态：0-未过期，1-已过期，2-已消费
isNearlyExpired	number	❌	是否临期：0-否，1-是
categoryId	number	❌	分类 ID
pageNum	number	❌	页码，默认 1
pageSize	number	❌	每页数量，默认 20

get_item - 获取详情

参数	类型	必填	说明
id	number	✅	物品 ID

🏗️ 项目结构

baozhibao-mcp-server/
├── src/
│   ├── api/
│   │   └── client.ts          # API 客户端
│   ├── tools/
│   │   ├── login.ts           # 登录工具
│   │   ├── addItem.ts         # 添加物品工具
│   │   ├── scanAddItem.ts     # 扫码添加工具
│   │   ├── queryItems.ts      # 查询物品工具
│   │   └── getItem.ts         # 获取详情工具
│   ├── types/
│   │   └── index.ts           # 类型定义
│   ├── index.ts               # 入口文件
│   └── server.ts              # MCP Server 主逻辑
├── dist/                      # 编译输出
├── .env.example               # 环境变量示例
├── package.json
├── tsconfig.json
└── README.md

⚠️ 注意事项

• 🔑 API Key 只在创建时显示一次，请妥善保存
• 🚫 不要将 API Key 提交到代码仓库
• 🔄 如果 API Key 泄露，请立即在小程序中删除并重新创建
• 📝 所有日志输出到 stderr，数据通信通过 stdout

📌 当前限制

仅支持个人模式

当前 MCP Server 仅支持个人模式，所有物品操作均以当前登录用户的个人身份进行（familyId = null），不支持家庭相关的功能。

不受影响的功能：

• ✅ 添加/查询/详情查看个人物品
• ✅ 扫码添加个人物品
• ✅ 个人位置和分类管理

暂不支持的功能：

• ❌ 家庭物品管理（共享物品、家庭内私有物品）
• ❌ 家庭成员相关操作（查看成员、邀请、移除等）
• ❌ 按家庭成员筛选物品
• ❌ 个人与家庭数据同步
• ❌ 家庭位置/分类管理

后端 API 已具备完整的家庭功能支持（17 个接口），后续版本会逐步接入。

🤝 贡献

欢迎贡献代码、报告问题或提出建议！

请查看 CONTRIBUTING.md 了解详情。

📄 许可证

MIT License

🔗 相关链接

• MCP 官方文档
• 不过期助手小程序
• 问题反馈

📞 联系方式

• 作者: fawaikuangtuzhangfei
• GitHub: @fawaikuangtuzhangfei

---

如果这个项目对你有帮助，请给个 ⭐️ Star！