项目简介

本项目实现了一套基于图结构的 MCP 工具链路径优化与评测方法：针对 LLM Agent 通过 MCP 调用外部工具时轨迹中存在的大量冗余调用与绕路问题，构建有向加权调用图，对工具链进行离线可达性保持压缩，在保持任务可达性与关键依赖（答案步）的前提下显著缩短工具链、减少冗余调用；并配套实现了图建模（M1）、检索增强路由（M2）、自反思闭环（M3）以及一套完整的离线/在线评测栈，用任务级 pass/fail 替代伪代理指标，对压缩效果进行可复现的诚实评测。

作者团队

东南大学网络安全学院

队长

余博嘉

MCP-Graph-Toolchain — 基于图结构的 MCP 工具链路径优化与评测

Graph-based path planning & retrieval-augmented routing for MCP (Model Context Protocol) tool chains, plus a full offline/online evaluation stack built on top of MCP-Universe.

本项目围绕一个核心目标：LLM Agent 通过 MCP 调用外部工具时，真实轨迹存在大量冗余调用与绕路——能否用图结构（工具转移概率）压缩 / 缩短工具链，在保持任务可达性的前提下减少冗余调用？工具链压缩是本项目首要交付物，其主评测轴是离线保真度与调用数下降；端到端任务成功率仅作为诊断性指标（受 base 模型制约，非本方法所能决定）。

主要贡献（均已实测，核心是「离线工具链压缩」）：

⭐ 链级压缩 / 规划（项目核心）：基于有向加权调用图的离线可达性保持压缩——语料 −10.5%、依赖 100% 保持、Track1 9 例 55→37 步（−32.7%）、离线保真度 100%；图规划最优仅 19 步，证明杠杆在「规划」而非「事后去重」。这是本项目首要、可复现的成果（详见 §2.1）。
M1 图建模：有向加权调用图 + 超图谱聚类 + Laplacian 标签传播。是 next-tool 路由中唯一稳定有效的组件（MCPU 全量 +2.03pp），也是链压缩的底层结构。
M2 检索增强路由：BGE-M3 嵌入 + FAISS HNSW + Cross-Encoder 重排（已证在 next-tool 上有害，保留为对照）。
M3 自反思闭环：失败诊断 + 经验缓冲 + 进化优化（live-loop 集成见 mcp-universe-addons/integration/）。
诚实评测：用 MCP-Universe 自带 evaluator 当裁判，指出 step-match/next-tool 准确率 是伪代理目标，评测轴必须换成任务级 pass/fail；并明确在线任务成功率受 base 模型制约，并非本压缩方法的评测主轴。

换行符约定：本仓库所有文本文件均已统一为 LF（Unix/Linux）行尾，.gitattributes 中已设 eol=lf；Windows 上编辑后请勿提交 CRLF（可用 git add --renormalize . 校正）。

1. 仓库结构

本仓库只含你自己的代码与文档，外部大型依赖（MCP-Universe 本体、BGE-M3 模型、Blender）通过 clone / 下载获取（见 §3）。

mcp-graph-toolchain/
├── src/mcp_path_optimization/        # 核心代码
│   ├── core/             # 数据类型 (ToolDef, CallGraph, RouterQuery) + 全局配置
│   ├── m1_graph/         # 调用图 / 超图 / 拉普拉斯标签传播（图调用核心）
│   ├── m2_router/        # BGE-M3 嵌入 / FAISS / CE 重排 / 训练
│   ├── m3_reflector/     # 反思 / 评估 / 进化
│   ├── orchestrator/     # 中央编排循环（M1→M2→执行→M3）
│   ├── bridge/           # MCP-Universe / Toucan 桥接（动态工具发现 + 真实执行）
│   ├── chain_analysis/   # 阶段 0–4 + 方向 A（诊断/依赖/压缩/评测/规划）
│   └── experiments/      # next-tool 消融路由器
├── configs/              # default.yaml / bridge.yaml / ablation/
├── docs/                 # 专题文档（运行指南、技术文档、离线压缩评测、报告…）
├── mcp-universe-addons/  # ⭐ 你对外部 MCP-Universe 仓库的所有自定义改动（见 §4）
│   ├── mcp_universe.patch        # 15 个改原文件的 git 补丁
│   ├── MCP_UNIVERSE_COMMIT.txt   # 补丁所基于的 MCP-Universe commit
│   ├── scripts/                  # 自定义评测/分析脚本（run_ab_multi.py, offline_compress.py…）
│   ├── integration/              # M3 live-loop 集成代码（graph_reflect_react.py 等）
│   ├── docs/                     # eval-workflows-zh.md
│   └── example_outputs/          # 示例评测结果 (.txt)
├── build_mcpu_ce.py              # CE 训练数据构建
├── build_multidomain_ce.py       # 多域 CE 训练数据构建
├── build_pptx.js                 # 项目介绍 PPT 生成
├── mcpu_traces.jsonl             # 小型轨迹数据（MCPU）
├── mcpu_ce_*.jsonl / mcpu_tool_registry.json   # ce_train_toucan.jsonl 由脚本生成（53MB，未入库）
├── toucan_e2e_results.json
├── MCP工具链路径优化_项目介绍*.pptx
├── requirements.txt
├── pyproject.toml
├── notes/                  # 方法论文档与轨迹数据（evaluation_plan_zh.md 等）
└── README.md

