TapCard MCP

一套只依賴 Cloudflare 執行的開源 NFC／QR 電子名片與私人 AI 名片庫。每位使用者 fork 一份，部署到自己的 Cloudflare 帳號；公開頁呈現自己的簡介，登入後的卡片牆管理收到的名片，Remote MCP 讓 ChatGPT 等 AI 工具預覽、確認、匯入與搜尋。

目前可用功能

• 公開個人頁：/p/:slug
• 同一網址可寫入 NFC，也能產生 QR Code 截圖保存在手機
• 標準化 contact.json 與 vCard 下載
• 手機原生分享與「複製 AI 匯入指令」
• 私人管理後台：公開簡介表單、卡片牆／條列檢視、受保護縮圖
• Remote MCP：建立、搜尋、讀取、更新、封存及匯出名片
• URL 匯入：先 preview_contact_from_url，明確確認後才 import_contact_from_url
• 匯入 TapCard 時產生並保存名片縮圖，不建立無圖資料
• D1 FTS5 全文搜尋；目前尚未加入向量語意搜尋

使用者流程

碰 NFC／掃手機 QR／收到網址
              ↓
       公開個人簡介與電子名片
        ├─ 儲存 vCard
        ├─ 開啟社群連結
        └─ 分享到 AI 對話
              ↓
  preview_contact_from_url（只讀預覽）
              ↓ 使用者確認
  import_contact_from_url（寫入私人名片庫）
              ↓
       私人卡片牆與 MCP 搜尋

NFC 卡只寫入穩定 HTTPS 網址，例如 https://card.example.com/p/me。資料更新不需要重寫 NFC，QR Code 也使用同一網址。

Cloudflare-only 架構

NFC / QR / Browser / AI client
                 │
          Cloudflare Worker
          ├── Static Assets：UI
          ├── D1：公開簡介＋私人名片＋FTS
          ├── R2：私人 Markdown＋縮圖
          └── KV：可撤銷 MCP key

GitHub 只保存程式碼，不是執行期依賴。管理登入使用部署者設定的 ADMIN_TOKEN Worker Secret，不需要 Firebase、Netlify、傳統 CMS 或外部帳號服務。

部署

需求：Node.js 20+、GitHub 帳號、Cloudflare 帳號及 Wrangler 登入。

npm install
npx wrangler d1 create tapcard-mcp
npx wrangler r2 bucket create tapcard-mcp-assets
npx wrangler kv namespace create CARD_KEYS

將 CLI 回傳的 D1、R2、KV ID 填進已追蹤的 wrangler.jsonc，再設定只有部署者知道的管理憑證。請勿把實際 ID 的修改提交回公開 repo：

npx wrangler secret put ADMIN_TOKEN
npx wrangler d1 migrations apply tapcard-mcp --remote
npm test
npm run typecheck
npx wrangler deploy

部署完成後：

1. 開啟 /app，輸入 ADMIN_TOKEN。
2. 建立並發布自己的公開名片。
3. 將 /p/:slug 寫入 NFC，或在公開頁顯示／截圖 QR Code。
4. 在「MCP 連線」產生 Connector URL，加入支援 Remote MCP 的 AI 工具。

完整 MCP URL 含私人 key，請勿公開、截圖或提交到 GitHub。

MCP 工具

工具	行為
preview_contact_from_url	讀取公開 TapCard，顯示預覽，不寫入
import_contact_from_url	僅在 confirmed: true 時匯入並生成縮圖
create_contact	建立已確認且含 WebP 縮圖的名片
search_contacts	搜尋私人名片
get_contact	取得完整名片
update_contact	更新欄位、標籤與備註
archive_contact	可恢復式封存，不直接永久刪除
export_contact	匯出 Markdown 或 vCard

安全邊界

• 公開簡介和私人聯絡人使用不同資料表及不同 API。
• 私人 API 需要管理憑證；MCP 使用個別可撤銷 key。
• URL 匯入只接受符合 /p/:slug 的公開 HTTPS TapCard，阻擋本機、私有 IP、重新導向、非 JSON 與過大回應。
• 遠端資料一律當成不可信內容，不會當作 MCP 指令執行。
• 匯入是寫入動作，工具 schema 強制要求 confirmed: true。
• repo 僅含合成測試資料，不含任何真實名片或部署 ID。

完整契約見 docs/SPEC.md，架構見 docs/ARCHITECTURE.md。

驗證

npm test
npm run typecheck
npm audit --omit=dev
npx wrangler deploy --dry-run

Coverage 門檻：lines／functions／statements 80%，branches 75%。

License

Apache-2.0。