`code-scanner-server`

Una herramienta CLI y un servidor MCP que escanea archivos de código en busca de definiciones (clases, funciones, etc.), respeta .gitignore, proporciona números de línea y genera formatos compatibles con LLM (XML/Markdown).

Este proyecto proporciona una herramienta versátil de escaneo de código desarrollada con TypeScript y Node.js. Utiliza la biblioteca de análisis Tree-sitter para analizar el código fuente y extraer información estructural. Puede funcionar como herramienta de interfaz de línea de comandos (CLI) y como servidor MCP (Protocolo de Contexto de Modelo).

Nota: Esta herramienta se encuentra en desarrollo activo. Si bien la funcionalidad principal está operativa, es posible que algunas características o analizadores de lenguaje específicos no estén completamente probados y presenten errores o limitaciones.

Características

Extracción de definición de código: identifica funciones, clases, variables, interfaces, métodos, etc.
Compatibilidad con varios idiomas: analiza JavaScript ( .js , .jsx ), TypeScript ( .ts , .tsx ), C# ( .cs ), PHP ( .php ), CSS ( .css ) y Python ( .py ) a través de Tree-sitter.
.gitignore Aware: respeta automáticamente las reglas definidas en los archivos .gitignore .
Filtrado flexible: filtre los resultados por tipo de definición, modificadores ( public , private ), patrones de nombre (expresiones regulares) y patrones de ruta de archivo.
Múltiples formatos de salida: genera resultados en Markdown (predeterminado), XML o JSON.
Niveles de detalle configurables: Nivel de verbosidad de salida: minimal , standard (predeterminado), detailed .
Operación en modo dual: Ejecútelo como una herramienta CLI independiente o como un servidor MCP integrado.

Modos de uso

1. Interfaz de línea de comandos (CLI)

Ejecute el escáner directamente desde su terminal. Este modo requiere el argumento --directory , que especifica el código base de destino.

Uso básico:

node build/index.js --directory /path/to/your/codebase

Opciones comunes:

-d, --directory <path> : (Obligatorio) Ruta absoluta o relativa al directorio a escanear.
-p, --patterns <patterns...> : Patrones globales para extensiones de archivo (p. ej., "**/*.ts"``"**/*.js" ). El valor predeterminado son archivos JS, TSX, CS, PHP, CSS y PY.
-f, --format <format> : Formato de salida ( xml , markdown , json ). Predeterminado: markdown .
-l, --detail <level> : Nivel de detalle ( minimal , standard , detailed ). Predeterminado: standard .
--include-types <types...> : incluye solo tipos de definición específicos (por ejemplo, class , method ).
--exclude-types <types...> : Excluye tipos de definición específicos.
--include-modifiers <modifiers...> : solo incluye definiciones con modificadores específicos (por ejemplo, public ).
--exclude-modifiers <modifiers...> : Excluye definiciones con modificadores específicos.
--name-pattern <regex> : incluye definiciones que coincidan con un patrón de expresión regular de JavaScript.
--exclude-name-pattern <regex> : excluye definiciones que coincidan con un patrón de expresión regular de JavaScript.
--include-paths <paths...> : Patrones de rutas de archivos adicionales (glob) para incluir.
--exclude-paths <paths...> : Patrones de rutas de archivo (glob) a excluir.
-h, --help : Muestra información de ayuda detallada para todas las opciones.

Ejemplo (Escanear archivos TypeScript en src , generar JSON detallado):

node build/index.js -d ./src -p "**/*.ts" -f json -l detailed

2. Modo de servidor MCP (herramienta `scan_code` )

Si se ejecuta sin el argumento --directory , la herramienta se inicia como un servidor MCP, escuchando solicitudes mediante entrada/salida estándar. Esto permite la integración con clientes MCP, como asistentes de IA.

Nombre de la herramienta: scan_code
Descripción: Escanea un directorio específico en busca de archivos de código y devuelve una lista de definiciones según los filtros proporcionados.
Esquema de entrada: Acepta argumentos correspondientes a las opciones de la CLI. La propiedad directory es obligatoria.
{ "type": "object", "properties": { "directory": { "type": "string", "description": "Absolute path to the directory to scan." }, "filePatterns": { "type": "array", "items": { "type": "string" }, "description": "Glob patterns for files.", "default": ["**/*.js", ..., "**/*.py"] }, "outputFormat": { "type": "string", "enum": ["xml", "markdown", "json"], "default": "markdown" }, "detailLevel": { "type": "string", "enum": ["minimal", "standard", "detailed"], "default": "standard" }, "includeTypes": { "type": "array", "items": { "type": "string" } }, "excludeTypes": { "type": "array", "items": { "type": "string" } }, "includeModifiers": { "type": "array", "items": { "type": "string" } }, "excludeModifiers": { "type": "array", "items": { "type": "string" } }, "namePattern": { "type": "string", "description": "Regex pattern for names." }, "excludeNamePattern": { "type": "string", "description": "Regex pattern to exclude names." }, "includePaths": { "type": "array", "items": { "type": "string" } }, "excludePaths": { "type": "array", "items": { "type": "string" } } }, "required": ["directory"] }
Ejemplo de uso con AI Assistant: "Utilice code-scanner-server scan_code en el directorio /path/to/project generando salida en formato xml".

Instalación

Requisitos previos: asegúrese de tener Node.js y npm instalados.
Clonar (opcional): si no tiene el código, clone el repositorio.
# git clone <repository_url> # cd code-scanner-server
Dependencias de instalación:
npm install
Compilación: compila el código TypeScript.
npm run build
Esto crea el archivo JavaScript ejecutable en build/index.js .

Configuración (Servidor MCP)

Para utilizar el modo de servidor MCP, agréguelo al archivo de configuración de su cliente MCP (por ejemplo, claude_desktop_config.json para la aplicación de escritorio o cline_mcp_settings.json para la extensión VS Code).

Importante: reemplace /path/to/code-scanner-server en el siguiente ejemplo con la ruta absoluta al directorio de este proyecto en su sistema.

Ejemplo ( claude_desktop_config.json / cline_mcp_settings.json ):

{
  "mcpServers": {
    "code-scanner-server": {
      "command": "node",
      "args": [
        "/absolute/path/to/your/code-scanner-server/build/index.js" // <-- Replace this path! (e.g., "C:\\Users\\YourUser\\Projects\\code-scanner-server\\build\\index.js" on Windows)
      ],
      "env": {},
      "disabled": false,
      "autoApprove": [] // Add tool names here for auto-approval if desired
    }
  }
}

Recuerde reiniciar su aplicación cliente MCP (IDE, aplicación de escritorio) después de modificar la configuración para que los cambios surtan efecto.

Desarrollo

Modo de observación: reconstruye automáticamente el proyecto cuando cambian los archivos de origen:
npm run watch
Depuración (Modo MCP): Depurar servidores MCP con stdio puede ser complejo. Utilice la herramienta Inspector de MCP para una depuración más sencilla.
npm run inspector
Esto inicia el servidor con el inspector Node.js adjunto y proporciona una URL para conectar herramientas de depuración (como Chrome DevTools).

Expresiones de gratitud

Este proyecto se desarrolló significativamente con la ayuda de IA, principalmente utilizando el modelo Gemini 2.5 Pro de Google al que se accede a través de la extensión Roo Code para Visual Studio Code.

Licencia

Este proyecto está licenciado bajo la Licencia Pública General GNU v3.0 - consulte el archivo LICENCIA para obtener más detalles.

code-scanner-server