damonzucconi-mcp

Servidor MCP remoto para gestionar damonzucconi.com a través de su API GraphQL.

Endpoint de producción: https://damonzucconi-mcp.damonzucconi.workers.dev/mcp

El servidor es un único Cloudflare Worker sin estado y sin bindings de almacenamiento. Un token de portador estático protege el endpoint MCP. El Worker inicia sesión en la API GraphQL con las credenciales de administrador existentes y almacena en caché el JWT resultante hasta poco antes de que caduque.

Expone herramientas para obras de arte, exposiciones, etiquetas, entidades anidadas y ordenación. La eliminación de obras de arte y exposiciones no está disponible de forma intencionada; hazlo manualmente.

Desarrollo local

Requiere Node.js 20+ y npm.

npm install
cp .dev.vars.example .dev.vars

Configura los tres secretos en .dev.vars:

openssl rand -hex 32

MCP_AUTH_TOKEN=<paste-generated-value>
ADMIN_USERNAME=your-api-admin-username
ADMIN_PASSWORD=your-api-admin-password

MCP_AUTH_TOKEN es un secreto compartido, no un nombre de usuario ni un token de inicio de sesión. El Worker almacena una copia y cada cliente MCP envía el mismo valor como token de portador. La posesión de este valor otorga acceso al servidor.

No hay sincronización automática:

• .dev.vars alimenta al Worker local y es la fuente que usa npm run secrets:push.

• npm run secrets:push copia el valor a los secretos cifrados del Worker de Cloudflare para producción.

• Cursor y ChatGPT leen ese mismo valor de la variable de entorno del lado del cliente DAMONZUCCONI_MCP_TOKEN.

Si cambias MCP_AUTH_TOKEN, ejecuta npm run secrets:push, actualiza DAMONZUCCONI_MCP_TOKEN y reinicia el cliente. Un cliente que use un valor distinto recibirá 401 Unauthorized.

npm run codegen
npm run typecheck
npm run dev

El endpoint MCP local es http://127.0.0.1:8787/mcp. En otra terminal:

npm run smoke

Para probar producción, en su lugar:

MCP_URL=https://damonzucconi-mcp.damonzucconi.workers.dev npm run smoke

Conectar desde Cursor

Añade esto a .cursor/mcp.json para este proyecto o a ~/.cursor/mcp.json de forma global:

{
  "mcpServers": {
    "damonzucconi": {
      "url": "https://damonzucconi-mcp.damonzucconi.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:DAMONZUCCONI_MCP_TOKEN}"
      }
    }
  }
}

Configura DAMONZUCCONI_MCP_TOKEN en el entorno que Cursor hereda, con el mismo valor que MCP_AUTH_TOKEN en .dev.vars, y reinicia Cursor. Los servidores remotos no admiten envFile.

Conectar desde ChatGPT de escritorio

La aplicación de escritorio de ChatGPT comparte la configuración de MCP con Codex en ~/.codex/config.toml. Añade:

[mcp_servers.damonzucconi]
url = "https://damonzucconi-mcp.damonzucconi.workers.dev/mcp"
bearer_token_env_var = "DAMONZUCCONI_MCP_TOKEN"
default_tools_approval_mode = "writes"

En macOS, haz que el token esté disponible para las aplicaciones iniciadas desde Finder o el Dock:

read -s "DAMONZUCCONI_MCP_TOKEN?MCP token: "
echo
launchctl setenv DAMONZUCCONI_MCP_TOKEN "$DAMONZUCCONI_MCP_TOKEN"
unset DAMONZUCCONI_MCP_TOKEN

Pega el mismo valor que MCP_AUTH_TOKEN cuando read lo solicite. El token no se escribe en config.toml ni en el historial del shell.

Sal por completo de ChatGPT y vuelve a abrirlo; luego abre Configuración → Servidores MCP y selecciona Reiniciar. Escribe /mcp en el compositor para confirmar que damonzucconi está conectado. Consulta la documentación de MCP de OpenAI si la interfaz de escritorio cambia.

Despliegue

La autenticación de Wrangler abre un navegador:

npx wrangler login

Para un primer despliegue:

npm run deploy
npm run secrets:push

secrets:push sube las tres entradas de .dev.vars. En despliegues posteriores, ejecuta solo npm run deploy a menos que un secreto haya cambiado.

Antes de desplegar cambios:

npm run codegen
npm run typecheck
npm run smoke
npm run deploy
MCP_URL=https://damonzucconi-mcp.damonzucconi.workers.dev npm run smoke

Generación de código GraphQL

Las consultas y mutaciones se encuentran en src/graphql/. npm run codegen hace introspección de la API en vivo y actualiza:

• schema.graphql

• src/generated/

No edites los archivos generados. Si codegen o la comprobación de tipos falla tras un cambio en la API, actualiza las operaciones .graphql o los esquemas de sus herramientas Zod antes de desplegar.