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

$3

``bash
npm install -g aic-modernization-mcp-server
`

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

$3

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

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

$3

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

$3

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

Uso

$3

`bash
npm run dev
`

$3

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

$3

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

`json
{
"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)

`json
{
"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)

`json
{
"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"
}
}
}
}
`

$3

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

`json
{
"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:

`json
{
"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

$3

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:
`json
{
"name": "list_symbols",
"arguments": {
"project_id": "project-123",
"symbol_type": "CLASS"
}
}
`

$3

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:
`json
{
"name": "get_symbol_markdown",
"arguments": {
"project_id": "project-123",
"symbol_id": "symbol-456",
"language": "pt_BR"
}
}
`

$3

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

$3

Lista todos os epics de um projeto.

$3

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

$3

Lista todas as user stories de um projeto.

$3

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

Distribuição para Usuários

$3

1. Verifique se está logado no npm:
`bash
npm whoami
`

2. Publicar:
`bash
npm publish --access public
`

Depois, os usuários podem instalar com:
`bash
npm install -g aic-modernization-mcp-server
`

$3

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

1. Criar um tarball:
`bash
npm pack
`

2. Distribuir o arquivo .tgz gerado

3. Usuários instalam com:
`bash
npm install -g aic-modernization-mcp-server-1.0.0.tgz
`

$3

Crie um guia simples para seus usuários:

`markdown


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

$3

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

$3

`bash
npm run build
`

$3

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

Troubleshooting

$3

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

$3

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

`bash
node --version
`

$3

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

`bash
npm config get prefix


Adicione o bin deste caminho ao seu PATH


`

$3

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