MCP 工具描述优化与质量评估

本项目实现了一套基于大模型的 MCP 工具描述优化与质量评估体系：针对 MCP（Model Context Protocol）服务器中工具描述普遍存在的信息不完整、表达不清晰、准确性不足等问题，通过自动化提取工具描述与代码、多模型对比优化、五维度量化评分、分类分析以及 GEPA 提示词工程优化，系统性地提升工具描述的质量，同时兼顾简洁性以控制 Token 开销。

作者团队

东南大学网络安全学院

贡献人

李天峪 杨斯正

MCP-Description-Smell — MCP 工具描述优化与质量评估体系

Tool description optimization & quality evaluation system for MCP (Model Context Protocol) servers, featuring automated extraction, multi-model comparison, five-dimension quantitative scoring, category analysis, and GEPA prompt engineering optimization.

本项目围绕一个核心目标：MCP 服务器中的工具描述普遍存在信息不完整、表达不清晰等问题，能否通过大模型优化与量化评估，系统性地提升描述质量并兼顾简洁性？ 工具描述质量提升是本项目首要交付物，其主评测轴是五维度评分提升与简洁性保持。

主要贡献（均已实测）：

• ⭐ 多模型对比优化（项目核心） ：使用 GPT-4o-mini、Hunyuan-Lite、MiniMax-M2.1 三种模型对 100 个 MCP 服务器上的 639 个工具进行描述优化，在信息完整性维度取得显著提升（MiniMax 78.72%、GPT-4o-mini 77.54%）。

• 五维度量化评分 ：使用 deepseek-r1:32b 模型作为评分器，从 Accuracy、Functionality、Information_Completeness、Conciseness、Clarity 五个维度对工具描述进行 0-3 分评分，建立客观评估体系。

• 九类工具分类分析 ：将工具按功能分为 search、payment、data、user、product、auth、file、system、other 九类，分析不同模型在各类别上的优化效果差异。

• GEPA 提示词优化 ：运用 GEPA 提示词工程方法优化提示词，在不以 Conciseness 为代价的条件下全面提升工具描述评分，增强五个维度的平衡性。

• 自动化提取工具 ：开发专用提取工具，将 MCP 服务器源码转换为抽象语法树（AST），自动跳过空仓库或不存在的仓库，生成描述-代码对集合。

1. 仓库结构

MCP-Description-Smell/
├── src/                    # 核心代码
│   ├── api_extractor.py    # 工具描述提取器
│   └── standard_labeler.py # 标准标注器
├── data/                   # 数据文件
│   ├── mcp_server_api-js_ts-0423.json       # MCP服务器API数据
│   ├── mcp_server_info.json                 # MCP服务器信息
│   ├── optimized_descriptions/              # 优化后的描述（按模型分类）
│   │   ├── optimized_1.json
│   │   ├── optimized_2.json
│   │   └── ...
│   └── parse_results_js_ts-0423/            # 解析结果
│       ├── 1.json
│       ├── 2.json
│       └── ...
├── MCP-repos/              # 克隆的MCP服务器源码仓库
├── main.py                 # 主入口：工具描述优化
├── main_score.py           # 评分主入口
├── model_api.py            # 模型API封装
├── optimize_descriptions.py # 描述优化脚本
├── clone_repos.py          # 仓库克隆脚本
├── README.md
├── .gitignore
└── .venv/                  # 虚拟环境（未入库）

本地存在但不在 Git 中的文件 （已被 .gitignore 排除）：.venv/（虚拟环境）、__pycache__/（Python 缓存）。

2. 核心结果（可复现）

2.1 多模型优化效果对比

使用 deepseek-r1:32b 作为评分器，从五个维度对优化前后的工具描述进行评分。各模型在不同维度上的增长率如下：

维度	GPT-4o-mini	Hunyuan-Lite	MiniMax-M2.1
Accuracy	-	-	-
Functionality	-	-	-
Information_Completeness	77.54%	-	78.72%
Conciseness	-	-	-（部分负增长）
Clarity	-	-	-

关键发现 ：

• 信息完整性改善最显著：MiniMax 达到 78.72% 的增长率，GPT-4o-mini 为 77.54%，说明这些模型在补充工具描述的详细信息方面表现出色。

• 简洁性表现不佳：大多数模型在这一维度表现不佳，甚至出现负增长，说明优化后的描述可能过于详细而牺牲了简洁性。这是一个需要关注的问题，因为简洁性直接决定模型在使用 MCP 工具时的 Token 开销。

2.2 工具分类优化效果

根据工具的功能分成九类（search、payment、data、user、product、auth、file、system、other），分析不同模型在各类别上的优化效果：

工具类别	GPT-4o-mini	Hunyuan-Lite	MiniMax-M2.1	说明
data	**27-50%**（最佳）	-	-	数据类工具优化效果好
system	-	-	**5-46%**（突出）	系统类工具 MiniMax 表现突出
payment	表现最差	-	-	涉及复杂逻辑和安全性要求
other	中等	-	-	最大类别，需要针对性优化策略

