Business Card MCP

AIネイティブでセルフホスト可能なプライベート名刺ライブラリ。ユーザーがChatGPTで名刺をアップロードし、既存のマルチモーダルモデルが認識・確認します。Remote MCPが検証、プライベート保存、検索、変更、アーカイブ、エクスポートを担当し、追加のモデルAPI呼び出しは行いません。

機能

• ChatGPT Remote MCP：名刺の作成、検索、読み取り、更新、アーカイブ、エクスポート

• プライベート管理サイト：独自パスワードでのログイン、カードウォール／リスト表示、保護されたサムネイル

• D1 FTS5：氏名、会社、役職、電話、メール、住所、タグ、場面、備考の検索

• R2：プライベートMarkdownと480px WebPサムネイル

• KV：ユーザーごとに独立したbc_ Connector Key

• 書き込み後にクリック可能な名刺確認ページを返却

• サムネイルは名刺作成時の必須フィールドであり、画像のないデータを防ぐ

現在はキーワード全文検索であり、embedding／ベクトル意味検索ではありません。

Related MCP server: DuckPond MCP Server

アーキテクチャ

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

元の名刺画像はデフォルトでは保存されません。GitHubリポジトリにはコード、マイグレーション、合成テストデータのみが含まれ、ユーザーの連絡先は一切含まれません。

MCP Tools

デプロイ要件

• Node.js 20+

• Cloudflareアカウント

• Wrangler CLIで正しいCloudflareアカウントにログイン

デプロイ

1. インストールとローカル設定の作成

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

wrangler.jsoncはリポジトリにゼロ値プレースホルダー版として同梱されています（SmallGreen標準では静的に判定可能なリソース宣言が必要です）。次のステップで実際のIDを入力します。入力後はgit update-index --skip-worktree wrangler.jsoncを実行して、実際のIDがコミットされないようにすることをお勧めします。public/config.jsはGitで無視されており、Web認証にフロントエンド設定は不要です。

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

• R2 bucket名

次にWebログイン用の独自パスワードを設定します。パスワードはWrangler secretのみで管理し、wrangler.jsoncには書き込みません：

npx wrangler secret put WEB_PASSWORD

CF_ACCESS_TEAM_DOMAINとCF_ACCESS_AUDはデフォルトで空のままで問題ありません。空のままにすると、Webはパスワードログインを使用し、カード登録は不要です。

3. オプションのアップグレード：Cloudflare Access email OTP

Cloudflareがエッジでemail One-Time PINを先に行うように変更する場合は、このセクションを設定します。Zero Trustのオンボーディングではクレジットカードの登録が必要になる場合があります。無料プラン自体は$0です。

1. Cloudflare Zero TrustでこのWorkerドメインを保護するself-hosted Access applicationを作成します。

2. ログイン方法でOne-Time PINを有効にし、emailまたはemail domainポリシーでログイン可能なユーザーを制限します。

3. ブラウザUIと/api/*がすべてAccessの保護範囲内にあることを確認します。

4. /mcpパスをAccessログイン要件から除外します。例えば、path-based Bypassポリシーを使用するか、Accessを適用しないパスルールに分割します。/mcpは引き続きbc_ MCPキーで認証され、ChatGPT/ClaudeはCloudflare Access cookieを持ち込みません。

5. そのAccess applicationのAudience tagをCF_ACCESS_AUDに、Zero Trust team domainをCF_ACCESS_TEAM_DOMAINに入力し、再デプロイします。入力後、Accessを通過したWebリクエストは自動的に許可され、独自パスワードは要求されなくなります。

4. マイグレーション、テスト、デプロイ

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

5. ChatGPTへの接続

1. デプロイ後のWebサイトを開き、WEB_PASSWORDで設定した独自パスワードを入力します。Cloudflare Accessにアップグレード済みの場合は、email One-Time PINで検証します。

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

セキュリティとプライバシー

• すべての名刺クエリは、パスワードログインのowner、Cloudflare Accessのsub、または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プロトコル、Web API、権限、ストレージ、UI契約テストがあります。カバレッジしきい値はlines/functions/statements 80%、branches 75%です。

既知の制限

• ベクトル意味検索はまだ提供されていません。

• 既存の画像なし名刺には画像補完インターフェースがまだ提供されていません。新しいデータではサムネイルが必須になっています。

• 完全削除はデフォルトで無効です。誤削除を防ぐためアーカイブを使用します。

License

Apache-2.0。詳細はLICENSEを参照してください。