# Code Analysis MCP

一个面向 `kb_system` 的多项目代码分析 MCP。MCP层不理解项目业务，也不解析项目的 `MODULE.md`、Agent或SKILL内容；它只在已注册项目根目录中启动一次独立的 `claude -p`，并将项目SKILL产生的完整Markdown报告直接返回给MCP客户端。

`kb_system` 接入方请阅读 [kb_system接入Code Analysis MCP指南](docs/kb-system-mcp-integration.md)。

## 当前边界

- 一个MCP服务支持多个项目。
- 项目通过服务端配置的精确绝对根目录选择。
- Agent和SKILL由项目提供，客户端不能自行指定。
- 每次分析使用独立的无持久化Claude Code进程。
- MCP只透传Markdown报告，不解析报告正文。
- 第一阶段只允许代码和日志分析；可按项目在每次分析前执行一次 `svn update`，但不负责修改源码、构建、启动、部署、热更新或提交项目。

## 环境要求

- Node.js 22或更高版本。
- Claude Code已安装并完成认证。
- 每个项目至少提供：
  - `.claude/agents/<agent>.md`
  - `.claude/skills/<skill>/SKILL.md`
- `MODULE.md`由项目决定是否使用；MCP只在检查结果中报告它是否存在。

当前依赖MCP TypeScript SDK v2，对应2026-07-28协议，同时保留对2025-era客户端的无状态兼容处理。

## 安装与构建

```powershell
npm install
npm run build
npm test
```

### 复用脚本：更新指定SVN目录

三个配置项目无需重复输入URL、根目录和更新路径：

```powershell
# 首次建立sparse checkout；只下载update_paths及必要父目录
npm run svn:checkout -- --all

# 后续按各项目配置的update_paths更新
npm run svn:update:projects -- --all
```

也可以只处理一个项目：

```powershell
npm run svn:checkout -- --project qt_01_trunk
npm run svn:update:projects -- --project qt_05_trunk
```

批量脚本默认串行，可用 `--jobs 2` 控制并发。checkout先以 `--depth empty` 建立工作副本，再用 `--parents` 只展开 `update_paths`；重复执行会核对URL并补齐缺失路径。

脚本不会默认更新整个工作副本，必须显式传入一个或多个 `--path`：

```powershell
npm run svn:update -- --root D:/server05/trunk2 --path src --path config/app --username svn-reader
```

Linux示例：

```bash
npm run svn:update -- --root /data/server05/trunk2 --path src --path include
```

目录必须是相对 `--root` 的路径，不能使用 `../` 跳出工作副本。脚本默认使用 `--ignore-externals`，更新后检查SVN冲突；密码只使用当前服务账号的SVN认证缓存。需要服务器版本强制覆盖指定路径时增加 `--server-wins`，该参数会永久清除指定路径内的所有本地改动和未版本化/忽略项。完整参数可运行 `npm run svn:update -- --help` 查看。

## 多项目配置

编辑 `config/projects.yaml`：

```yaml
server:
  host: 127.0.0.1
  port: 3100
  mcp_path: /mcp
  health_path: /healthz

defaults:
  timeout_ms: 300000
  hard_timeout_ms: 900000
  max_concurrency: 4
  max_output_bytes: 2097152
  max_question_chars: 16000

claude:
  executable: auto

projects:
  server05_trunk2:
    name: server05 Erlang game server
    code: server05
    root: D:/server05/trunk2
    agent: code-error-logic-agent
    skill: code-error-logic-consultant
    allowed_dirs:
      - .claude/agents
      - src
      - config/app
      - logs
    allowed_files:
      - AGENTS.md
      - CLAUDE.md
      - proto/game_proto.txt
    exclude_dirs:
      - .svn
      - _build
      - node_modules
      - bak
      - config/excel
    svn:
      update_before_analysis: true
      executable: svn
      username: svn-reader
      expected_url: https://svn.example.internal/project/trunk
      update_paths:
        - .claude/agents
        - .claude/skills/code-error-logic-consultant
        - src
        - config/app
        - AGENTS.md
      conflict_policy: server_wins
      ignore_externals: true
      timeout_ms: 120000
    timeout_ms: 600000
    max_concurrency: 2
```

