MCP Description Smell-Aware Native Protocol Stack

MCP 工具描述异味感知原生协议栈 — 将工具描述异味检测、描述优化（SFT）、上下文预算管理与安全门控封装为可接入操作系统原生 MCP 协议栈的用户态服务层原型。

项目简介

本项目围绕一个核心目标：现有 MCP 工具描述常出现触发条件缺失、参数/返回值不完整、表述含糊等问题，Agent 依赖这些描述选择工具时容易误选、重复调用、无效重试——能否在 MCP 协议栈层统一检测和修复描述质量问题，在保持 MCP tools/list 兼容的前提下，暴露经过 SFT 优化的高质量描述，并配套上下文预算、缓存摘要和安全门控策略？

核心思想：MCP 协议栈在 tools/list、工具注册、Agent 工具发现阶段，不直接暴露原始工具描述，而是暴露经过异味检测和 SFT 优化后的协议描述，并在上下文预算不足时启用缓存摘要和 top-k 工具发现策略，从而降低 Agent 误选工具、重复调用、无效重传和上下文浪费。

作者团队

东南大学网络安全学院 指导老师：蒋鹏队长：周雨佳队员：薛烁敏鲍奕飞

主要贡献（均已实测，核心是「描述异味感知与 SFT 优化」）

⭐ 描述异味感知与 SFT 优化（项目核心）

基于真实 MCP 工具样本（605 条原始候选 → 482 条 clean SFT 样本），构建五维描述质量评估体系，并通过 SFT（Qwen3-0.6B + LoRA, rank=32）显著提升工具描述质量。**SFT Overall 提升 +14.65%**，Functionality 提升 +43.82%，Information Completeness 提升 +36.71%，Clarity 提升 +26.67%。无效调用风险代理下降 **60.39%**（0.3681 → 0.1458）。这是本项目首要、可复现的成果。

M1 描述异味检测器

五维评分模型（Accuracy / Functionality / Information Completeness / Conciseness / Clarity）+ Sensitivity 标记，覆盖 482 条样本的原始描述与优化描述的 before/after 对比评测。

M2 SFT 描述优化器

基于 Qwen3-0.6B + LoRA（rank=32, alpha=16, 3 epochs），对 434 条训练样本学习”原始描述 → 优化描述”映射，在 48 条验证集上取得稳定提升。Conciseness 下降（−15.28%）是预期现象：优化描述补充了参数、返回值、触发条件和错误信息。

M3 上下文预算与缓存

协议栈支持五类 registry payload：raw、optimized、protocol_selected、cached_digest、top-k。缓存摘要减少 54.53% payload（70,204 → 31,924 bytes），top-k 减少 46.49% payload（70,204 → 37,569 bytes）。优化描述更完整导致全量更长（+274%），真正的通信优化来自协议栈内置缓存和上下文预算，而非简单把描述压短。

M4 安全策略引擎

对敏感工具和系统修改类工具自动生成安全策略（requires_auth / requires_user_confirmation / mask_arguments）。482 条工具中 188 条触发认证和用户确认策略，覆盖 simulator boot/shutdown/install/launch 等危险操作。

M5 OpenHarmony 原生组件骨架

提供完整的 OpenHarmony native component skeleton（bundle.json、BUILD.gn、C++ API、demo、单元测试），含 5 个对外 API（SelectProtocolDescription、BuildSecurityPolicy、MaskSensitiveText、SelectTopKByQuality、EstimateRegistryPayloadBytes），错误码体系（6 种）和 9 种异常处理方案。C++ sanity compile + 最小单元测试均通过。

M6 RL/GRPO 训练链路验证

RL smoke test 验证强化学习训练链路可跑通（exit code 0, global step 3, reward mean@1 = 0.9349, llm_score mean@1 = 0.74）。该指标为 reward 体系，不与五维描述质量表直接比较。

1. 仓库结构

本仓库只含自己的代码与文档，训练依赖（模型权重、checkpoint、完整训练环境）保留在原项目 /root/autodl-tmp/mcp_smell_project。