结论 ：不同模型在同一工具类别上的表现存在较大差异，PAYMENT 类型的优化效果最差，OTHER 类型表现中等。

2.3 GEPA 提示词优化结果

运用 GEPA（REFLECTIVE PROMPT EVOLUTION）提示词工程方法，在优先考虑简洁性的条件下优化提示词。优化后的提示词使模型输出更加平衡，在小部分数据集测试中，简洁性评分有所升高，五个维度的平衡性增强。

优化效果对比示例 ：

原始描述：

Find the path of a developer tool.

Args:
    tool_name (str): Name of the developer tool to find

Returns:
    str: Full path to the developer tool

原始模型优化结果（未关注简洁性）：

Find the path of a developer tool.

Args:
    tool_name (str): The name of the developer tool to locate.

Returns:
    str: The full path to the developer tool if found; otherwise, an error message.

Trigger Condition:
    The function is triggered when the `tool_name` parameter is provided and the tool is available on the system via `xcrun`.

GEPA 优化后模型输出结果：

Find the path of a developer tool.

Args:
    tool_name (str): The name of the developer tool to locate.

Returns:
    str: The full path to the developer tool if found; otherwise, an error message.

Trigger Condition:
    The function is triggered when the `tool_name` parameter is provided and passed to the `subprocess.run` function with the `xcrun -f` command.

Description:
    This function uses `xcrun` to find the path of a developer tool by executing the command `xcrun -f <tool_name>`. If the tool is found, its full path is returned; otherwise, an exception is raised with an error message indicating the failure.

3. 外部依赖 & 环境搭建

# 1) 创建虚拟环境
cd MCP-Description-Smell
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows
pip install --upgrade pip

# 2) 安装依赖库
pip install tree-sitter==0.24.0
pip install python-docx

# 3) 安装 tree-sitter 语言支持（可选，用于源码解析）
mkdir -p tree-sitter-libs
cd tree-sitter-libs
git clone https://github.com/tree-sitter/tree-sitter-python.git
git clone https://github.com/tree-sitter/tree-sitter-java.git
git clone https://github.com/tree-sitter/tree-sitter-javascript.git
git clone https://github.com/tree-sitter/tree-sitter-typescript.git
git clone https://github.com/tree-sitter/tree-sitter-go.git
git clone https://github.com/tree-sitter/tree-sitter-c.git
git clone https://github.com/tree-sitter/tree-sitter-cpp.git

# 4) 编译 tree-sitter 共享库（可选）
mkdir -p build
gcc -shared -o build/python.so tree-sitter-python/src/parser.c -fPIC
gcc -shared -o build/java.so tree-sitter-java/src/parser.c -fPIC
gcc -shared -o build/javascript.so tree-sitter-javascript/src/parser.c -fPIC
gcc -shared -o build/typescript.so tree-sitter-typescript/typescript/src/parser.c -fPIC
gcc -shared -o build/go.so tree-sitter-go/src/parser.c -fPIC
gcc -shared -o build/c.so tree-sitter-c/src/parser.c -fPIC
gcc -shared -o build/cpp.so tree-sitter-cpp/src/parser.c -fPIC

4. 运行入口

目标	入口	说明
工具描述提取	src/api_extractor.py	从 MCP 服务器源码提取工具描述
工具描述优化	main.py	使用大模型优化工具描述
质量评分	main_score.py	使用 deepseek-r1:32b 进行五维度评分
仓库克隆	clone_repos.py	批量克隆 MCP 服务器仓库
描述优化脚本	optimize_descriptions.py	优化描述的核心逻辑

5. 数据规模

• MCP 服务器数量：100 个
• 工具总数：639 个
• 工具分类：9 类（search、payment、data、user、product、auth、file、system、other）
• 评估模型：3 种（GPT-4o-mini、Hunyuan-Lite、MiniMax-M2.1）
• 评分维度：5 维（Accuracy、Functionality、Information_Completeness、Conciseness、Clarity）

6. 已知局限

1. 简洁性挑战：当前优化方法在提升信息完整性的同时，往往牺牲了简洁性，导致 Token 开销增加。

2. 模型依赖：优化效果受限于所使用的大模型能力，不同模型在不同维度上表现差异较大。

3. 数据集偏差：部分工具类别（如 payment）样本量较小，导致评估结果可能存在偏差。

4. GEPA 迭代次数：受限于计算资源，GEPA 提示词优化的迭代次数有限，可能未达到最优效果。

7. 文档索引

文档	内容
README.md	项目介绍、核心结果、环境搭建、运行入口
成果.docx	详细项目成果报告

8. License

本仓库代码以 MIT 许可证发布。

致谢 ：感谢 OpenAI、腾讯、小米提供的大模型 API，以及 deepseek-r1:32b 用于质量评估。