Agentic SDLC Control Plane (GitHub)

agentic-sdlc-mcp

Controles de governança e evidências para agentes de codificação de IA trabalhando em repositórios GitHub reais.

Deixe Claude Code, Cursor e outros clientes do Model Context Protocol (MCP) trabalharem com contexto de repositório, portões de revisão, evidências de segurança e pontos de aprovação humana.

中文 · npm · MCP Registry · Roadmap

agentic-sdlc-mcp é uma camada de governança do ciclo de vida de desenvolvimento de software (SDLC) para equipes que já permitem que agentes de codificação de IA alterem repositórios de produção. Ela transforma contexto do GitHub, políticas, verificações, revisões, alertas de segurança e sinais de release em 13 ferramentas MCP de nível de fluxo de trabalho. Doze ferramentas são somente leitura. A única ferramenta de escrita do GitHub pré-visualiza alterações por padrão.

A versão 1.11.0 também fornece agentic-sdlc, um CLI somente leitura para avaliação de PR, evidências portáteis, comparações de snapshots e rastreabilidade de aceitação. agentic-sdlc-mcp permanece como o ponto de entrada do servidor MCP. Verifique o pacote exato e os metadados de release ao instalar esta versão.

O que muda com este MCP

Agentes de codificação de IA podem criar código e pull requests sem entender todas as regras do repositório. Este servidor dá ao agente contexto limitado e dá aos revisores lacunas de evidências explícitas em vez de outro resumo de forma livre.

Este servidor não escreve código, mescla pull requests, faz force-push, cria releases, implanta software ou substitui a revisão de segurança humana.

Como ele se encaixa em um fluxo de trabalho de agente de produção

O MCP fica entre um agente de codificação de IA e as evidências do GitHub. As alterações no repositório ainda acontecem pelo ambiente de desenvolvimento normal do agente, e decisões de alto impacto permanecem com sua equipe.

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

Onde ele ajuda

Use as ferramentas como suporte à decisão nos pontos onde um agente autônomo adivinharia ou dependeria de prosa desatualizada.

Revisar um PR sem um agente

Colete uma decisão legível por humanos e um snapshot JSON com um comando. A avaliação combina evidências de revisão existentes baseadas em portões e regras, vincula-as ao head/base do PR e ao digest de política, e preserva bloqueadores, evidências ausentes, contagens de solicitações e duração da coleta.

Compile a partir de um checkout revisado com Node.js 22 ou mais recente:

npm ci
npm run build
node dist/cli.js doctor --repo acme/widget
node dist/cli.js assess-pr --repo acme/widget --pr 42 --output artifacts/pr-42-first.json --summary artifacts/pr-42-first.md

Injete GITHUB_TOKEN pelo seu processo ou gerenciador de segredos antes da coleta online. O CLI lê apenas variáveis de ambiente; ele não carrega uma configuração home ou .env. doctor é offline a menos que --online seja fornecido, e configuração ausente retorna código de saída 2. Uma vez que o pacote esteja instalado, agentic-sdlc executa o mesmo CLI que node dist/cli.js.

assess-pr e evidence também aceitam --previous, --acceptance e --mappings opcional para uma coleta mais análise local. Arquivos de mapeamento usam o esquema estrito de array descrito em continuidade de evidências. --json altera o stdout; --output sempre cria um arquivo JSON. Arquivos existentes nunca são sobrescritos. --summary cria um novo arquivo Markdown, ou anexa quando aponta para o caminho exato de GITHUB_STEP_SUMMARY do GitHub Actions.

As avaliações são consultivas por padrão: um relatório concluído retorna 0 mesmo quando sua decisão está bloqueada ou precisa de evidências. assess-pr --enforce retorna 1 para blocked, 2 para needs_evidence e 0 para ready_for_review. Erros de configuração/entrada/fonte indisponível retornam 2; cancelamento retorna 130. Um comando bem-sucedido de diff ou trace significa que a análise foi concluída, não que as evidências ou condições de aceitação passaram.

