Arquitectura y evolución técnica de neges-mcp

Objetivo y límites del componente

neges-mcp es un servicio NestJS que expone operaciones seguras de Neges mediante Model Context Protocol. Su trabajo es traducir una intención conversacional a una acción tipada, validar la autorización MCP, llamar al backend con la identidad real del usuario y devolver un resultado pequeño y predecible.

No es un segundo backend de negocio. Strapi sigue siendo la fuente de verdad para usuarios, empresas, membresías, roles, features, productos, pedidos y reglas de integridad. Si una regla debe cumplirse también desde backoffice, API o procesos internos, esa regla pertenece a Strapi y no sólo al MCP.

Glosario esencial

Arquitectura de extremo a extremo

ChatGPT es el host, el modelo decide qué acción conviene y su cliente MCP llama por HTTPS. Railway ejecuta neges-mcp como una capa stateless por request. El estado que debe sobrevivir despliegues —clientes OAuth, sesiones, códigos y tokens— se guarda en un PostgreSQL propio del MCP.

El MCP recupera o renueva el access token de Strapi asociado a la sesión y llama la Content API con Authorization: Bearer y X-Tenant-Id. Strapi resuelve la empresa y aplica sus políticas. El storefront público vive en Vercel, pero las operaciones de mantenimiento pasan por Strapi; el MCP no llama Vercel directamente.

Stack y superficies públicas

Estructura del repositorio

neges-mcp/
├── src/main.ts                       # inicio, CORS y router OAuth
├── src/app.module.ts                 # composición NestJS y contexto por request
├── src/mcp/                          # endpoint /mcp, servidor y resultados
├── src/auth/                         # bearer, AuthContext y scopes por tool
├── src/oauth/                        # OAuth 2.1, login, sesiones y stores
├── src/database/                     # Postgres y migraciones propias
├── src/neges-api/                    # cliente Strapi, queries y errores
├── src/features/
│   ├── tenants/                      # empresas y configuración de venta
│   ├── products/                     # catálogo, categorías y precios
│   ├── product-images/               # imágenes y protecciones SSRF
│   ├── orders/                       # lectura y transiciones de pedidos
│   ├── redirects/                    # redirecciones de URL
│   └── storefront/                   # caché vía storefront-studio de Strapi
├── src/audit/                        # eventos seguros de mutaciones
├── test/                             # pruebas unitarias y de contrato
├── scripts/check-strapi-contract.cjs # guard contra drift de schemas
└── docs/                             # alcance V1, scopes y paquete de publicación

Cada feature mantiene cerca sus tools, schemas, types, adapters, queries y servicio. Esa proximidad evita un registro monolítico y permite probar reglas de un dominio sin conocer todos los demás módulos.

McpServerFactory crea un McpServer nuevo por solicitud, registra las tools de todos los features y lo conecta a un StreamableHTTPServerTransport. Al terminar la respuesta, cierra transporte y servidor. El estado durable no vive dentro de esa instancia.

Qué ocurre en una conexión MCP

1. Inicialización

   Cliente y servidor negocian versión del protocolo y capacidades.

2. Descubrimiento de tools

   ChatGPT solicita la lista. Recibe nombres, descripciones, schemas, seguridad y annotations.

3. Selección por el modelo

   El modelo compara el prompt con la metadata. El código de Neges no decide qué tool elegir; sí valida todo lo que recibe.

4. tools/call

   El cliente envía el nombre de la tool y un objeto de argumentos compatible con inputSchema.

5. Ejecución autorizada

   El servidor verifica token y scope, llama al servicio del feature y luego a Strapi.

6. Resultado

   La tool devuelve content y structuredContent compatible con outputSchema. El modelo redacta la respuesta final.

OAuth 2.1, PKCE y resource/audience

neges-mcp funciona como authorization server OAuth frente al login existente de Strapi. ChatGPT se registra mediante DCR y ejecuta Authorization Code + PKCE S256. El MCP emite sus propios access y refresh tokens opacos; no entrega el JWT de Strapi al cliente.

