Autodocument

Gera automaticamente documentação para repositórios de código analisando estruturas de diretórios e arquivos de código usando a API OpenRouter.

GitHub
6

Documentação

Servidor MCP Autodocument

Um servidor MCP (Model Context Protocol) que gera automaticamente documentação para repositórios de código, analisando estruturas de diretórios e arquivos de código usando a API OpenRouter.

Recursos

  • Análise Inteligente de Diretórios: Analisa recursivamente diretórios e arquivos em um repositório de código
  • Integração com Git: Respeita padrões .gitignore para ignorar arquivos ignorados
  • Documentação com IA: Usa a API OpenRouter (com Claude 3.7 por padrão) para gerar documentação abrangente
  • Geração de Planos de Teste: Cria automaticamente planos de teste com tipos de teste adequados, casos extremos e requisitos de mock
  • Revisão de Código: Realiza revisões de código em nível de desenvolvedor sênior, focadas em segurança, boas práticas e melhorias
  • Abordagem de Baixo para Cima: Começa com diretórios folha e avança para cima, criando uma hierarquia de documentação coerente
  • Manipulação Inteligente de Arquivos:
    • Cria arquivos documentation.md, testplan.md e review.md em cada nível de diretório
    • Ignora diretórios de arquivo único, mas inclui seu conteúdo nas saídas dos diretórios pai
    • Suporta atualização de arquivos existentes
    • Cria arquivos de fallback para diretórios que excedem os limites
  • Relatório de Progresso: Fornece atualizações detalhadas de progresso para evitar timeouts em operações de longa duração
  • Altamente Configurável: Personalize extensões de arquivo, limites de tamanho, modelos, prompts e muito mais
  • Arquitetura Extensível: Design modular facilita a adição de mais ferramentas auto-* no futuro

Instalação

Pré-requisitos

Etapas de Instalação

# Clone the repository
git clone https://github.com/PARS-DOE/autodocument.git
cd autodocument

# Install dependencies
npm install

# Build the project
npm run build

Configuração

Configure o autodocument usando variáveis de ambiente, argumentos de linha de comando ou um arquivo de configuração MCP:

Variáveis de Ambiente

  • OPENROUTER_API_KEY: Sua chave de API OpenRouter
  • OPENROUTER_MODEL: Modelo a ser usado (padrão: anthropic/claude-3-7-sonnet)
  • MAX_FILE_SIZE_KB: Tamanho máximo de arquivo em KB (padrão: 100)
  • MAX_FILES_PER_DIR: Número máximo de arquivos por diretório (padrão: 20)

Usando com Roo ou Cline

Roo Code e Cline são assistentes de IA que suportam o Model Context Protocol (MCP), o que permite que eles usem ferramentas externas como o autodocument.