A coleta online usa um timeout padrão de 30 segundos e um orçamento de 120 solicitações; as substituições suportadas são --timeout-ms de 1 a 120000 e --max-requests de 2 a 500. doctor tem suas próprias sondas limitadas e aceita a opção de timeout. Entradas de arquivo e saídas serializadas são limitadas a 1 MiB.

Um snapshot inalterado nunca herda uma verificação anterior. Alterações em head/base, política, versão do produtor, frescor e completude podem exigir recoleção. Caixas marcadas, afirmações de agentes e CI verde comum não provam aceitação de negócios; o CLI não tem um produtor de aceitação confiável configurado por padrão. Nem um relatório pronto nem --enforce aprovam, mesclam ou implantam um PR.

Para sessões de revisão MCP, defina SDLC_CONFIG_MODE=envonly para evitar configuração home/.env e SDLC_READ_ONLY=true para rejeitar criação de Issue ao vivo enquanto mantém pré-visualizações. Use um token restrito aos repositórios pretendidos e permissões de leitura. A configuração do cliente e a habilidade de revisão portátil estão em receitas de cliente; o plano de validação de pequena amostra não executado está em piloto de usuário.

Instalar a partir do npm

Você precisa de Node.js 22 ou mais recente. Node 22 e 24 são testados no GitHub Actions. Execute o pacote publicado diretamente do npm:

npx -y agentic-sdlc-mcp

Para uma instalação CLI global:

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

O transporte padrão é stdio. A maioria dos clientes MCP deve iniciar o pacote para você em vez de executá-lo em um terminal separado.

Estes comandos npm resolvem releases publicados. Fixe agentic-sdlc-mcp@1.11.0 para reproduzir esta versão, verifique seus metadados de release/pacote e reinicie qualquer conexão MCP existente após uma atualização.

Deixe um agente de codificação configurá-lo

Cole este prompt no Codex, Claude Code ou outro agente de codificação:

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.

Revise cada comando e alteração de configuração antes de aprová-lo. Node.js 22 ou mais recente é necessário.

Conectar um cliente MCP

Adicione o servidor ao Claude Desktop, Cursor, Windsurf ou outro cliente MCP. Injete o token do GitHub pela configuração de segredo ou ambiente do 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"
      }
    }
  }
}

Alguns clientes MCP do Windows exigem npx por meio de cmd:

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

GITHUB_OWNER e GITHUB_REPO são padrões opcionais. Chamadas de ferramentas podem fornecer coordenadas de repositório explicitamente. Use a matriz de permissões do GitHub para conceder apenas as capacidades que você habilita.

npx -y agentic-sdlc-mcp configure

Verificar a conexão

Comece com uma chamada somente leitura para que você possa inspecionar o limite do repositório antes de conceder acesso de escrita:

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.

Em seguida, valide o limite de escrita sem criar 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.

Veja o teste de fumaça neutro de cliente para um caminho de verificação de cinco minutos.

Ferramentas

O servidor registra 13 ferramentas de nível de fluxo de trabalho. Os clientes MCP recebem os esquemas completos de entrada e saída em tempo de execução; este catálogo explica quando usar cada ferramenta e como interpretar seu resultado.

O servidor também expõe cinco recursos sdlc:// somente leitura para o padrão SDLC e modelos de Issue, resumo de PR, prontidão de release e handoff.

Workflows comuns

Essas sequências reduzem a ambiguidade de seleção de ferramentas. Cada sequência termina com uma decisão 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

Permissões do GitHub

Não conceda todas as permissões por padrão. Selecione as permissões exigidas pelas ferramentas que sua equipe habilita e teste primeiro em um repositório não produtivo.

Permissões e requisitos de endpoint do GitHub podem mudar. Confirme falhas na documentação de permissões da API REST do GitHub. Permissões opcionais ausentes podem produzir evidências degradadas ou não verificadas; isso não é motivo para conceder acesso não relacionado.

