Business Card MCP

AI-native, самостоятельно размещаемая частная библиотека визитных карточек. Пользователь загружает визитную карточку в ChatGPT, её распознаёт и подтверждает существующая мультимодальная модель; Remote MCP отвечает за проверку, приватное хранение, поиск, изменение, архивирование и экспорт, без дополнительных вызовов API моделей.

Возможности

• ChatGPT Remote MCP: создание, поиск, чтение, обновление, архивирование и экспорт визитных карточек

• Приватный сайт управления: вход по собственному паролю, просмотр стеной карточек/списком, защищённые миниатюры

• D1 FTS5: поиск по имени, компании, должности, телефону, email, адресу, тегам, случаю и примечаниям

• 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; для веб-аутентификации фронтенд-конфигурация не нужна.

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

Затем задайте собственный пароль для входа на сайт; пароль передаётся только через Wrangler secret и не записывается в wrangler.jsonc:

npx wrangler secret put WEB_PASSWORD

CF_ACCESS_TEAM_DOMAIN и CF_ACCESS_AUD по умолчанию можно оставить пустыми; пустое значение означает вход на сайт по паролю, без привязки карты.

3. Необязательное обновление: Cloudflare Access email OTP

Если хотите, чтобы Cloudflare выполнял email One-Time PIN на границе сети, настройте этот раздел. Онбординг Zero Trust может потребовать привязки кредитной карты; сам бесплатный тариф — $0.

1. Создайте в Cloudflare Zero Trust self-hosted Access application, защищающую домен этого Worker.

2. Включите для входа One-Time PIN и ограничьте круг входящих политикой по email или домену email.

3. Убедитесь, что браузерный UI и /api/* находятся под защитой Access.

4. Исключите путь /mcp из требования входа Access, например с помощью path-based Bypass policy или отдельного правила путей без Access. /mcp по-прежнему аутентифицируется ключом bc_ MCP; ChatGPT/Claude не передают cookie Cloudflare Access.

5. Впишите Audience tag этого Access application в CF_ACCESS_AUD, а Zero Trust team domain — в CF_ACCESS_TEAM_DOMAIN, затем переразверните. После этого веб-запросы, прошедшие Access, пропускаются автоматически, без запроса собственного пароля.

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_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, sub из Cloudflare Access или владельцем MCP Key.

• R2 bucket остаётся приватным; миниатюры отдаёт API, защищённый входом.

• MCP принимает и Bearer token, и query token из Connector URL.

• Полный 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-контрактов; порог покрытия — lines/functions/statements 80%, branches 75%.

Известные ограничения

• Векторный семантический поиск пока не реализован.

• Для существующих визитных карточек без изображения интерфейс добавления изображения пока не предусмотрен; для новых данных миниатюра уже обязательна.

• Окончательное удаление по умолчанию не открыто; используйте архивацию, чтобы избежать случайного удаления.

Лицензия

Apache-2.0. Подробнее см. LICENSE.