resource es el destinatario solicitado según RFC 8707. Neges lo fija exactamente en https://mcp.neges.cl/mcp, lo conserva en autorización pendiente, authorization code, access token y refresh token, y vuelve a validarlo al intercambiar, renovar y usar el token. Un token emitido para otro recurso se rechaza aunque sea válido en los demás aspectos.

Cómo se conserva y protege el estado OAuth

Las migraciones son forward-only y se ejecutan al arrancar. El storage durable permite que una conexión continúe después de un redeploy o entre réplicas. Sin NEGES_DATABASE_URL el código ofrece stores de memoria o archivo sólo para desarrollo y pruebas.

Anatomía de una tool

server.registerTool(
  'list_products',
  {
    title: 'List Neges products',
    description: 'Lists or searches products for a Neges tenant...',
    inputSchema: listProductsInputSchema,
    outputSchema: listProductsOutputSchema,
    _meta: oauthToolMeta('products:read'),
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: false,
    },
  },
  async (input) =>
    toolAuthorization.requireScope('products:read', async () =>
      jsonToolResult(await productsService.listProducts(input)),
    ),
);

La regla de diseño es una tool por intención clara. list_products busca o lista; get_product abre un objeto; update_product cambia campos. Una tool genérica execute_strapi_request sería difícil de describir, imposible de revisar con seguridad y permitiría saltarse el diseño del dominio.

Inventario vigente de 30 tools

securitySchemes y requireScope

securitySchemes es la declaración: permite que ChatGPT sepa que una tool necesita OAuth y qué scope solicitar. requireScope es la aplicación real: detiene el handler si el token no contiene el permiso. Ambas partes deben coincidir y Strapi debe volver a autorizar.

Si falta un scope, ToolAuthorizationService devuelve un resultado MCP con isError y _meta["mcp/www_authenticate"]. Ese challenge indica insufficient_scope, metadata del recurso y scope requerido, para que ChatGPT pueda iniciar una reautorización en vez de mostrar sólo un error genérico.

Annotations, idempotencia y confirmaciones

Las annotations ayudan a ChatGPT a decidir confirmaciones, pero no son controles de seguridad. Neges valida confirm=true dentro del input y vuelve a comprobarlo en el servicio para archivar productos, quitar imágenes, eliminar redirecciones y cambiar estados de pedidos. delete_product_category agrega una fase de preview con affectedProductCount.

Seguridad multi-tenant en capas

Las relaciones también deben permanecer dentro del tenant. Por ejemplo, asignar una categoría o un precio no puede conectar documentos de otra empresa. Esta defensa pertenece al backend, porque cualquier cliente —no sólo ChatGPT— podría intentar la misma operación.

Contrato entre neges-mcp y neges-strapi

El MCP consume rutas REST, nombres de campos, relaciones pobladas, enums y formas de respuesta específicas. Los adapters convierten ese formato a objetos de dominio estables. Una modificación de Strapi puede compilar correctamente y aun romper una tool en silencio si el adapter espera otro campo.

Inputs, outputs y errores seguros

Los inputs se validan con Zod antes de llegar al servicio. Deben representar conceptos del negocio —tenantDocumentId, SKU, acción de pedido— y no detalles de transporte. Los campos opcionales deben diferenciar “no cambiar” de “limpiar” cuando corresponda.

{
  "content": [
    {
      "type": "text",
      "text": "{ ...resultado serializado... }"
    }
  ],
  "structuredContent": {
    "items": [],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "pageCount": 0,
      "total": 0
    }
  }
}

Todas las tools públicas declaran outputSchema y devuelven structuredContent. jsonToolResult agrega también una representación textual JSON como fallback. El output debe incluir identificadores útiles para la siguiente llamada, pero no tokens, cookies, stack traces, URLs internas ni objetos completos de infraestructura.

Casos sensibles implementados

Caso de estudio: autorización de storefront

La implementación inicial podía ejecutar mantenimiento de infraestructura desde el MCP usando una allowlist global. Eso no demostraba que el usuario autenticado perteneciera al tenant y colocaba secretos operativos demasiado cerca de la capa conversacional.

La corrección reutilizó el módulo storefront-studio de Strapi. La única tool pública vigente es refresh_storefront_cache. Strapi exige el feature storefront-maintenance.refresh, deriva internamente el tag tenant:<slug> y mantiene los secretos de Vercel. Las tools antiguas de status, sitemap, revalidación por path, purge CDN y redeploy fueron retiradas.

