Code Scanner Server

Escanea archivos de código en busca de definiciones, respeta .gitignore y genera resultados en formatos compatibles con LLM como XML o Markdown.

GitHub
2
Prueba este MCPPatrocinado

Documentación

MseeP.ai Security Assessment Badge

Code Scanner Server MCP server

code-scanner-server

Una herramienta CLI y 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 construida con TypeScript y Node.js. Utiliza la biblioteca de análisis Tree-sitter para analizar código fuente y extraer información estructural. Puede funcionar tanto como herramienta de interfaz de línea de comandos (CLI) como servidor MCP (Model Context Protocol).

Nota: Esta herramienta está en desarrollo activo. Si bien la funcionalidad principal está operativa, algunas características o analizadores de lenguajes específicos pueden no estar completamente probados y podrían contener errores o limitaciones.

Características

  • Extracción de definiciones de código: Identifica funciones, clases, variables, interfaces, métodos, etc.
  • Soporte multi-lenguaje: Analiza JavaScript (.js, .jsx), TypeScript (.ts, .tsx), C# (.cs), PHP (.php), CSS (.css) y Python (.py) mediante Tree-sitter.
  • Compatibilidad con .gitignore: Respeta automáticamente las reglas definidas en los archivos .gitignore.
  • Filtrado flexible: Filtra resultados por tipo de definición, modificadores (public, private), patrones de nombre (regex) y patrones de ruta de archivo.
  • Múltiples formatos de salida: Genera resultados en Markdown (predeterminado), XML o JSON.
  • Niveles de detalle configurables: Verbosidad de salida: minimal, standard (predeterminado), detailed.
  • Modo de operación dual: Funciona como herramienta CLI independiente o como 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 glob para extensiones de archivo (p. ej., "**/*.ts" "**/*.js"). Por defecto, archivos JS, TSX, CS, PHP, CSS, 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...>: Incluir solo tipos de definición específicos (p. ej., class, method).
  • --exclude-types <types...>: Excluir tipos de definición específicos.
  • --include-modifiers <modifiers...>: Incluir solo definiciones con modificadores específicos (p. ej., public).
  • --exclude-modifiers <modifiers...>: Excluir definiciones con modificadores específicos.
  • --name-pattern <regex>: Incluir definiciones que coincidan con un patrón regex de JavaScript.
  • --exclude-name-pattern <regex>: Excluir definiciones que coincidan con un patrón regex de JavaScript.
  • --include-paths <paths...>: Patrones adicionales de ruta de archivo (glob) a incluir.
  • --exclude-paths <paths...>: Patrones de ruta de archivo (glob) a excluir.
  • -h, --help: Mostrar información de ayuda detallada para todas las opciones.

Ejemplo (Escaneo de archivos TypeScript en src, salida JSON detallada):

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

2. Modo Servidor MCP (herramienta scan_code)

Si se ejecuta sin el argumento --directory, la herramienta se inicia como servidor MCP, escuchando solicitudes a través de la 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 especificado 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 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 asistente de IA: "Usa code-scanner-server scan_code en el directorio /path/to/project generando formato xml."

Instalación

  1. Requisitos previos: Asegúrese de tener Node.js y npm instalados.
  2. Clonar (opcional): Si no tiene el código, clone el repositorio. 
    # git clone <repository_url>
# cd code-scanner-server
  3. Instalar dependencias: 
    npm install
  4. Compilar: Compile el código TypeScript. 
    npm run build
    Esto crea el archivo JavaScript ejecutable en build/index.js.

Configuración (Servidor MCP)

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

Importante: Reemplace /path/to/code-scanner-server en el ejemplo siguiente 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 watch: Reconstruye automáticamente el proyecto cuando los archivos fuente cambian: 
    npm run watch
  • Depuración (modo MCP): Depurar servidores MCP a través de stdio puede ser complejo. Use la herramienta MCP Inspector para facilitar la depuración: 
    npm run inspector
    Esto inicia el servidor con el inspector de Node.js adjunto y proporciona una URL para conectar herramientas de depuración (como Chrome DevTools).

Agradecimientos

Este proyecto fue desarrollado significativamente con la asistencia de IA, principalmente utilizando el modelo Gemini 2.5 Pro de Google accedido a través de la extensión Roo Code para Visual Studio Code.

Licencia

Este proyecto está licenciado bajo la GNU General Public License v3.0; consulte el archivo LICENSE para obtener más detalles.