Servidor MCP de secureFlows

Servidor MCP desplegable en la nube que envuelve la superficie OpenAPI de secureFlows etiquetada como ai-safe y ai-optional.

Este repositorio es un espejo público, publicado periódicamente desde el monorepo privado de secureFlows donde realmente ocurre el desarrollo. Los problemas y las solicitudes de extracción son bienvenidos; los cambios grandes pueden tardar un ciclo de lanzamiento en llegar primero a la fuente.

¿Qué es un servidor MCP?

Un servidor MCP es un pequeño servicio HTTP que expone un conjunto de "herramientas" que un cliente de IA puede llamar de manera estándar.

En este repositorio:

• El servidor MCP de secureFlows expone herramientas que se generan automáticamente a partir de sus especificaciones YAML de OpenAPI.

• Cuando un cliente llama a una herramienta, el servidor MCP reenvía la llamada a su backend real de secureFlows (connection.host) y devuelve la respuesta en un resultado de herramienta normalizado.

Esto permite que un cliente de IA:

• descubra las operaciones disponibles de secureFlows mediante listTools

• las llame mediante callTool

• sin codificar la superficie de la API ni el cableado manual de autenticación/encabezados

Qué hace

Dos tipos de herramientas, registradas juntas en src/server.ts:

Herramientas generadas (src/tools/build-tools.ts) — una por operación de OpenAPI:

• Carga:

  • docs/openapi/session/secure-flows-session-api.yaml

  • docs/openapi/user/secure-flows-user-api.yaml

  • docs/openapi/docs/secure-flows-docs-api.yaml

• Expone solo las operaciones etiquetadas como ai-safe o ai-optional como herramientas MCP

• Reenvía las solicitudes a un host de secureFlows proporcionado por el llamador — un envoltorio HTTP delgado y genérico sin juicio específico de secureFlows. Cada una de estas requiere un token auth.* activo, por lo que solo son útiles una vez que ya existe una sesión (consulte Modelo de ejecución a continuación).

• Asigna los encabezados de autenticación de secureFlows desde las entradas de la herramienta MCP:

  • auth.firebaseToken

  • auth.sessionToken

  • auth.userToken

Herramientas estáticas (src/tools/static-tools.ts) — escritas a mano, no generadas a partir de la especificación:

• secureflows_build_login_url / secureflows_build_logout_url — construyen las URL de inicio de sesión alojado y de cierre de sesión con redirección correctamente por construcción (siempre /app/sessions/login, nunca la heredada /app/login; rechaza un redirect_uri posterior al cierre de sesión que apunte a /callback o que filtre session_token). No se requiere token de secureFlows.

• secureflows_lint_integration — verifica el código fuente de la aplicación generada contra las reglas de integración e informa hallazgos estructurados en lugar de dejarlos como prosa que el agente debe auto-vigilar. No se requiere token de secureFlows. Dos tipos de hallazgo:

  • scope: "file" — una construcción prohibida está presente, en una file:line exacta: constantes de configuración de variables de entorno, token en localStorage, /app/login heredado, cierre de sesión con fetch/XHR, decodificación de JWT en el cliente, revocación al cerrar sesión, catch {} vacío, restauración de setSession(null) en errores que no son de autenticación, CTA de continuar condicionado a session === null, …

  • scope: "project" — el manejo requerido está ausente en todos los archivos pasados: detectar 401/410 pero nunca borrar el token, nunca manejar 403, o manejar 403 sin la excepción BILLING_GRACE_LOCK.

  Las comprobaciones de ausencia existen porque las reglas de patrones estructuralmente no podían capturar la clase de defecto que domina las aplicaciones generadas reales. Medido: en la aplicación de una prueba real que el juez LLM del arnés de evaluación calificó con 4/10 — citando "token obsoleto nunca borrado al cerrar sesión", "variantes de 403 sin manejar", "sin manejo de errores" — las reglas de patrones solas produjeron cero hallazgos, porque cada uno de esos errores es una ausencia, y una expresión regular solo puede ver lo que está presente. Con las comprobaciones de ausencia produce 3, incluida la de severidad error sobre el borrado de token. Ambos tipos de comprobación se validan contra el iniciador canónico templates/web-app-secureflows, que debe permanecer con cero hallazgos.

  Sigue siendo análisis de texto heurístico, no un analizador sintáctico ni un verificador de tipos: omite lo que no tiene regla, una comprobación de proyecto puede satisfacerse con la palabra clave correcta en el lugar incorrecto, y no puede cubrir las comprobaciones que necesitan una aplicación en ejecución (carreras de montaje del guard de autenticación, la comprobación de recarga fresca). Un primer pase rápido — no un reemplazo de la lista de verificación de implementación del agente en SKILL.md.

Estas herramientas estáticas existen porque las herramientas generadas no pueden ayudar con la parte de una integración que ocurre antes de que exista una sesión — el andamiaje del código de redirección/callback/ciclo de vida del token — que es exactamente donde ocurren la mayoría de los errores de integración de secureFlows.

Utiliza un transporte MCP HTTP sin estado, por lo que el servidor no persiste la configuración del inquilino ni los secretos.

