npm package: @marcelocorrea/mcp-plan
Description: MCP server for intelligent software feature planning
Author: Marcelo Correa
Latest version: 1.0.1

# @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

```bash
npm install -g @marcelocorrea/mcp-plan
```

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

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

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

Ou com opções adicionais:

```toml
[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:**
```json
{
  "projectRoot": "/path/to/project"
}
```

**Saída:**
```json
{
  "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:**
```json
{
  "projectRoot": "/path/to/project"
}
```

### 3. `context.upsert`

Atualiza contexto persistente em `.ai/context.json`.

**Entrada:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "planContent": "# Plano: ..."
}
```

**Saída:**
```json
{
  "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:**
```json
{
  "projectRoot": "/path/to/project",
  "feature": "Sistema de Notificações",
  "businessContext": "...",
  "maxIterations": 3
}
```

**Saída:**
```json
{
  "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:**
```json
{
  "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

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

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

```bash
# 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](https://github.com/maximweb/mcp-plan)
- [NPM](https://www.npmjs.com/package/@marcelocorrea/mcp-plan)
- [Documentação MCP](https://modelcontextprotocol.io)