가정용 약품 관리 시스템 (Happy MedBox)

3단계 소프트웨어 스캐폴딩: 위챗 미니프로그램 + Node/SQLite 백엔드 + MCP 서버 + A2A 알림 에이전트. 핵심 전체 프로세스: 촬영 인식 → 데이터베이스 기록 → 정기적 유효기간 스캔 → MCP 데이터 인터페이스 제공 → A2A 알림 트리거 → 미니프로그램 알림 및 제안 표시.

기술 스택: 백엔드와 미니프로그램 모두 네이티브/제로 외부 의존성으로 구현(Node 22 내장 http / node:sqlite / node:test), 오프라인에서 node로 실행 및 테스트 가능, npm install 불필요.

디렉토리 구조

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

빠른 시작

1. 백엔드 + A2A 시작(기본 포트 3000 / 4100 / 4200)

cd happy-medbox
node src/index.js

시작 후:

• 미니프로그램 REST 연동: http://localhost:3000

• 알림 에이전트(AgentCard / 스캔 트리거): http://localhost:4100

• 사용자 에이전트 수신함: http://localhost:4200

환경 변수: API_PORT / REMINDER_PORT / USER_PORT / WARNING_DAYS(기본 30) / REMINDER_INTERVAL_MS(기본 60000) / MEDBOX_DB(기본 data/medbox.db, 메모리 DB는 :memory: 사용).

2. 테스트 실행(19개 항목, 전부 통과)

node --test

3. MCP 서버 단독 실행(AI 어시스턴트 stdio 호출용)

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. 미니프로그램 열기

위챗 개발자 도구로 miniprogram/ 디렉토리 가져오기(appid는 이미 touristappid로 설정되어 게스트 모드에서 바로 미리보기 가능). 실제 기기 디버깅 시 miniprogram/app.js의 baseUrl을 컴퓨터 LAN IP(예: http://192.168.x.x:3000)로 변경하고, 개발자 도구에서 "합법적 도메인 검증 안 함"을 체크.

핵심 프로세스 설명

• 촬영 인식: capture 페이지 wx.chooseMedia → POST /api/ocr → 현재 Mock 구조화된 필드(이름/규격/생산일/유효기간) 반환, 사용자 확인 후 POST /api/medicines로 DB 저장.

• 카운트다운 유효기간: 백엔드 expiry.js가 당일 기준 실시간으로 남은 일수와 상태(safe/warning/expired) 계산; 미니프로그램 홈페이지와 상세 페이지에 표시.

• 정기 스캔 + A2A 푸시: a2a-server.js의 알림 에이전트가 간격에 따라 유효기간 임박 약품 스캔 → reminders 테이블에 기록 및 A2A Task 캡슐화 → HTTP로 사용자 에이전트 /tasks에 푸시(크로스 에이전트 메시지 전달) → 미니프로그램 reminder 페이지에서 폴링하여 표시, 읽음 표시 가능.

• MCP 데이터 인터페이스: AI 어시스턴트가 stdio JSON-RPC를 통해 6개 도구 호출, 필요에 따라 약품/인식/유효기간 계산/복용 제안 검색.

프로덕션 교체 제안(인터페이스 계약 불변)

• 데이터베이스: node:sqlite → better-sqlite3(더 빠름, 동기식).

• MCP: src/mcp-server.js 자체 구현 JSON-RPC → 공식 @modelcontextprotocol/sdk.

• REST: 내장 http → Express/Fastify.

• OCR: ocr.js의 Mock 분기 → Tencent Cloud 일반 인쇄체 OCR 또는 위챗 OCR 플러그인 연동(키/자격증 필요).

알려진 경계(MVP 범위)

• 알림 채널은 먼저 미니프로그램 내 폴링 사용, 위챗 구독 메시지 인터페이스는 남겨둠.

• 지식 베이스는 내장 소량 샘플, 관리자 백엔드는 추후 구현(P2).

• 계정 시스템 없음, 단일 가정 로컬 식별(P2 다중 기기 클라우드 동기화).