sharebill-mcp-server

Model Context Protocol (MCP) server cho ShareBill — cho phép AI clients (Claude Desktop, Cursor, custom agents) tương tác với data chia tiền nhóm của bạn qua natural language.

Status

Phase 3 (full feature set) — 13 tools + 4 resources + 2 prompts:

• 1 health, 6 read, 5 write tools, 1 advanced (scan_bill)
• 4 URI-addressable resources (sharebill://plans, sharebill://insights, ...)
• 2 slash-prompts (/analyze-spending, /quick-expense)

Xem spec: documents/feature/mcp-server-spec.md.

Cài đặt

1. Tạo Personal Access Token (PAT)

1. Mở ShareBill web app → đăng nhập
2. Vào /profile/api-tokens
3. Click "Tạo token mới", nhập tên (vd "Claude Desktop laptop"), chọn thời hạn
4. Sao chép plaintext ngay (chỉ hiển thị 1 lần) — định dạng sbpat_xxxxx...

2. Cài MCP server

Cách A: Via npx (recommended — không cần clone repo)

npx -y sharebill-mcp-server

npx tự tải package mới nhất từ npm registry và chạy — giống npx @playwright/mcp / uvx plane-mcp-server. Pin version nếu cần: npx -y [email protected].

Cách B: Build local (cho dev hoặc chạy từ source)

cd apps/mcp-server
pnpm install
pnpm build

Đường dẫn binary: apps/mcp-server/dist/index.js

Release lên npm: bump version trong package.json, push tag mcp-server-v* → CI (.github/workflows/mcp-publish.yml) tự publish (cần secret NPM_TOKEN).

3. Cấu hình Claude Desktop

Mở file config Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Thêm (cách A — npx):

{
  "mcpServers": {
    "sharebill": {
      "command": "npx",
      "args": ["-y", "sharebill-mcp-server"],
      "env": {
        "SHAREBILL_API_URL": "https://your-sharebill.com",
        "SHAREBILL_PAT": "sbpat_your_token_here"
      }
    }
  }
}

Hoặc cách B — chạy từ build local:

{
  "mcpServers": {
    "sharebill": {
      "command": "node",
      "args": ["/absolute/path/to/apps/mcp-server/dist/index.js"],
      "env": {
        "SHAREBILL_API_URL": "http://localhost:8080",
        "SHAREBILL_PAT": "sbpat_your_token_here"
      }
    }
  }
}

SHAREBILL_API_URL là URL origin của BE (KHÔNG có /api/v1 ở cuối — server tự append). Restart hoàn toàn Claude Desktop sau khi sửa config.

4. Test

Trong chat Claude Desktop:

Use the sharebill_health tool

Kết quả mong đợi:

OK — đã xác thực thành công.
User: <tên của bạn>
API: http://localhost:8080

Tools available (Phase 3)

Read tools (7)

| Tool | Mô tả | Endpoint chính | |------|-------|----------------| | sharebill_health | Kiểm tra MCP server + PAT validity | GET /users/me | | list_plans | Liệt kê plans (filter status, limit) | GET /plans | | get_plan | Chi tiết plan: info + members + 20 expenses + debts | 4 calls song song | | list_expenses | Expenses của plan (filter from, to, categoryId, paidById, limit) | GET /plans/{id}/expenses | | get_debt_summary | Bảng nợ (pending/waiting/settled + balances) | GET /plans/{id}/debts | | list_friends | Bạn bè + tổng nợ (filter local theo search) | GET /friends | | get_insights | Thống kê chi tiêu theo tháng/danh mục/plan | GET /users/me/insights |

Write tools (5) — đều có dryRun?: boolean

| Tool | Mô tả | Endpoint chính | |------|-------|----------------| | create_plan | Tạo plan mới (template, categories, budget) | POST /plans | | create_expense | Tạo expense (5 splitType, validation client-side) | POST /plans/{id}/expenses | | add_member | Thêm member (guest hoặc link userId) | POST /plans/{id}/members | | confirm_settlement | Xác nhận đã nhận tiền cho 1 settlement | POST /settlements/{id}/confirm | | simplify_debts | Tối ưu công nợ (gom thành ít lượt chuyển) | POST /plans/{id}/debts/simplify |

Dry-run pattern (chống AI bấm nhầm)

Mọi write tool support dryRun: true — KHÔNG persist, chỉ trả preview với payload sẽ gửi. AI workflow chuẩn:

1. AI gọi create_expense({ ..., dryRun: true }) → preview
2. AI hiển thị preview cho user: "Sẽ tạo expense X cho 5 người, OK?"
3. User confirm → AI gọi lại với dryRun: false

Tool description đã enforce pattern này; AI client như Claude tuân thủ.

Advanced tool (1)

| Tool | Mô tả | |------|-------| | scan_bill | Parse text bill (paste / OCR result) bằng heuristic regex → trả parsed (description, items, total, confidence) + suggestedExpense payload sẵn cho create_expense. Lưu ý: BE chỉ scan IMAGE qua FE; MCP tool dùng heuristic client-side. |

Resources (4)

URI-addressable read-only data, AI client có thể attach vào conversation context:

| URI | Mô tả | |-----|-------| | sharebill://plans | List all ACTIVE plans (summary) | | sharebill://plans/{planId} | Plan detail (members + categories + invite info) | | sharebill://plans/{planId}/debts | Bảng nợ của plan | | sharebill://insights | Insights tháng hiện tại |

Prompts (2 — slash commands)

Trong Claude Desktop, gõ / để thấy:

| Prompt | Args | Mô tả | |--------|------|-------| | /analyze-spending | months? (1, 3, 6, 12) | AI fetch insights, phân tích pattern, suggest tối ưu | | /quick-expense | planId?, amount? | AI guided flow: hỏi info từng bước → dryRun → confirm → persist |

Ví dụ query

"List my plans" → list_plans
"Tôi nợ ai bao nhiêu trong plan X?" → get_debt_summary
"Thêm 280k bữa lẩu Đà Lạt cho 5 người chia đều" → list_plans + get_plan + create_expense(dryRun=true) → confirm → create_expense(dryRun=false)
"Tối ưu công nợ trip Đà Lạt" → simplify_debts(dryRun=true) → confirm → simplify_debts(dryRun=false)
"Tạo plan mới Phú Quốc 5 ngày, ngân sách 10 triệu" → create_plan
"Tôi đã nhận tiền từ An rồi" → get_debt_summary → confirm_settlement
"Quán Lẩu Cô Tư - Lẩu thái 280k - Bia 120k - Tổng 400k" → scan_bill → create_expense
/analyze-spending 3 → AI fetch + analyze 3 tháng
/quick-expense → AI hỏi step-by-step

Troubleshooting

Invalid environment configuration — kiểm tra SHAREBILL_API_URL (URL hợp lệ) và SHAREBILL_PAT (bắt đầu bằng sbpat_).

UNAUTHORIZED / Lỗi (UNAUTHORIZED) — token expired hoặc đã revoke. Tạo token mới ở /profile/api-tokens.

Network error / connection refused — BE chưa chạy hoặc URL sai. Kiểm tra curl $SHAREBILL_API_URL/api/v1/health từ terminal.

Development

pnpm dev       # tsup watch mode
pnpm test      # vitest
pnpm typecheck # tsc --noEmit

Docs

Spec đầy đủ: documents/feature/mcp-server-spec.md.