Limites de segurança e confiança

O servidor restringe suas próprias ferramentas. Ele não pode controlar todas as ações disponíveis para o agente de IA ou cliente MCP ao redor.

• Uma única ferramenta de escrita com preview primeiro: create_issue_set é a única ferramenta de escrita do GitHub e usa como padrão dryRun: true
• Sem mutações privilegiadas de repositório: não há ferramentas de merge, aprovação, force-push, exclusão de branch, mutação de regras de branch, criação de release ou deploy
• Portões humanos permanecem externos: o servidor reporta evidências de CODEOWNERS, revisão, política, CI, segurança e release; o GitHub e sua equipe aplicam a decisão final
• Evidências permanecem qualificadas: fontes ausentes, desatualizadas, truncadas, malformadas ou com permissão limitada permanecem visíveis como lacunas
• A política do repositório é vinculada à base: a política de PR é lida do SHA da base quando disponível, para que um pull request não possa silenciosamente enfraquecer seu próprio portão
• Texto externo não é confiável: o texto do repositório e do chamador é limitado e escapado; qualquer padrão detectado de override de instrução, exfiltração de segredo/dados, comando codificado ou coerção de ferramenta é omitido do Markdown voltado ao agente, enquanto evidências estruturadas brutas permanecem disponíveis para inspeção
• A detecção de segredos tem limites: proveniência confiável do scanner e heurísticas de patch reduzem o risco, mas fluxo de dados entre arquivos ou em tempo de execução ainda precisa de CodeQL ou outra análise estática de segurança de aplicações (SAST), scanners de segredos, testes e revisão humana
• Credenciais continuam sendo sua responsabilidade: prefira injeção de segredo no cliente ou variáveis de ambiente; nunca faça commit de tokens nem os cole em conteúdo de Issue, PR ou logs
• Limite de transporte apenas local: stdio e HTTP loopback são para uma estação de trabalho local confiável. OAuth remoto e hospedagem multi-tenant não estão no roadmap atual do produto

Consulte Repository policy para o esquema de .agentic-sdlc.yml, proveniência, limites e comportamento de automodificação base-SHA. Consulte Testing strategy para a matriz adversarial e regras de cobertura.

Política e recursos do repositório

Adicione .agentic-sdlc.yml quando verificações específicas do repositório devem afetar planos, caminhos protegidos, portões de PR, revisores, labels de bloqueio, requisitos de changelog e requisitos de rollback. A saída da política inclui sua ref de origem, blob SHA, digest, IDs de regra estáveis e avisos.

Recursos estáticos estão disponíveis sob o esquema sdlc://:

Perfil HTTP local

Stdio é o transporte local padrão e recomendado. Ambas as entradas locais usam o roteador oficial da era SDK v2: clientes de 2025 continuam via initialize, enquanto clientes que negociam explicitamente 2026-07-28 usam server/discover. Ambas as eras expõem as mesmas 13 ferramentas e 5 recursos.

Um cliente local que exija Streamable HTTP pode optar por isso após compilar a partir do código-fonte:

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

O endpoint é http://127.0.0.1:3000/mcp. Ele vincula apenas a loopback, valida Host e o Origin fornecido antes de analisar um corpo de requisição limitado, cria um servidor e transporte stateless isolados para cada POST, rejeita operações de sessão GET/DELETE não suportadas, limita detalhes de erro e aborta trocas em andamento durante o desligamento.

O perfil HTTP stateless de 2025 não tem sessão nem identidade de cliente para correlacionar um POST notifications/cancelled separado a uma requisição anterior. O cliente ainda observa seu cancelamento local, mas a operação original do servidor pode ser executada até a conclusão natural. Ambas as eras stdio e o HTTP de 2026 propagam o cancelamento para a requisição do servidor. Prefira stdio quando o cancelamento no lado do servidor de chamadas legadas for necessário.

