GenSpec MCP Server

Converte um arquivo USER-STORIES.md em documentos README, ROADMAP e SYSTEM-ARCHITECTURE para o fluxo de trabalho GenSpec.

GitHubExperimente este MCPPatrocinado

Documentação

GenSpec MCP Server

Um servidor Model Context Protocol (MCP) que converte histórias de usuário em documentação estruturada, incluindo documentos README, ROADMAP e SYSTEM-ARCHITECTURE, por meio de um fluxo de trabalho guiado de aprovação.

Visão Geral

O GenSpec MCP Server simplifica o processo de criação de documentação ao receber histórias de usuário como entrada e gerar três artefatos principais de documentação:

  • README.md - Visão geral do projeto e instruções de configuração
  • ROADMAP.md - Roteiro de desenvolvimento e marcos
  • SYSTEM-ARCHITECTURE.md - Documentação da arquitetura técnica

O servidor utiliza um fluxo de trabalho de continuação em que cada fase pode ser aprovada ou editada antes de prosseguir para a próxima fase, garantindo uma saída de documentação de alta qualidade.

Recursos

  • Integração MCP - Funciona perfeitamente com Claude Desktop, VS Code com extensão MCP e Cursor
  • Geração Baseada em Modelos - Utiliza modelos predefinidos para uma estrutura de documentação consistente
  • Fluxo de Aprovação - Ciclo Gerar → Apresentar → Aprovar/Editar para cada documento
  • Dependências de Fase - ROADMAP requer README, SYSTEM-ARCHITECTURE requer ambos
  • Múltiplos Pontos de Entrada - Comece em qualquer fase ou execute o fluxo de trabalho completo
  • Acesso a Recursos - Expõe modelos por meio do protocolo de recursos MCP

Instalação

Pré-requisitos

  • Node.js 18.0.0 ou superior
  • Gerenciador de pacotes npm ou yarn

Instalar a partir do npm

npm install -g genspec-mcp

Instalar a partir do código-fonte

git clone <repository-url>
cd genspec-mcp
npm install
npm run build

Integração com Clientes MCP

Claude Desktop

Adicione ao seu arquivo de configuração do Claude Desktop:

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

{
  "mcpServers": {
    "genspec": {
      "command": "npx",
      "args": ["genspec-mcp"]
    }
  }
}

VS Code com Extensão MCP

  1. Instale a extensão MCP para VS Code
  2. Adicione às configurações do VS Code ou à configuração MCP:
{
  "mcp.servers": {
    "genspec": {
      "command": "npx",
      "args": ["genspec-mcp"]
    }
  }
}

Cursor

Adicione à sua configuração MCP do Cursor:

{
  "mcpServers": {
    "genspec": {
      "command": "npx",
      "args": ["genspec-mcp"]
    }
  }
}

Uso

O servidor GenSpec MCP oferece várias maneiras de iniciar o fluxo de trabalho de geração de documentação:

Ferramentas Disponíveis

  • start_genspec - Executa o fluxo de trabalho completo: README → ROADMAP → SYSTEM-ARCHITECTURE
  • generate_readme - Gera o README e continua pelo ROADMAP → SYSTEM-ARCHITECTURE
  • generate_roadmap - Gera o ROADMAP e continua pelo SYSTEM-ARCHITECTURE
  • generate_architecture - Gera apenas o SYSTEM-ARCHITECTURE

Prompts Disponíveis

  • /start-genspec - Invoca a ferramenta start_genspec
  • /start-readme - Invoca a ferramenta generate_readme
  • /start-roadmap - Invoca a ferramenta generate_roadmap
  • /start-arch - Invoca a ferramenta generate_architecture

Métodos de Entrada

O servidor aceita histórias de usuário em três ordens de prioridade:

  1. Texto inline - Envie histórias de usuário diretamente como parâmetro userStory
  2. Referência URI - Forneça userStoryUri para o cliente buscar via MCP ReadResource
  3. Arquivo local - Recorre a USER-STORIES.md no diretório atual

Exemplo de Fluxo de Trabalho

  1. Inicie o fluxo de trabalho:

    Use the /start-genspec prompt or start_genspec tool

  2. Revise e aprove/edite:

    • O documento gerado é apresentado para revisão
    • Responda com termos de aprovação: "approve", "approved", "ok", "okay", "yes", "y", "lgtm"
    • Ou forneça feedback de edição para regenerar

  3. Continue pelas fases:

    • Após a aprovação, o fluxo de trabalho continua para a próxima fase
    • Cada fase segue o mesmo ciclo gerar → apresentar → aprovar/editar

Estrutura de Arquivos

