Spec Workflow MCP — Instalar & Demo ao vivo

Name: Spec Workflow MCP Server
Author: Pimzino

Por que usar

Principais recursos

Fluxo sequencial Requisitos → Design → Tarefas com aprovação entre cada etapa
Dashboard web em localhost:5000 com atualizações ao vivo
Extensão VSCode com barra lateral integrada à IDE
Interface em 11 idiomas
Logs de implementação pesquisáveis com estatísticas de código

Demo ao vivo

Como fica na prática

spec-workflow-mcp.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "spec-workflow-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pimzino/spec-workflow-mcp@latest",
        "/path/to/project"
      ]
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "spec-workflow-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pimzino/spec-workflow-mcp@latest",
        "/path/to/project"
      ]
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "spec-workflow-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pimzino/spec-workflow-mcp@latest",
        "/path/to/project"
      ]
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "spec-workflow-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pimzino/spec-workflow-mcp@latest",
        "/path/to/project"
      ]
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "spec-workflow-mcp",
      "command": "npx",
      "args": [
        "-y",
        "@pimzino/spec-workflow-mcp@latest",
        "/path/to/project"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "spec-workflow-mcp": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@pimzino/spec-workflow-mcp@latest",
          "/path/to/project"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add spec-workflow-mcp -- npx -y @pimzino/spec-workflow-mcp@latest /path/to/project

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: Spec Workflow

Construir uma funcionalidade com especificação, não com um prompt improvisado

👤 Devs entregando funcionalidades de complexidade média ⏱ ~90 min intermediate

Quando usar: Você está prestes a pedir ao Claude para "adicionar OAuth" e teme o diff de 500 linhas que vai aparecer de uma vez.

Pré-requisitos

Caminho do projeto conhecido — O MCP é iniciado com /caminho/para/projeto como argumento

Fluxo

Requisitos

Use spec-workflow. Crie uma spec chamada oauth-login. Comece pelos requisitos — o que estamos adicionando, para quem, quais são os não-objetivos?✓ Copiado

→ Documento de requisitos redigido, link para o dashboard de aprovação
Aprovar + Design

Aprovei no dashboard. Agora escreva o design: componentes, modelo de dados, diagrama de sequência, casos de erro.✓ Copiado

→ Documento de design com arquitetura concreta
Tarefas + Executar

Aprovei. Divida em tarefas. Depois execute a tarefa 1.1 — só essa, pare depois.✓ Copiado

→ Lista de tarefas criada; apenas a tarefa 1.1 implementada com entrada no log

Resultado: Uma funcionalidade entregue com artefatos intermediários revisáveis — não um diff misterioso.

Armadilhas

Claude tenta pular direto para o código — O MCP bloqueia — mas seja explícito nos prompts mesmo assim: "não implemente ainda"

Combine com: github · filesystem

Conseguir que um stakeholder não técnico aprove a spec antes do código começar

👤 Times com ciclos de aprovação de PM/design ⏱ ~60 min intermediate

Quando usar: Você precisa da aprovação do PM antes da implementação e o PM não lê PRs do GitHub.

Pré-requisitos

URL do dashboard compartilhável — Faça port-forward ou exponha o localhost:5000 via ngrok para PMs remotos

Fluxo

Spec

Rascunhe o documento de requisitos para checkout-v2 e compartilhe a URL do dashboard.✓ Copiado

→ Documento + link compartilhável
Iterar via feedback

O PM deixou 3 comentários de revisão no dashboard. Busque-os e revise o documento.✓ Copiado

→ Documento atualizado com histórico de revisão visível
Executar após aprovação

A aprovação acabou de passar — prossiga para o design.✓ Copiado

→ Próxima etapa iniciada; timestamp da aprovação registrado

Resultado: Cadeia de aprovação rastreável por stakeholders não técnicos.

Armadilhas

Dashboard inacessível para usuários remotos — Use Tailscale ou ngrok com autenticação

Combine com: github

Combinações

Combine com outros MCPs para 10× de alavancagem

spec-workflow-mcp + github

Abrir um PR por tarefa aprovada

Após executar a tarefa 2.1, abra um PR no GitHub com o título "feat(oauth): task 2.1" e o diff.✓ Copiado

spec-workflow-mcp + filesystem

Salvar specs no repositório junto com o código

Salve a spec aprovada em /docs/specs/oauth-login.md e faça commit.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
create_spec	name: str	Iniciar uma nova funcionalidade	free
write_requirements	spec_id, content: markdown	Primeira fase de qualquer spec	free
write_design	spec_id, content: markdown	Após os requisitos serem aprovados	free
create_tasks	spec_id, tasks: []	Após o design ser aprovado	free
execute_task	spec_id, task_id	Implementar uma tarefa por vez	free
get_approval_status	spec_id, stage	Controlar a passagem para a próxima etapa	free

Custo e limites

O que custa rodar

Cota de API: Local
Tokens por chamada: Proporcional ao tamanho do documento/tarefa
Monetário: Gratuito
Dica: Mantenha os requisitos concisos — o custo da aprovação é tempo humano, não tokens

Segurança

Permissões, segredos, alcance

Escopos mínimos: filesystem-write (for spec docs)

Armazenamento de credenciais: Nenhum

Saída de dados: Nenhum — dashboard em localhost

Não exponha o localhost:5000 para a internet pública sem autenticação

Solução de problemas

Erros comuns e correções

Dashboard não carrega

Inicie explicitamente: npx -y @pimzino/spec-workflow-mcp@latest --dashboard

Verificar: Acesse localhost:5000

Porta 5000 em uso (AirPlay no macOS)

Passe --port 5050 ou desative o AirPlay Receiver nas Configurações do Sistema

Verificar: Verifique com `lsof -i :5000`

Tarefas ficam em pendente após aprovação

O cliente MCP pode estar com cache de resultados antigos — reinicie o cliente

Alternativas

Spec Workflow vs. outros

Alternativa	Quando usar	Troca
Plain Markdown in /docs	Dev solo sem necessidade de loop de aprovação	Sem imposição de estrutura, sem dashboard
Linear MCP	Você já usa o Linear para tarefas e quer que o Claude interaja diretamente com os issues	Sem camada de documento de spec

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills