Agentic SDLC Control Plane (GitHub)

agentic-sdlc-mcp

Controles de gobernanza y evidencia para agentes de codificación de IA que trabajan en repositorios reales de GitHub.

Permite que Claude Code, Cursor y otros clientes del Protocolo de Contexto de Modelo (MCP) trabajen con contexto de repositorio, compuertas de revisión, evidencia de seguridad y puntos de aprobación humana.

中文 · npm · MCP Registry · Roadmap

agentic-sdlc-mcp es una capa de gobernanza del ciclo de vida de desarrollo de software (SDLC) para equipos que ya permiten que los agentes de codificación de IA modifiquen repositorios de producción. Convierte el contexto de GitHub, las políticas, los checks, las revisiones, las alertas de seguridad y las señales de release en 13 herramientas MCP a nivel de flujo de trabajo. Doce herramientas son de solo lectura. La única herramienta de escritura de GitHub previsualiza los cambios de forma predeterminada.

Qué cambia con este MCP

Los agentes de codificación de IA pueden crear código y pull requests sin comprender todas las reglas del repositorio. Este servidor proporciona al agente un contexto acotado y ofrece a los revisores brechas de evidencia explícitas en lugar de otro resumen de formato libre.

Este servidor no escribe código, no fusiona pull requests, no hace force-push, no crea releases, no despliega software ni reemplaza la revisión de seguridad humana.

Cómo encaja en un flujo de trabajo de agente en producción

El MCP se sitúa entre un agente de codificación de IA y la evidencia de GitHub. Los cambios en el repositorio siguen ocurriendo a través del entorno de desarrollo normal del agente, y las decisiones de alto impacto permanecen en tu equipo.

flowchart LR
    Policy["Engineering policy<br>and repository rules"] --> MCP["agentic-sdlc-mcp"]
    Agent["AI coding agent<br>Claude Code · Cursor · MCP client"] --> MCP
    MCP --> GitHub["GitHub API evidence"]
    GitHub --> MCP
    MCP --> Reports["Briefs · plans · gates<br>reviews · release reports"]
    Reports --> Agent
    Reports --> Human["Human review and approval"]
    Agent -. "Code · commits · pull requests" .-> GitHub
    Human -. "Merge · release · deploy" .-> GitHub

Dónde ayuda

Usa las herramientas como soporte de decisión en los puntos donde un agente autónomo de otro modo adivinaría o se basaría en prosa desactualizada.

Instalar desde npm

Necesitas Node.js 22 o superior. Node 22 y 24 se prueban en GitHub Actions. Ejecuta el paquete publicado directamente desde npm:

npx -y agentic-sdlc-mcp

Para una instalación CLI global:

npm install -g agentic-sdlc-mcp
agentic-sdlc-mcp

El transporte predeterminado es stdio. La mayoría de los clientes MCP deberían iniciar el paquete por ti en lugar de ejecutarlo en una terminal separada.

Deja que un agente de codificación lo configure

Pega este prompt en Codex, Claude Code u otro agente de codificación:

Use npm install -g agentic-sdlc-mcp to install and configure this MCP globally. Repository: https://github.com/SakuraCianna/agentic-sdlc-mcp
Configure GITHUB_TOKEN and optional repository defaults through the MCP client's secret or environment configuration. On a trusted single-user machine, you may instead run agentic-sdlc-mcp configure or write them to ~/.agentic-sdlc-mcp.json. Never expose the token in chat, logs, or repository files; ask me for missing non-secret details.
Then verify the connection with the read-only repo_context tool and summarize its capabilities, required GitHub permissions, and safety boundaries.

Revisa cada comando y cambio de configuración antes de aprobarlo. Se requiere Node.js 22 o superior.

Conectar un cliente MCP

Añade el servidor a Claude Desktop, Cursor, Windsurf u otro cliente MCP. Inyecta el token de GitHub a través de la configuración de secretos o entorno del cliente.

{
  "mcpServers": {
    "agentic-sdlc": {
      "command": "npx",
      "args": ["-y", "agentic-sdlc-mcp"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here",
        "GITHUB_OWNER": "your_organization",
        "GITHUB_REPO": "your_repository"
      }
    }
  }
}

Algunos clientes MCP de Windows requieren npx a través de cmd:

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "agentic-sdlc-mcp"]
}

GITHUB_OWNER y GITHUB_REPO son valores predeterminados opcionales. Las llamadas a herramientas pueden proporcionar coordenadas de repositorio explícitamente. Usa la matriz de permisos de GitHub para otorgar solo las capacidades que habilites.

npx -y agentic-sdlc-mcp configure

Verificar la conexión