本地存在但不在 Git 中的大文件（已被 .gitignore 排除，见 §5）： traces_*/、router_eval/、results_*/（运行生成的轨迹与评测产物，约 210 MB）、 models/（BGE-M3 + CE 模型，6.8 GB）、checkpoints/、.env（密钥）。

2. 核心结果（可复现）

2.1 链压缩消融（主评测轴：链长 + 保真度，离线零 API）

本项目的核心成效以链长下降 + 依赖/答案步保持衡量，而非 next-tool 准确率（后者是伪代理目标，见 §2.3 与「诚实评测」）。以 Track1 的 9 个成功轨迹（原始总链长 55 步）为基准，对图方法进行链长口径的消融：

配置	总链长	压缩率	依赖保持	离线保真度	说明
基线（不压缩 / 频次）	55	0%	—	—	原始轨迹
Mode A（连续去重）	37	−32.7%	100%	100%	频次驱动的冗余删除
Mode B（图感知折叠）	35	−36.4%	100%	100%	折叠纯 navigate↔snapshot 回环
图规划最优	19	−65.5%	100%	100%	beam-search 整链规划，杠杆在「规划」

结论：图方法的真正杠杆在「整链规划」而非「事后去重」（19 vs 37，再省 18 步）；压缩全程 100% 保持依赖与答案步——即「链短了，关键没丢」。

注：M1 调用图是上述压缩的底层结构；M2 检索增强路由、M3 自反思闭环在 next-tool 路由上有害 / 未闭环（详见 src/.../experiments/run_ablation.py），故未进入主压缩路径。

2.2 阶段化链路（0–4，离线，零 API）

阶段	产出	关键数字
0 诊断	链长/冗余度量	均链长 3.36，冗余 33%，语料可压缩 10.5%
1 依赖 DAG	工具依赖无环图	34 节点 25 边
2 压缩器	可达性保持删除	语料压缩 10.51%（finance 45.3%），依赖 100% 保持
3 评测器	保真度 + 合法性	压缩保真度 0.89、依赖合法性 0.97
4 规划器	beam search 整链规划	图规划 ≫ 频次基线

上述为全语料层面的压缩度量；轨迹级链长消融见 §2.1。

2.3 在线真实成功率（诊断性指标）

本项目的核心目标是工具链压缩（减少冗余调用、保持任务可达性），其主评测轴是离线链长下降与保真度（见 §2.1 链压缩消融），而非端到端任务成功率。下方在线指标仅作诊断参考，用以定位瓶颈在模型侧而非链结构。

语料级（232 轨迹，可达性保持删除）（来源 results_chain/compression_report.json）：总调用 780 → 698，删除 82 次，压缩率 10.51%；实际被压缩的链 52/232；依赖顺序 100% 保持（dependency_preserved_all: true）。

分域压缩率：

域	n	原→压缩调用	压缩率
finance	40	117 → 64	45.3%
maps	40	98 → 80	18.4%
other	2	6 → 5	16.7%
browser	50	107 → 103	3.7%
dev	26	201 → 195	3.0%

结论：MCP 链的压缩收益高度集中在只读重复密集域（finance 45.3%、maps 18.4%）；search（每步参数不同、真链式）与 dev（多为写操作）压缩空间近乎为零。在真实执行下，压缩能少调用约 1/5 而不破坏任务可达性——即”用更短工具链完成工作”的因果证据。

3. 外部依赖 & 环境搭建（Linux / Ubuntu + Python 3.11）

# 1) 创建虚拟环境（推荐 Python 3.11）
cd mcp-graph-toolchain
python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip

# 2) 安装本项目（CPU 版用 [cpu] extra；有 GPU 用 faiss-gpu）
pip install -e .

# 3) 克隆并安装 MCP-Universe（外部评测框架，本项目 bridge 依赖它）
cd ..
git clone https://github.com/SalesforceAIResearch/MCP-Universe.git
cd MCP-Universe
pip install -e .
playwright install

