# 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 全文搜尋；目前尚未加入向量語意搜尋

## 使用者流程

```text
碰 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 架構

```text
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 登入。

```bash
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：

```bash
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/SPEC.md)，架構見 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。

## 驗證

```bash
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。