Auditoría y observabilidad actuales

Las mutaciones registran eventos JSON con acción, actorUserId, tenantDocumentId, targetDocumentId, metadata segura y timestamp. /health entrega servicio, versión y estado, sin exponer URL de Strapi, configuración ni tokens.

Estrategia de pruebas y verificación

cd /ruta/a/neges-mcp
npm ci
npm run verify

# verify ejecuta, en orden:
# check:contract → lint → typecheck → test → build

La suite debe fallar si una tool pública no tiene scope, outputSchema o annotations coherentes. Los tests de seguridad mínimos incluyen token para otra audiencia, scope faltante, acceso cruzado de tenant, confirm=false, refresh rotado y sesión Strapi revocada.

Developer Mode, Scan Tools y publicación

1. Desplegar un endpoint HTTPS estable

   La V1 usa https://mcp.neges.cl/mcp. El hostname debe fijarse antes de publicar.

2. Probar en Developer Mode

   Crear una app manual, conectar OAuth, revisar las 30 tools y ejecutar casos positivos y negativos con una cuenta de prueba.

3. Verificar dominio

   El portal entrega un token; Railway lo configura como OPENAI_APPS_CHALLENGE y el endpoint well-known devuelve sólo ese valor.

4. Ejecutar Scan Tools

   OpenAI importa nombres, descripciones, schemas, securitySchemes, annotations, _meta e instrucciones.

5. Completar el paquete de revisión

   Identidad verificada, textos, íconos, política, términos, soporte, prompts, cinco pruebas positivas, tres negativas y credenciales demo.

6. Enviar, aprobar y publicar

   Enviar inicia la revisión; no publica automáticamente. Después de aprobación, el responsable elige Publish.

La app de Neges se distribuye como un plugin con una app respaldada por MCP. Una UI embebida es opcional; la V1 funciona sólo con tools y respuestas estructuradas. Un widget futuro puede agregarse para tablas, previews o formularios sin mover la autoridad de negocio fuera de Strapi.

Versionado y compatibilidad después de publicar

En Developer Mode, después de cambiar la lista o descripción de tools se usa Refresh en la configuración de la app. Un plugin publicado usa un snapshot revisado: desplegar código no reemplaza automáticamente la metadata aprobada.

Procedimiento para agregar o modificar una tool

1. Escribir la intención de usuario

   Define una frase concreta, el resultado esperado, quién puede ejecutarla y qué efectos causa. Evita empezar por un endpoint existente.

2. Decidir la frontera

   Si hay integridad, transacción, permisos o secretos, implementa un comando seguro en Strapi. El MCP sólo adapta y orquesta.

3. Definir el contrato

   Elige nombre estable, descripción, inputSchema, outputSchema, scope y annotations. Usa documentId y conceptos de dominio.

4. Diseñar confirmación e idempotencia

   Para efectos sensibles agrega preview/confirm. Para reintentos de creación diseña una Idempotency-Key durable en el backend antes de marcar idempotente.

5. Implementar por feature

   Agrega schema, types, queries, adapter, service y tool en el módulo correcto. Mantén el handler delgado.

6. Minimizar el output

   Devuelve resumen, identificadores estables y campos útiles. Quita PII, secretos y detalles internos.

7. Actualizar el contrato compartido

   Si consume algo nuevo de Strapi, modifica MCP-CONTRACT.md y agrega el guard automático cuando sea posible.

8. Probar fallos y seguridad

   Incluye input inválido, scope ausente, tenant ajeno, permiso Strapi ausente, retry, timeout, conflicto y output schema.

9. Verificar y probar con el modelo

   Ejecuta npm run verify, despliega y prueba prompts que deberían y no deberían elegir la tool.

10. Versionar la app

    Si cambió metadata pública, Refresh en Developer Mode y Scan Tools para una nueva versión del plugin.

Método general para construir cualquier MCP

Deuda técnica conocida y evolución recomendada

Runbook de diagnóstico

Definition of Done para un cambio MCP

Fuentes y documentos de referencia