Não exponha nem faça reverse-proxy deste endpoint para outra máquina. OAuth remoto e hospedagem multi-tenant não estão planejados. Se esse escopo for reconsiderado, o projeto deve primeiro atender aos critérios separados de reentrada para deploy remoto; o servidor local atual não é uma base segura para deploy remoto.

Links de desenvolvimento e projeto

Clone o repositório somente quando quiser contribuir ou inspecionar a implementação:

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

O portão de integração chama todas as 13 ferramentas públicas por meio de um Client.callTool real do SDK em ambas as eras: legado por meio do wrapper stdio do projeto e moderno por meio do manipulador HTTP de busca direta de produção fixado em 2026-07-28. Ele valida esquemas de saída registrados, principais resultados Markdown/estruturados, limites de confiança, semântica de erro/degradação, cabeçalhos de wire modernos e o comportamento padrão de dry-run create_issue_set. O fixture falha imediatamente em qualquer escrita de Issue ao vivo e bloqueia acesso externo a fetch/socket.

O portão stdio separado do Inspector fixa o Inspector 2.0.0 atrás de seu próprio lockfile e invoca o dist/index.js real de fora do processo. Ele verifica initialize legado, todas as 13 declarações de ferramentas, todas as cinco leituras de recursos, um preview explícito de zero escrita create_issue_set, e contratos JSON/exit estáveis para entrada inválida e URI de recurso desconhecido. Cada tools/call tem como alvo create_issue_set com dryRun:true. O Inspector passa uma allowlist de ambiente fixa para o alvo com sua opção oficial -e, e a execução falha a menos que o servidor real escreva um marcador carregado por harness temporário. O harness preserva o valor HOME do usuário, mas bloqueia a sondagem do arquivo de configuração global do produto, substitui credenciais herdadas do GitHub por um placeholder de teste não secreto, isola o armazenamento/estado OAuth do Inspector e desativa toda conexão fetch/TCP para esta verificação somente stdio. Isso é evidência de compatibilidade black-box, não certificação MCP e não é evidência para server/discover moderno.

O portão HTTP inicia o adaptador de produção em 127.0.0.1:0, tem como alvo sua URL canônica /mcp com o modo não interativo --stored-auth-only do Inspector, compara o JSON completo de ferramentas/recursos com uma descoberta stdio independente do Inspector e fecha cada filho após sucesso ou falha. Um fixture separado de loopback 401 com store vazio força a elegibilidade de auto-open, mas ainda exige 3/auth_required imediato; um marcador de spawn de navegador faz qualquer tentativa de OAuth interativo falhar no portão. O harness permite apenas alvos exatos de fetch/socket IPv4 loopback; aliases DNS, hostnames enganosos, acesso a rede externa e credenciais herdadas permanecem indisponíveis. No Windows, o Inspector 2.0.0 pode emitir o erro JSON correto e então atingir uma asserção de fechamento libuv upstream. O runner aceita apenas essa assinatura exata de plataforma/status/duas linhas e reporta a classe de exit bruta; Linux e qualquer outra falha permanecem fail-closed.

O piloto Conformance fixa o 0.1.16 oficial e sua suíte ativa legada 2025-11-25. Atualmente registra 30 cenários: cinco passes diretos e 25 falhas esperadas governadas, principalmente porque os prompts do everything-server upstream, URIs de fixture, ferramentas de fixture, assinaturas, capacidades de mídia/callback e suposições SSE stateful não são o contrato público deste produto. Cada falha esperada tem motivo, responsável e condição de remoção; uma nova falha ou entrada obsoleta falha a execução. O checks.json enviado exclui detalhes brutos de resposta e credenciais. Este é um piloto de compatibilidade não bloqueante, não certificação e não é motivo para adicionar capacidades de produção somente para teste.

