@marcelocorrea/mcp-plan

MCP server for intelligent software feature planning

Servidor MCP (Model Context Protocol) para geração inteligente de planos de implementação de features de software. Detecta automaticamente o tipo de projeto (Laravel, NestJS, Next.js, Django, etc.), mantém memória persistente e gera planos estruturados sempre no mesmo formato fixo de 10 seções em português.

Características

• 🔍 Detecção Automática de Stack: Identifica Laravel, NestJS, Next.js, Django e outros frameworks
• 📝 Formato Fixo: Gera sempre 10 seções obrigatórias com estrutura consistente
• 💾 Memória Persistente: Salva contexto, perguntas e decisões em .ai/
• ❓ Perguntas Explícitas: Marca perguntas como [BLOQUEIA] ou [NICE]
• 📁 Inventário Completo: Lista todos os arquivos a criar/modificar por fase
• 💻 Snippets de Código: Inclui exemplos de migrations, models, controllers, testes
• ✅ Validação Automática: Detecta planos vagos ou incompletos
• 🔄 Refinamento Iterativo: Loop de 1-3 iterações com crítica e correção automática

Instalação

npm install -g @marcelocorrea/mcp-plan

Configuração no Claude Desktop (via Codex CLI)

Adicione ao seu arquivo ~/.codex/config.toml:

[mcpServers.mcp-plan]
command = "mcp-plan"
args = ["--projectRoot", "/path/to/your/project"]

Ou com opções adicionais:

[mcpServers.mcp-plan]
command = "mcp-plan"
args = [
  "--projectRoot", "/home/user/my-project",
  "--memoryDir", ".ai",
  "--logLevel", "warn"
]

Ferramentas Disponíveis

1. repo.inspect

Inspeciona um projeto e detecta stack, estrutura, comandos e padrões de banco de dados.

Entrada:

{
  "projectRoot": "/path/to/project"
}

Saída:

{
  "stack": {
    "name": "laravel",
    "version": "10.x",
    "confidence": 95,
    "evidence": ["laravel/framework in composer.json", "artisan file exists"]
  },
  "structure": {
    "srcDirectories": ["app/", "resources/js/"],
    "testDirectories": ["tests/"],
    "configFiles": ["composer.json", "artisan"]
  },
  "commands": {
    "test": "php artisan test",
    "lint": "vendor/bin/pint",
    "build": "npm run build"
  },
  "database": {
    "orm": "eloquent",
    "migrationsPath": "database/migrations/"
  }
}

2. context.get

Recupera contexto persistente de .ai/context.json.

Entrada:

{
  "projectRoot": "/path/to/project"
}

3. context.upsert

Atualiza contexto persistente em .ai/context.json.

Entrada:

{
  "projectRoot": "/path/to/project",
  "updates": {
    "preferences": {
      "language": "pt-BR"
    }
  }
}

4. plan.generate

Gera um plano estruturado em português com 10 seções obrigatórias.

Entrada:

{
  "projectRoot": "/path/to/project",
  "feature": "Sistema de Autenticação",
  "businessContext": "Aplicativo de gestão de tarefas que precisa de login seguro"
}

Saída: String markdown com o plano completo.

5. plan.critic

Valida um plano e retorna problemas com severidade.

Entrada:

{
  "planContent": "# Plano: ..."
}

Saída:

{
  "valid": false,
  "issues": [
    {
      "type": "blocker",
      "section": "Perguntas",
      "message": "Pergunta sem tag: \"Qual banco de dados?\". Adicione [BLOQUEIA] ou [NICE]."
    }
  ],
  "suggestions": ["Considere adicionar mais snippets de código"],
  "score": 75
}

6. plan.refine

Executa loop iterativo de refinamento (1-3 iterações).

Entrada:

{
  "projectRoot": "/path/to/project",
  "feature": "Sistema de Notificações",
  "businessContext": "...",
  "maxIterations": 3
}

Saída:

{
  "success": true,
  "finalPlan": "# Plano: ...",
  "iterations": [
    {
      "iteration": 1,
      "validation": { "valid": false, "issues": [...] }
    },
    {
      "iteration": 2,
      "validation": { "valid": true, "issues": [] }
    }
  ],
  "message": "Plano refinado com sucesso em 2 iteração(ões). Score: 95/100."
}

7. plan.save

Persiste o plano em PLAN.md e atualiza arquivos em .ai/.

Entrada:

{
  "projectRoot": "/path/to/project",
  "planContent": "# Plano: ..."
}

Estrutura de Arquivos Gerados

seu-projeto/
├── PLAN.md                    # Plano gerado (output principal)
└── .ai/
    ├── context.json          # Contexto do projeto (inspeção, preferências)
    ├── questions.md          # Perguntas abertas e respondidas
    ├── decisions.md          # Decisões arquiteturais
    ├── worklog.md           # Log de execução (opcional)
    └── PLAN_TEMPLATE.md     # Template fixo das 10 seções

Formato do Plano

Todos os planos seguem exatamente esta estrutura:

1. # Plano: <TITULO>
2. ## Resumo
3. ## Contexto do Negócio
4. ## Perguntas (obrigatórias) - Com tags [BLOQUEIA] ou [NICE]
5. ## Premissas
6. ## Esquema de Banco de Dados - Tabelas em markdown
7. ## Arquivos a Criar/Modificar - Por fases (Documentação, Backend, Frontend, Testes)
8. ## Detalhes de Implementação - Com snippets de código
9. ## Ordem de Execução
10. ## Verificação - Comandos de teste e validação

Exemplo de Uso

# 1. Inspecionar projeto
mcp-plan
# (Em Claude Desktop, chamar: repo.inspect({ projectRoot: "/path/to/project" }))

# 2. Gerar plano
# (Chamar: plan.generate({ projectRoot: "...", feature: "Sistema de Notificações", businessContext: "..." }))

# 3. Validar plano
# (Chamar: plan.critic({ planContent: "..." }))

# 4. Refinar automaticamente
# (Chamar: plan.refine({ projectRoot: "...", feature: "...", maxIterations: 3 }))

# 5. Salvar plano
# (Chamar: plan.save({ projectRoot: "...", planContent: "..." }))

Stacks Suportados

• Laravel (PHP) - Detecta via composer.json + artisan
• NestJS (TypeScript) - Detecta via nest-cli.json
• Next.js (React) - Detecta via next.config.js
• Django (Python) - Detecta via manage.py
• React (genérico) - Detecta via package.json
• Generic (fallback) - Para projetos não detectados

Flags CLI

mcp-plan [opções]

Opções:
  --projectRoot <path>    Caminho do projeto (padrão: diretório atual)
  --memoryDir <path>      Diretório de memória (padrão: .ai)
  --template <path>       Caminho do template customizado
  --http                  Habilitar transport HTTP (padrão: STDIO)
  --port <number>         Porta HTTP (padrão: 3000)
  --logLevel <level>      Nível de log (padrão: info)

Desenvolvimento

# Instalar dependências
npm install

# Desenvolvimento (com hot reload)
npm run dev

# Build
npm run build

# Testes
npm test

# Lint
npm run lint

Segurança

• ✅ Validação rigorosa de paths (previne path traversal)
• ✅ Nenhuma execução de código arbitrário
• ✅ Limite de tamanho de arquivos lidos (1MB por arquivo)
• ✅ Ignora node_modules/, .git/, vendor/ automaticamente

Licença

MIT © Marcelo Correa

Links

• GitHub
• NPM
• Documentação MCP