Code Scanner Server

Escaneia arquivos de código em busca de definições, respeita o .gitignore e gera saídas em formatos amigáveis para LLM, como XML ou Markdown.

GitHub
2
Experimente este MCPPatrocinado

Documentação

MseeP.ai Security Assessment Badge

Code Scanner Server MCP server

code-scanner-server

Uma ferramenta CLI e servidor MCP que escaneia arquivos de código em busca de definições (classes, funções, etc.), respeita .gitignore, fornece números de linha e gera formatos amigáveis para LLMs (XML/Markdown).

Este projeto fornece uma ferramenta versátil de escaneamento de código construída com TypeScript e Node.js. Ela utiliza a biblioteca de parsing Tree-sitter para analisar código-fonte e extrair informações estruturais. Pode operar tanto como uma ferramenta de interface de linha de comando (CLI) quanto como um servidor MCP (Model Context Protocol).

Nota: Esta ferramenta está em desenvolvimento ativo. Embora a funcionalidade principal esteja operacional, alguns recursos ou parsers de linguagens específicas podem não estar totalmente testados e podem conter bugs ou limitações.

Recursos

  • Extração de Definições de Código: Identifica funções, classes, variáveis, interfaces, métodos, etc.
  • Suporte a Múltiplas Linguagens: Analisa JavaScript (.js, .jsx), TypeScript (.ts, .tsx), C# (.cs), PHP (.php), CSS (.css) e Python (.py) via Tree-sitter.
  • Consciente de .gitignore: Respeita automaticamente as regras definidas nos arquivos .gitignore.
  • Filtragem Flexível: Filtra resultados por tipo de definição, modificadores (public, private), padrões de nome (regex) e padrões de caminho de arquivo.
  • Múltiplos Formatos de Saída: Gera resultados em Markdown (padrão), XML ou JSON.
  • Níveis de Detalhe Configuráveis: Verbosidade da saída: minimal, standard (padrão), detailed.
  • Modo de Operação Duplo: Execute como uma ferramenta CLI independente ou como um servidor MCP integrado.

Modos de Uso

1. Interface de Linha de Comando (CLI)

Execute o scanner diretamente do seu terminal. Este modo requer o argumento --directory especificando o código-fonte alvo.

Uso Básico:

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

Opções Comuns:

  • -d, --directory <path>: (Obrigatório) Caminho absoluto ou relativo do diretório a ser escaneado.
  • -p, --patterns <patterns...>: Padrões glob para extensões de arquivo (ex.: "**/*.ts" "**/*.js"). Padrão: arquivos JS, TSX, CS, PHP, CSS, PY.
  • -f, --format <format>: Formato de saída (xml, markdown, json). Padrão: markdown.
  • -l, --detail <level>: Nível de detalhe (minimal, standard, detailed). Padrão: standard.
  • --include-types <types...>: Incluir apenas tipos específicos de definição (ex.: class, method).
  • --exclude-types <types...>: Excluir tipos específicos de definição.
  • --include-modifiers <modifiers...>: Incluir apenas definições com modificadores específicos (ex.: public).
  • --exclude-modifiers <modifiers...>: Excluir definições com modificadores específicos.
  • --name-pattern <regex>: Incluir definições que correspondam a um padrão regex JavaScript.
  • --exclude-name-pattern <regex>: Excluir definições que correspondam a um padrão regex JavaScript.
  • --include-paths <paths...>: Padrões adicionais de caminho de arquivo (glob) a incluir.
  • --exclude-paths <paths...>: Padrões de caminho de arquivo (glob) a excluir.
  • -h, --help: Exibir informações detalhadas de ajuda para todas as opções.

Exemplo (Escaneie arquivos TypeScript em src, gere JSON detalhado):

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

2. Modo Servidor MCP (ferramenta scan_code)

Se executado sem o argumento --directory, a ferramenta inicia como um servidor MCP, ouvindo solicitações via entrada/saída padrão. Isso permite integração com clientes MCP, como assistentes de IA.

  • Nome da Ferramenta: scan_code
  • Descrição: Escaneia um diretório especificado em busca de arquivos de código e retorna uma lista de definições de acordo com os filtros fornecidos.
  • Esquema de Entrada: Aceita argumentos correspondentes às opções da CLI. A propriedade directory é obrigatória. 
    {
  "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"]
}
  • Exemplo de Uso com Assistente de IA: "Use code-scanner-server scan_code no diretório /path/to/project gerando formato xml."

Instalação

  1. Pré-requisitos: Certifique-se de ter Node.js e npm instalados.
  2. Clonar (Opcional): Se você não tiver o código, clone o repositório. 
    # git clone <repository_url>
# cd code-scanner-server
  3. Instalar Dependências: 
    npm install
  4. Compilar: Compile o código TypeScript. 
    npm run build
    Isso cria o arquivo JavaScript executável em build/index.js.

Configuração (Servidor MCP)

Para usar o modo servidor MCP, adicione-o ao arquivo de configuração do seu cliente MCP (ex.: claude_desktop_config.json para o aplicativo de desktop ou cline_mcp_settings.json para a extensão do VS Code).

Importante: Substitua /path/to/code-scanner-server no exemplo abaixo pelo caminho absoluto do diretório deste projeto no seu sistema.

Exemplo (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
    }
  }
}

Lembre-se de reiniciar seu aplicativo cliente MCP (IDE, aplicativo de desktop) após modificar a configuração para que as alterações tenham efeito.

Desenvolvimento

  • Modo de Observação: Recompila automaticamente o projeto quando os arquivos de origem mudam: 
    npm run watch
  • Depuração (Modo MCP): Depurar servidores MCP via stdio pode ser complexo. Use a ferramenta MCP Inspector para facilitar a depuração: 
    npm run inspector
    Isso inicia o servidor com o inspetor Node.js anexado e fornece uma URL para conectar ferramentas de depuração (como Chrome DevTools).

Agradecimentos

Este projeto foi significativamente desenvolvido com assistência de IA, principalmente usando o modelo Google Gemini 2.5 Pro acessado via extensão Roo Code para Visual Studio Code.

Licença

Este projeto é licenciado sob a GNU General Public License v3.0 - consulte o arquivo LICENSE para detalhes.