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，但不负责修改源码、构建、启动、部署、热更新或提交项目。

环境要求

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

错误码	含义
`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值。

远程配置示例：

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

kb_system接入信息

交付时提供：

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

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

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
code_src		code_src
config		config
docs		docs
examples		examples
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
README.md		README.md
evals.xml		evals.xml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

Code Analysis MCP

当前边界

环境要求

安装与构建

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

多项目配置

SVN更新与目录过滤

Claude Code可执行文件

启动

Streamable HTTP

stdio

分析耗时日志

MCP工具

`list_projects`

`inspect_repository`

`analyze_codebase`

错误码

超时、取消与并发

HTTP安全

kb_system接入信息

Windows首版部署

kb_system调用示例

已知限制

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Code Analysis MCP

当前边界

环境要求

安装与构建

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

多项目配置

SVN更新与目录过滤

Claude Code可执行文件

启动

Streamable HTTP

stdio

分析耗时日志

MCP工具

list_projects

inspect_repository

analyze_codebase

错误码

超时、取消与并发

HTTP安全

kb_system接入信息

Windows首版部署

kb_system调用示例

已知限制

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`list_projects`

`inspect_repository`

`analyze_codebase`