Business Card MCP

AI-native, selbst hostbare private Visitenkarten-Bibliothek. Benutzer laden Visitenkarten in ChatGPT hoch, die von einem vorhandenen multimodalen Modell erkannt und bestätigt werden; das Remote MCP übernimmt Validierung, privaten Speicher, Suche, Änderung, Archivierung und Export, ohne zusätzliche Modell-APIs aufzurufen.

Funktionen

• ChatGPT Remote MCP: Visitenkarten erstellen, suchen, lesen, aktualisieren, archivieren und exportieren

• Private Verwaltungswebsite: Login mit selbst festgelegtem Passwort, Kartenwand/Listenansicht, geschützte Thumbnails

• D1 FTS5: Suche nach Name, Firma, Position, Telefon, E-Mail, Adresse, Tags, Anlass und Notizen

• R2: Private Markdown- und 480px-WebP-Thumbnails

• KV: Pro Benutzer unabhängiger bc_-Connector-Key

• Nach dem Schreiben wird eine klickbare Visitenkarten-Bestätigungsseite zurückgegeben

• Thumbnail ist ein Pflichtfeld beim Erstellen von Visitenkarten, um Datensätze ohne Bild zu vermeiden

Derzeit handelt es sich um eine Stichwort-Volltextsuche, nicht um Embedding-/Vektor-Semantiksuche.

Related MCP server: DuckPond MCP Server

Architektur

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

Originale Visitenkartenbilder werden standardmäßig nicht gespeichert. Das GitHub-Repository enthält nur Code, Migrationen und synthetische Testdaten, keine Benutzerkontakte.

MCP Tools

Bereitstellungsanforderungen

• Node.js 20+

• Cloudflare-Konto

• Wrangler CLI, angemeldet beim richtigen Cloudflare-Konto

Bereitstellung

1. Installation und lokale Einrichtung

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

wrangler.jsonc wird mit dem Repository als Nullwert-Platzhalterversion geliefert (der SmallGreen-Standard erfordert statisch bestimmbare Ressourcendeklarationen); im nächsten Schritt werden die echten IDs eingetragen. Nach dem Ausfüllen wird git update-index --skip-worktree wrangler.jsonc empfohlen, um zu vermeiden, dass echte IDs committet werden. public/config.js wird von Git ignoriert; die Web-Authentifizierung benötigt keine Frontend-Konfiguration.

2. Cloudflare-Ressourcen erstellen

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

Trage die von Cloudflare zurückgegebenen Account-, D1- und KV-IDs in wrangler.jsonc ein und konfiguriere:

• PUBLIC_BASE_URL

• R2-Bucket-Name

Lege anschließend das selbst festgelegte Passwort für den Web-Login fest. Das Passwort läuft nur über Wrangler-Secrets und wird nicht in wrangler.jsonc geschrieben:

npx wrangler secret put WEB_PASSWORD

CF_ACCESS_TEAM_DOMAIN und CF_ACCESS_AUD können standardmäßig leer bleiben; leer bedeutet, dass die Website Passwort-Login verwendet, ohne Kartenbindung.

3. Optionale Erweiterung: Cloudflare Access E-Mail-OTP

Konfiguriere diesen Abschnitt nur, wenn Cloudflare am Edge zuerst eine E-Mail-One-Time-PIN-Prüfung durchführen soll. Das Zero-Trust-Onboarding kann eine Kreditkartenbindung verlangen; der kostenlose Plan selbst kostet $0.

1. Erstelle in Cloudflare Zero Trust eine self-hosted Access-Anwendung, die die Domain dieses Workers schützt.

2. Aktiviere One-Time PIN als Anmeldemethode und beschränke die Anmeldeberechtigten per E-Mail- oder E-Mail-Domain-Policy.

3. Stelle sicher, dass die Browser-UI und /api/* im Access-Schutzbereich liegen.

4. Befreie den Pfad /mcp von der Access-Anmeldeanforderung, z. B. per path-based Bypass-Policy oder durch Aufteilung in Pfadregeln ohne Access. /mcp wird weiterhin über den bc_-MCP-Key authentifiziert; ChatGPT/Claude senden keine Cloudflare-Access-Cookies.

5. Trage das Audience-Tag der Access-Anwendung in CF_ACCESS_AUD und die Zero-Trust-Team-Domain in CF_ACCESS_TEAM_DOMAIN ein und stelle erneut bereit. Danach werden Web-Anfragen, die Access passieren, automatisch durchgelassen, ohne nach dem selbst festgelegten Passwort zu fragen.

4. Migration, Tests und Bereitstellung

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

5. ChatGPT verbinden

1. Öffne die bereitgestellte Website und gib das mit WEB_PASSWORD festgelegte Passwort ein; bei Cloudflare-Access-Upgrade erfolgt die Verifizierung per E-Mail-One-Time-PIN.

2. Generiere den Visitenkarten-MCP-Key.

3. Kopiere die vollständige Connector-URL; die URL enthält den Key und gilt als Passwort.

4. Füge im ChatGPT-Entwicklermodus ein Remote-MCP hinzu.

5. Teste nach dem Scannen der Tools mit „Suche mit dem Visitenkarten-MCP nach jemandem“.

Lokale Entwicklung

npm run migrate:local
npm run dev

Health-Check: GET /healthz

Remote MCP: POST /mcp

Sicherheit und Datenschutz

• Alle Visitenkartenabfragen sind auf den per Passwort angemeldeten owner, die Cloudflare-Access-sub oder den MCP-Key-Inhaber beschränkt.

• Der R2-Bucket bleibt privat; Thumbnails werden über eine login-geschützte API bereitgestellt.

• Das MCP akzeptiert sowohl Bearer-Tokens als auch Connector-URL-Query-Tokens.

• Der vollständige Key wird nur beim Erstellen angezeigt; einzelne Widerrufe werden unterstützt.

• Commite nicht .env, .dev.vars, wrangler.jsonc oder public/config.js.

Sicherheitsprobleme bitte gemäß SECURITY.md privat melden, keine öffentlichen Issues erstellen.

Verifizierung

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

Das Projekt verfügt derzeit über Unit-, MCP-Protokoll-, Web-API-, Berechtigungs-, Speicher- und UI-Vertragstests; die Coverage-Schwellenwerte liegen bei 80 % für Lines/Functions/Statements und 75 % für Branches.

Bekannte Einschränkungen

• Vektor-Semantiksuche ist noch nicht verfügbar.

• Für bestehende Visitenkarten ohne Bild gibt es noch keine Schnittstelle zum Nachreichen von Bildern; für neue Daten ist das Thumbnail bereits Pflicht.

• Dauerhaftes Löschen ist standardmäßig nicht verfügbar; Archivierung wird verwendet, um versehentliches Löschen zu vermeiden.

Lizenz

Apache-2.0. Siehe LICENSE.