Code Scanner Server

code-scanner-server

一款 CLI 工具和 MCP 服务，可扫描代码文件中的定义（类、函数等），遵循 .gitignore 规则，提供行号，并输出适合大模型使用的格式（XML/Markdown）。

本项目提供了一款使用 TypeScript 和 Node.js 构建的多功能代码扫描工具。它借助 Tree-sitter 解析库分析源代码并提取结构信息。该工具既可作为命令行界面（CLI）工具运行，也可作为 MCP（模型上下文协议）服务运行。

注意： 此工具正在积极开发中。核心功能已可正常运行，但部分功能或特定语言解析器可能尚未经过全面测试，且可能存在错误或限制。

功能

• 代码定义提取： 识别函数、类、变量、接口、方法等。
• 多语言支持： 通过 Tree-sitter 解析 JavaScript（.js、.jsx）、TypeScript（.ts、.tsx）、C#（.cs）、PHP（.php）、CSS（.css）和 Python（.py）。
• 遵循 .gitignore： 自动遵循 .gitignore 文件中定义的规则。
• 灵活筛选： 按定义类型、修饰符（public、private）、名称模式（正则表达式）和文件路径模式筛选结果。
• 多种输出格式： 以 Markdown（默认）、XML 或 JSON 格式生成结果。
• 可配置的详细程度： 输出详细程度：minimal、standard（默认）、detailed。
• 双模式运行： 可作为独立 CLI 工具运行，也可作为集成的 MCP 服务运行。

使用模式

1. 命令行界面（CLI）

直接从终端运行扫描器。此模式需要通过 --directory 参数指定目标代码库。

基本用法：

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

常用选项：

• -d, --directory <path>：（必填）要扫描目录的绝对路径或相对路径。
• -p, --patterns <patterns...>：文件扩展名的 Glob 模式（例如，"**/*.ts" "**/*.js"）。默认扫描 JS、TSX、CS、PHP、CSS、PY 文件。
• -f, --format <format>：输出格式（xml、markdown、json）。默认值：markdown。
• -l, --detail <level>：详细程度（minimal、standard、detailed）。默认值：standard。
• --include-types <types...>：仅包含指定的定义类型（例如，class、method）。
• --exclude-types <types...>：排除指定的定义类型。
• --include-modifiers <modifiers...>：仅包含带有指定修饰符的定义（例如，public）。
• --exclude-modifiers <modifiers...>：排除带有指定修饰符的定义。
• --name-pattern <regex>：包含符合 JavaScript 正则表达式模式的定义。
• --exclude-name-pattern <regex>：排除符合 JavaScript 正则表达式模式的定义。
• --include-paths <paths...>：要包含的额外文件路径模式（Glob）。
• --exclude-paths <paths...>：要排除的文件路径模式（Glob）。
• -h, --help：显示所有选项的详细帮助信息。

示例（扫描 src 中的 TypeScript 文件，并输出详细 JSON）：

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

2. MCP 服务模式（scan_code 工具）

如果未使用 --directory 参数运行，工具会以 MCP 服务模式启动，通过标准输入/输出监听请求。这样即可与 AI 助手等 MCP 客户端集成。

• 工具名称： scan_code
• 描述： 扫描指定目录中的代码文件，并根据提供的筛选条件返回定义列表。
• 输入架构： 接受与 CLI 选项对应的参数。directory 属性为必填项。

  {
    "type": "object",
    "properties": {
      "directory": { "type": "string", "description": "要扫描的目录的绝对路径。" },
      "filePatterns": { "type": "array", "items": { "type": "string" }, "description": "文件的 Glob 模式。", "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": "名称的正则表达式模式。" },
      "excludeNamePattern": { "type": "string", "description": "用于排除名称的正则表达式模式。" },
      "includePaths": { "type": "array", "items": { "type": "string" } },
      "excludePaths": { "type": "array", "items": { "type": "string" } }
    },
    "required": ["directory"]
  }
  

• 使用 AI 助手的示例：“使用 code-scanner-server scan_code 扫描目录 /path/to/project，并以 xml 格式输出。”

安装

1. 前提条件： 确保已安装 Node.js 和 npm。
2. 克隆（可选）： 如果尚未获取代码，请克隆代码库。

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

3. 安装依赖项：

   npm install
   

4. 构建： 编译 TypeScript 代码。

   npm run build
   

   这会在 build/index.js 创建可执行的 JavaScript 文件。

配置（MCP 服务）

要使用 MCP 服务模式，请将其添加到 MCP 客户端的配置文件中（例如，桌面应用使用的 claude_desktop_config.json，或 VS Code 扩展使用的 cline_mcp_settings.json）。

重要提示： 请将以下示例中的 /path/to/code-scanner-server 替换为系统上此项目目录的绝对路径。

示例（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
    }
  }
}

修改配置后，请记得重启 MCP 客户端应用（IDE、桌面应用），以使更改生效。

开发

• 监视模式： 源文件发生变化时自动重新构建项目：

  npm run watch
  

• 调试（MCP 模式）： 通过 stdio 调试 MCP 服务可能比较复杂。使用 MCP Inspector 工具可以更轻松地进行调试：

  npm run inspector
  

  这会启动带有 Node.js 检查器的服务，并提供一个用于连接调试工具（例如 Chrome DevTools）的 URL。

致谢

本项目的开发在很大程度上得到了 AI 的协助，主要使用通过 Visual Studio Code 的 Roo Code 扩展访问的 Google Gemini 2.5 Pro 模型。

许可证

本项目采用 GNU General Public License v3.0 许可。详情请参阅 LICENSE 文件。