Comienza con una llamada de solo lectura para poder inspeccionar el límite del repositorio antes de otorgar acceso de escritura:

Use agentic-sdlc-mcp to run repo_context for the configured repository. Include package scripts, workflows, governance, and repository policy. Do not create issues or modify GitHub.

Luego valida el límite de escritura sin crear nada:

Generate a feature plan and pass its issue drafts to create_issue_set with dryRun: true. Show the target repository, titles, labels, body summaries, and warnings. Do not write to GitHub.

Consulta la prueba de humo neutral al cliente para una ruta de verificación de cinco minutos.

Herramientas

El servidor registra 13 herramientas a nivel de flujo de trabajo. Los clientes MCP reciben los esquemas completos de entrada y salida en tiempo de ejecución; este catálogo explica cuándo usar cada herramienta y cómo interpretar su resultado.

El servidor también expone cinco recursos sdlc:// de solo lectura para el estándar SDLC y las plantillas de Issue, resumen de PR, preparación de release y handoff.

Workflows comunes

Estas secuencias reducen la ambigüedad en la selección de herramientas. Cada secuencia termina con una decisión humana.

Start work
repo_context → plan_from_context → create_issue_set (dryRun: true)
→ human confirms the work items → create_issue_set (dryRun: false)
→ prepare_work_item

Review a pull request
create_pr_summary → quality_gate_status → review_pr_against_standard
→ human reviews findings and decides whether to merge

Review governance
branch_protection_status → workflow_permissions_audit → security_triage
→ repository owners decide which settings or workflows to change

Prepare a release
security_triage → release_readiness_check → sdlc_evidence_packet
→ human approves the tag, release, and deployment

Transfer work
relevant evidence tools → sdlc_evidence_packet → agent_handoff_packet
→ the next agent validates stale or caller-asserted state before continuing

Permisos de GitHub

No otorgues todos los permisos por defecto. Selecciona los permisos requeridos por las herramientas que tu equipo habilita y prueba contra un repositorio que no sea de producción primero.

Los permisos de GitHub y los requisitos de endpoint pueden cambiar. Confirma los fallos contra la documentación de permisos de la API REST de GitHub. Los permisos opcionales faltantes pueden producir evidencia degradada o no verificada; eso no es motivo para otorgar acceso no relacionado.

Límites de seguridad y confianza

El servidor restringe sus propias herramientas. No puede controlar cada acción disponible para el agente IA circundante o el cliente MCP.

• Una sola herramienta de escritura con vista previa primero: create_issue_set es la única herramienta de escritura de GitHub y por defecto usa dryRun: true
• Sin mutaciones privilegiadas del repositorio: sin herramientas de merge, aprobación, force-push, eliminación de ramas, mutación de reglas de ramas, creación de releases o despliegues
• Los gates humanos siguen siendo externos: el servidor informa evidencia de CODEOWNERS, revisión, política, CI, seguridad y release; GitHub y tu equipo aplican la decisión final
• La evidencia permanece calificada: las fuentes faltantes, obsoletas, truncadas, malformadas o limitadas por permisos siguen siendo visibles como brechas
• La política del repositorio está vinculada a la base: la política de PR se lee desde la SHA base cuando está disponible para que un pull request no pueda debilitar silenciosamente su propio gate
• El texto externo no es confiable: el texto del repositorio y del llamador está acotado y escapado; cualquier patrón detectado de anulación de instrucciones, exfiltración de secretos/datos, comando codificado o coerción de herramientas se omite del Markdown dirigido al agente, mientras que la evidencia estructurada sin procesar permanece disponible para inspección
• La detección de secretos tiene límites: la procedencia confiable del escáner y las heurísticas de parches reducen el riesgo, pero el flujo de datos entre archivos o en tiempo de ejecución aún necesita CodeQL u otras pruebas estáticas de seguridad de aplicaciones (SAST), escáneres de secretos, pruebas y revisión humana
• Las credenciales siguen siendo tu responsabilidad: prefiere la inyección de secretos del cliente o variables de entorno; nunca comprometas tokens ni los pegues en contenido de Issue, PR o logs
• Límite de transporte solo local: stdio y HTTP de loopback son para una estación de trabajo local confiable. El OAuth remoto y el hosting multi-tenant no están en la hoja de ruta actual del producto

Consulta Política de repositorio para conocer el esquema, la procedencia, los límites y el comportamiento de auto-modificación de .agentic-sdlc.yml y la SHA base. Consulta Estrategia de pruebas para la matriz adversarial y las reglas de cobertura.

Política de repositorio y recursos

Agrega .agentic-sdlc.yml cuando los checks específicos del repositorio deban afectar planes, rutas protegidas, gates de PR, revisores, etiquetas de bloqueo, requisitos de changelog y requisitos de rollback. La salida de la política incluye su ref de origen, SHA de blob, digest, IDs de reglas estables y advertencias.