MCP Description Smell-Aware Native Protocol Stack/
├── src/smell_aware_stack/              # 核心 Python 原型
│   ├── __init__.py                     # 模块导出
│   ├── schema.py                       # 数据类型 (SmellAwareToolRecord, ToolQuality)
│   ├── description_layer.py            # 描述质量层 (tools/list, smell/quality 摘要)
│   ├── context_budget.py               # 上下文预算 (5 种 registry payload 模式)
│   └── security.py                     # 安全策略 (敏感文本脱敏, 安全门控)
├── scripts/
│   └── benchmark_smell_aware_stack.py  # 端到端 benchmark 脚本
├── openharmony/                        # ⭐ OpenHarmony 原生组件骨架
│   ├── bundle.json                     # 组件元数据 (@openharmony/mcp_desc_stack v0.1.0)
│   ├── BUILD.gn                        # 顶层 GN 构建入口
│   └── services/mcp_desc_stack/
│       ├── README.md
│       ├── BUILD.gn                     # ohos_static_library + ohos_executable
│       ├── include/
│       │   └── mcp_desc_stack.h         # C++ 公共 API 头文件
│       ├── src/
│       │   ├── mcp_desc_stack.cpp       # 核心 C++ 逻辑（5 个 API 实现）
│       │   └── mcp_desc_stack_demo.cpp  # 可运行 demo
│       └── test/
│           ├── BUILD.gn
│           └── mcp_desc_stack_test.cpp  # 最小单元测试
├── third_party_refs/mcp_smell_project_core/  # 训练/评估模块引用副本
│   ├── reward.py                       # GRPO 自定义 reward 函数 (~450 行)
│   ├── run_train.sh                    # GRPO RL 训练脚本
│   ├── run_eval.sh                     # 评估 pipeline 脚本
│   ├── run_sft_baseline.sh             # SFT LoRA 训练全流程
│   └── scripts/
│       ├── prepare_sft_dataset.py       # SFT 数据集构造
│       ├── train_sft_lora.py            # LoRA SFT 训练器 (Qwen3-0.6B)
│       ├── mcp_smell_eval.py            # LLM 六维评估器
│       ├── compare_eval_before_after.py # before/after 对比
│       └── compare_eval_summaries.py    # 多评测摘要表生成
├── data/
│   ├── dataset_summary.json            # 数据集摘要 (605→482 条)
│   └── smell_aware_tool_records.jsonl  # 482 条样本 (1.8 MB)
├── results/
│   ├── smell_aware_stack_benchmark.json          # 综合 benchmark 输出
│   ├── compare_original_sft_rl_zip482_val.json   # before/after + RL smoke 汇总
│   ├── compare_original_vs_sft_zip482_val_greedy_len180.json  # 48 条验证集逐工具对比
│   └── rl_smoke_test_summary.json                # RL smoke test 摘要
├── docs/
│   ├── END_TO_END_DEMO.md               # 端到端应用案例
│   └── COMPETITION_REQUIREMENT_MAPPING.md  # 赛题要求映射
├── DESIGN_DOC.md                        # 架构设计文档
├── FEATURE_DESIGN_OPENHARMONY.md        # 特性设计文档（OpenHarmony）
├── DATASET_AND_EXPERIMENTS.md           # 数据集与实验说明
├── TEST_PLAN.md                         # 测试方案
├── TEST_REPORT.md                       # 测试报告
├── RUNBOOK.md                           # 运行指南
├── SUBMISSION_SUMMARY.md                # 提交摘要
├── CODE_SUBMISSION_RECORD.md            # 代码提交记录说明
├── COMPETITION_PROPOSAL.md              # 竞赛提案
├── requirements.txt                     # Python ≥ 3.10（仅标准库）
└── README.md

2. 核心结果（可复现）

2.1 描述质量 before/after（主评测轴：五维评分）

以 48 条验证集为基准，对 SFT 描述优化进行五维消融：

Metric	Original	SFT	优化率
Accuracy	2.6875	2.8125	+4.65%
Functionality	1.8542	2.6667	+43.82%
Information_Completeness	1.6458	2.2500	+36.71%
Conciseness	3.0000	2.5417	−15.28%
Clarity	2.1875	2.7708	+26.67%
Overall	2.2750	2.6083	+14.65%

结论：SFT baseline 稳定优于原始描述。Functionality、Information Completeness、Clarity 提升显著。Conciseness 下降是预期现象——优化描述会补充参数、返回值、触发条件和错误信息，因此更长但更完整。

2.2 无效调用风险代理

定义：Functionality、Information_Completeness、Clarity 三个维度距离满分 3 的平均归一化 gap。