CI executa a suíte completa do produto e a comparação de contrato atual no Node 22 e Node 24. Jobs separados do Node 24 reproduzem a baseline imutável e executam o portão obrigatório de contrato/avaliação: Inspector stdio/HTTP, Conformance, 12 cenários fixos, todos os 13 orçamentos de resposta e a matriz de falhas do GitHub de 11 casos. O portão exige pelo menos 90% de precisão total de cenários e 100% para os seis cenários críticos de segurança, então envia apenas cinco artefatos de resumo limitados. Node 20 não é um runtime suportado porque está em fim de vida; contribuidores locais só precisam de uma versão Node suportada, enquanto a matriz de compatibilidade é aplicada pelo GitHub Actions.

Os resultados de avaliação retêm sua proveniência. scripted significa um fixture determinístico, recorded-agent significa uma execução histórica sanitizada reproduzida contra entradas fixas, e live-model significa uma execução opcional de modelo atual. A CI obrigatória contém seis cenários roteirizados e seis de agente gravado e nenhuma execução de modelo ao vivo. Um replay aprovado prova que o workflow verificado permanece determinístico; não é uma afirmação sobre todo modelo, provedor, prompt futuro ou certificação MCP. Consulte o guia de avaliação.

Testes comuns, contracts:check e contracts:verify-baseline nunca reescrevem a baseline. O comando de replay e o comando contracts:generate somente para mantenedores verificam a tag/commit fixado, instalam o lockfile histórico com scripts de ciclo de vida, auditoria e saída de funding desabilitados, compilam-no no diretório temporário do sistema e usam chamadas reais tools/list e resources/list em um processo filho limitado cujo cwd permanece fora do checkout. Esse filho recebe apenas uma allowlist de variáveis de ambiente de caminho de SO, diretório temporário, locale e biblioteca dinâmica; credenciais, configuração de negócios, NODE_OPTIONS e caminhos de estado local não são herdados. A limpeza no Windows usa tentativas limitadas após a liberação de handles históricos. Os comandos exigem acesso ao registro npm, mas não chamam APIs do GitHub nem serviços de modelo. Apenas contracts:generate escreve o JSON rastreado, deixando seu diff visível para revisão.

Contribua por meio de issues e pull requests

Issues e pull requests são bem-vindos. Verifique as issues abertas e o roadmap antes de começar. Abra uma Issue primeiro quando uma mudança afetar comportamento público, limites de segurança, esquemas de ferramentas ou arquitetura.

1. Faça um fork do repositório e crie um branch focado a partir do main mais recente.
2. Execute npm ci e então faça apenas as mudanças necessárias para a contribuição.
3. Adicione ou atualize testes e documentação quando o comportamento mudar.
4. Execute as verificações relevantes para sua mudança. A matriz Node 22/24 executa npm run check:line-endings, npm run typecheck, npm run build, a forma compilada de npm run contracts:check, npm run test, npm run smoke e npm run test:coverage; jobs separados do Node 24 executam o replay da baseline imutável e os contratos fixados Inspector stdio/HTTP e Conformance.
5. Abra um pull request contra main. Descreva o problema, a solução, os riscos, os resultados de validação e as Issues vinculadas.

Mantenha tokens, credenciais, conteúdo privado do repositório e configuração local gerada fora de commits, Issues, pull requests e logs. Uma execução de CI aprovada apoia a revisão, mas não substitui a aprovação do mantenedor.

• Roadmap
• Guia de política do repositório
• Receitas para clientes e habilidade de revisão portátil
• Continuidade de evidências e rastreabilidade de aceitação
• Plano piloto de usuários
• Estratégia de testes
• Critérios de reentrada para implantação remota
• Notas de versão v1.10.0
• Notas de versão v1.9.0
• Teste de fumaça para agentes de codificação com IA
• Changelog
• Versões
• Problemas em aberto

Os fluxos de trabalho do npm e do MCP Registry usam publicação confiável via GitHub OpenID Connect (OIDC). Publicar uma Release no GitHub aciona ambos os fluxos de trabalho. O fluxo de trabalho do Registry aguarda essa versão exata do pacote npm antes de publicar metadados stdio imutáveis correspondentes.

Licença

MIT