claude-mcp

[cyl19970726]

MCP (Model Context Protocol) Integration for MiniAgent

概述

将 MCP (Model Context Protocol) 集成到 MiniAgent 框架中，使其能够使用标准的 MCP 服务器和工具。

技术分析

当前架构

MiniAgent 采用模块化架构：

• BaseAgent: 核心代理实现，协调各个组件
• IChat: 处理 LLM 通信的抽象接口
• IToolScheduler: 管理工具执行的调度器
• ITool: 工具的抽象接口
• 支持类型安全的流式响应和事件系统

MCP 集成点

1. 工具层集成: 创建 MCP 工具适配器，将 MCP 工具包装为 ITool 接口
2. 服务器管理: 实现 MCP 服务器连接和管理
3. 类型安全: 确保所有 MCP 交互都有完整的类型定义
4. 错误处理: 实现完善的错误处理和重试机制

实现方案

1. 核心接口定义

// src/mcp/interfaces.ts
export interface MCPConfig {
  servers: MCPServerConfig[];
  timeout?: number;
  retryAttempts?: number;
  logLevel?: LogLevel;
}

export interface MCPServerConfig {
  name: string;
  command: string;
  args?: string[];
  env?: Record<string, string>;
  disabled?: boolean;
}

export interface MCPTool extends ITool {
  serverName: string;
  mcpToolName: string;
}

2. MCP 服务器管理器

// src/mcp/mcpServerManager.ts
export class MCPServerManager {
  private servers: Map<string, MCPServer> = new Map();
  
  async startServer(config: MCPServerConfig): Promise<void>
  async stopServer(name: string): Promise<void>
  async getServerTools(serverName: string): Promise<MCPTool[]>
  async executeServerTool(serverName: string, toolName: string, params: any): Promise<any>
}

3. MCP 工具适配器

// src/mcp/mcpToolAdapter.ts
export class MCPToolAdapter implements ITool {
  constructor(
    private serverManager: MCPServerManager,
    private serverName: string,
    private mcpTool: MCPToolDefinition
  )
  
  async execute(params: any, signal: AbortSignal): Promise<ToolResult>
  validateToolParams(params: any): string | null
  shouldConfirmExecute(params: any): Promise<ToolCallConfirmationDetails | false>
}

4. MCP Agent 扩展

// src/mcp/mcpAgent.ts
export class MCPAgent extends BaseAgent {
  private mcpManager: MCPServerManager;
  
  constructor(config: AllConfig & { mcpConfig: MCPConfig })
  
  async loadMCPTools(): Promise<void>
  async refreshMCPTools(): Promise<void>
}

5. 配置和初始化

// 使用示例
const config: AllConfig & { mcpConfig: MCPConfig } = {
  agentConfig: { /* ... */ },
  chatConfig: { /* ... */ },
  toolSchedulerConfig: { /* ... */ },
  mcpConfig: {
    servers: [
      {
        name: 'filesystem',
        command: 'npx',
        args: ['@modelcontextprotocol/server-filesystem', '/path/to/allowed/directory']
      },
      {
        name: 'git',
        command: 'mcp-server-git',
        args: []
      }
    ],
    timeout: 30000,
    retryAttempts: 3
  }
};

const agent = new MCPAgent(tools, config);
await agent.loadMCPTools();

实现细节

类型安全

• 所有 MCP 相关接口都有完整的 TypeScript 类型定义
• 使用泛型确保工具参数和返回值的类型安全
• 运行时参数验证

错误处理

• MCP 服务器连接失败的重试机制
• 工具执行超时处理
• 详细的错误日志和调试信息
• 优雅的降级处理（MCP 服务器不可用时不影响其他工具）

配置管理

• 支持环境变量配置
• 支持动态服务器启停
• 配置验证和默认值处理

性能优化

• 连接池管理
• 工具缓存机制
• 异步非阻塞执行

测试策略

单元测试

• MCP 服务器管理器测试
• 工具适配器测试
• 错误处理测试

集成测试

• 与实际 MCP 服务器的集成测试
• 端到端工具执行测试
• 性能和稳定性测试

示例和文档

• 完整的使用示例
• 配置指南
• 故障排除文档

交付物

1. 核心实现文件:

   • src/mcp/interfaces.ts - MCP 接口定义
   • src/mcp/mcpServerManager.ts - 服务器管理
   • src/mcp/mcpToolAdapter.ts - 工具适配器
   • src/mcp/mcpAgent.ts - MCP 集成的 Agent

2. 配置和工具:

   • src/mcp/config.ts - 配置管理
   • src/mcp/utils.ts - 工具函数

3. 测试文件:

   • src/test/mcp/ - 所有 MCP 相关测试

4. 示例和文档:

   • examples/mcpExample.ts - 使用示例
   • docs/mcp-integration.md - 集成文档

成功标准

• 成功连接和管理多个 MCP 服务器
• 动态加载和执行 MCP 工具
• 完整的类型安全保证
• 优雅的错误处理和恢复
• 性能满足生产环境要求
• 完整的测试覆盖率 (>90%)
• 详细的文档和示例

风险和缓解

技术风险

• MCP 协议兼容性: 使用官方 MCP SDK，确保协议兼容性
• 性能问题: 实现连接池和缓存机制
• 稳定性问题: 完善的错误处理和重试机制

集成风险

• 向后兼容性: 确保现有 API 不受影响
• 配置复杂性: 提供合理的默认配置和验证

时间估算

• 设计和接口定义: 1 天
• 核心实现: 3-4 天
• 测试和调试: 2 天
• 文档和示例: 1 天
• 总计: 7-8 天

依赖项

需要添加的 npm 依赖：

• @modelcontextprotocol/sdk - MCP 官方 SDK
• 可能需要的其他 MCP 相关包

🤖 Generated with Claude Code