模型/描述	Risk Proxy	变化
Original	0.3681	—
SFT	0.1458	−60.39%

该指标不是实际线上重传次数，而是由工具描述质量推导出的无效调用风险代理。

2.3 上下文预算（通信优化）

Payload 模式	Bytes	相比 raw full registry
raw full registry	70,204	baseline
optimized full registry	262,715	+274.21%
protocol selected full registry	260,685	+271.32%
cached digest registry	31,924	−54.53%
top-k registry	37,569	−46.49%

解释：优化描述更完整，因此全量返回会变长。真正的通信收益来自协议栈内置缓存和上下文预算——多 Agent 重复发现工具时只传 digest，任务相关场景只返回 top-k 描述——而不是简单把描述压短。

2.4 安全策略覆盖

项目	数量
工具数	482
requires_auth	188
requires_user_confirmation	188

策略覆盖敏感工具和系统修改类工具（如 simulator boot / shutdown / install / launch）。

2.5 RL/GRPO smoke test

指标	数值
Exit code	0
Final global step	3
Final validation reward mean@1	0.9349609971
Final llm_score mean@1	0.74

说明：该 smoke test 验证强化学习训练链路可跑通，使用 reward/llm_score 指标体系，不与五维描述质量表直接比较。

2.6 数据集规模

数据项	数量
原始 MCP 工具候选	605
clean SFT 样本	482
SFT train	434
SFT validation	48
未匹配或被过滤	123

数据来源：从 100 个 MCP 仓库中提取的真实 MCP 工具描述。

3. 架构与接入点

3.1 五层总体架构

MCP Server / Tool Provider
        │
        ▼
Tool Registration Hook
        │
        ▼
Description Smell Detector          ← 五维异味评分 + Sensitivity
        │
        ▼
SFT Description Optimizer           ← Qwen3-0.6B + LoRA
        │
        ▼
Native MCP Description Quality Layer
        │
        ├── tools/list description replacement
        ├── context budget manager
        ├── cache digest registry
        └── security policy engine
        │
        ▼
Agent / Multi-Agent Runtime

当前提交中的 src/smell_aware_stack 即为 Native MCP Description Quality Layer 的用户态原型。

3.2 四阶段接入点

阶段	接入点	核心逻辑
工具注册	Tool Registration Hook	记录 tool name、raw description、smell score、optimized description、sensitivity metadata
工具发现	`tools/list`	调用 `record.protocol_description()`——优化描述质量 ≥ 原始描述则返回优化描述，否则回退
上下文预算	Context Budget Manager	五类 payload：raw / optimized / protocol_selected / cached_digest / top-k
安全策略	Security Policy Engine	对敏感/系统修改类工具生成 auth + confirmation + mask 策略

4. 外部依赖 & 环境搭建

4.1 Python 原型（仅标准库，无需额外安装）

cd "MCP Description Smell-Aware Native Protocol Stack"
# Python ≥ 3.10，无需 pip install
PYTHONPATH=src python scripts/benchmark_smell_aware_stack.py \
  --top-k 64 \
  --output results/smell_aware_stack_benchmark.json

4.2 C++ sanity compile

g++ -std=c++17 \
  -I openharmony/services/mcp_desc_stack/include \
  openharmony/services/mcp_desc_stack/src/mcp_desc_stack.cpp \
  openharmony/services/mcp_desc_stack/src/mcp_desc_stack_demo.cpp \
  -o /tmp/mcp_desc_stack_demo

/tmp/mcp_desc_stack_demo

4.3 C++ 单元测试

g++ -std=c++17 \
  -I openharmony/services/mcp_desc_stack/include \
  openharmony/services/mcp_desc_stack/src/mcp_desc_stack.cpp \
  openharmony/services/mcp_desc_stack/test/mcp_desc_stack_test.cpp \
  -o /tmp/mcp_desc_stack_test

/tmp/mcp_desc_stack_test
# 输出: mcp_desc_stack_test passed

4.4 OpenHarmony 目标构建

当前服务器未安装完整 OpenHarmony SDK，因此只完成 C++ sanity compile。进入 OpenHarmony 源码树后，应将 openharmony/ 放置到 foundation/ai/mcp_desc_stack 并接入产品构建：

# 在 OpenHarmony 源码树中
cp -r openharmony/ foundation/ai/mcp_desc_stack
./build.sh --product-name <your_product>

