Servidor MCP para API de Documentação AI Cockpit

Este servidor MCP (Model Context Protocol) expõe a API de documentação do AI Cockpit Modernization para consumo em editores como VSCode/Kilocode.

Instalação

Opção 1: Instalação Global (Recomendado para Distribuição)

npm install -g aic-modernization-mcp-server

Após instalar globalmente, o comando aic-mcp-server estará disponível no PATH.

Opção 2: Via npx (Sem Instalação) ⭐ Recomendado para Distribuição

O servidor pode ser executado diretamente via npx sem instalação:

npx -y aic-modernization-mcp-server

Como funciona: O npx baixa o pacote do npm na primeira execução e mantém em cache. Nas próximas vezes, usa do cache. Perfeito para distribuição porque os usuários não precisam executar comandos no terminal!

💡 Veja explicação detalhada em: NPX_EXPLAINED.md

Opção 3: Instalação Local (Desenvolvimento)

cd mcp-server
npm install
npm run build

Configuração

O servidor MCP requer as seguintes variáveis de ambiente:

• AIC_API_URL: URL base da API Python (FastAPI) (padrão: http://localhost:3000)
• AIC_API_TOKEN: Token de autenticação para a API (opcional, mas recomendado)

Importante: O http://localhost:3000 se refere à API Python (FastAPI) que deve estar rodando. O servidor MCP é um cliente que faz chamadas HTTP para essa API.

💡 Veja a arquitetura completa em: ARCHITECTURE.md

Exemplo de configuração

export AIC_API_URL="https://api.aicockpit.com"
export AIC_API_TOKEN="seu-token-aqui"

Uso

Modo Desenvolvimento

npm run dev

Modo Produção

npm start
# ou se instalado globalmente:
aic-mcp-server

O servidor MCP se comunica via STDIN/STDOUT usando o protocolo MCP.

Configuração no VSCode/Kilocode

VSCode (settings.json)

Opção A: Comando Global (Após npm install -g)

{
  "mcp.servers": {
    "aic-documentation": {
      "command": "aic-mcp-server",
      "env": {
        "AIC_API_URL": "http://localhost:3000",
        "AIC_API_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Opção B: Via npx (Sem instalação global)

{
  "mcp.servers": {
    "aic-documentation": {
      "command": "npx",
      "args": ["aic-modernization-mcp-server"],
      "env": {
        "AIC_API_URL": "http://localhost:3000",
        "AIC_API_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Opção C: Caminho Local (Desenvolvimento)

{
  "mcp.servers": {
    "aic-documentation": {
      "command": "node",
      "args": ["/caminho/absoluto/para/mcp-server/dist/index.js"],
      "env": {
        "AIC_API_URL": "http://localhost:3000",
        "AIC_API_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Kilocode

No Kilocode, a configuração é similar. Adicione no arquivo de configuração do editor:

{
  "mcpServers": {
    "aic-documentation": {
      "command": "aic-mcp-server",
      "env": {
        "AIC_API_URL": "http://localhost:3000",
        "AIC_API_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Nota: O Kilocode usa mcpServers (camelCase) ao invés de mcp.servers.

Alternativa com npx:

{
  "mcpServers": {
    "aic-documentation": {
      "command": "npx",
      "args": ["-y", "aic-modernization-mcp-server"],
      "env": {
        "AIC_API_URL": "http://localhost:3000",
        "AIC_API_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Tools Disponíveis

1. list_symbols

Lista todos os symbols de um projeto.

Parâmetros:

• project_id (obrigatório): ID do projeto
• symbol_type (opcional): Filtrar por tipo de symbol

Exemplo:

{
  "name": "list_symbols",
  "arguments": {
    "project_id": "project-123",
    "symbol_type": "CLASS"
  }
}

2. get_symbol_markdown

Obtém a documentação Markdown de um symbol específico por ID.

Parâmetros:

• project_id (obrigatório): ID do projeto
• symbol_id (obrigatório): ID do symbol
• language (opcional): Idioma (en_US ou pt_BR)

Exemplo:

{
  "name": "get_symbol_markdown",
  "arguments": {
    "project_id": "project-123",
    "symbol_id": "symbol-456",
    "language": "pt_BR"
  }
}

3. get_symbol_markdown_by_name

Obtém a documentação Markdown de um symbol por nome.

Parâmetros:

• project_id (obrigatório): ID do projeto
• symbol_name (obrigatório): Nome do symbol
• symbol_type (opcional): Filtrar por tipo
• language (opcional): Idioma

4. list_epics

Lista todos os epics de um projeto.

5. get_epic_markdown

Obtém a documentação Markdown de um epic específico.

6. list_user_stories

Lista todas as user stories de um projeto.

7. get_user_story_markdown

Obtém a documentação Markdown de uma user story específica.

Distribuição para Usuários

Publicar no npm (Recomendado)

1. Verifique se está logado no npm:

npm whoami

2. Publicar:

npm publish --access public

Depois, os usuários podem instalar com:

npm install -g aic-modernization-mcp-server

Distribuir como Pacote Local

Se preferir não publicar no npm público, você pode:

1. Criar um tarball:

npm pack

2. Distribuir o arquivo .tgz gerado

3. Usuários instalam com:

npm install -g aic-modernization-mcp-server-1.0.0.tgz

Instruções para Usuários Finais

Crie um guia simples para seus usuários:

## Instalação do Servidor MCP

1. Instale o servidor MCP:
   ```bash
   npm install -g aic-modernization-mcp-server

2. Configure no Kilocode/VSCode usando uma das opções acima

3. Defina as variáveis de ambiente com sua URL da API e token

## Desenvolvimento

### Estrutura do Projeto

mcp-server/ ├── src/ │ └── index.ts # Código principal do servidor MCP ├── dist/ # Código compilado (gerado) ├── package.json ├── tsconfig.json └── README.md

### Build

```bash
npm run build

Testes

Para testar o servidor MCP localmente, você pode usar o cliente MCP ou integrá-lo diretamente no editor.

Troubleshooting

Erro de Conexão com a API

Verifique:

1. Se a API está rodando (AIC_API_URL)
2. Se o token de autenticação está correto (AIC_API_TOKEN)
3. Se há firewall/proxy bloqueando a conexão

Erro de Compilação

Certifique-se de que está usando Node.js >= 18.0.0:

node --version

Comando não encontrado após instalação global

Verifique se o diretório npm global bin está no PATH:

npm config get prefix
# Adicione o bin deste caminho ao seu PATH

Logs

O servidor MCP escreve logs de erro no stderr. Verifique os logs do editor para mais detalhes.

Exemplos de Uso

Para ver exemplos práticos de como usar o servidor MCP no Reasoning/Kilocode, incluindo prompts para buscar user stories e solicitar modernização, consulte: USAGE_EXAMPLES.md

Licença

MIT