Business Card MCP

AI-native、可自架的私人名片庫。使用者在 ChatGPT 上傳名片，由既有多模態模型辨識並確認；Remote MCP 負責驗證、私人儲存、搜尋、修改、封存與匯出，不額外呼叫模型 API。

功能

• ChatGPT Remote MCP：建立、搜尋、讀取、更新、封存及匯出名片
• 私人管理網站：Google 登入、卡片牆／條列檢視、受保護縮圖
• D1 FTS5：姓名、公司、職稱、電話、Email、地址、標籤、場合及備註搜尋
• R2：私人 Markdown 與 480px WebP 縮圖
• KV：每位使用者獨立的 bc_ Connector Key
• 寫入後回傳可點擊的名片確認頁
• 縮圖為建立名片的必填欄位，避免產生無圖資料

目前是關鍵字全文搜尋，不是 embedding／向量語意搜尋。

架構

ChatGPT / Claude
       │ Remote MCP
       ▼
Cloudflare Worker ── Firebase ID token 驗證
       ├── D1：聯絡人與 FTS5
       ├── R2：Markdown、WebP 縮圖
       ├── KV：MCP Key
       └── Static Assets：私人管理網站

原始名片圖片預設不保存。GitHub repo 只包含程式碼、migration 與合成測試資料，不包含任何使用者聯絡人。

MCP Tools

Tool	用途
create_contact	寫入使用者已確認的資料、Markdown 與必要縮圖
search_contacts	搜尋自己的名片
get_contact	取得完整名片與確認頁連結
update_contact	更新欄位、標籤與備註
archive_contact	封存名片，不永久刪除
export_contact	匯出 Markdown 或 vCard

部署需求

• Node.js 20+
• Cloudflare 帳號
• Firebase 專案，啟用 Google 登入
• Wrangler CLI 登入正確的 Cloudflare 帳號

部署

1. 安裝與建立本機設定

npm install
cp wrangler.example.jsonc wrangler.jsonc
cp public/config.example.js public/config.js

wrangler.jsonc 與 public/config.js 已被 Git 忽略，請勿提交 production IDs 或 Firebase 設定。

2. 建立 Cloudflare 資源

npx wrangler d1 create business-card-mcp
npx wrangler r2 bucket create business-card-mcp-assets
npx wrangler kv namespace create CARD_KEYS

把 Cloudflare 回傳的 account、D1 與 KV ID 填入 wrangler.jsonc，並設定：

• PUBLIC_BASE_URL
• FIREBASE_PROJECT_ID
• R2 bucket 名稱

再把 Firebase Web App 的 apiKey、authDomain、projectId 填入 public/config.js。

3. Migration、測試與部署

npx wrangler types
npm run typecheck
npm test
npx wrangler d1 migrations apply business-card-mcp --remote
npx wrangler deploy

部署後，把 Workers 網域加入 Firebase Authentication 的 Authorized domains。

4. 連接 ChatGPT

1. 開啟部署後的網站並以 Google 登入。
2. 產生名片 MCP Key。
3. 複製完整 Connector URL；URL 內含 Key，視同密碼。
4. 在 ChatGPT 開發人員模式新增 Remote MCP。
5. 掃描工具後，以「使用名片 MCP 搜尋某某人」測試。

本機開發

npm run migrate:local
npm run dev

健康檢查：GET /healthz

Remote MCP：POST /mcp

安全與隱私

• 所有名片查詢都以 Firebase UID 或 MCP Key 擁有者限制。
• R2 bucket 維持私人；縮圖由登入保護的 API 提供。
• MCP 同時接受 Bearer token 與 Connector URL query token。
• 完整 Key 只在建立當下顯示，支援個別撤銷。
• 請勿提交 .env、.dev.vars、wrangler.jsonc 或 public/config.js。

安全問題請依 SECURITY.md 私下回報，不要建立公開 Issue。

驗證

npm test
npm run typecheck
npm audit --omit=dev

專案目前有單元、MCP protocol、Web API、權限、儲存及 UI 合約測試；coverage threshold 為 lines/functions/statements 80%、branches 75%。

已知限制

• 尚未提供向量語意搜尋。
• 既有無圖名片尚未提供補圖介面；新資料已強制縮圖必填。
• 永久刪除預設不開放，使用封存避免誤刪。

License

Apache-2.0。詳見 LICENSE。