Code Analysis MCP

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

kb_system 接入方请阅读 kb_system接入Code Analysis MCP指南。

当前边界

• 一个MCP服务支持多个项目。

• 项目通过服务端配置的精确绝对根目录选择。

• Agent和SKILL由项目提供，客户端不能自行指定。

• 每次分析使用独立的无持久化Claude Code进程。

• MCP只透传Markdown报告，不解析报告正文。

• 第一阶段只允许代码和日志分析；可按项目在每次分析前执行一次 svn update，但不负责修改源码、构建、启动、部署、热更新或提交项目。

Related MCP server: cc-agent

环境要求

• 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客户端的无状态兼容处理。

安装与构建

npm install
npm run build
npm test

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

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

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

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

也可以只处理一个项目：

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：

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

Linux示例：

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：

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拼接命令。也可以配置固定路径：

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

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

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

npm run build
npm run start:http

默认地址：

• MCP：http://127.0.0.1:3100/mcp

• 健康检查：http://127.0.0.1:3100/healthz

指定其他配置：

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

stdio

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

输入：

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

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

analyze_codebase

输入：

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

等价的内部调用逻辑：

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 返回，文本包含稳定错误码和下一步建议：

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值。

远程配置示例：

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 -ExecutionPolicy Bypass -File .\scripts\windows\install-code-mcp-task.ps1

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

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

重启服务：

Stop-ScheduledTask -TaskName CodeAnalysisMCP
Start-ScheduledTask -TaskName CodeAnalysisMCP

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

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：

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提交能力。