delete: remove docs folder
赛题： 泛在操作系统原生的 MCP 协议栈设计 项目名称：PoisonGuard-MCP：面向工具投毒攻击检测的原生 MCP 协议栈
作者团队：北京大学计算机学院
队长：李如钦
队员：李少飞
Model Context Protocol (MCP) 已成为 LLM Agent 集成外部工具的事实标准。在 MCP 架构中，Agent 依据工具描述 (tool description) 进行工具选择和参数构造，但不检查工具源代码。这一设计在描述与实现之间引入了固有的语义分离，构成了工具投毒攻击 (Tool Poisoning Attack, TPA) 的攻击面：攻击者向工具描述中注入恶意指令，Agent 将其解释为权威命令，从而被诱导执行非预期操作。
MCPTox 基准测试表明，在 20 个 LLM Agent 和 45 个真实 MCP Server 上，攻击成功率最高达 72.8%；MCP-ITP 研究显示，隐式工具投毒可达到 84.2% 的攻击成功率，而恶意工具检测率仅为 0.3%。
赛题同时指出现有 MCP 协议栈存在的性能问题：
本系统构建一套面向工具投毒攻击的原生 MCP 协议栈，将细粒度工具描述-代码语义一致性比较技术 (SCA) 深度集成到协议栈安全层，在工具注册阶段自动检测描述投毒攻击。系统支持：
本系统的安全检测机制基于两点核心认识：
第一，检测范式应从攻击模式匹配转向语义一致性分析。 现有防御手段（规则匹配型扫描器、运行时行为监控、宏观语义相似度比较）的共同局限在于依赖攻击模式匹配，即计算与已知攻击的相似度。本系统不问”该工具是否类似于已知攻击”，而问”描述中的每个声明是否在代码中有对应实现”。恶意工具因注入行为，其描述必然包含代码未实现的声明；良性工具出于可用性需求，必然保持描述与代码的强语义一致性。
第二，语义一致性验证应从宏观相似度计算转向原子级语义推理。 现有方法将描述和代码作为整体进行相似度比较，类似于判断两个物体在外观上是否相似，只能得到表层相似度。本方案将描述分解为元动作 (meta-action)，将代码分割为语义连贯的功能块 (functional block)，对每个对齐对进行语义推理，验证代码是否逻辑支撑描述声明。
威胁模型设定：攻击者采用非对称注入策略，即向描述中注入恶意内容而保持源代码良性。这是实践中的主要攻击模式，因为注入恶意代码会将攻击转化为传统恶意软件，可被成熟的代码扫描工具检测。
系统自底向上分为五层：
mcp_os/protocol/
mcp_os/security/
mcp_os/context/
工具注册请求到达后，协议栈执行以下流程：
工具调用阶段，协议栈仅检查工具的 verified 标志位，不重新执行 SCA 检测，确保运行时零安全开销。
安全验证在工具注册阶段完成，而非每次工具调用时执行。该设计基于以下考量：
src/ ├── mcp_os/ # 协议栈主包 │ ├── config.py # 全局配置 │ ├── detector_core/ # SCA 框架原始源码（MCPDetector 项目） │ │ ├── config.py # 检测器配置 │ │ ├── model.py # ConsistencyCrossEncoder 模型定义 │ │ ├── code_parser.py # MMD 边缘校准代码切分器 │ │ ├── desc_parser.py # spaCy 依存句法描述解析器 │ │ ├── code_ast.py # Tree-sitter 代码特征提取 │ │ ├── detector.py # PoisonDetector 检测器 │ │ ├── dataset.py # 训练数据集封装 │ │ ├── process_data.py # 训练数据构造（对齐 + 硬负采样） │ │ └── clean_code.py # AST 代码净化（防数据泄露） │ ├── protocol/ # 协议核心层 │ │ ├── jsonrpc.py # JSON-RPC 2.0 消息处理 │ │ ├── messages.py # MCP 消息类型定义 │ │ ├── transport.py # 传输层（stdio / SSE / WebSocket） │ │ └── server.py # MCP Server（请求路由 + 工具管理） │ ├── security/ # 安全层 │ │ ├── auth.py # HMAC-SHA256 身份认证 │ │ ├── crypto.py # AES-256-GCM 数据加密 │ │ ├── consistency_verifier.py # SCA 框架集成封装 │ │ └── security_gate.py # 安全网关（三重检查统一入口） │ ├── context/ # 上下文优化层 │ │ ├── compressor.py # 语义压缩器 │ │ └── cache.py # LRU 缓存 + Gzip 压缩 │ ├── registry/ # 工具注册中心 │ │ └── tool_registry.py # 工具全生命周期管理 │ └── os_integration/ # OS 适配层 │ └── service.py # 守护进程 + 信号处理 ├── tests/ # 测试代码（68 个用例） ├── examples/ # 示例应用 │ ├── weather_server.py # 描述投毒检测演示 │ └── travel_agent.py # 多 Agent 协作演示 └── scripts/ # 启动与工具脚本 ├── run_server.py # Server 启动脚本 ├── run_client.py # Client 启动脚本 ├── e2e_server.py # 端到端 Server（自带工具实现） ├── e2e_test.py # 端到端测试（SCA 验证 + GLM 问答） ├── interactive_client.py # 交互式客户端 ├── benchmark.py # 性能基准测试 ├── train_model.py # Cross-Encoder 训练脚本 ├── process_data.py # 训练数据构造脚本 └── clean_code.py # 代码净化脚本
SCA 框架包含三个模块，源码完整保留在 detector_core/ 目录中。
detector_core/
从工具描述和源代码中提取安全相关关键特征，用于训练阶段建立自然语言与代码语言之间的细粒度映射关系。
描述特征提取：使用 spaCy 依存句法分析生成依赖树，识别所有具有直接宾语 (dobj) 的动词，提取以该动词为根的完整动词短语作为元动作。元动作集合中的每个元素代表描述中声明的一个完整动作。
源代码特征提取：使用 Tree-sitter 将源代码解析为 AST，从五个维度提取特征：外部依赖（识别潜在恶意库）、函数签名（捕获声明意图）、关键行为指令（监控敏感系统调用）、数据扫描（确定处理目标）、输出流（识别数据去向）。
提出基于 MMD 的语义分布偏移检测算法，将源代码分割为语义连贯的功能块。核心认识：同一功能块内的代码行在嵌入空间中呈现相似的语义分布，功能边界处的代码行呈现分布偏移。
算法流程：
对每个描述元动作，在所有代码功能块中检索最大一致性分数。UniXcoder Cross-Encoder 使每个元动作与对应代码块在每一层 Transformer 中进行完整的自注意力交互，验证描述中的每个指令是否被代码逻辑支撑。若任意元动作的最大支持度低于阈值，判定为孤立描述意图，触发投毒告警。
模型结构：UniXcoder 编码器提取 [CLS] 向量，经 Dropout(0.1) → Linear(hidden, hidden) → Tanh → Linear(hidden, 2) 分类头输出二分类结果。损失函数为 CrossEntropyLoss。
训练严格按 MCPDetector 项目原始源码实现：
clean_code.py
process_data.py
train.py
安全网关是安全层的统一入口，将三个安全组件组合为串行验证流水线：
initialize
{}
{protocolVersion, capabilities, serverInfo}
ping
{status, timestamp}
tools/list
{tools: [...]}
tools/call
{name, arguments}
{content, isError}
shutdown
{status}
tools/register
{name, description, source_code, inputSchema}
VerificationReport
security/verify_tool
{name}
security/get_report
{tools_verified, tools_blocked, ...}
context/compress
{text}
{original_length, compressed_length, ratio}
context/cache_stats
{hit_rate, hits, misses, compression}
from mcp_os.protocol.server import MCPServer from mcp_os.security.security_gate import SecurityGate from mcp_os.context.cache import ContextOptimizer gate = SecurityGate() optimizer = ContextOptimizer() server = MCPServer(security_gate=gate, context_optimizer=optimizer) # 注册工具（自动触发 SCA 安全验证） report = server.register_tool( name="get_weather", description="Get weather for a city", handler=get_weather_handler, source_code=weather_code_string, ) # report.is_poisoned == False → 注册成功 # report.is_poisoned == True → 抛出 SecurityViolationError await server.run()
工具注册时若 SCA 检测发现描述中存在元动作缺乏代码支撑，安全网关抛出 SecurityViolationError，返回 SECURITY_VIOLATION (-32005) 错误，工具不注册到工具表中。
SecurityViolationError
ConsistencyVerifier 在初始化前检查权重文件。权重文件不存在时抛出 FileNotFoundError 并提示运行训练流程。权重文件为空（未训练）时抛出 RuntimeError 并给出训练指引。
ConsistencyVerifier
FileNotFoundError
RuntimeError
兼容 MCP 2024-11-05 规范，完整支持标准方法。扩展方法以非冲突方式提供，标准客户端可忽略。Agent 框架（LangChain、HelloAgents）可通过 stdio 传输集成。
# 安装依赖 pip install -r requirements.txt # 安装 spaCy 模型 python -m spacy download en_core_web_sm # 下载 UniXcoder 模型（从 ModelScope，国内可用） pip install modelscope python -c "from modelscope import snapshot_download; snapshot_download('microsoft/unixcoder-base')" # 运行测试 cd src python -m pytest tests/ -v # 运行描述投毒检测演示 python examples/weather_server.py # 运行多 Agent 协作演示 python examples/travel_agent.py
cd src/scripts python clean_code.py # AST 净化训练数据 python process_data.py # 构造对齐训练对（正负比 1:3） python train_model.py # 微调 Cross-Encoder（AdamW lr=2e-5）
export ZHIPUAI_API_KEY=你的key cd src python scripts/e2e_test.py "帮我查北京天气" python scripts/e2e_test.py "上海有哪些景点" python scripts/e2e_test.py "从故宫到颐和园怎么走"
cd src python scripts/run_server.py --transport stdio python scripts/run_server.py --transport sse --port 9000
cd src python scripts/benchmark.py
双 Intel Xeon Platinum 8358 CPU (64 核 128 线程)，NVIDIA RTX A6000 GPU (48GB GDDR6)，256GB 内存。
SCA 在标准化基准上 F1 达到 0.9714，较 MCP-Scan 提升 36%；在真实生态数据集上 F1 达到 0.8950，Recall 维持 0.9676。
客户端通过 JSON-RPC 协议逐个注册工具，每个工具注册时安全网关调用 SCA 框架执行验证：
集成智谱 GLM-5.2 大模型，实现从用户自然语言提问到自然语言回复的完整链路：
用户: "帮我查北京天气" ↓ GLM 分析意图，选择 get_weather 工具 ↓ 通过 JSON-RPC 调用 MCP Server ↓ Server 执行 get_weather(city="beijing") ↓ 返回 {temperature: 25, condition: "晴"} ↓ GLM 生成回复 用户收到: "北京今天天气晴，温度25℃，湿度60%。"
MCP-OS 是面向 OpenHarmony 的原生 Model Context Protocol (MCP) 协议栈实现。将细粒度工具描述与工具代码的语义一致性比较技术深度集成到协议栈安全层，在工具注册阶段自动检测投毒攻击，同时提供上下文压缩、缓存优化和原生系统服务集成。
版权所有：中国计算机学会技术支持：开源发展技术委员会 京ICP备13000930号-9 京公网安备 11010802047560号
PoisonGuard-MCP
目录
作者团队：北京大学计算机学院
队长：李如钦
队员：李少飞
1. 需求分析
1.1 赛题背景解读
Model Context Protocol (MCP) 已成为 LLM Agent 集成外部工具的事实标准。在 MCP 架构中，Agent 依据工具描述 (tool description) 进行工具选择和参数构造，但不检查工具源代码。这一设计在描述与实现之间引入了固有的语义分离，构成了工具投毒攻击 (Tool Poisoning Attack, TPA) 的攻击面：攻击者向工具描述中注入恶意指令，Agent 将其解释为权威命令，从而被诱导执行非预期操作。
MCPTox 基准测试表明，在 20 个 LLM Agent 和 45 个真实 MCP Server 上，攻击成功率最高达 72.8%；MCP-ITP 研究显示，隐式工具投毒可达到 84.2% 的攻击成功率，而恶意工具检测率仅为 0.3%。
赛题同时指出现有 MCP 协议栈存在的性能问题：
1.2 项目简介
本系统构建一套面向工具投毒攻击的原生 MCP 协议栈，将细粒度工具描述-代码语义一致性比较技术 (SCA) 深度集成到协议栈安全层，在工具注册阶段自动检测描述投毒攻击。系统支持：
1.3 功能需求映射
1.4 核心洞察
本系统的安全检测机制基于两点核心认识：
第一，检测范式应从攻击模式匹配转向语义一致性分析。 现有防御手段（规则匹配型扫描器、运行时行为监控、宏观语义相似度比较）的共同局限在于依赖攻击模式匹配，即计算与已知攻击的相似度。本系统不问”该工具是否类似于已知攻击”，而问”描述中的每个声明是否在代码中有对应实现”。恶意工具因注入行为，其描述必然包含代码未实现的声明；良性工具出于可用性需求，必然保持描述与代码的强语义一致性。
第二，语义一致性验证应从宏观相似度计算转向原子级语义推理。 现有方法将描述和代码作为整体进行相似度比较，类似于判断两个物体在外观上是否相似，只能得到表层相似度。本方案将描述分解为元动作 (meta-action)，将代码分割为语义连贯的功能块 (functional block)，对每个对齐对进行语义推理，验证代码是否逻辑支撑描述声明。
威胁模型设定：攻击者采用非对称注入策略，即向描述中注入恶意内容而保持源代码良性。这是实践中的主要攻击模式，因为注入恶意代码会将攻击转化为传统恶意软件，可被成熟的代码扫描工具检测。
2. 总体设计思路
2.1 架构分层
系统自底向上分为五层：
mcp_os/protocol/mcp_os/security/mcp_os/context/2.2 工具注册数据流
工具注册请求到达后，协议栈执行以下流程：
工具调用阶段，协议栈仅检查工具的 verified 标志位，不重新执行 SCA 检测，确保运行时零安全开销。
2.3 抢占式安全验证设计
安全验证在工具注册阶段完成，而非每次工具调用时执行。该设计基于以下考量：
3. 核心模块划分
3.1 模块总览
3.2 SCA 框架
SCA 框架包含三个模块，源码完整保留在
detector_core/目录中。3.2.1 特征提取模块
从工具描述和源代码中提取安全相关关键特征，用于训练阶段建立自然语言与代码语言之间的细粒度映射关系。
描述特征提取：使用 spaCy 依存句法分析生成依赖树，识别所有具有直接宾语 (dobj) 的动词，提取以该动词为根的完整动词短语作为元动作。元动作集合中的每个元素代表描述中声明的一个完整动作。
源代码特征提取：使用 Tree-sitter 将源代码解析为 AST，从五个维度提取特征：外部依赖（识别潜在恶意库）、函数签名（捕获声明意图）、关键行为指令（监控敏感系统调用）、数据扫描（确定处理目标）、输出流（识别数据去向）。
3.2.2 源代码分割模块
提出基于 MMD 的语义分布偏移检测算法，将源代码分割为语义连贯的功能块。核心认识：同一功能块内的代码行在嵌入空间中呈现相似的语义分布，功能边界处的代码行呈现分布偏移。
算法流程：
3.2.3 跨语言语义推理模块
对每个描述元动作，在所有代码功能块中检索最大一致性分数。UniXcoder Cross-Encoder 使每个元动作与对应代码块在每一层 Transformer 中进行完整的自注意力交互，验证描述中的每个指令是否被代码逻辑支撑。若任意元动作的最大支持度低于阈值，判定为孤立描述意图，触发投毒告警。
模型结构：UniXcoder 编码器提取 [CLS] 向量，经 Dropout(0.1) → Linear(hidden, hidden) → Tanh → Linear(hidden, 2) 分类头输出二分类结果。损失函数为 CrossEntropyLoss。
3.3 训练流程
训练严格按 MCPDetector 项目原始源码实现：
clean_code.pyprocess_data.pytrain.py3.4 安全网关
安全网关是安全层的统一入口，将三个安全组件组合为串行验证流水线：
4. 关键技术选型
5. 接口设计
5.1 MCP 标准方法
initialize{}{protocolVersion, capabilities, serverInfo}ping{}{status, timestamp}tools/list{}{tools: [...]}tools/call{name, arguments}{content, isError}shutdown{}{status}5.2 扩展方法
tools/register{name, description, source_code, inputSchema}VerificationReportsecurity/verify_tool{name}VerificationReportsecurity/get_report{}{tools_verified, tools_blocked, ...}context/compress{text}{original_length, compressed_length, ratio}context/cache_stats{}{hit_rate, hits, misses, compression}5.3 错误码
5.4 核心 Python API
6. 异常处理方案
6.1 安全违规
工具注册时若 SCA 检测发现描述中存在元动作缺乏代码支撑，安全网关抛出
SecurityViolationError，返回 SECURITY_VIOLATION (-32005) 错误，工具不注册到工具表中。6.2 模型权重不可用
ConsistencyVerifier在初始化前检查权重文件。权重文件不存在时抛出FileNotFoundError并提示运行训练流程。权重文件为空（未训练）时抛出RuntimeError并给出训练指引。6.3 传输层异常
6.4 工具调用异常
7. 兼容性说明
7.1 运行环境
7.2 依赖兼容性
7.3 MCP 协议兼容
兼容 MCP 2024-11-05 规范，完整支持标准方法。扩展方法以非冲突方式提供，标准客户端可忽略。Agent 框架（LangChain、HelloAgents）可通过 stdio 传输集成。
8. 部署与运行
8.1 快速开始
8.2 SCA 模型训练
8.3 端到端 Agent 问答
8.4 启动 MCP Server
8.5 性能基准
9. 性能指标与测试方案
9.1 测试覆盖
9.2 协议栈性能基准
10. SCA 检测性能评估
10.1 实验环境
双 Intel Xeon Platinum 8358 CPU (64 核 128 线程)，NVIDIA RTX A6000 GPU (48GB GDDR6)，256GB 内存。
10.2 数据集
10.3 检测效果
SCA 在标准化基准上 F1 达到 0.9714，较 MCP-Scan 提升 36%；在真实生态数据集上 F1 达到 0.8950，Recall 维持 0.9676。
10.4 效率
10.5 消融研究
11. 端到端应用案例
11.1 工具注册与 SCA 验证
客户端通过 JSON-RPC 协议逐个注册工具，每个工具注册时安全网关调用 SCA 框架执行验证：
11.2 GLM Agent 端到端问答
集成智谱 GLM-5.2 大模型，实现从用户自然语言提问到自然语言回复的完整链路：
12. 未来扩展方向