code-scanner-server

A CLI tool and MCP server that scans code files for definitions (classes, functions, etc.), respects .gitignore, provides line numbers, and outputs LLM-friendly formats (XML/Markdown).

This project provides a versatile code scanning tool built with TypeScript and Node.js. It leverages the Tree-sitter parsing library to analyze source code and extract structural information. It can operate both as a command-line interface (CLI) tool and as an MCP (Model Context Protocol) server.

Note: This tool is under active development. While core functionality is operational, some features or specific language parsers may not be fully tested and might contain bugs or limitations.

Features

• Code Definition Extraction: Identifies functions, classes, variables, interfaces, methods, etc.
• Multi-Language Support: Parses JavaScript (.js, .jsx), TypeScript (.ts, .tsx), C# (.cs), PHP (.php), CSS (.css), and Python (.py) via Tree-sitter.
• .gitignore Aware: Automatically respects rules defined in .gitignore files.
• Flexible Filtering: Filter results by definition type, modifiers (public, private), name patterns (regex), and file path patterns.
• Multiple Output Formats: Generates results in Markdown (default), XML, or JSON.
• Configurable Detail Levels: Output verbosity: minimal, standard (default), detailed.
• Dual Mode Operation: Run as a standalone CLI tool or as an integrated MCP server.

Development

• Watch Mode: Automatically rebuild the project when source files change:
  Copy

  npm run watch

• Debugging (MCP Mode): Debugging MCP servers over stdio can be complex. Use the MCP Inspector tool for easier debugging:
  Copy

  npm run inspector

  This starts the server with the Node.js inspector attached and provides a URL to connect debugging tools (like Chrome DevTools).

Usage Modes

1. Command-Line Interface (CLI)

Run the scanner directly from your terminal. This mode requires the --directory argument specifying the target codebase.

Basic Usage:

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

Common Options:

• -d, --directory <path>: (Required) Absolute or relative path to the directory to scan.
• -p, --patterns <patterns...>: Glob patterns for file extensions (e.g., "**/*.ts" "**/*.js"). Defaults to JS, TSX, CS, PHP, CSS, PY files.
• -f, --format <format>: Output format (xml, markdown, json). Default: markdown.
• -l, --detail <level>: Level of detail (minimal, standard, detailed). Default: standard.
• --include-types <types...>: Only include specific definition types (e.g., class, method).
• --exclude-types <types...>: Exclude specific definition types.
• --include-modifiers <modifiers...>: Only include definitions with specific modifiers (e.g., public).
• --exclude-modifiers <modifiers...>: Exclude definitions with specific modifiers.
• --name-pattern <regex>: Include definitions matching a JavaScript regex pattern.
• --exclude-name-pattern <regex>: Exclude definitions matching a JavaScript regex pattern.
• --include-paths <paths...>: Additional file path patterns (glob) to include.
• --exclude-paths <paths...>: File path patterns (glob) to exclude.
• -h, --help: Display detailed help information for all options.

Example (Scan TypeScript files in src, output detailed JSON):

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

2. MCP Server Mode (scan_code tool)

If run without the --directory argument, the tool starts as an MCP server, listening for requests via standard input/output. This allows integration with MCP clients like AI assistants.

• Tool Name: scan_code
• Description: Scans a specified directory for code files and returns a list of definitions according to the provided filters.
• Input Schema: Accepts arguments corresponding to the CLI options. The directory property is required.
  Copy

  {
    "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"]
  }

• Example Usage with AI Assistant: "Use code-scanner-server scan_code on directory /path/to/project outputting xml format."

Installation

1. Prerequisites: Ensure you have Node.js and npm installed.
2. Clone (Optional): If you don't have the code, clone the repository.
   Copy

   # git clone <repository_url>
   # cd code-scanner-server

3. Install Dependencies:
   Copy

   npm install

4. Build: Compile the TypeScript code.
   Copy

   npm run build

   This creates the executable JavaScript file at build/index.js.

Configuration (MCP Server)

To use the MCP server mode, add it to your MCP client's configuration file (e.g., claude_desktop_config.json for the desktop app or cline_mcp_settings.json for the VS Code extension).

Important: Replace /path/to/code-scanner-server in the example below with the absolute path to this project's directory on your system.

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

Remember to restart your MCP client application (IDE, Desktop App) after modifying the configuration for changes to take effect.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.