Agentic SDLC Control Plane (GitHub)

agentic-sdlc-mcp

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

Permita que Claude Code, Cursor e outros clientes do Model Context Protocol (MCP) trabalhem 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 visualiza alterações por padrã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 fornece ao agente contexto limitado e dá aos revisores lacunas de evidência explícitas em vez de outro resumo de formato livre.

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

Como ele se encaixa em um fluxo de trabalho de agente em 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 em que um agente autônomo adivinharia ou dependeria de prosa desatualizada.

Instale via npm

Você precisa do 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 global de CLI:

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.

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á-los. Node.js 22 ou mais recente é necessário.

Conecte um cliente MCP

Adicione o servidor ao Claude Desktop, Cursor, Windsurf ou outro cliente MCP. Injete o token do GitHub pela configuração de segredos 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 ferramenta podem fornecer coordenadas de repositório explicitamente. Use a matriz de permissões do GitHub para conceder apenas os recursos que você ativar.

npx -y agentic-sdlc-mcp configure

Verifique a conexão

Comece com uma chamada somente leitura para 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.

Consulte 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.

Fluxos comuns

Estas sequências reduzem a ambiguidade na 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 em um repositório não produtivo primeiro.

Permissões do GitHub e requisitos de endpoint podem mudar. Confirme falhas na documentação de permissões da API REST do GitHub. Permissões opcionais ausentes podem produzir evidência degradada ou não verificada; 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 ao agente de IA ou cliente MCP ao redor.

• Uma única ferramenta de escrita com pré-visualização: create_issue_set é a única ferramenta de escrita do GitHub e usa dryRun: true como padrão
• Sem mutações privilegiadas no 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
• Gates humanos permanecem externos: o servidor reporta evidências de CODEOWNERS, revisão, política, CI, segurança e release; o GitHub e sua equipe impõem a decisão final
• Evidências permanecem qualificadas: fontes ausentes, obsoletas, truncadas, malformadas ou limitadas por permissão continuam visíveis como lacunas
• A política do repositório está vinculada à base: a política de PR é lida do SHA base quando disponível, para que um pull request não possa enfraquecer silenciosamente seu próprio gate
• Texto externo não é confiável: texto de repositório e do chamador é limitado e escapado; qualquer padrão detectado de sobrescrita de instrução, exfiltração de segredos/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 de scanner e heurísticas de patch reduzem risco, mas fluxo de dados entre arquivos ou em tempo de execução ainda exige CodeQL ou outro teste estático 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 pelo cliente ou variáveis de ambiente; nunca confirme tokens nem os cole em conteúdo de Issue, PR ou logs
• Limite de transporte somente 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 Política de repositório para obter o esquema de .agentic-sdlc.yml, proveniência, limites e comportamento de automodificação com SHA base. Consulte Estratégia de testes para a matriz adversarial e as regras de cobertura.

Política de repositório e recursos

Adicione .agentic-sdlc.yml quando verificações específicas do repositório devem afetar planos, caminhos protegidos, gates de PR, revisores, labels de bloqueio, requisitos de changelog e requisitos de rollback. A saída da política inclui sua ref de origem, SHA de blob, digest, IDs estáveis de regra 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 da era oficial do SDK v2: clientes de 2025 continuam por 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 ativá-lo 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-se apenas a loopback, valida Host e o Origin fornecido antes de analisar um corpo de solicitação limitado, cria um servidor e transporte sem estado e 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 sem estado de 2025 não tem sessão nem identidade de cliente com a qual correlacionar um POST separado de notifications/cancelled a uma solicitaçã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 de stdio e o HTTP de 2026 propagam cancelamento para a solicitaçã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 de deploy remoto; o servidor local atual não é uma base segura de deploy remoto.

Desenvolvimento e links do 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 separado do Inspector stdio fixa o Inspector 2.0.0 atrás do seu próprio lockfile e invoca o dist/index.js real de fora do processo. Ele verifica o initialize legado, todas as 13 declarações de ferramentas, todas as cinco leituras de recursos, uma pré-visualização explícita de zero-escrita create_issue_set, e contratos estáveis de JSON/saída para entrada inválida e um 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 temporário carregado pelo harness. O harness preserva o valor de HOME do usuário, mas bloqueia a sondagem do arquivo de configuração global do produto, substitui as credenciais GitHub herdadas 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 o 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 independente do Inspector stdio, e fecha cada filho após sucesso ou falha. Um fixture separado de loopback 401 com store vazio força a elegibilidade de auto-abertura, mas ainda exige 3/auth_required imediato; um marcador de spawn de navegador faz qualquer tentativa OAuth interativa falhar no portão. O harness permite apenas alvos de fetch/socket de loopback IPv4 exatos; 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 do libuv upstream. O runner aceita apenas essa assinatura exata de plataforma/status/duas linhas e reporta a classe de saída bruta; Linux e qualquer outra falha permanecem fail-closed.

O piloto de Conformance fixa o oficial 0.1.16 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 uma razão, um responsável e uma 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 uma razão para adicionar capacidades de produção somente para teste.

O 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 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. O Node 20 não é um runtime suportado porque está em fim de vida; contribuidores locais só precisam de uma versão suportada do Node, 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. O CI obrigatório contém seis cenários scriptados e seis de agente gravado e nenhuma execução de modelo ao vivo. Uma reprodução bem-sucedida prova que o workflow verificado permanece determinístico; não é uma afirmação sobre cada modelo, provedor, prompt futuro ou certificação MCP. Veja o guia de avaliação.

Testes comuns, contracts:check e contracts:verify-baseline nunca reescrevem a baseline. O comando de reprodução 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 financiamento desabilitados, constroem no diretório temporário do sistema e usam chamadas reais de 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 do 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 novas tentativas limitadas após os handles históricos serem liberados. Os comandos exigem acesso ao registro npm, mas não chamam APIs do GitHub ou serviços de modelo. Apenas contracts:generate escreve o JSON rastreado, deixando seu diff visível para revisão.

Contribua através 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 uma branch focada a partir do main mais recente.
2. Execute npm ci, depois 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 construída de npm run contracts:check, npm run test, npm run smoke e npm run test:coverage; jobs separados do Node 24 executam a reprodução da baseline imutável e os contratos fixados do 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 de repositório privado e configuração local gerada fora de commits, Issues, pull requests e logs. Uma execução de CI bem-sucedida apoia a revisão, mas não substitui a aprovação do mantenedor.

• Roadmap
• Guia de política do repositório
• Estratégia de testes
• Critérios de reentrada para deploy remoto
• Notas de lançamento v1.10.0
• Notas de lançamento v1.9.0
• Teste de fumaça para agente de codificação de IA
• Changelog
• Lançamentos
• Issues abertas

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

Licença

MIT