aidemd-mcp

@aidemd-mcp/server

Servidor MCP que traz desenvolvimento orientado por intenção para qualquer IDE com IA. Gerencie arquivos de especificação .aide que ficam ao lado do seu código — o contexto de domínio a partir do qual arquitetos planejam, implementadores constroem e QA valida.

Saiba mais em aidemd.dev.

Recursos

• Descoberta de especificações em todo o projeto com uma árvore de divulgação progressiva que revela especificações de intenção, pesquisa e QA em todos os níveis do seu codebase
• Bootstrap de projeto com um comando via aide_init — conecta documentos de metodologia, comandos de pipeline e este servidor MCP ao seu projeto em um único fluxo guiado
• Aplicação automática de convenções de nomenclatura — aide_scaffold lida com as regras de renomeação .aide / intent.aide para que você nunca crie especificações conflitantes
• Validação de verificação de saúde via aide_validate — detecta especificações órfãs, descrições ausentes, links quebrados e conflitos de nomenclatura antes que causem desvio
• Introspecção de código via aide_inspect — retorna JSDoc, assinaturas e tipo para símbolos nomeados sem abrir arquivos, dando aos agentes divulgação progressiva de Nível 2 para código
• Detecção de desvio de atualização via aide_upgrade — compara os artefatos de metodologia AIDE do seu projeto com versões canônicas e escreve atualizações por categoria
• Ponto de entrada do cérebro em tempo de execução via aide_brain — ferramenta sob demanda que retorna prosa pronta para execução dizendo ao agente quais ferramentas MCP chamar e como alcançar qualquer backend de cérebro conectado, sem que o agente saiba qual backend é

Instalação

Início Rápido (Claude Code)

O caminho mais rápido é um único comando npx que configura tudo automaticamente:

npx @aidemd-mcp/server@latest init

Este comando:

• Mescla a entrada do servidor MCP AIDE em .mcp.json
• Mescla uma entrada MCP de cérebro placeholder em .mcp.json (caminho do vault preenchido por /aide)
• Escreve todos os comandos de barra do pipeline em .claude/commands/aide/
• Instala 9 agentes de pipeline canônicos em .claude/agents/aide/
• Instala habilidades (study-playbook, brain) em .claude/skills/
• Instala o hub de documentos de metodologia em .aide/docs/
• Escreve o lançador aide-tree em .aide/bin/aide-tree.mjs
• Adiciona um selo AIDE a README.md (anexa se não estiver presente)

Todas as operações são aditivas — arquivos que já existem nunca são sobrescritos. Seguro para executar novamente a qualquer momento.

Passe --vault-path <path> para registrar a localização do vault do seu cérebro no momento da instalação, pulando o prompt de caminho do vault quando /aide for executado pela primeira vez.

Após a execução, abra o Claude Code e execute /aide — o orquestrador solicitará qualquer configuração que o cli não conseguiu concluir (escolha da IDE, caminho do vault se não fornecido).

Sincronizando brain.aide para .mcp.json

Execute isto após editar .aide/config/brain.aide — por exemplo, quando você atualizar o argumento do caminho do vault em mcpServerConfig.args ou renomear o cérebro no campo name:

npx @aidemd-mcp/server@latest sync

sync lê .aide/config/brain.aide, copia mcpServerConfig literalmente para .mcp.json sob a chave fixa brain, e escreve o campo name como o rótulo do servidor. Todas as outras chaves em mcpServers (incluindo sua entrada aide e quaisquer integrações MCP pessoais) são deixadas byte-idênticas. Se uma chave legada obsidian estiver presente, ela é removida na mesma escrita. O comando é idempotente — executá-lo duas vezes produz os mesmos bytes de .mcp.json, e a segunda invocação imprime already in sync sem tocar no arquivo. O código de saída é 0 em caso de sucesso (incluindo o caso sem alterações), 1 em caso de brain.aide ausente ou malformado ou .mcp.json inválido, e 2 em caso de --help.

Exemplo de saída após atualizar o caminho do vault em mcpServerConfig.args:

Read .aide/brain.aide
Wrote brain MCP entry into .mcp.json
  command: npx
  args: [-y, obsidian-mcp, D:/notes/new-vault]
Done.

Configuração Manual

