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／向量語意搜尋。

Related MCP server: MemHeaven

架構

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

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

MCP Tools

部署需求

• 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。