timohaa/scopewalker-mcp
GitHub: timohaa/scopewalker-mcp
面向 AI 编程助手的本地 MCP 服务器，用于执行代码库质量标准并检测复杂度与代码异味。
Stars: 0 | Forks: 0
# Scopewalker MCP
AI agents 非常乐意创建 1000 多行的源文件，并在函数调用中添加第 20 个参数，即使有规则文件告诉它们不要这样做。Scopewalker 的存在就是为了执行更严格的代码库标准。
它是一个本地 MCP server（开源，通过 stdio 运行，不进行任何网络调用），提供 8 个只读工具：
- `get_line_counts` - 每个文件的行数统计（总计、代码、空行、注释），支持排序、扩展名过滤和全项目总计
- `get_functions` - 函数和方法检测；可通过 `detail=lines` 查看每个文件的计数或每个函数的行数指标，并带有 `min_lines` 过滤器，用于查找过大的函数
- `get_complexity_metrics` - 最大/平均嵌套深度和参数计数（包括 JSX props）、import 计数，以及每个文件的认知复杂度评分，并标记深度嵌套或参数过多的函数作为热点
- `check_thresholds` - 标记超过大小阈值的文件和函数（默认：每个文件 300 行，每个函数 100 行）
- `get_code_inventory` - 类及其方法、函数、接口/类型、枚举和常量，每个都标记是否导出；默认隐藏私有符号
- `get_documentation_coverage` - 覆盖率百分比，以及缺少文档注释（JSDoc、Python docstrings、Rust `///` 和其他特定语言格式）的每个函数、类或方法
- `get_code_smells` - 通过 AST 扫描实际注释找到的 TODO/FIXME/HACK/XXX/BUG/UNUSED/DEPRECATED 标记（字符串字面量不会产生误报），以及 TypeScript 中的 `as unknown as` / `as any as` 双重类型转换
- `get_prop_drilling` - 贯穿多个函数和文件的参数名称，带有转发证据和高/中/低风险评级
它底层使用 tree-sitter（解析）+ tokei（行数统计）+ fast-glob（文件发现）；没有任何内容是自定义解析的。在 macOS 上结合 Claude Code 进行了测试，但应该适用于 Cursor、VS Code、Windsurf、Gemini CLI、Codex 或任何其他支持 MCP 的工具。
请参阅 [TOOLS.md](TOOLS.md) 获取快速参考，以及 [docs/](docs/) 了解各工具的参数和示例响应。
## 安全默认设置
- **无网络访问：** 所有分析均通过 stdio 在本地运行——不会有任何数据离开您的机器，不涉及 API 密钥或外部服务。
- **路径范围限制：** 所有工具仅在允许的根目录（默认：当前工作目录和系统 temp）内运行。可通过 `SCOPEWALKER_ALLOWED_ROOTS=/abs/path1,/abs/path2` 进行覆盖。
- **大文件防护：** 基于 AST 的工具会跳过大于 1 MB 的文件，以避免过多的内存/CPU 消耗。基于 tokei 的行数统计不执行此限制。
- **输出限制：** 除非设置了 `limit`，否则工具默认返回 20 个文件/项目。
- **注释脱敏：** `get_code_smells` 默认隐藏注释文本；传入 `include_text: true` 可显式返回代码片段。
## 环境要求
- Node.js 22+
- [tokei](https://github.com/XAMPPRocky/tokei) - 通过 `brew install tokei` 或 `cargo install tokei` 安装
## 安装
Scopewalker 已发布到 npm，包名为 [`scopewalker-mcp`](https://www.npmjs.com/package/scopewalker-mcp)——无需克隆或构建。配置您的 MCP client 通过 `npx` 运行它（示例见下文），或者使用 `npm install -g scopewalker-mcp` 全局安装。
如果要从源码构建，请参阅[开发](#development)。
## 配置
### Claude Code
```
claude mcp add scopewalker-mcp --scope user -- npx -y scopewalker-mcp
```
或者添加到 `~/.claude.json`：
```
{
"mcpServers": {
"scopewalker-mcp": {
"command": "npx",
"args": ["-y", "scopewalker-mcp"]
}
}
}
```
详情请参阅 [Claude Code MCP 文档](https://code.claude.com/docs/en/mcp)。
### Claude Desktop
从[最新发布版本](https://github.com/timohaa/scopewalker-mcp/releases/latest)下载 `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 文档](https://cursor.com/docs/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 文档](https://code.visualstudio.com/docs/agent-customization/mcp-servers)。
### Windsurf
添加到 `~/.codeium/windsurf/mcp_config.json`：
```
{
"mcpServers": {
"scopewalker-mcp": {
"command": "npx",
"args": ["-y", "scopewalker-mcp"]
}
}
}
```
或者通过“Windsurf Settings > Cascade > Manage MCPs”进行配置。
详情请参阅 [Windsurf MCP 文档](https://docs.devin.ai/desktop/cascade/mcp)。
### Gemini CLI
添加到 `~/.gemini/settings.json`：
```
{
"mcpServers": {
"scopewalker-mcp": {
"command": "npx",
"args": ["-y", "scopewalker-mcp"]
}
}
}
```
详情请参阅 [Gemini CLI MCP 文档](https://geminicli.com/docs/tools/mcp-server/)。
### 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 文档](https://developers.openai.com/codex/mcp/)。
## 用法
配置完成后，AI 助手会自动调用 Scopewalker 的工具——无需特殊语法。您可以这样提问：
- "在提交之前，检查这个仓库是否符合我们的大小阈值"
- "`src/` 中哪些函数的认知复杂度最高？"
- "找出 `src/auth` 中未记录文档的导出项"
- "这个模块中还有遗留的 TODO/FIXME/HACK 标记吗？"
- "给我展示接收超过 5 个参数的函数"
它会根据请求选择合适的工具和参数。
本仓库还通过 Claude Code 的 skills 和 agents 自用（dogfood）了其工具：
- [`.claude/skills/check-quality/SKILL.md`](.claude/skills/check-quality/SKILL.md) — 作为质量门禁的一部分运行 `check_thresholds` 和 `get_code_smells`
- [`.claude/agents/standards-enforcer.md`](.claude/agents/standards-enforcer.md) — 使用全套工具来查找并修复标准违规
- [`.claude/agents/docs-reality-sync.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 client 指向构建输出，例如 `claude mcp add scopewalker-mcp --scope user -- node /path/to/scopewalker-mcp/dist/index.js`。
```
npm run build # Build the project
npm run check # Lint + typecheck
npm run test # Run tests
npm run test:coverage # Run tests with coverage
```
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解贡献指南，以及 [docs/patterns.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](docs/tools-overview.md#supported-languages) 了解每种语言的检测内容。
## 许可证
MIT
标签：AI辅助编程, MCP服务器, MITM代理, Tree-sitter, 云安全监控, 代码规范, 代码质量分析, 自动化攻击, 静态分析