SDD MCP Server

Servidor MCP em Python para conduzir um fluxo de Spec-Driven Development (SDD) com artefatos versionados, aprovações humanas e implementação orientada por testes.

Estrutura

sdd-mcp-server/
|-- server.py                 # transporte e registro das tools MCP
|-- sdd_server/
|   |-- workflow.py           # regras do pipeline e persistência dos artefatos
|   `-- __init__.py
|-- specs/
|   |-- checkout-flow.md      # formato legado, ainda suportado
|   `-- <feature>/
|       |-- requirements.md
|       |-- design.md
|       |-- tasks.md
|       `-- status.json
|-- skills/
|   |-- skill-*/SKILL.md      # Agent Skills por fase
|   `-- api-rest.md           # skill legada, ainda suportada
|-- test_workflow.py
`-- pyproject.toml

Cada feature nova fica em specs/<feature>/. O arquivo status.json guarda as aprovações das etapas; os Markdown continuam sendo a fonte de verdade revisável no Git. Specs e skills no formato anterior continuam disponíveis pelas tools legadas.

Related MCP server: Omni Skills

Instalação

Com uv:

uv sync
uv run sdd-mcp-server

Com pip:

python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -e .
sdd-mcp-server

No Windows, setup.bat cria o ambiente virtual, instala o projeto e gera configurações MCP com caminhos absolutos.

Transportes

O transporte padrão é stdio, indicado para iniciar o servidor como processo local de um cliente MCP:

python server.py
# ou
sdd-mcp-server

Para Streamable HTTP, o endpoint padrão é http://127.0.0.1:8000/mcp:

python server.py --transport streamable-http

Configure SDD_MCP_HOST e SDD_MCP_PORT para alterar endereço e porta. Para acesso fora da máquina local, coloque o servidor atrás de um proxy com autenticação e TLS; o servidor não configura autenticação por conta própria.

Configuração de clientes

VS Code (.vscode/mcp.json):

{
  "servers": {
    "sddServer": {
      "type": "stdio",
      "command": "C:\\caminho\\para\\sdd-mcp-server\\.venv\\Scripts\\python.exe",
      "args": ["C:\\caminho\\para\\sdd-mcp-server\\server.py"]
    }
  }
}

Claude Code/Desktop (configuração MCP do cliente):

{
  "mcpServers": {
    "sdd-server": {
      "command": "python",
      "args": ["/caminho/absoluto/para/sdd-mcp-server/server.py"]
    }
  }
}

Pipeline

1. steering lê ou inicializa .kiro/steering/constitution.md.

2. spec-init cria a pasta da feature e um rascunho de requirements.md.

3. spec-requirements salva requisitos funcionais, critérios de aceitação e limites de escopo.

4. spec-approve registra a aprovação humana de requirements antes do design.

5. spec-design salva arquitetura, decisões, contratos e estratégia de testes; validate-design verifica as seções obrigatórias.

6. spec-approve registra a aprovação de design antes das tarefas.

7. spec-tasks salva tarefas numeradas e testáveis; spec-approve libera a implementação após a revisão humana.

8. spec-impl prepara o contexto de implementação TDD para todas as tarefas pendentes ou para IDs selecionados.

9. spec-status, spec-feedback e validate-gap acompanham o progresso e apontam lacunas.

Exemplos de invocação:

spec-init {"project_description":"Implementar autenticação JWT com refresh token"}
spec-requirements {"feature_name":"autenticacao-jwt","content":"...markdown dos requisitos..."}
spec-approve {"feature_name":"autenticacao-jwt","stage":"requirements"}
spec-design {"feature_name":"autenticacao-jwt","content":"...markdown do design..."}
validate-design {"feature_name":"autenticacao-jwt"}
spec-approve {"feature_name":"autenticacao-jwt","stage":"design"}
spec-tasks {"feature_name":"autenticacao-jwt","content":"...tarefas em checkboxes numerados..."}
spec-approve {"feature_name":"autenticacao-jwt","stage":"tasks"}
spec-impl {"feature_name":"autenticacao-jwt","tasks":"1,2"}
spec-status {"feature_name":"autenticacao-jwt"}
spec-feedback {"feature_name":"autenticacao-jwt","mode":"report"}
validate-gap {"feature_name":"autenticacao-jwt","implementation_summary":"...resumo com evidências de testes..."}

O servidor bloqueia a gravação de design antes da aprovação dos requisitos, tarefas antes da aprovação do design e contexto de implementação antes da aprovação das tarefas. Editar um artefato invalida sua própria aprovação e as aprovações posteriores. A aprovação deve corresponder a uma decisão explícita do usuário; o servidor não consegue autenticar por conta própria quem forneceu o argumento da tool.

spec-impl fornece instruções e contexto ao agente MCP, mas não altera código de produção diretamente. A implementação e a execução dos testes são feitas pelo agente no workspace. validate-gap verifica o estado do workflow e o resumo informado, mas não inspeciona automaticamente o código-fonte.

As skills por etapa estão em skills/skill-*/SKILL.md e são servidas pelas tools list_skills e get_skill. Comandos slash como /speckit.specify dependem de suporte e configuração do cliente; eles não são registrados pelo protocolo MCP.

Testes

python -m unittest

Para inspecionar o servidor MCP:

npx @modelcontextprotocol/inspector python server.py