Autodocument

Genera automáticamente documentación para repositorios de código analizando estructuras de directorios y archivos de código mediante la API de OpenRouter.

GitHub
6

Documentación

Servidor MCP de Autodocument

Un servidor MCP (Model Context Protocol) que genera automáticamente documentación para repositorios de código analizando estructuras de directorios y archivos de código mediante la API de OpenRouter.

Características

  • Análisis inteligente de directorios: Analiza recursivamente directorios y archivos en un repositorio de código
  • Integración con Git: Respeta los patrones .gitignore para omitir archivos ignorados
  • Documentación impulsada por IA: Utiliza la API de OpenRouter (con Claude 3.7 por defecto) para generar documentación completa
  • Generación de planes de prueba: Crea automáticamente planes de prueba con tipos de prueba adecuados, casos límite y requisitos de mocks
  • Revisión de código: Realiza revisiones de código a nivel de desarrollador senior centradas en seguridad, mejores prácticas y mejoras
  • Enfoque ascendente: Comienza con los directorios hoja y avanza hacia arriba, creando una jerarquía de documentación coherente
  • Manejo inteligente de archivos:
    • Crea archivos documentation.md, testplan.md y review.md en cada nivel de directorio
    • Omite directorios de un solo archivo pero incluye su contenido en las salidas del directorio padre
    • Soporta la actualización de archivos existentes
    • Crea archivos de respaldo para directorios que exceden los límites
  • Informe de progreso: Proporciona actualizaciones detalladas de progreso para evitar tiempos de espera en operaciones de larga duración
  • Altamente configurable: Personaliza extensiones de archivo, límites de tamaño, modelos, indicaciones y más
  • Arquitectura extensible: El diseño modular facilita la adición de más herramientas auto-* en el futuro

Instalación

Requisitos previos

Pasos de instalación

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

# Install dependencies
npm install

# Build the project
npm run build

Configuración

Configura autodocument usando variables de entorno, argumentos de línea de comandos o un archivo de configuración MCP:

Variables de entorno

  • OPENROUTER_API_KEY: Tu clave de API de OpenRouter
  • OPENROUTER_MODEL: Modelo a utilizar (predeterminado: anthropic/claude-3-7-sonnet)
  • MAX_FILE_SIZE_KB: Tamaño máximo de archivo en KB (predeterminado: 100)
  • MAX_FILES_PER_DIR: Número máximo de archivos por directorio (predeterminado: 20)

Uso con Roo o Cline

Roo Code y Cline son asistentes de IA que soportan el Model Context Protocol (MCP), lo que les permite usar herramientas externas como autodocument.

Configuración para Roo/Cline

  1. Clona y compila el repositorio (sigue los Pasos de instalación anteriores)

  2. Configura el servidor MCP:

    Para Roo:

    En el menú de Servidores MCP, edita la Configuración MCP y añade la configuración de autodocument usando la ruta completa donde clonaste el repositorio:

    Añade la configuración de autodocument usando la ruta completa donde clonaste el repositorio:

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

    Para la aplicación de escritorio de Claude:

    Edita el archivo de configuración de la aplicación de escritorio de Claude en:

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

    Añade la configuración de autodocument usando la ruta completa donde clonaste el repositorio:

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

  3. Importante: Asegúrate de usar rutas absolutas al archivo build/index.js en tu repositorio clonado

  4. Reinicia Roo/Cline o la aplicación de escritorio de Claude

  5. Usa la herramienta: En una conversación con Roo o Claude, ahora puedes pedirle que genere documentación o planes de prueba para tu repositorio de código:

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

    O para planes de prueba:

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

    O para revisiones de código:

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

Cómo funciona

El servidor autodocument funciona con un enfoque ascendente:

  1. Descubrimiento: Escanea el directorio de destino recursivamente, respetando las reglas de .gitignore
  2. Procesamiento inteligente de directorios:
    • Identifica directorios con múltiples archivos de código o subdirectorios
    • Omite directorios de un solo archivo pero incluye su contenido en la documentación del directorio padre
  3. Análisis de archivos: Analiza archivos de código, filtrando por extensión y tamaño
  4. Generación de documentación: Para cada directorio que califica:
    • Lee los archivos de código
    • Envía el código a la API de OpenRouter con indicaciones optimizadas
    • Crea un archivo documentation.md (o actualiza uno existente)
  5. Agregación: A medida que avanza por el árbol de directorios:
    • Procesa cada directorio padre
    • Incluye documentación de los directorios hijos
    • Crea una visión general completa en cada nivel

