场景：AI Agent 写出 3000 行文件？Scopewalker MCP 用 8 个分析工具守住代码质量防线
你让 Claude Code 重构一个模块，它利落地写完了一整个文件——3000 行，一个函数塞了 15 个参数，一个接口嵌套了 8 层。这不是个例：AI 编码 Agent 天然倾向于写大文件、长函数、多参数，因为它在上下文窗口中看到的是整个文件，自然不会意识到「这个文件已经太大了」。
传统上我们依赖代码审查来阻止这类问题，但审查到发现一个函数有 12 个参数时，代码已经合并了。事后审查的成本远高于事前约束——这正是 Scopewalker MCP 要解决的核心问题。
| 场景 | 传统方案 | Scopewalker 方案 |
|---|---|---|
| Agent 写了一个 500 行函数 | 审查时发现，要求重构 | Agent 写之前就知道 100 行上限 |
| 文件膨胀到 2000 行 | 没人注意，直到重构困难 | check_thresholds 在每次提交前自动阻止 |
| 参数从 3 个慢慢加到 12 个 | 渐进式恶化，无人察觉 | get_complexity_metrics 标记危险区 |
| 代码中出现 FIXME/TODO | 在 Issue 中累积 | get_code_smells 在合并前捕获 |
| 深层 prop drilling | 运行时才发现 | get_prop_drilling 静态分析预警 |
5 分钟上手 Scopewalker
Scopewalker 是一个本地 MCP 服务端，纯本地运行，无网络调用，通过 stdio 与你的 AI 编码 Agent 通信。
依赖：
- Node.js 22+
- tokei（行计数工具）：
brew install tokei或cargo install tokei
安装：
git clone https://github.com/timohaa/scopewalker-mcp.git cd scopewalker-mcp npm install npm run build
配置到 Claude Code：
{
"mcpServers": {
"scopewalker-mcp": {
"command": "node",
"args": ["/path/to/scopewalker-mcp/dist/index.js"]
}
}
}
或用 CLI 命令：claude mcp add scopewalker-mcp --scope user -- node /path/to/scopewalker-mcp/dist/index.js
配置好后，你在 Claude Code 中说一句「检查这个仓库的质量阈值」——Agent 就会自动调用 Scopewalker 的工具进行分析。
Scopewalker 也支持 Cursor（~/.cursor/mcp.json）、VS Code（.vscode/mcp.json）、Windsurf、Gemini CLI 和 OpenAI Codex CLI，配置方式几乎相同。
8 个分析工具，覆盖代码质量的方方面面
文件与函数规模管控
get_line_counts 返回每个文件的总行数、代码行、空行和注释行，支持按扩展名过滤和排序。你的 Agent 在提交前可以自动调用它，确保没有一个文件突破团队约定的上限。
check_thresholds 更进一步——直接标记超过阈值的文件和函数（默认：文件 300 行、函数 100 行）。你可以想象成在 Agent 的思维链中嵌入了一个「代码质量门禁」：在 Agent 决定「这个文件写完了」之前，先跑一次阈值检查，如果超标就主动拆分。
复杂度诊断
get_complexity_metrics 是 Scopewalker 最核心的工具之一。它计算每个文件的：
- 最大/平均嵌套深度——超过 4 层的函数会被标记为热点
- 参数数量——包括 JSX props，超过 5 个参数即预警
- 认知复杂度（cognitive complexity）——比圈复杂度更准确地反映人类理解代码的难度
- 导入数量——间接的耦合度指标
get_functions 提供了更细粒度的控制：你可以要求它返回所有超过 min_lines 阈值的函数，按行数排序。这在重构遗留代码时尤其有用——先找到最大的函数，再决定如何拆分。
代码库清单与文档覆盖
get_code_inventory 生成完整的代码库结构清单：类及其方法、函数、接口/类型、枚举、常量，每个元素都会标注是否为公开导出。默认隐藏私有符号，让 Agent 只关注公共 API。
get_documentation_coverage 则扫描每个函数、类和方法，找出缺少文档注释的代码段——支持 JSDoc、Python docstrings、Rust /// 等多种格式。在生成 PR 时，你可以让 Agent 先运行这个工具，自动补全缺失的文档。
代码异味与 prop drilling
get_code_smells 从 AST 层面扫描 TODO、FIXME、HACK、XXX、BUG、UNUSED、DEPRECATED 标记——但只扫描注释节点，不会因为字符串中出现「TODO」就误报。同时也会检测 TypeScript 中的 as unknown as 强制类型转换，这是代码腐烂的常见前兆。
get_prop_drilling 追踪参数在多函数/多文件之间传递的路径。它返回风险评级（高/中/低），并附上传播证据——参数名、传递链、涉及的函数名。这是纯静态分析，不需要运行代码就能发现深层嵌套的 prop drilling 问题。
与其他方案对比
| 特性 | Scopewalker MCP | ESLint + Prettier | SonarQube | Claude Code Rules |
|---|---|---|---|---|
| MCP 原生集成 | ✅ 直接调用 | ❌ 需自定义工具 | ❌ 外部 API | ✅ |
| 函数复杂度分析 | ✅ 嵌套深度+认知复杂度 | ✅ cyclomatic | ✅ 完整 | ❌ |
| Prop drilling 检测 | ✅ 静态追踪 | ❌ | 部分 | ❌ |
| 文档覆盖率 | ✅ 多种语言 | ❌ | ✅ | ❌ |
| 文件阈值 | ✅ 可配置 | ✅ max-lines | ✅ | 部分 |
| 完全本地/无网络 | ✅ | ✅ | ❌ 需服务器 | ✅ |
| 支持语言数量 | 7 种 | 数十种 | 20+ 种 | 不限 |
注意事项
- 需要 Node.js 22+：旧版本 Node 可能无法运行
- tokei 是必需依赖：
get_line_counts依赖 tokei 做行计数，需要额外安装 - 大文件跳过：AST 分析工具会跳过超过 1MB 的文件，这是为了防止内存/CPU 耗尽
- 输出上限：默认返回 20 个文件/项，可通过
limit参数调整 - 仅适用于本地分析：因为是纯 stdio MCP 服务端，只能在开发机上使用，不适合 CI/CD 集成
总结
Scopewalker MCP 解决的不是「能不能写出代码」的问题，而是「AI Agent 写出的是否是可维护的代码」的问题。它的 8 个工具覆盖了文件规模、函数复杂度、代码异味、文档覆盖、prop drilling 等关键质量维度——全部以 MCP 工具的形式直接融合到 Agent 的工作流中，无需切换工具、无需手动触发。
对于已经受困于「AI 代码质量下降」的团队来说，在 Agent 的配置中加上 Scopewalker，让质量检查前移到「写代码时」而非「审查时」，是一个低投入高回报的改进方向。
- GitHub：https://github.com/timohaa/scopewalker-mcp
- 许可证：MIT
- 技术栈：TypeScript + tree-sitter + tokei