genspec-mcp/
├── dist/                   # Compiled JavaScript files
├── src/                    # TypeScript source files
│   ├── index.ts           # MCP server entry point
│   ├── server.ts          # GenSpecServer implementation
│   ├── types.ts           # Type definitions and constants
│   └── utils/             # Utility modules (Track B, C, D)
├── templates/              # Generation templates
│   ├── 1-generate-readme.md
│   ├── 2-generate-roadmap.md
│   └── 3-generate-system-architecture.md
├── _ai/docs/              # Generated documentation output
├── package.json           # Package configuration
├── tsconfig.json          # TypeScript configuration
└── README.md              # This file

Saída Gerada

Todos os documentos gerados são salvos no diretório _ai/docs/:

  • _ai/docs/README.md - README do projeto gerado
  • _ai/docs/ROADMAP.md - Roteiro de desenvolvimento gerado
  • _ai/docs/SYSTEM-ARCHITECTURE.md - Arquitetura de sistema gerada

Desenvolvimento

Compilação

npm run build

Modo de Desenvolvimento

npm run dev

Executando Testes

npm test

Solução de Problemas

Problemas Comuns

Problema: servidor MCP não detectado pelo cliente

  • Solução: Garanta que o servidor esteja instalado corretamente e que a sintaxe do arquivo de configuração esteja correta
  • Verificação: Reinicie seu cliente MCP após alterações de configuração

Problema: erro "ERR_MISSING_USER_STORIES"

  • Solução: Forneça histórias de usuário por um dos três métodos suportados (inline, URI ou arquivo local)
  • Verificação: Garanta que USER-STORIES.md exista se estiver usando o fallback de arquivo local

Problema: erro "ERR_MISSING_PREREQUISITES"

  • Solução: Gere primeiro as fases de pré-requisito (README antes de ROADMAP, README e ROADMAP antes de SYSTEM-ARCHITECTURE)
  • Verificação: Use ferramentas de fluxo de trabalho de continuação que incluam os pré-requisitos

Problema: Modelos não carregando

  • Solução: Verifique se o diretório templates/ existe e contém os arquivos de modelo necessários
  • Verificação: Garanta que o pacote foi instalado corretamente com todos os arquivos

Problema: Erros de permissão ao gravar em _ai/docs/

  • Solução: Garanta que o diretório atual seja gravável e que o diretório _ai/docs/ possa ser criado
  • Verificação: Execute a partir de um diretório onde você tenha permissões de gravação

Depuração

Ative o registro de depuração definindo a variável de ambiente DEBUG:

DEBUG=genspec:* npx genspec-mcp

Obtendo Ajuda

  • Consulte a especificação MCP para detalhes do protocolo
  • Revise os arquivos de modelo no diretório templates/ para a lógica de geração
  • Registre problemas ou solicitações de recursos no repositório do projeto

Requisitos do Sistema

  • Node.js: 18.0.0 ou superior
  • Memória: Mínimo de 512MB de RAM disponível
  • Espaço em Disco: 50MB para instalação e arquivos gerados
  • Rede: Conexão com a internet para instalação via npm

Dependências

Dependências de Produção

  • @modelcontextprotocol/sdk - Implementação do protocolo MCP
  • typescript - Compilador e runtime TypeScript
  • tsx - Mecanismo de execução TypeScript

Dependências de Desenvolvimento

  • @types/node - Definições de tipos do Node.js

Arquitetura

O servidor GenSpec MCP segue uma arquitetura modular com cinco trilhas principais:

Componentes Principais

  • GenSpecServer (src/server.ts) - Implementação principal do servidor MCP
  • Sistema de Tipos (src/types.ts) - Definições de tipos e constantes
  • Sistema de Modelos (src/utils/templates.ts) - Carregamento e gerenciamento de modelos
  • Geração de Documentos (src/utils/llm.ts) - Interface de geração e construção de contexto
  • Sistema de Validação (src/utils/validation.ts) - Validação de entrada e verificação de pré-requisitos
  • Sistema de Aprovação (src/utils/approval.ts) - Detecção de aprovação e feedback de edição
  • Gerenciamento de Fases (src/utils/phases.ts) - Execução e coordenação do fluxo de trabalho

Suporte ao Protocolo MCP

  • Prompts - Prompts no estilo de comando que invocam ferramentas
  • Recursos - Acesso a modelos via esquema de URI template://
  • Ferramentas - Ferramentas de fluxo de trabalho de geração de documentos

Gerenciamento do Fluxo de Trabalho

  • Dependências de Fase - Garante a ordem correta de geração
  • Lógica de Continuação - Transições perfeitas entre fases
  • Concorrência de Fluxo Único - Evita fluxos de trabalho conflitantes por workspace
  • Ciclos de Aprovação - Até 5 ciclos de edição por fase antes da interrupção

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.