新增项目只需要登记项目代码、根目录、Agent、SKILL、SVN账号和过滤目录，不需要修改MCP代码。`repo_path`必须与注册表中的根目录精确匹配；项目子目录、未注册目录和相对路径都会被拒绝。

### SVN更新与目录过滤

- `root` 是本地SVN工作副本绝对路径；`svn.expected_url` 可选，用于在更新前核对工作副本对应的仓库地址。
- `svn.update_before_analysis: true` 时必须配置 `svn.update_paths`。每次 `analyze_codebase` 只更新这些相对路径，成功后才启动Claude Code；服务不会默认执行 `svn update .`。
- `svn.username` 是可选账号名；省略时使用MCP服务账号已有的SVN认证缓存。密码不得写入YAML、日志或启动参数。
- `svn.ignore_externals: true` 会给更新命令增加 `--ignore-externals`。
- SVN更新与同一项目的分析共用项目并发锁，不会并行更新同一个工作副本。`update_paths` 不能位于 `exclude_dirs` 内。
- `svn.conflict_policy: fail` 会保留本地状态并在冲突时失败。
- `svn.conflict_policy: server_wins` 会在每次更新前，对 `update_paths` 执行递归 `revert --remove-added` 和 `cleanup --remove-unversioned --remove-ignored`，永久清除这些路径中的本地修改、添加项、未版本化项和忽略项，然后以服务器版本更新。该策略不会清理 `update_paths` 之外的内容。
- 更新、清理、认证或冲突检查失败时，本次分析直接失败。
- `allowed_dirs` 和 `allowed_files` 是分析白名单；只要其中任意一个非空，Claude就只能读取、搜索和引用这些路径。二者都为空时允许分析整个项目。
- `exclude_dirs` 是最高优先级排除列表，即使路径同时位于白名单内也不得分析。三类路径都必须是相对项目根目录的路径。
- 白名单和排除列表只约束分析提示，不会删除目录，也不会改变SVN sparse depth。

### Claude Code可执行文件

`executable: auto` 在Windows优先解析npm全局安装中的原生 `claude.exe`，避免通过CMD或PowerShell拼接命令。也可以配置固定路径：

```yaml
claude:
  executable: C:/tools/claude/claude.exe
```

Linux也可以配置Claude包装脚本，例如 `claude-glm-cli.sh`：

```yaml
claude:
  executable: /opt/claude/claude-glm-cli.sh
  prefix_args: []
```

当 `executable` 以 `.sh` 结尾且运行在Linux/macOS时，MCP会使用 `/bin/bash <脚本> ...` 执行，脚本通过stdin接收完整问题，后续参数仍保持原有Claude Code参数。脚本应最终转发这些参数并返回Markdown到stdout；stderr不会返回给客户端。

服务端使用参数数组启动进程，并通过stdin传递用户问题；不会把问题拼进Shell命令。
Claude Code显式加载 `user,project,local` 设置来源：`user` 提供服务账号的模型和认证配置，`project/local` 提供目标项目的Agent、SKILL及项目规则。生产环境应使用专用服务账号，并审查该账号的Claude用户级配置。

## 启动

### Streamable HTTP

```powershell
npm run build
npm run start:http
```

默认地址：

- MCP：`http://127.0.0.1:3100/mcp`
- 健康检查：`http://127.0.0.1:3100/healthz`

指定其他配置：

```powershell
node dist/src/http.js --config config/projects.local.yaml
```

### stdio

```powershell
npm run build
npm run start:stdio
```