Modelo de ejecución

Cada llamada de herramienta recibe:

• connection.host: URL base de secureFlows

• connection.workspaceName: espacio de trabajo predeterminado opcional

• connection.appId: id de aplicación predeterminado opcional

• auth.*: el token que necesite el endpoint seleccionado

workspaceName y appId se tratan como configuración estable de la aplicación. El servidor los inyecta en las formas de solicitud conocidas de secureFlows cuando el llamador los omite.

Para agentes (la única ruta de cliente compatible)

Apunte el cliente MCP a la URL alojada — mismo host que el producto, ruta /mcp (no un subdominio):

{
  "mcpServers": {
    "secureflows": {
      "url": "https://www.secure-flows.com/mcp"
    }
  }
}

No les diga a los agentes que ejecuten npx ni que usen localhost — eso divide la historia y rompe a cualquiera que nunca inicie un proceso local. Conectado en la imagen Docker web (Node en 127.0.0.1:8787, nginx location = /mcp; consulte docs/ROUTING.md). El proceso Node instala guardas de uncaughtException / unhandledRejection para que una sola solicitud incorrecta no salga del proceso; docker/entrypoint.sh también reinicia MCP si el proceso aún sale.

Desarrollo local (mantenedores de este paquete)

cd mcp-server
npm install
npm run build
npm test
npm run dev

El servidor se inicia en http://0.0.0.0:8787 de forma predeterminada (POST /mcp, GET /health). Esto es para cambiar el propio servidor MCP — no la ruta que los agentes del producto deben configurar.

Variables de entorno

• PORT: puerto HTTP, predeterminado 8787 (en el contenedor web, el entrypoint establece PORT=8787 solo para el hijo MCP para que nginx mantenga el $PORT público de Render)

• HOST: host de enlace, predeterminado 0.0.0.0 (el contenedor web usa 127.0.0.1)

• ALLOWED_HOSTS: lista de hosts permitidos opcional separada por comas para la validación del encabezado Host de MCP

• MCP_ALLOWED_HOSTS: anulación del entrypoint para ALLOWED_HOSTS al iniciar el proceso en la imagen

Endpoints

• POST /mcp: endpoint HTTP transmisible de MCP

• GET /health: verificación de salud (expuesta públicamente como GET /mcp/health a través de nginx)

Incrustar secureFlows en una aplicación

Las aplicaciones de producto se integran directamente con las API HTTP de secureFlows y el inicio de sesión alojado. Comience desde:

• docs/integration/quickstart.md — aprovisionamiento (espacio de trabajo + aplicación) e inicio de sesión alojado en tiempo de ejecución

• docs/integration/CONCEPT.md — orden de línea base: inicio de sesión → crear espacio de trabajo antes de las funciones avanzadas

• docs/openapi/integration-auth.yaml — /app/sessions/login (aplicaciones de sesión) vs /app/login (heredado/consola)

Las aplicaciones de producto aún se integran directamente con las API HTTP anteriores, no a través de este servidor. Las herramientas generadas aquí son para agentes/automatización que ya tienen un token (pruebas, verificación scriptada). Las herramientas estáticas (secureflows_build_login_url, secureflows_build_logout_url, secureflows_lint_integration) no necesitan token y están destinadas a ser llamadas por un agente de codificación mientras aún está andamiando la integración — consulte Qué hace arriba.

Pruebas de este servidor MCP

1. npm test en mcp-server/ — pruebas unitarias más prueba de humo HTTP (test/http-smoke.test.ts): inicia la aplicación Express en un puerto efímero, verifica GET /health, GET /mcp → 405, y un cliente real de Streamable-HTTP listTools + callTool(secureflows_build_login_url).

2. Después del despliegue: Playwright tests/smoke/mcp-health.spec.ts golpea el público GET /mcp/health y GET /mcp en el host objetivo (trabajo de humo de producción).

3. Bucle local del mantenedor: npm run dev, luego curl -sS http://127.0.0.1:8787/health.

4. Opcional: cliente MCP contra POST /mcp con connection.host + auth.* para herramientas generadas.

Despliegue

Enviado dentro de la imagen Docker web y proxy en /mcp en www.secure-flows.com / staging (consulte Para agentes arriba). Sin subdominio separado.

El paquete npm secureflows-mcp-server es cómo CI publica un artefacto versionado (y cómo un contenedor independiente se puede construir desde mcp-server/Dockerfile); no es la ruta de configuración orientada al agente. Publique en etiquetas v*.*.* a través de .github/workflows/publish-secureflows-mcp-server.yml.

docker build -f mcp-server/Dockerfile -t secureflows-mcp-server .
docker run --rm -p 8787:8787 secureflows-mcp-server

Notas

• Los endpoints de inicio de sesión alojado / redirección se exponen solo si están etiquetados como ai-safe o ai-optional en las especificaciones OpenAPI.

• Búsqueda de documentación (get_docs_search) es ai-safe, requiere sin auth.* — solo connection.host y la consulta q.

• Las API de consola de administración solo para humanos están excluidas intencionalmente.

• La carga útil de respuesta de cada herramienta incluye:

  • status

  • ok

  • url

  • headers

  • data