# 4) 应用本项目对 MCP-Universe 的自定义改动（见 §4）
cp ../mcp-graph-toolchain/mcp-universe-addons/mcp_universe.patch .
git apply mcp_universe.patch
# 并把 mcp-universe-addons/integration/ 下的新文件按 §4 复制到对应路径

# 5) 下载 BGE-M3 模型（首次 ~2.2 GB，自动缓存）
export HF_HOME="<你的模型缓存目录>"
python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('BAAI/bge-m3')"

# 6) 复制 .env（含 API 密钥，不进仓库，需自行创建，参考 docs/RUN_GUIDE.md）

4. `mcp-universe-addons/` 说明（重要）

MCP-Universe 是第三方仓库，本仓库不直接包含它的源码，而是用以下方式保留你的全部自定义改动：

4.1 改原文件的补丁 — `mcp_universe.patch`

由 git diff 生成，覆盖 15 个被你修改的上游文件（如 mcpuniverse/mcp/client.py、 gateway.py、benchmark/task.py、llm/base.py、mcp/configs/server_list.json 等）。应用方式见 §3 第 4 步。补丁基于 MCP_UNIVERSE_COMMIT.txt 中的 commit，克隆后建议先 git checkout <该commit> 再 git apply，避免冲突。

4.2 新增文件 — `integration/`（M3 live-loop 集成，补丁不含新增文件）

需手动复制到 MCP-Universe 对应路径：

本仓库文件	复制到 MCP-Universe 的路径
`integration/graph_reflect_react.py`	`mcpuniverse/agent/graph_reflect_react.py`
`integration/domain_playbooks.py`	`mcpuniverse/agent/domain_playbooks.py`
`integration/task_helpers.py`	`mcpuniverse/agent/task_helpers.py`
`integration/react_enhanced_prompt.j2`	`mcpuniverse/agent/configs/react_enhanced_prompt.j2`
`integration/env.py`	`mcpuniverse/common/env.py`

4.3 自定义脚本 — `scripts/`

你写在 MCP-Universe 根目录的评测/分析脚本，直接复制到 MCP-Universe 根目录运行即可，例如：run_ab_multi.py（多组消融）、offline_compress.py（离线链压缩）、 success_rate.py / build_success_baseline.py（成功率基线）、analyze_chain.py（链分析）等。

4.4 示例评测结果 — `example_outputs/`

success_baseline.txt、chain_len.txt、all_detail.txt、ws_now.txt 等，作为评测产物样例留存。

5. 运行入口

目标	入口	是否需要 MCP-Universe / API
next-tool 消融	`src/.../experiments/run_ablation.py`	BGE-M3（本地）
链级诊断/依赖/压缩/规划	`src/.../chain_analysis/*`	否（读 `traces_*`）
CE 重排器训练数据	`build_mcpu_ce.py` / `build_multidomain_ce.py`	BGE-M3（本地）
离线链压缩评测	`mcp-universe-addons/scripts/offline_compress.py`	否
在线多域运行 / 成功率	`mcp-universe-addons/scripts/run_ab_multi.py`、`run_deepseek_*`	是（MCP-Universe + keys）
M3 live-loop 集成 Agent	`mcp-universe-addons/integration/graph_reflect_react.py`	是

完整分组命令见 docs/RUN_GUIDE.md。

6. 已知局限

样本小：干净答案型域仅 ~40 任务，普适性受限。
base 模型弱：deepseek-chat 内容正确性是主瓶颈。
环境约束：SERP 失效、yfinance 限流、3d/financial 缺本地依赖（BLENDER_APP_PATH 等）。
M3 反馈未完全闭环：aggregate_reflections() 未接回 call_graph.update_edge_weight。
DAG 用途边界：依赖图适合链压缩 / 整链规划，已证不适合单步 next-tool 路由（−2.7pp）。

7. 文档索引

文档	内容
`docs/RUN_GUIDE.md`	按用途分组的全部运行命令（Linux）
`docs/technical_doc.md`	模块算法、数据流、配置细节
`docs/offline_chain_compression_eval.md`	离线链压缩评测方法论与实测
`docs/report.md`	阶段性报告
`docs/PPT_GUIDE.md`	14 页项目介绍幻灯逐页脚本
`mcp-universe-addons/docs/eval-workflows-zh.md`	MCP-Universe 评测工作流

8. License & 致谢

评测框架依赖 MCP-Universe（Salesforce AI Research，请遵循其许可证）。
检索模型使用 BAAI/bge-m3（MIT）。
本仓库代码以 MIT 许可证发布（见 LICENSE）。