stdio模式所有运行日志都写入stderr，不会污染MCP JSON-RPC标准输出。

### 分析耗时日志

`analyze_codebase` 的结构化日志使用同一个 `request_id` 串联请求，并按阶段输出：

- `analysis_queue_acquired`：`project_queue_ms`、`global_queue_ms`。
- `svn_started`、`svn_phase_completed`、`svn_update_completed`：分别记录 `info`、`revert`、`cleanup`、`update`、`status` 和 `svn_total_ms` 对应耗时。
- `claude_spawned`：Claude子进程PID和启动耗时。
- `claude_first_output`：从启动到首次标准输出的耗时。
- `process_tree_terminated`：取消、超时或结果过大时的进程组终止耗时与是否升级到强制终止。
- `analysis_completed`：校验、排队、SVN、Claude首输出、Claude总耗时和工具处理总耗时。
- `analysis_failed`：工具处理总耗时、稳定错误码和错误类型。

`analysis_completed.duration_ms` 从工具处理入口计到分析结果生成完成，不包含客户端网络接收完成时间。日志不记录问题正文、Claude报告、SVN密码或Token值。

## MCP工具

### `list_projects`

列出已启用项目的精确 `repo_path`、Agent和SKILL。项目不明确时先调用。

### `inspect_repository`

输入：

```json
{
  "repo_path": "D:/server05/trunk2"
}
```

只检查项目目录、`MODULE.md`、Agent和SKILL是否可用，不启动Claude Code。

### `analyze_codebase`

输入：

```json
{
  "repo_path": "D:/server05/trunk2",
  "question": "分析错误码11050的定义、触发位置和调用链",
  "mode": "analyze"
}
```

等价的内部调用逻辑：

```text
cwd = D:/server05/trunk2
claude -p --agent code-error-logic-agent --permission-mode dontAsk --no-session-persistence --output-format text
stdin = /code-error-logic-consultant <用户问题> + MCP只读约束
```

成功结果是MCP文本内容，正文为Claude Code生成的Markdown报告。MCP不会让Agent在项目目录中落盘报告。

## 错误码

工具错误使用MCP `isError: true` 返回，文本包含稳定错误码和下一步建议：

| 错误码 | 含义 |
| --- | --- |
| `INVALID_ARGUMENT` | 参数或绝对路径格式错误 |
| `REPOSITORY_NOT_FOUND` | 已注册项目当前不存在或不可访问 |
| `REPOSITORY_NOT_ALLOWED` | 项目未注册、未启用或不是精确根目录 |
| `AGENT_NOT_FOUND` | 项目配置的Agent文件不存在 |
| `SKILL_NOT_FOUND` | 项目配置的SKILL文件不存在 |
| `SVN_NOT_FOUND` | SVN客户端无法启动 |
| `SVN_UPDATE_FAILED` | SVN更新失败、超时、认证失败或工作副本异常 |
| `CLAUDE_NOT_FOUND` | Claude Code可执行文件无法启动 |
| `CLAUDE_UPSTREAM_BUSY` | Claude上游模型返回HTTP 529容量过载，可稍后重试 |
| `TOOL_TIMEOUT` | 排队或分析超过项目超时 |
| `RESULT_TOO_LARGE` | Markdown报告超过响应上限 |
| `REQUEST_CANCELLED` | 客户端取消请求 |
| `ANALYSIS_FAILED` | Claude Code失败、无输出或其他分析错误 |

Claude Code的stderr仅在服务端有界读取并用于识别已知错误；客户端只收到安全的分类结果，不返回原始stderr，避免泄露服务器路径、认证状态或其他无关诊断。

## 超时、取消与并发

- 默认超时5分钟，项目可覆盖，硬上限15分钟。
- MCP客户端超时建议比项目超时多30到60秒。
- 客户端取消后，服务端终止对应Claude Code进程树。
- 同时应用全局并发上限和项目并发上限。
- 项目排队不会占用全局执行槽，避免单个项目饿死其他项目。
- 不复用Claude会话，不在请求之间共享当前项目或问题上下文。