Los recursos estáticos están disponibles bajo el esquema sdlc://:

Perfil HTTP local

Stdio es el transporte local predeterminado y recomendado. Ambas entradas locales usan el router de la era SDK v2 oficial: los clientes de 2025 continúan a través de initialize, mientras que los clientes que negocian explícitamente 2026-07-28 usan server/discover. Ambas eras exponen las mismas 13 herramientas y 5 recursos.

Un cliente local que requiera Streamable HTTP puede optar por él después de compilar desde el código fuente:

$env:TRANSPORT = "http"
$env:PORT = "3000"
node dist/index.js

El endpoint es http://127.0.0.1:3000/mcp. Se vincula solo a loopback, valida Host y los Origin proporcionados antes de analizar un cuerpo de solicitud acotado, crea un servidor y transporte sin estado aislados para cada POST, rechaza operaciones GET/DELETE de sesión no compatibles, acota los detalles de error y aborta los intercambios en curso durante el apagado.

El perfil HTTP sin estado de 2025 no tiene identidad de sesión o de cliente con la que correlacionar un POST de notifications/cancelled separado con una solicitud anterior. El cliente aún observa su cancelación local, pero la operación original del servidor puede ejecutarse hasta su finalización natural. Ambas eras de stdio y el HTTP de 2026 propagan la cancelación a la solicitud del servidor. Prefiere stdio cuando se requiera la cancelación en el lado del servidor de llamadas heredadas.

No expongas ni hagas reverse-proxy de este endpoint a otra máquina. El OAuth remoto y el hosting multi-tenant no están planificados. Si ese alcance se reconsidera, el proyecto debe primero satisfacer los criterios de reingreso de despliegue remoto separados; el servidor local actual no es una base segura para un despliegue remoto.

Enlaces de desarrollo y proyecto

Clona el repositorio solo cuando quieras contribuir o inspeccionar la implementación:

git clone https://github.com/SakuraCianna/agentic-sdlc-mcp.git
Set-Location agentic-sdlc-mcp
npm install
npm run build
npm run test

La puerta separada de Inspector stdio fija Inspector 2.0.0 detrás de su propio lockfile e invoca el dist/index.js real desde fuera del proceso. Verifica el initialize heredado, las 13 declaraciones de herramientas, las cinco lecturas de recursos, una vista previa explícita de cero escrituras create_issue_set y contratos estables de JSON/salida para entrada inválida y una URI de recurso desconocida. Cada tools/call apunta a create_issue_set con dryRun:true. Inspector pasa una lista de permitidos de entorno fija al objetivo con su opción oficial -e, y la ejecución falla a menos que el servidor real escriba un marcador temporal cargado por el harness. El harness conserva el valor HOME del usuario pero bloquea la sonda del archivo de configuración global del producto, reemplaza las credenciales de GitHub heredadas con un marcador de prueba no secreto, aísla el almacenamiento/estado OAuth de Inspector y desactiva toda conexión fetch/TCP para esta comprobación solo-stdio. Esto es evidencia de compatibilidad de caja negra, no certificación MCP ni evidencia para el server/discover moderno.

La puerta HTTP inicia el adaptador de producción en 127.0.0.1:0, apunta a su URL canónica /mcp con el modo no interactivo --stored-auth-only de Inspector, compara el JSON completo de herramientas/recursos con un descubrimiento stdio independiente de Inspector y cierra cada hijo tras éxito o fracaso. Un fixture separado de bucle local 401 con almacenamiento vacío fuerza la elegibilidad de apertura automática pero aun así requiere la 3/auth_required inmediata; un marcador de apertura del navegador hace que cualquier intento OAuth interactivo falle la puerta. El harness permite solo destinos exactos de fetch/socket de bucle local IPv4; los alias DNS, los nombres de host engañosos, el acceso a red externa y las credenciales heredadas permanecen no disponibles. En Windows, Inspector 2.0.0 puede emitir el error JSON correcto y luego alcanzar una aserción de cierre de libuv aguas arriba. El runner acepta solo esa firma exacta de plataforma/estado/dos líneas y reporta la clase de salida cruda; Linux y cualquier otro fallo permanecen en modo fail-closed.

