What is Code Scanner Server

code-scanner-server is a CLI tool and MCP server designed to scan code files for definitions like classes and functions. Built with TypeScript and Node.js, it utilizes the Tree-sitter library for code analysis, ensures compliance with .gitignore files, and supports multiple output formats including XML, Markdown, and JSON.

Use cases

This tool is ideal for developers who need to extract and analyze code structure across various programming languages. It can help in code documentation generation, refactoring efforts, or understanding codebases, particularly in large projects. Additionally, it can be integrated with AI assistants for convenient code analysis requests.

How to use

Users can run the scanner as a CLI tool by providing the directory to scan and various optional parameters like file patterns and output format. Alternatively, it can function as an MCP server by omitting the directory argument, allowing integration with external tools or AI assistants that conform to the Model Context Protocol.

Key features

The tool boasts multi-language support for languages like JavaScript, TypeScript, C#, PHP, CSS, and Python. It also respects .gitignore rules, offers flexible filtering options, and allows for detailed customization of the output format and verbosity levels, catering to diverse user needs.

Where to use

code-scanner-server is suitable for use in development environments where code structure needs to be understood or documented. It can be used in IDEs as a plugin or through command line in continuous integration systems, making it a versatile tool for developers and teams aiming to enhance code quality and maintainability.

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.

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.

• 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.

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

3. Install Dependencies:

   npm install
   

4. Build: Compile the TypeScript code.

   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):

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

Development

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

  npm run watch
  

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

  npm run inspector
  

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

Acknowledgments

This project was significantly developed with the assistance of AI, primarily using Google’s Gemini 2.5 Pro model accessed via the Roo Code extension for Visual Studio Code.

License

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