## HTTP安全

- 默认只监听 `127.0.0.1`。
- 校验Host和Origin，防止本地服务DNS重绑定攻击。
- 限制HTTP请求体大小、问题长度和Claude输出大小。
- 监听非回环地址时必须配置 `server.auth_token_env`，Token仅从环境变量读取。
- 远程访问还必须在反向代理或网关启用HTTPS；本服务不直接管理TLS证书。
- 不要在配置文件、日志或接入文档中保存Token值。

远程配置示例：

```yaml
server:
  host: 0.0.0.0
  port: 3100
  auth_token_env: CODE_MCP_BEARER_TOKEN
  allowed_origins:
    - https://kb.example.internal
```

## kb_system接入信息

交付时提供：

1. 服务地址或stdio启动命令。
2. Streamable HTTP或stdio传输方式。
3. 必需环境变量名称，不提供Token值。
4. `config/projects.yaml` 的项目登记方式。
5. `tools/list` 的实际输出。
6. `inspect_repository` 与 `analyze_codebase` 调用样例。
7. 超时和错误调用样例。
8. 项目Agent、SKILL缺失时的处理方式。
9. 当前只读边界和已知限制。

### Windows首版部署

首版使用当前Windows用户的登录触发计划任务，因为Claude Code认证和用户级配置属于该账号。它不是“开机但尚未登录”就启动的系统服务；当前用户登录后自动启动。默认仅监听回环地址，不需要开放Windows防火墙。若安装终端没有UAC提升权限，安装器会自动退回当前用户的“启动”目录快捷方式，登录启动行为相同；以后从提升权限的PowerShell重跑安装器即可切换为计划任务。

安装并立即启动：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\windows\install-code-mcp-task.ps1
```

查看任务状态和健康检查：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\windows\status-code-mcp.ps1
```

重启服务：

```powershell
Stop-ScheduledTask -TaskName CodeAnalysisMCP
Start-ScheduledTask -TaskName CodeAnalysisMCP
```

卸载计划任务（保留项目和日志）：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\windows\uninstall-code-mcp-task.ps1
```

运行日志位于 `logs/`。运行包装器在进程失败后每分钟重试，最多3次；计划任务模式还会拒绝重复实例。

### kb_system调用示例

同一台Windows机器上的地址为 `http://127.0.0.1:3100/mcp`。可运行示例会依次调用 `list_projects`、`inspect_repository` 和 `analyze_codebase`：

```powershell
node .\examples\kb-system-client.mjs "D:/server05/trunk2" "分析错误码11050的定义、触发位置和调用链"
```

脚本将完整Markdown报告单独写到stdout，项目检查等诊断写到stderr，`kb_system`可直接接收stdout入库。当前项目服务端超时为600秒，示例客户端超时为660秒；可通过 `CODE_MCP_CLIENT_TIMEOUT_MS` 覆盖。

如果 `kb_system` 不在同一台机器，不要直接暴露当前回环端点。第二阶段应改为非回环监听，配置 `server.auth_token_env`，并通过带HTTPS的反向代理或网关访问。

## 已知限制

- Markdown中的证据准确性由项目Agent和SKILL负责，MCP不解析或二次验证报告行号。
- Agent工具权限由项目Claude配置决定；MCP会追加只读提示，但提示本身不等价于操作系统沙箱。
- `allowed_dirs`、`allowed_files` 和 `exclude_dirs` 都是提示级过滤，不是操作系统级文件访问控制；需要硬隔离时应使用独立的过滤工作副本和受限服务账号。
- 非法Agent名称可能被Claude Code退回默认会话，因此MCP在启动前强制检查Agent文件存在。
- 当前不提供项目写操作、构建、运行、部署、热更新、Git或SVN提交能力。