scopewalker-mcp

Scopewalker MCP

AI Agent 往往会轻易创建超过 1000 行的源文件，还会在函数调用中增加第 20 个参数，即使规则文件明确要求不要这样做。Scopewalker 旨在强制执行更严格的代码库规范。

这是一个本地 MCP 服务（开源，通过 stdio 运行，不会发起网络请求），提供 9 个只读工具：

• get_line_counts - 按文件统计行数（总行数、代码行、空行、注释行），支持排序、扩展名筛选和项目级总计
• get_functions - 检测函数和方法；可统计每个文件中的数量，或通过 detail=lines 获取每个函数的行数指标，并使用 min_lines 筛选以查找过大的函数
• get_complexity_metrics - 最大/平均嵌套深度和参数数量（包括 JSX props）、导入数量、每个文件的认知复杂度评分，以及每个函数的圈复杂度和高/极高严重性分级；还会标记深度嵌套或参数过多的函数热点
• check_thresholds - 标记超过大小阈值的文件和函数（默认值：每个文件 300 行，每个函数 100 行）
• get_code_inventory - 类及其方法、函数、接口/类型、枚举和常量，并逐个标注是否已导出；默认隐藏私有符号
• get_documentation_coverage - 文档覆盖率百分比，以及每个缺少文档注释的函数、类或方法（支持 JSDoc、Python 文档字符串、Rust /// 和其他语言专用格式）
• get_code_smells - 通过 AST 扫描实际注释，查找 TODO/FIXME/HACK/XXX/BUG/UNUSED/DEPRECATED 标记（不会将字符串字面量误报为问题）；还会查找 TypeScript 中的 as unknown as / as any as 双重类型断言
• get_prop_drilling - 追踪在多个函数和文件中传递的参数名，并提供转发证据和高/中/低风险评级
• find_dead_code - 查找未引用的顶层符号和私有方法，并分为确定的 dead_code 和需要人工判断的 unreferenced_exports

底层使用 tree-sitter（解析）+ tokei（行数统计）+ fast-glob（文件查找）；没有自定义解析器。已在 macOS 上使用 Claude Code 测试，但应该也适用于 Cursor、VS Code、Windsurf、Antigravity CLI、Codex，或任何支持 MCP 的工具。

请参阅 TOOLS.md 查看快速参考，docs/ 查看各工具的参数和响应示例，并参阅 docs/usage-examples.md 查看如何将 Scopewalker 接入技能、子 Agent 和 AGENTS.md 的指南。

安全默认设置

• 无网络访问： 所有分析都在本地通过 stdio 运行：数据不会离开你的设备，也不涉及 API 密钥或外部服务。
• 路径范围： 所有工具只能在允许的根目录内操作。设置后，SCOPEWALKER_ALLOWED_ROOTS=/abs/path1,/abs/path2 优先级最高。否则，服务会使用 MCP 客户端共享的工作区根目录；如果客户端没有共享任何根目录，则回退到当前工作目录和系统临时目录。
• 大文件保护： 基于 AST 的工具会跳过大于 1 MB 的文件，以避免过度占用内存/CPU。基于 Tokei 的行数统计不受此限制。
• 输入上限： max_files 上限为 10000，max_depth 上限为 64，limit 上限为 5000。
• 符号链接： 扫描目录时不会跟随符号链接。
• 输出限制： 除非设置 limit，否则工具默认最多返回 20 个文件/项目。
• 注释脱敏： get_code_smells 默认会对注释文本进行脱敏；传入 include_text: true 可显式返回代码片段。

要求

• Node.js 22+
• tokei - 使用 brew install tokei 或 cargo install tokei 安装

安装

Scopewalker 已发布到 npm，包名为 scopewalker-mcp；无需克隆或构建。将 MCP 客户端配置为通过 npx 运行（示例如下），或使用 npm install -g scopewalker-mcp 全局安装。

如需从源码构建，请参阅开发。

配置

Claude Code

claude mcp add --scope user scopewalker-mcp -- npx -y scopewalker-mcp

或者添加到 ~/.claude.json：

{
  "mcpServers": {
    "scopewalker-mcp": {
      "command": "npx",
      "args": ["-y", "scopewalker-mcp"]
    }
  }
}

详情请参阅 Claude Code MCP 文档。

