code-scanner-server

一个 CLI 工具和 MCP 服务器，用于扫描代码文件的定义（类、函数等）、尊重 .gitignore、提供行号并输出 LLM 友好格式（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 Aware：**自动遵守.gitignore文件中定义的规则。
• **灵活过滤：**按定义类型、修饰符（ public 、 private ）、名称模式（正则表达式）和文件路径模式过滤结果。
• **多种输出格式：**以 Markdown（默认）、XML 或 JSON 生成结果。
• **可配置的详细程度：**输出详细程度： minimal 、 standard （默认）、 detailed 。
• **双模式操作：**作为独立 CLI 工具或集成 MCP 服务器运行。

使用模式

1.命令行界面（CLI）

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

基本用法：

常用选项：

• -d, --directory <path> ：（必需）要扫描的目录的绝对路径或相对路径。
• -p, --patterns <patterns...> ：文件扩展名的全局模式 (例如， "**/*.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）：

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

如果运行时不带--directory参数，该工具将作为 MCP 服务器启动，并通过标准输入/输出监听请求。这允许与 AI 助手等 MCP 客户端集成。

• 工具名称： scan_code
• **描述：**扫描指定目录中的代码文件并根据提供的过滤器返回定义列表。
• **输入模式：**接受与 CLI 选项对应的参数。 directory属性是必需的。
  { "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"] }
• AI 助手的使用示例： “在目录 /path/to/project 上使用 code-scanner-server scan_code 输出 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 ）：

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

发展

• **监视模式：**当源文件发生变化时自动重建项目：
  npm run watch
• **调试（MCP 模式）：**通过 stdio 调试 MCP 服务器可能比较复杂。使用 MCP Inspector 工具可以更轻松地进行调试：
  npm run inspector
  这将启动附加了 Node.js 检查器的服务器并提供用于连接调试工具（如 Chrome DevTools）的 URL。

致谢

该项目在人工智能的帮助下得到了显著发展，主要使用通过 Visual Studio Code 的 Roo Code 扩展访问的 Google Gemini 2.5 Pro 模型。

执照

该项目根据 GNU 通用公共许可证 v3.0 获得许可 - 有关详细信息，请参阅LICENSE文件。