Business Card MCP

Tarjetero personal privado, nativo de IA y autoalojable. Los usuarios suben tarjetas de visita en ChatGPT, que son reconocidas y confirmadas por el modelo multimodal existente; Remote MCP se encarga de la verificación, el almacenamiento privado, la búsqueda, la modificación, el archivado y la exportación, sin llamadas adicionales a la API del modelo.

Funciones

• ChatGPT Remote MCP: crear, buscar, leer, actualizar, archivar y exportar tarjetas de visita

• Sitio web de administración privado: inicio de sesión con contraseña propia, vista de muro de tarjetas / lista, miniaturas protegidas

• D1 FTS5: búsqueda por nombre, empresa, cargo, teléfono, correo electrónico, dirección, etiquetas, ocasión y notas

• R2: Markdown privado y miniaturas WebP de 480px

• KV: clave de conector bc_ independiente por usuario

• Página de confirmación de tarjeta clicable devuelta tras la escritura

• La miniatura es un campo obligatorio al crear la tarjeta, para evitar datos sin imagen

Actualmente es búsqueda de texto completo por palabras clave, no búsqueda semántica por embedding / vectores.

Related MCP server: DuckPond MCP Server

Arquitectura

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

Las imágenes originales de las tarjetas no se guardan por defecto. El repositorio de GitHub solo contiene código, migraciones y datos de prueba sintéticos, sin ningún contacto de usuario.

Herramientas MCP

Requisitos de despliegue

• Node.js 20+

• Cuenta de Cloudflare

• CLI de Wrangler conectada a la cuenta de Cloudflare correcta

Despliegue

1. Instalación y configuración local

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

wrangler.jsonc se incluye en el repositorio como versión de marcador de posición con valores cero (el estándar SmallGreen requiere declaraciones de recursos estáticamente determinables); en el siguiente paso se rellenan los ID reales. Después de rellenarlos, se recomienda git update-index --skip-worktree wrangler.jsonc para evitar que se confirmen los ID reales. public/config.js está ignorado por Git; la autenticación web no necesita configuración en el frontend.

2. Crear recursos de Cloudflare

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

Rellena los ID de account, D1 y KV devueltos por Cloudflare en wrangler.jsonc y configura:

• PUBLIC_BASE_URL

• El nombre del bucket de R2

A continuación, configura la contraseña propia para el inicio de sesión web; la contraseña solo se gestiona mediante el secreto de Wrangler, no se escribe en wrangler.jsonc:

npx wrangler secret put WEB_PASSWORD

CF_ACCESS_TEAM_DOMAIN y CF_ACCESS_AUD pueden dejarse vacíos por defecto; dejarlos vacíos significa que la web usa inicio de sesión con contraseña, sin vinculación de tarjeta.

3. Mejora opcional: OTP por correo electrónico de Cloudflare Access

Para cambiar a que Cloudflare realice primero un One-Time PIN por correo electrónico en el borde, configura esta sección. La incorporación a Zero Trust puede requerir vincular una tarjeta de crédito; el plan gratuito en sí es de $0.

1. Crea una aplicación de Access autoalojada en Cloudflare Zero Trust que proteja el dominio de este Worker.

2. Habilita One-Time PIN como método de inicio de sesión y restringe quién puede iniciar sesión con una política de correo electrónico o dominio de correo.

3. Confirma que la interfaz del navegador y /api/* estén dentro de la cobertura de Access.

4. Exime la ruta /mcp del requisito de inicio de sesión de Access, por ejemplo con una política de Bypass basada en ruta o dividiéndola en reglas de ruta sin Access. /mcp sigue autenticándose con la clave MCP bc_; ChatGPT/Claude no llevan la cookie de Cloudflare Access.

5. Rellena la etiqueta de audiencia de esa aplicación de Access en CF_ACCESS_AUD y el dominio del equipo de Zero Trust en CF_ACCESS_TEAM_DOMAIN, y vuelve a desplegar. Una vez rellenado, las solicitudes web que pasen Access se permitirán automáticamente sin preguntar por la contraseña propia.

4. Migración, pruebas y despliegue

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

5. Conexión con ChatGPT

1. Abre el sitio web desplegado e introduce la contraseña propia configurada en WEB_PASSWORD; si ya se ha actualizado a Cloudflare Access, se verificará con el One-Time PIN por correo electrónico.

2. Genera la clave MCP de la tarjeta de visita.

3. Copia la URL completa del conector; la URL contiene la clave, así que trátala como una contraseña.

4. Añade Remote MCP en el modo de desarrollador de ChatGPT.

5. Tras escanear las herramientas, prueba con «buscar a alguien con la tarjeta MCP».

Desarrollo local

npm run migrate:local
npm run dev

Comprobación de salud: GET /healthz

Remote MCP: POST /mcp

Seguridad y privacidad

• Todas las consultas de tarjetas están restringidas al owner que inició sesión con contraseña, al sub de Cloudflare Access o al propietario de la clave MCP.

• El bucket de R2 se mantiene privado; las miniaturas se sirven mediante una API protegida por inicio de sesión.

• MCP acepta tanto el token Bearer como el token de consulta de la URL del conector.

• La clave completa solo se muestra en el momento de la creación y admite revocación individual.

• No confirmes .env, .dev.vars, wrangler.jsonc ni public/config.js.

Los problemas de seguridad deben notificarse de forma privada según SECURITY.md, no crees un Issue público.

Verificación

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

El proyecto cuenta actualmente con pruebas unitarias, de protocolo MCP, de API web, de permisos, de almacenamiento y de contrato de UI; el umbral de cobertura es del 80 % en líneas/funciones/sentencias y del 75 % en ramas.

Limitaciones conocidas

• Aún no se ofrece búsqueda semántica por vectores.

• Las tarjetas existentes sin imagen aún no tienen interfaz para añadir imagen; los datos nuevos ya exigen miniatura obligatoria.

• La eliminación permanente no está habilitada por defecto; se usa el archivado para evitar borrados accidentales.

Licencia

Apache-2.0. Ver LICENSE.