# 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

```text
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.

## Instalação

Com `uv`:

```bash
uv sync
uv run sdd-mcp-server
```

Com `pip`:

```bash
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:

```bash
python server.py
# ou
sdd-mcp-server
```

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

```bash
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`):

```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):

```json
{
  "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:

```text
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

```bash
python -m unittest
```

Para inspecionar o servidor MCP:

```bash
npx @modelcontextprotocol/inspector python server.py
```