Se você usa um cliente diferente do Claude Code, ou prefere configurar manualmente, adicione a entrada do servidor ao arquivo de configuração MCP do seu cliente.

Claude Code

claude mcp add aide npx -- -y @aidemd-mcp/server@latest

Ou adicione ao .mcp.json do seu projeto:

{
  "mcpServers": {
    "aide": {
      "command": "npx",
      "args": ["-y", "@aidemd-mcp/server@latest"]
    }
  }
}

[!NOTE] O comando de Início Rápido acima lida com isso automaticamente para usuários do Claude Code.

Claude Desktop

Locais dos arquivos de configuração:

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

{
  "mcpServers": {
    "aide": {
      "command": "npx",
      "args": ["-y", "@aidemd-mcp/server@latest"]
    }
  }
}

[!NOTE] O Claude Desktop não herda o PATH do terminal. Se você usa nvm ou Homebrew para gerenciar o Node, npx pode não ser encontrado. Execute which npx no seu terminal para obter o caminho absoluto e substitua "npx" por ele na configuração acima.

O Claude Desktop requer uma saída e reabertura completas após qualquer alteração de configuração.

Cursor

Adicione a ~/.cursor/mcp.json:

{
  "mcpServers": {
    "aide": {
      "command": "npx",
      "args": ["-y", "@aidemd-mcp/server@latest"]
    }
  }
}

VS Code / Copilot

Adicione a .vscode/mcp.json:

{
  "servers": {
    "aide": {
      "command": "npx",
      "args": ["-y", "@aidemd-mcp/server@latest"]
    }
  }
}

[!NOTE] VS Code / Copilot usa "servers" como a chave raiz, não "mcpServers". Usar a chave raiz errada faz com que o servidor falhe silenciosamente ao carregar.

Windsurf

Adicione a ~/.windsurf/mcp.json:

{
  "mcpServers": {
    "aide": {
      "command": "npx",
      "args": ["-y", "@aidemd-mcp/server@latest"]
    }
  }
}

Ferramentas

aide_discover

Escaneie o projeto em busca de arquivos de especificação .aide e retorne um mapa de árvore de divulgação progressiva mostrando o tipo, localização e resumo de cada especificação.

Entradas:

• path (string, opcional): Subdiretório para aprofundar. Quando fornecido, a resposta abre com a cadeia de ancestrais — a linhagem de intenção em cascata da raiz ao alvo, cada ancestral mostrando sua descrição e status de alinhamento — seguida pela subárvore detalhada com resumos e avisos. Quando omitido, retorna um mapa superficial de todo o projeto (apenas localizações e tipos).

aide_read

Leia um arquivo de especificação .aide com contexto completo, retornando o conteúdo do arquivo, seu tipo classificado (intenção/pesquisa/plano/todo), especificações relacionadas no mesmo diretório e links encontrados no conteúdo.

Entradas:

• path (string, obrigatório): Caminho para o arquivo .aide a ser lido.

aide_scaffold

Crie novos arquivos de especificação .aide com aplicação automática de convenções de nomenclatura. Lida com as regras de renomeação: especificações de intenção são .aide por padrão, mas tornam-se intent.aide quando research.aide existe na mesma pasta; criar um research.aide renomeia automaticamente qualquer .aide existente para intent.aide.

Entradas:

• directory (string, obrigatório): Diretório onde o(s) arquivo(s) .aide será(ão) criado(s).
• type (string, obrigatório): Tipo de arquivo .aide a criar. Um de: intent, research, both, todo, plan.

aide_inspect

Retorna o bloco JSDoc, assinatura e tipo para uma função, método, classe, interface ou alias de tipo nomeado no workspace — divulgação progressiva de Nível 2 para código. Agentes podem entender o contrato de um símbolo sem abrir o arquivo.

Entradas:

• name (string, obrigatório): Nome do símbolo a ser pesquisado.
• file (string, opcional): Restringir a busca a um único arquivo (relativo à raiz do projeto).

aide_validate

Execute uma verificação de saúde nos arquivos de especificação .aide no projeto. Detecta especificações órfãs, especificações ausentes, conflitos de nomenclatura (.aide e intent.aide na mesma pasta), links quebrados, arquivos de pesquisa órfãos e descrições de frontmatter ausentes.

Entradas:

• path (string, opcional): Subdiretório a validar. Padrão para todo o projeto quando omitido.

aide_info

Relator de pré-condições em tempo de inicialização. Retorna dois campos independentes nos quais o orquestrador ramifica separadamente: outdated (um array de chaves de artefatos AIDE desatualizados, comparando o versions.json do projeto contra o manifesto enviado), e brain (um objeto { status, name?, hints } relatando se a configuração brain.aide do projeto está conectada a .mcp.json). brain.status é a união de quatro estados ok | no-brain-aide | no-mcp-entry | mcp-drift, derivada comparando .aide/config/brain.aide contra .mcp.json — sem validação de caminho de disco. name é o rótulo declarado pelo usuário de brain.aide (presente apenas em estados não-no-brain-aide). hints é um array de locais candidatos de vault que o orquestrador pode apresentar durante a recuperação.

Entradas:

(nenhuma)

aide_brain

Ferramenta de ponto de entrada do cérebro sob demanda. Chame isto quando precisar alcançar o cérebro no meio da tarefa — NÃO chame em toda inicialização /aide. O estado de pré-condição do cérebro em tempo de inicialização já é relatado por aide_info.brain.status; disparar aide_brain na inicialização duplica esse trabalho desnecessariamente.

Retorna { status, instructions } — exatamente dois campos. Sem backend, sem connector, sem name. status espelha aide_info.brain.status (ok | no-brain-aide | no-mcp-entry | mcp-drift). instructions é sempre não-vazio: em ok é o corpo ## Prose literal do .aide/config/brain.aide do usuário (sem substituição do servidor); nos estados de falha carrega prosa de remediação fixa nomeando o comando CLI de recuperação correto (npx @aidemd-mcp/server@latest init para no-brain-aide, npx @aidemd-mcp/server@latest sync para no-mcp-entry e mcp-drift).

Entradas:

(nenhuma)

aide_init

Inicialize o ambiente de desenvolvimento AIDE em um projeto usando um assistente guiado um-de-cada-vez. Na primeira chamada (sem category), retorna um resumo de cada etapa com status e framework detectado. Em chamadas subsequentes (com category), escreve todos os arquivos pendentes para essa categoria no disco e retorna um manifesto.

Entradas:

• framework (string, opcional): Forçar um framework específico em vez de auto-detecção. Um de: claude, cursor, windsurf, copilot.
• path (string, opcional): Caminho raiz do projeto personalizado. Padrão para o diretório de trabalho do servidor.
• category (string, opcional): Escrever todos os arquivos would-create para esta categoria e retornar um manifesto. Um de: framework, methodology, commands, agents, skills, mcp, brain, ide, readme. Omita na primeira chamada para obter um resumo apenas com metadados.
• brainPath (string, opcional): Caminho do vault do cérebro resolvido. Obrigatório quando category=brain.

aide_upgrade

Compare os artefatos de metodologia AIDE neste projeto contra versões canônicas e retorne um diff estruturado agrupado por categoria. Na primeira chamada (sem category), retorna um resumo leve de cada categoria com status de desvio. Em chamadas subsequentes (com category), escreve todos os arquivos com diff ou ausentes para essa categoria no disco e retorna um manifesto.

Entradas:

• framework (string, opcional): Forçar um framework específico em vez de auto-detecção. Um de: claude, cursor, windsurf, copilot.
• path (string, opcional): Caminho raiz do projeto personalizado. Padrão para o diretório de trabalho do servidor.
• category (string, opcional): Escrever todos os arquivos com desvio ou ausentes para esta categoria e retornar um manifesto. Um de: pointer-stub, methodology-docs, version-metadata, commands, agents, skills, mcp, ide, readme. Omita na primeira chamada para obter um resumo apenas com metadados.

Começando

Após adicionar o servidor ao seu cliente MCP, peça ao seu agente para executar aide_init para inicializar a metodologia AIDE no seu projeto. Isso instala os documentos de metodologia, cria os comandos de pipeline e conecta tudo.

Depois tente: "Crie uma especificação de intenção para meu módulo de autenticação" — o agente usará aide_discover para mapear seu projeto e aide_scaffold para criar a especificação no lugar certo com as convenções de nomenclatura corretas.

Desenvolvimento

npm install
npm run build
npm test

Licença

MIT