Configuração para Roo/Cline

  1. Clone e construa o repositório (siga as Etapas de Instalação acima)

  2. Configure o servidor MCP:

    Para Roo:

    No menu de Servidores MCP, edite as Configurações MCP e adicione a configuração do autodocument usando o caminho completo para onde você clonou o repositório:

    Adicione a configuração do autodocument usando o caminho completo para onde você clonou o repositório:

    {
  "mcpServers": {
    "autodocument": {
      "command": "node",
      "args": ["/path/to/autodocument/build/index.js"],
      "env": {
        "OPENROUTER_API_KEY": "your-api-key-here"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

    Para o Aplicativo de Desktop Claude:

    Edite o arquivo de configuração do aplicativo de desktop Claude em:

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

    Adicione a configuração do autodocument usando o caminho completo para onde você clonou o repositório:

    {
  "mcpServers": {
    "autodocument": {
      "command": "node",
      "args": ["/path/to/autodocument/build/index.js"],
      "env": {
        "OPENROUTER_API_KEY": "your-api-key-here"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

  3. Importante: Certifique-se de usar caminhos absolutos para o arquivo build/index.js no seu repositório clonado

  4. Reinicie o Roo/Cline ou o aplicativo de desktop Claude

  5. Use a ferramenta: Em uma conversa com Roo ou Claude, você agora pode pedir para gerar documentação ou planos de teste para o seu repositório de código:

    Please generate documentation for my project at /path/to/my/project

    Ou para planos de teste:

    Please create a test plan for my project at /path/to/my/project

    Ou para revisões de código:

    Please review the code in my project at /path/to/my/project

Como Funciona

O servidor autodocument funciona usando uma abordagem de baixo para cima:

  1. Descoberta: Escaneia o diretório alvo recursivamente, respeitando as regras de .gitignore
  2. Processamento Inteligente de Diretórios:
    • Identifica diretórios com múltiplos arquivos de código ou subdiretórios
    • Ignora diretórios de arquivo único, mas inclui seu conteúdo na documentação do diretório pai
  3. Análise de Arquivos: Analisa arquivos de código, filtrando por extensão e tamanho
  4. Geração de Documentação: Para cada diretório qualificado:
    • Lê arquivos de código
    • Envia código para a API OpenRouter com prompts otimizados
    • Cria um arquivo documentation.md (ou atualiza um existente)
  5. Agregação: À medida que sobe na árvore de diretórios:
    • Processa cada diretório pai
    • Inclui documentação dos diretórios filhos
    • Cria uma visão geral abrangente em cada nível

Arquitetura

O projeto segue uma arquitetura modular:

  • Componentes Principais: Gerenciamento de configuração e implementação do servidor
  • Módulo Crawler: Travessia de diretórios e descoberta de arquivos
  • Módulo Analisador: Análise e filtragem de arquivos de código
  • Módulo OpenRouter: Integração de IA para geração de conteúdo baseado em LLM
  • Módulo de Documentação: Orquestração do processo de documentação
  • Módulo de Ferramentas: Sistema extensível para diferentes ferramentas auto-* (documentação, planos de teste, etc.)
  • Configuração de Prompts: Gerenciamento centralizado de prompts para fácil personalização

Exemplo de Uso

Linha de Comando

# Navigate to your cloned repository
cd path/to/cloned/autodocument

# Set your API key (or configure in environment variables)
export OPENROUTER_API_KEY=your-api-key-here

# Run documentation generation on a project
node build/index.js /path/to/your/project

Uso Programático

const { spawn } = require('child_process');
const path = require('path');

// Path to your project
const projectPath = '/path/to/your/project';

// Your OpenRouter API key
const apiKey = 'your-api-key-here';

// Create a JSON command to simulate an MCP tool call
const toolCallCommand = JSON.stringify({
  jsonrpc: '2.0',
  method: 'call_tool',
  params: {
    name: 'generate_documentation',
    arguments: {
      path: projectPath,
      openRouterApiKey: apiKey
    }
  },
  id: 1
});

// Start the server process - use the full path to your cloned repository
const serverProcess = spawn('node', ['/path/to/autodocument/build/index.js'], {
  env: {
    ...process.env,
    OPENROUTER_API_KEY: apiKey
  }
});

// Send the tool command
serverProcess.stdin.write(toolCallCommand + '\n');

// Handle server output and errors
// ...

Personalizando Prompts

Você pode facilmente personalizar os prompts usados pelas ferramentas editando o arquivo src/prompt-config.ts. Isso permite que você:

  • Ajuste o tom e o estilo do conteúdo gerado
  • Adicione instruções específicas para as necessidades do seu projeto
  • Modifique como o conteúdo existente é atualizado

A configuração de prompts é separada da implementação da ferramenta, facilitando a experimentação com diferentes prompts sem alterar o código.

Ferramentas Disponíveis

generate_documentation

Gera documentação abrangente para um repositório de código:

{
  "path": "/path/to/your/project",
  "openRouterApiKey": "your-api-key-here", // Optional
  "model": "anthropic/claude-3-7-sonnet", // Optional
  "updateExisting": true // Optional, defaults to true
}

autotestplan

Gera planos de teste para funções e componentes em um repositório de código:

{
  "path": "/path/to/your/project",
  "openRouterApiKey": "your-api-key-here", // Optional
  "model": "anthropic/claude-3-7-sonnet", // Optional
  "updateExisting": true // Optional, defaults to true
}

autoreview

Gera uma revisão de código em nível de desenvolvedor sênior para um repositório:

{
  "path": "/path/to/your/project",
  "openRouterApiKey": "your-api-key-here", // Optional
  "model": "anthropic/claude-3-7-sonnet", // Optional
  "updateExisting": true // Optional, defaults to true
}

Arquivos de Saída

O servidor cria vários tipos de arquivos de saída:

documentation.md

Contém documentação abrangente do código em um diretório, incluindo:

  • Propósito do código
  • Principais funções e classes
  • Relações entre arquivos
  • Integração com componentes filhos

testplan.md

Contém planos de teste detalhados para código em um diretório, incluindo:

  • Tipos de teste apropriados (unitário, integração, e2e) para cada função
  • Casos extremos comuns para testar
  • Requisitos de mock de dependências
  • Estratégias de teste de integração

review.md

Contém feedback de revisão de código em nível de desenvolvedor sênior, incluindo:

  • Problemas de segurança e vulnerabilidades
  • Violações de boas práticas
  • Possíveis bugs ou preocupações arquiteturais
  • Oportunidades de refatoração
  • Feedback prático e construtivo (não críticas de estilo)

Arquivos de Fallback

Criados quando um diretório excede os limites de tamanho ou número de arquivos:

  • undocumented.md - Para geração de documentação
  • untested.md - Para geração de planos de teste
  • review-skipped.md - Para geração de revisão de código

Esses arquivos contêm:

  • Motivo para pular o processamento
  • Lista de arquivos que foram analisados e excluídos
  • Instruções sobre como corrigir (aumentar limites ou criar conteúdo manualmente)

Solução de Problemas

Problemas com Chave de API

Se você vir erros sobre chave de API inválida:

  • Certifique-se de ter definido a variável de ambiente OPENROUTER_API_KEY
  • Verifique se sua conta OpenRouter está ativa
  • Verifique se você tem créditos suficientes para as chamadas de API

Erros de Limite de Tamanho

Se muitos diretórios forem ignorados devido aos limites de tamanho:

  • Defina variáveis de ambiente para aumentar os limites: MAX_FILE_SIZE_KB e MAX_FILES_PER_DIR
  • Considere documentar diretórios muito grandes manualmente

Seleção de Modelo

Se você não estiver satisfeito com a qualidade da documentação:

  • Tente um modelo diferente definindo a variável de ambiente OPENROUTER_MODEL

Licença

Licença CC0-1.0 - Este trabalho é dedicado ao domínio público sob CC0 pelo Departamento de Energia dos Estados Unidos

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Adicionando Novas Ferramentas

A arquitetura é projetada para facilitar a adição de novas ferramentas auto-*:

  1. Crie uma nova classe que estenda BaseTool no diretório src/tools
  2. Defina os prompts em src/prompt-config.ts
  3. Registre a ferramenta no ToolRegistry

Veja as ferramentas existentes para exemplos de como implementar novas funcionalidades.