El piloto de Conformance fija la versión oficial 0.1.16 y su suite activa heredada 2025-11-25. Actualmente registra 30 escenarios: cinco pasos directos y 25 fallos esperados gobernados, principalmente porque los prompts del everything-server aguas arriba, las URIs de fixture, las herramientas de fixture, las suscripciones, las capacidades de medios/callback y los supuestos de SSE con estado no son parte del contrato público de este producto. Cada fallo esperado tiene una razón, un responsable y una condición de eliminación; un fallo nuevo o una entrada obsoleta hace fallar la ejecución. El checks.json cargado excluye detalles de respuesta crudos y credenciales. Este es un piloto de compatibilidad no bloqueante, no una certificación ni una razón para añadir capacidades de producción solo para pruebas.

CI ejecuta la suite completa del producto y la comparación de contrato actual en Node 22 y Node 24. Trabajos separados de Node 24 reproducen la línea base inmutable y ejecutan la puerta obligatoria de contrato/evaluación: Inspector stdio/HTTP, Conformance, 12 escenarios fijos, los 13 presupuestos de respuesta y la matriz de fallos de GitHub de 11 casos. La puerta exige al menos 90 % de precisión total de escenarios y 100 % para los seis escenarios de seguridad crítica, y luego sube solo cinco artefactos de resumen acotados. Node 20 no es un runtime compatible porque está en fin de vida; los contribuyentes locales solo necesitan una versión compatible de Node, mientras que la matriz de compatibilidad se aplica mediante GitHub Actions.

Los resultados de evaluación conservan su procedencia. scripted significa un fixture determinista, recorded-agent significa una ejecución histórica saneada reproducida con entradas fijas, y live-model significa una ejecución opcional de modelo actual. El CI obligatorio contiene seis escenarios guionizados y seis de agente grabado, sin ninguna ejecución de modelo en vivo. Una reproducción que pasa demuestra que el flujo de trabajo registrado sigue siendo determinista; no es una afirmación sobre cada modelo, proveedor, prompt futuro o certificación MCP. Consulta la guía de evaluación.

Las pruebas ordinarias, contracts:check y contracts:verify-baseline nunca reescriben la línea base. El comando de reproducción y el comando contracts:generate solo para mantenedores verifican la etiqueta/commit fijado, instalan el lockfile histórico con scripts de ciclo de vida, auditoría y salida de financiamiento deshabilitadas, lo compilan en el directorio temporal del sistema y usan llamadas reales tools/list y resources/list en un proceso hijo acotado cuyo directorio de trabajo permanece fuera del checkout. Ese hijo recibe solo una lista de permitidos de variables de entorno de rutas del sistema operativo, directorio temporal, locale y bibliotecas dinámicas; las credenciales, la configuración empresarial, NODE_OPTIONS y las rutas de estado local no se heredan. La limpieza en Windows usa reintentos acotados después de que se liberan los manejadores históricos. Los comandos requieren acceso al registro npm pero no llaman a las APIs de GitHub ni a servicios de modelo. Solo contracts:generate escribe el JSON rastreado, dejando su diff visible para revisión.

Contribuye mediante issues y pull requests

Las issues y los pull requests son bienvenidos. Consulta las issues abiertas y la hoja de ruta antes de empezar. Abre una Issue primero cuando un cambio afecte el comportamiento público, los límites de seguridad, los esquemas de herramientas o la arquitectura.

1. Haz un fork del repositorio y crea una rama enfocada desde la main más reciente.
2. Ejecuta npm ci y luego haz solo los cambios necesarios para la contribución.
3. Añade o actualiza las pruebas y la documentación cuando cambie el comportamiento.
4. Ejecuta las comprobaciones relevantes para tu cambio. La matriz Node 22/24 ejecuta npm run check:line-endings, npm run typecheck, npm run build, la forma compilada de npm run contracts:check, npm run test, npm run smoke y npm run test:coverage; los trabajos separados de Node 24 ejecutan la reproducción de línea base inmutable y los contratos fijados de Inspector stdio/HTTP y Conformance.
5. Abre un pull request contra main. Describe el problema, la solución, los riesgos, los resultados de validación y las Issues vinculadas.

Mantén los tokens, las credenciales, el contenido de repositorios privados y la configuración local generada fuera de los commits, las Issues, los pull requests y los registros. Una ejecución de CI que pasa respalda la revisión pero no reemplaza la aprobación del mantenedor.

• Hoja de ruta
• Guía de política del repositorio
• Estrategia de pruebas
• Criterios de reentrada para despliegue remoto
• Notas de la versión v1.10.0
• Notas de la versión v1.9.0
• Prueba de humo del agente de codificación con IA
• Changelog
• Versiones
• Issues abiertas

Los flujos de trabajo de npm y MCP Registry usan publicación de confianza con GitHub OpenID Connect (OIDC). Publicar una GitHub Release activa ambos flujos de trabajo. El flujo de Registry espera esa versión exacta del paquete npm antes de publicar los metadatos stdio inmutables correspondientes.

Licencia

MIT