Claude Desktop

从最新版本下载 scopewalker-mcp.mcpb，然后使用 Claude Desktop 打开它（或将其拖入 Settings > Extensions），即可一键安装。

Cursor

添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目）：

{
  "mcpServers": {
    "scopewalker-mcp": {
      "command": "npx",
      "args": ["-y", "scopewalker-mcp"]
    }
  }
}

或者通过 File > Preferences > Cursor Settings > MCP 进行配置。

详情请参阅 Cursor MCP 文档。

VS Code（GitHub Copilot）

添加到工作区中的 .vscode/mcp.json：

{
  "servers": {
    "scopewalker-mcp": {
      "command": "npx",
      "args": ["-y", "scopewalker-mcp"]
    }
  }
}

需要 VS Code 1.102+，并启用 Agent Mode。

详情请参阅 VS Code MCP 文档。

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "scopewalker-mcp": {
      "command": "npx",
      "args": ["-y", "scopewalker-mcp"]
    }
  }
}

或者通过 Windsurf Settings > Cascade > Manage MCPs 进行配置。

详情请参阅 Windsurf MCP 文档。

Antigravity CLI

添加到 ~/.gemini/config/mcp_config.json（全局）或 .agents/mcp_config.json（每个项目）：

{
  "mcpServers": {
    "scopewalker-mcp": {
      "command": "npx",
      "args": ["-y", "scopewalker-mcp"]
    }
  }
}

在提示词面板中使用 /mcp 检查服务状态并重新加载配置。

详情请参阅 Antigravity CLI MCP 文档。

对于 Gemini CLI，请将相同的 mcpServers 配置添加到 ~/.gemini/settings.json。请参阅 Gemini CLI MCP 文档。

OpenAI Codex CLI

添加到 ~/.codex/config.toml：

[mcp_servers.scopewalker-mcp]
command = "npx"
args = ["-y", "scopewalker-mcp"]

或者使用 CLI：

codex mcp add scopewalker-mcp -- npx -y scopewalker-mcp

详情请参阅 Codex MCP 文档。

使用

配置完成后，助手会自行调用 Scopewalker 的工具；无需特殊语法。可以这样提问：

• “提交前，检查此仓库是否符合我们的规模阈值”
• “src/ 中哪些函数的认知复杂度最高？”
• “查找 src/auth 中未编写文档的导出项”
• “此模块中是否还留有 TODO/FIXME/HACK 标记？”
• “显示参数超过 5 个的函数”

它会根据请求选择合适的工具和参数。

此仓库通过技能和 Agent 执行共享质量要求：

• .claude/skills/review-changes/SKILL.md：对尚未解决的规模、复杂度、代码异味、属性逐层传递或死代码问题，评审将不予通过
• .claude/agents/standards-enforcer.md：修复可执行的检查结果，并通过重新扫描和测试进行验证
• .claude/skills/polish/SKILL.md：在整个流程中跟踪尚未解决的检查结果，并验证最终状态
• .claude/agents/docs-reality-sync.md：使用 get_code_inventory 和 get_functions 使文档与代码保持同步

开发

如需从源码运行，而非使用 npm：

git clone https://github.com/timohaa/scopewalker-mcp.git
cd scopewalker-mcp
npm install
npm run build

然后将 MCP 客户端指向构建输出，例如 claude mcp add --scope user scopewalker-mcp -- node /path/to/scopewalker-mcp/dist/index.js。

npm run build          # Build the project
npm run check          # Version sync + lint + typecheck
npm run test           # Run tests
npm run test:coverage  # Run tests with coverage

贡献指南请参阅 CONTRIBUTING.md；有关工具注册、错误处理和测试模式，请参阅 docs/patterns.md。

支持的语言

基于 AST 的工具（除 get_line_counts 外的所有工具）可解析：

• TypeScript/JavaScript（.ts、.tsx、.js、.jsx、.mjs、.cjs）
• Python（.py）
• Go（.go）
• Rust（.rs）
• Java（.java）
• C/C++（.c、.h、.cpp、.cc、.cxx、.hpp）
• Ruby（.rb）

get_line_counts 通过 tokei 运行，因此会报告 tokei 可识别的所有语言。有关每种语言的检测内容，请参阅 docs/tools-overview.md。

许可证

MIT