4.5 训练环境（SFT / RL）

训练环境、模型权重和完整日志保留在原项目，不在本仓库中：

cd /root/autodl-tmp/mcp_smell_project
# SFT baseline
bash run_sft_baseline.sh
# RL/GRPO smoke test
bash run_train.sh
# Evaluation
bash run_eval.sh

训练配置：Qwen3-0.6B + LoRA (rank=32, alpha=16, 3 epochs)，1×RTX 4090 (24GB)，SFT 约 20–30 分钟。

5. 运行入口速查

目标	入口	依赖
Python benchmark（全栈）	`scripts/benchmark_smell_aware_stack.py`	Python ≥ 3.10（标准库）
Python 语法检查	`python -m py_compile src/smell_aware_stack/*.py`	无
C++ sanity compile	`g++ ... mcp_desc_stack.cpp mcp_desc_stack_demo.cpp`	g++ 支持 C++17
C++ 单元测试	`g++ ... mcp_desc_stack_test.cpp && /tmp/mcp_desc_stack_test`	g++ 支持 C++17
SFT 训练	`third_party_refs/mcp_smell_project_core/run_sft_baseline.sh`	PyTorch + PEFT + Qwen3-0.6B
RL 训练	`third_party_refs/mcp_smell_project_core/run_train.sh`	verl + vLLM + Qwen3-0.6B
评测对比	`third_party_refs/mcp_smell_project_core/run_eval.sh`	OpenAI-compatible API 或 Ollama

完整分组命令见 RUNBOOK.md。

6. 赛题要求映射

赛题要求	本项目对应实现	验证指标
原生 MCP 协议栈，减少中间层性能损耗	用户态 native service-layer 原型，协议栈统一处理描述质量，不依赖 Agent 框架自行修复	SFT Overall +14.65%，风险代理 −60.39%
通信效率提升 10%	缓存 digest registry payload −54.53%，top-k registry payload −46.49%	均远超 10% 目标
内置安全机制	对敏感/系统修改类工具生成 auth + confirmation + mask 策略	482 条策略，188 条触发认证
多 Agent / 边缘设备	协议栈缓存高质量描述，多 Agent 共享 registry，仅传 digest	已验证 digest/top-k 两种模式
端到端案例	`docs/END_TO_END_DEMO.md`	2 个完整案例（描述补全 + 安全门控）

详见 docs/COMPETITION_REQUIREMENT_MAPPING.md。

7. 已知局限

样本规模有限：482 条 clean 样本来自 100 个 MCP 仓库，普适性受限。
SFT 模型规模小：Qwen3-0.6B 作为 baseline，更大模型可能带来进一步的描述质量提升。
RL 未完全收敛：GRPO smoke test 仅验证训练链路可跑通（global step=3），尚未完成充分训练。
Conciseness 下降：优化描述补充了缺失信息，因此更长；通信优化依赖缓存策略而非缩短描述。
缺乏真实系统调用级指标：当前为原型验证，未采集 latency / throughput / 多 Agent 并发等系统级指标。
OpenHarmony 构建未在目标环境执行：仅完成 C++ sanity compile，未在完整 OpenHarmony SDK 中进行 GN/Ninja 构建。

8. 文档索引

文档	内容
README.md	项目总览（本文件）
DESIGN_DOC.md	架构设计文档（五层架构、四阶段接入点）
FEATURE_DESIGN_OPENHARMONY.md	特性设计文档（C++ API、异常处理、兼容性）
DATASET_AND_EXPERIMENTS.md	数据集说明与 SFT/RL 实验
TEST_PLAN.md	测试方案（4 类 19 个测试用例）
TEST_REPORT.md	测试报告（全部通过）
RUNBOOK.md	运行指南（9 个命令入口）
SUBMISSION_SUMMARY.md	一页提交摘要
COMPETITION_PROPOSAL.md	竞赛提案
CODE_SUBMISSION_RECORD.md	代码提交记录说明
docs/END_TO_END_DEMO.md	端到端应用案例（描述补全 + 安全门控）
docs/COMPETITION_REQUIREMENT_MAPPING.md	赛题要求逐条映射

9. License & 致谢

训练模型使用 Qwen3-0.6B（Apache 2.0）。
本仓库代码以 Apache 2.0 许可证发布。