convez.ai
MCP ServerDevOps & InfraestruturaAvançado
MikeyVK

Phase-Gate MCP Server

MikeyVK/phase-gate-mcp

Orquestrador de fases e qualidade para agentes IA gerenciarem repositórios

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que orquestra ciclos de desenvolvimento estruturados, impondo fases obrigatórias (pesquisa, design, implementação, validação, etc) e bloqueando progressão até cumprir contratos de qualidade. Integra Git, GitHub, testes (pytest) e verificações de código (Ruff, Pyright) em um fluxo controlado por configuração YAML.

Instalação

$npx convez-ai MikeyVK/phase-gate-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
1
Saúde
28%
Último commit
há 4 semanas
Versão
v4.0.0
Issues abertas
12
Contribuidores
3

Casos de uso

  • Impor ciclos TDD rigorosos e rastreáveis em projetos de equipe
  • Bloquear commits/PRs até completar artefatos (testes, docs, designs)
  • Automatizar transições de fase e validar contratos de entrega
  • Coordenar múltiplos agentes IA em fluxos estruturados sem desvios

Veredito

Solução robusta e opinada para quem quer impor disciplina severa em workflows de IA sobre repositórios. Exige configuração minuciosa (YAML complexo) e integração com CI/GitHub, não é plug-and-play — recomendado para equipes que precisam auditoria rigorosa e rastreabilidade de fases.

README

A tradução para o português deste README ainda está na fila.

Phase-Gate MCP Server

An MCP (Model Context Protocol) server that enforces structured software development lifecycles. It gives AI agents a toolset to navigate, manage, and execute work strictly within predefined project phases — ensuring consistent state management, quality enforcement, and repository orchestration.


For AI Agents

STOP. Do not guess. Do not scan random files.

Read AGENTS.md immediately to initialize your cooperation protocol. It contains the binding tool priority matrix, TDD cycle protocol, three-agent model, and all operating constraints.

For MCP server architecture details, see docs/reference/mcp/mcp_vision_reference.md.


What It Does

Phase-Gate MCP Server acts as an orchestrator and gatekeeper between an AI agent and a software repository. Rather than allowing arbitrary modifications, it mandates a structured workflow and prevents phase progression until all deliverables and quality contracts are fulfilled.

Supported workflow types: feature, bug, refactor, docs, hotfix, epic, custom

Each workflow defines an ordered sequence of phases (e.g. research → design → planning → implementation → validation → documentation → ready). The server tracks which phase is active, enforces transitions, and manages TDD cycle state within implementation phases.


Core Capabilities

  • Phase & cycle state management — tracks active phase and TDD cycle via .phase-gate/state.json; blocks progression until contracts are met
  • Intelligent scaffolding — generates code, documents, and test files from a centralised template registry with schema validation
  • Quality gates — runs Ruff (format + lint), Pyright, import checks, and line-length checks before allowing commits or PRs
  • Repository orchestration — native Git and GitHub integrations for branching, committing, PR creation, issue tracking, and label management
  • Config-driven policy enforcement — workflow rules, phase contracts, artifact requirements, and quality thresholds defined in YAML

Architecture

mcp_server/
├── core/          # Phase state engine, proxy, operation notes, error handling
├── managers/      # State persistence, git operations, pytest runner, QA manager
├── tools/         # MCP tool interfaces exposed to the agent
├── scaffolders/   # Jinja2 template engine and scaffold orchestration
├── scaffolding/   # Templates, template registry, version hashing
├── validation/    # File and artifact validators
├── config/        # Settings, schema loading, config contracts
└── schemas/       # Pydantic schemas for all internal contracts

Configuration lives in .phase-gate/config/ (per-project, not in this repo):

FilePurpose
workflows.yaml / workphases.yamlPhase sequences and lifecycle states
policies.yaml / enforcement.yamlTransition rules and strictness levels
artifacts.yaml / contracts.yamlExpected deliverables per phase
quality.yamlActive quality gates and thresholds
git.yamlBranch naming conventions

Environment Variables

VariableRequiredDescription
MCP_WORKSPACE_ROOTYesAbsolute path to the repository root
MCP_SERVER_PROJECT_DIRNoPhase-gate config dir (default: .phase-gate)
GITHUB_TOKENYesPersonal access token with repo and workflow scopes
GITHUB_OWNERYesGitHub account or org name
GITHUB_REPOYesRepository name
GITHUB_PROJECT_NUMBERNoGitHub Projects number for issue tracking
MCP_SERVER_NAMENoServer name reported in MCP handshake (default: phase-gate-mcp)
LOG_LEVELNoLogging verbosity (default: INFO)

Installation

Requirements: Python 3.11+

git clone https://github.com/MikeyVK/phase-gate-mcp.git
cd phase-gate-mcp
pip install -e .[dev]

Starting the server

The entry point is mcp_server.core.proxy — a thin proxy that handles stdio transport and auto-restart on exit code 42:

python -m mcp_server.core.proxy

For MCP client configuration, see docs/setup/mcp.json for a reference server definition.


Running Tests

pytest tests/mcp_server/

For coverage:

pytest tests/mcp_server/ --cov=mcp_server --cov-branch --cov-fail-under=90

License

(Specify License Information Here)

Ver o original no GitHub

Bom para

Relacionados