Arquitectura

El proyecto sigue una arquitectura modular:

  • Componentes principales: Gestión de configuración e implementación del servidor
  • Módulo de rastreo: Recorrido de directorios y descubrimiento de archivos
  • Módulo de análisis: Análisis y filtrado de archivos de código
  • Módulo de OpenRouter: Integración de IA para generación de contenido basado en LLM
  • Módulo de documentación: Orquestación del proceso de documentación
  • Módulo de herramientas: Sistema extensible para diferentes herramientas auto-* (documentación, planes de prueba, etc.)
  • Configuración de indicaciones: Gestión centralizada de indicaciones para facilitar la personalización

Ejemplo de uso

Línea de comandos

# 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
// ...

Personalización de indicaciones

Puedes personalizar fácilmente las indicaciones utilizadas por las herramientas editando el archivo src/prompt-config.ts. Esto te permite:

  • Ajustar el tono y estilo del contenido generado
  • Añadir instrucciones específicas para las necesidades de tu proyecto
  • Modificar cómo se actualiza el contenido existente

La configuración de indicaciones está separada de la implementación de las herramientas, lo que facilita experimentar con diferentes indicaciones sin cambiar el código.

Herramientas disponibles

generate_documentation

Genera documentación completa para un repositorio 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

Genera planes de prueba para funciones y componentes en un repositorio 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

Genera una revisión de código a nivel de desarrollador senior para un repositorio:

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

Archivos de salida

El servidor crea varios tipos de archivos de salida:

documentation.md

Contiene documentación completa del código en un directorio, incluyendo:

  • Propósito del código
  • Funciones y clases clave
  • Relaciones entre archivos
  • Integración con componentes hijos

testplan.md

Contiene planes de prueba detallados para el código en un directorio, incluyendo:

  • Tipos de prueba apropiados (unitarias, integración, e2e) para cada función
  • Casos límite comunes a probar
  • Requisitos de simulación de dependencias
  • Estrategias de prueba de integración

review.md

Contiene comentarios de revisión de código a nivel de desarrollador senior, incluyendo:

  • Problemas de seguridad y vulnerabilidades
  • Violaciones de mejores prácticas
  • Posibles errores o preocupaciones arquitectónicas
  • Oportunidades de refactorización
  • Comentarios prácticos y constructivos (no críticas de estilo)

Archivos de respaldo

Creados cuando un directorio excede los límites de tamaño o número de archivos:

  • undocumented.md - Para generación de documentación
  • untested.md - Para generación de planes de prueba
  • review-skipped.md - Para generación de revisiones de código

Estos archivos contienen:

  • Razón por la que se omitió el procesamiento
  • Lista de archivos que fueron analizados y excluidos
  • Instrucciones sobre cómo solucionarlo (aumentar límites o crear contenido manualmente)

Solución de problemas

Problemas con la clave de API

Si ves errores sobre clave de API inválida:

  • Asegúrate de haber configurado la variable de entorno OPENROUTER_API_KEY
  • Verifica que tu cuenta de OpenRouter esté activa
  • Confirma que tienes créditos suficientes para las llamadas a la API

Errores de límite de tamaño

Si demasiados directorios se omiten debido a límites de tamaño:

  • Configura variables de entorno para aumentar los límites: MAX_FILE_SIZE_KB y MAX_FILES_PER_DIR
  • Considera documentar manualmente directorios muy grandes

Selección de modelo

Si no estás satisfecho con la calidad de la documentación:

  • Prueba un modelo diferente configurando la variable de entorno OPENROUTER_MODEL

Licencia

Licencia CC0-1.0 - Este trabajo está dedicado al dominio público bajo CC0 por el Departamento de Energía de los Estados Unidos

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

Añadir nuevas herramientas

La arquitectura está diseñada para facilitar la adición de nuevas herramientas auto-*:

  1. Crea una nueva clase que extienda BaseTool en el directorio src/tools
  2. Define las indicaciones en src/prompt-config.ts
  3. Registra la herramienta en ToolRegistry

Consulta las herramientas existentes para ver ejemplos de cómo implementar nueva funcionalidad.