MCP 框架架构文档

1. 概述

MCP框架（模型上下文协议框架）是一个中间件系统，旨在连接大型语言模型（LLM）服务和工具。它提供了一个与OpenAI API兼容的接口，使客户端应用程序能够通过标准API与各种LLM服务进行交互，并集成多个工具服务（MCP服务器）以增强AI助手的功能。

核心特性：

• 兼容OpenAI的聊天完成API（OpenAI Python SDK）
• 支持多种LLM服务提供商
• 插件式工具集成架构（ModelContextProtocol Python SDK）
• 会话管理
• 交互式工具调用

2. 系统架构

MCP框架采用模块化架构设计，主要由以下核心组件组成：

系统架构图

客户端应用
    │
    ▼
┌───────────────────────────────────────────────┐
│                                               │
│               MCP框架 (FastAPI)               │
│                                               │
├───────────┬─────────────┬───────────┬─────────┤
│           │             │           │         │
│  API层    │ 聊天处理器  │ 会话管理器 │ 配置管理 │
│           │             │           │         │
├───────────┴──────┬──────┴───────────┴─────────┤
│                  │                            │
│  LLM服务客户端    │        MCP管理器           │
│                  │                            │
└──────┬───────────┴────────────┬───────────────┘
       │                        │
       ▼                        ▼
┌─────────────────┐    ┌─────────────────────────┐
│                 │    │                         │
│  LLM服务        │    │  MCP工具服务            │
│  (OpenAI等)     │    │  (文件系统、时间等)      │
│                 │    │                         │
└─────────────────┘    └─────────────────────────┘

架构描述：

• 客户端应用通过HTTP API与MCP框架交互
• MCP框架处理请求并协调LLM服务和工具服务
• LLM服务客户端负责与不同的LLM提供商通信
• MCP管理器负责启动、管理和调用各种工具服务
• 会话管理器维护客户端会话状态
• 配置管理负责系统设置和参数

2.1 核心组件

LLM服务客户端 (LLMServiceClient)

负责与各种LLM服务（如OpenAI、Anthropic、Ollama、LM Studio等）通信。其主要特点包括：

• 自动检测服务类型
• 统一的API调用接口
• 流式响应处理
• 健康检查和模型列表查询

MCP管理器 (MCPManager)

管理多个MCP工具服务器的连接和工具调用。主要功能包括：

• 启动和管理多个工具服务器
• 解析工具名称并路由工具调用
• 处理工具执行结果
• 提供系统中所有可用工具的列表

会话管理器

维护客户端会话状态。主要特点包括：

• 创建和管理会话
• 存储会话消息历史
• 会话超时处理和自动清理
• 会话数量限制

聊天处理器

处理客户端聊天请求，协调LLM服务和工具调用。主要功能包括：

• 处理聊天完成请求
• 管理工具交互
• 处理流式响应
• 构建系统提示和上下文

Web API (FastAPI 应用程序)

提供与OpenAI兼容的REST API接口，用于客户端与系统的交互。主要端点包括：

• /chat/completions - 聊天完成的主要端点
• /models - 获取可用模型列表
• /health - 系统健康检查

2.2 数据模型

系统使用Pydantic模型定义各种数据结构，主要包括：

• ChatMessage - 聊天消息格式
• ChatCompletionRequest - 客户端请求
• ChatCompletionResponse - API响应
• ModelObject - 模型信息
• ModelListResponse- 模型列表响应

3. 工作流程

3.1 启动过程

1. 程序入口是run.py，在main()函数中调用main.py
2. 设置日志系统
3. 加载配置文件 (config.json)
4. 创建一个FastAPI应用程序
5. 初始化主要组件：
   • LLM服务客户端
   • MCP管理器
   • 会话管理器
   • 聊天处理器
6. 启动配置的MCP服务器
7. 启动Web服务器

3.2 请求处理流程

1. 客户端向/chat/completions端点发送聊天完成请求
2. API层接收请求并创建会话（如果不存在）
3. 聊天处理器增强请求（添加工具信息和系统提示）
4. 将请求发送到LLM服务
5. 处理LLM响应并检查工具调用
6. 如果有工具调用，则执行工具并收集结果
7. 将工具结果添加到上下文中
8. 继续与LLM交互直到任务完成
9. 将最终结果流回客户端

4. MCP工具服务

MCP框架支持多个工具服务器，每个服务器提供不同类型的工具。服务器通过stdio通信协议与框架交互。

当前配置的工具服务包括：

• 时间服务 (time) - 提供与时间相关的功能
• 文件系统服务 (filesystem) - 文件和目录操作
• 浏览器自动化服务 (firecrawl) - 网页抓取和自动化
• SQLite数据库服务 (sqlite) - 数据库操作
• 顺序思维服务 (sequential-thinking) - 增强模型的思考能力

工具服务使用MCP客户端库 (mcp) 与框架通信，提供初始化、工具列表和执行功能。

5. 配置管理

系统配置使用config.json文件，主要包括：

• 服务器配置 - 主机、端口、CORS设置
• LLM服务配置 - 服务URL、默认模型、超时等
• MCP服务器配置 - 命令、参数、环境变量等
• 会话配置 - 超时、最大会话数
• 日志配置 - 日志级别和输出

配置由config.py模块加载和管理，提供对全局配置的访问。

6. 特殊功能

6.1 交互式工具调用

系统支持模型与工具之间的多轮交互，通过tool_interactive.py实现：

• 存储工具执行结果
• 参数中的结果引用解析
• 向模型提供上下文信息

这使得模型能够：

1. 调用工具检索信息
2. 查看执行结果
3. 根据结果确定下一步
4. 在后续工具调用中参考先前的结果

6.2 LLM服务适应性

系统可以自动适应多种LLM服务

• OpenAI API
• Azure OpenAI
• Anthropic
• Ollama
• LM Studio
• Qwen

每个服务都有特定的身份验证方法和参数格式，系统自动处理这些差异。

7. 扩展性

MCP框架设计易于扩展：

1. 添加新的工具服务 - 在配置中添加一个新的MCP服务器定义
2. 支持新的LLM服务 - 扩展LLMServiceClient以添加新的服务类型
3. 增加API功能 - 在FastAPI应用程序中添加新的端点
4. 自定义系统提示 - 修改ChatHandler中的提示模板

8. 部署

系统支持多种部署方式：

• 本地运行 - 直接执行run.py
• Docker容器 - 使用提供的Dockerfile和docker-compose.yml
• 云服务 - 可以部署在支持Python的任何云平台上

系统依赖项在requirements.txt中定义。

9. 安全考虑

• 所有对LLM服务的请求都通过框架代理
• MCP工具服务作为子进程运行，并受到框架权限的限制
• 会话具有超时机制，防止资源耗尽
• 支持CORS设置以控制访问源

10. 总结

MCP框架提供了一种灵活且可扩展的架构，用于集成大型语言模型和服务工具。它使开发者能够创建强大的AI助手应用程序，同时保持系统的模块性和可维护性。

核心优势：

• 与OpenAI API兼容的标准接口
• 灵活的工具集成机制
• 支持多种LLM服务提供商
• 交互式工具调用能力
• 模块化和可扩展的架构