9.5 实战:为MiniHarness集成MCP

本节在MiniHarness框架的基础上,实现完整的MCP Client集成,包括动态工具发现、Schema缓存、权限管理。

9.5.1 架构设计

MiniHarness的MCP集成采用四层架构:

  1. MiniHarness Agent:上下文管理和工具调用入口

  2. MCPToolAdapter:将MCP工具转换为LLM可调用形式,处理错误和降级

  3. MCPToolRegistry + SchemaCache:动态发现工具、缓存Schema和管理权限

  4. MCP Servers:多种传输协议支持(stdio、HTTP)

完整代码见 lab/mini_harness/mcp/integration.py

9.5.2 核心设计决策

双层 Schema 缓存策略

为什么需要两层缓存?

  • 内存缓存:毫秒级访问,适合热工具

  • 磁盘缓存:跨进程持久化,TTL机制自动过期

class ToolSchemaCache:
    """双层缓存:内存 + 磁盘"""
    async def get(self, server_id: str, tool_name: str):
        # 1. 检查内存缓存(毫秒级)
        if cache_key in self.memory_cache:
            if not expired:
                return cached

        # 2. 检查磁盘缓存(毫秒级,TTL)
        if disk_path.exists:
            cached = load_from_disk()
            self.memory_cache[cache_key] = cached  # 晋升
            return cached

        return None

效果:Schema缓存减少80%以上的令牌消耗。工具发现延迟从秒级降至毫秒级。

异步锁保护并发发现

多个Agent同时调用同一工具时的竞态条件:

好处:避免重复发现、减少Server负载、保证发现的一致性。

MCPServerConfig 数据类

为什么用dataclass而不是dict?

设计理由

  • 类型安全(IDE补全、类型检查)

  • 默认值管理

  • 易于扩展(如添加认证、速率限制)

  • 可持久化为JSON

MCPToolAdapter 的适配模式

为什么需要适配层?

优点

  • LLM SDK版本变化时,只需改适配层

  • 易于添加权限检查、审计、降级逻辑

  • 分离MCP协议和LLM SDK

9.5.3 关键代码片段

工具调用生命周期

以下代码展示工具调用的完整生命周期,从查找Server、发送请求到处理响应:

MiniHarness 集成入口

以下是MCP集成的核心类,负责初始化各层组件和处理工具调用:

错误处理与降级

以下代码演示了如何处理JSON解析错误和工具调用异常,确保系统稳定性:

9.5.4 集成清单

使用此MCP集成时的检查清单:

初始化

工具发现

工具调用

性能优化

错误处理

安全性

9.5.5 本小节小结

通过MCPToolRegistry、SchemaCache和MCPToolAdapter的组合,MiniHarness实现了完整的MCP集成:

  1. 动态发现:自动发现多个MCP Server提供的工具

  2. 智能缓存:双层Schema缓存减少延迟和令牌消耗

  3. 灵活适配:将MCP工具转换为LLM可用的格式

  4. 完整的生命周期:从发现、获取Schema到调用,一套完整的系统

关键指标:

  • Schema缓存减少80%以上的令牌消耗

  • 工具发现延迟从秒级降至毫秒级(缓存命中)

  • 支持并发工具调用和错误恢复

完整实现代码见 lab/mini_harness/mcp/integration.py

最后更新于