Happy MedBox Management System (Happy MedBox)

Three-terminal software scaffold: WeChat Mini Program + Node/SQLite Backend + MCP Server + A2A Reminder Agent. Core full workflow: Photo capture and recognition → Write to database → Scheduled expiration scanning → MCP provides data interface → A2A triggers reminders → Mini program displays reminders and suggestions.

Technology stack: Backend and mini program are implemented with native/zero external dependencies (Node 22 built-in http / node:sqlite / node:test), can be run and tested offline with node, no npm install required.

Directory Structure

happy-medbox/
├─ prd.md / architecture.md      # 产品需求 + 系统架构（团队 SOP 产出）
├─ package.json / README.md
├─ src/                          # 后端：API + 数据库 + MCP + A2A
│  ├─ db.js          # SQLite 连接与建表（node:sqlite）
│  ├─ expiry.js      # 过期计算（纯函数，可单测）
│  ├─ ocr.js         # OCR 接口 + Mock（预留腾讯云/微信 OCR）
│  ├─ repository.js  # 数据访问层 CRUD
│  ├─ mcp-server.js  # MCP 工具 + JSON-RPC（stdio）
│  ├─ server.js      # REST API（小程序对接）
│  ├─ a2a-server.js  # 提醒代理 + 用户代理（双端口，A2A 推送）
│  ├─ seed.js        # 样例数据
│  └─ index.js       # 编排入口（启动 + 定时扫描）
├─ miniprogram/                  # 微信小程序端（原生）
│  ├─ pages/{index,capture,detail,knowledge,reminder}/
│  └─ utils/{api,ocr,format}.js
└─ test/                         # 单元测试（expiry/db/mcp/a2a）

Related MCP server: Medical MCP Server

Quick Start

1. Start Backend + A2A (Default Ports 3000 / 4100 / 4200)

cd happy-medbox
node src/index.js

After starting:

• Mini program connects to REST: http://localhost:3000

• Reminder agent (AgentCard / trigger scanning): http://localhost:4100

• User agent inbox: http://localhost:4200

Environment variables: API_PORT / REMINDER_PORT / USER_PORT / WARNING_DAYS (default 30) / REMINDER_INTERVAL_MS (default 60000) / MEDBOX_DB (default data/medbox.db, use :memory: for in-memory database).

2. Run Tests (19 items, all pass)

node --test

3. Start MCP Server Independently (for AI assistant stdio calls)

node src/mcp-server.js
# 支持 initialize / tools/list / tools/call
# 工具：query_medicines / recognize_medicine_image / compute_expiry /
#       get_medication_advice / add_medicine / list_expiring

4. Open the Mini Program

Use WeChat Developer Tools to import the miniprogram/ directory (the appid is set to touristappid for guest mode, allowing direct preview). For real device debugging, change the baseUrl in miniprogram/app.js to your computer's LAN IP (e.g., http://192.168.x.x:3000), and check "Do not verify valid domain names" in the developer tools.

Key Process Description

• Photo Recognition: capture page wx.chooseMedia → POST /api/ocr → Currently returns Mock structured fields (name/specification/production date/expiration date), user reviews then POST /api/medicines to store.

• Countdown to Expiration: Backend expiry.js calculates remaining days and status (safe/warning/expired) in real-time based on the current day; displayed on the mini program's home page and detail page.

• Scheduled Scanning + A2A Push: The reminder agent in a2a-server.js scans for soon-to-expire medicines at intervals → writes to the reminders table and encapsulates an A2A Task → HTTP pushes to the user agent /tasks (cross-agent message flow) → the mini program's reminder page polls for display, allowing marking as read.

• MCP Data Interface: AI assistant calls six tools via stdio JSON-RPC to query medicines / recognize / calculate expiration dates / retrieve medication suggestions as needed.

Production Replacement Suggestions (Interface Contract Unchanged)

• Database: node:sqlite → better-sqlite3 (faster, synchronous).

• MCP: src/mcp-server.js self-implemented JSON-RPC → official @modelcontextprotocol/sdk.

• REST: Built-in http → Express/Fastify.

• OCR: Mock branch in ocr.js → Integrate Tencent Cloud Universal Print OCR or WeChat OCR plugin (requires key/qualification).

Known Boundaries (MVP Scope)

• Reminder channel uses in-app polling for now; WeChat subscription message interface is reserved.

• Knowledge base contains a few built-in examples; admin backend is pending (P2).

• No account system, single-family local identifier (P2 for multi-device cloud sync).