MCP 智能聊天助手示例项目
基于Model Context Protocol的智能对话系统示例
项目简介
本项目是基于MCP (Model Context Protocol)框架的智能聊天助手示例,展示了如何使用大语言模型(LLM)与外部数据源和工具进行集成,实现跨模态、多能力的智能对话系统。
MCP框架介绍
MCP (Model Context Protocol)是由Anthropic开源的开放协议,为LLM应用和外部数据源及工具之间的无缝集成提供标准化方式。可以将MCP理解为AI应用的”USB-C接口”,就像USB-C为设备提供了与各种外设和配件连接的标准方式一样,MCP为AI模型提供了与不同数据源和工具连接的标准方式。
MCP核心价值:连接用户、大模型与专业服务
MCP本质上是一个标准化的连接协议,它作为关键的桥梁,将三个核心组件优雅地连接在一起:
- 用户 - 通过自然语言表达需求的人或者其他的输入者
- 大模型 - 处理理解和生成的AI系统
- 专业服务 - 提供特定领域能力的工具和数据源
作为连接器,MCP实现了以下关键价值:
- 降低用户门槛:允许用户用自然语言表达复杂需求,无需了解底层技术细节
- 扩展模型能力:让大模型能够访问实时外部数据和专业功能,克服了模型知识局限和”幻觉”问题
- 激活专业服务:使现有专业服务能够被大模型智能调用,无需彻底重构现有系统
- 标准化交互:通过统一协议减少集成复杂性,降低开发和维护成本
这种标准协议的设计使得整个AI应用生态系统更加模块化和可扩展,各组件可以专注于自己的强项,同时通过标准接口协同工作,为用户提供集成化的智能体验。
为什么选择MCP?
MCP帮助你在LLM之上构建智能代理和复杂工作流。大语言模型经常需要与数据和工具集成,而MCP提供:
- 预构建集成列表,可直接连接到你的LLM
- 在不同LLM提供商和供应商之间切换的灵活性
- 在你的基础设施内保护数据的最佳实践
MCP架构
在核心上,MCP遵循客户端-服务器架构,其中主机应用程序可以连接到多个服务器:
- MCP主机:如Claude Desktop、IDE或AI工具等希望通过MCP访问数据的程序
- MCP客户端:维护与服务器1:1连接的协议客户端
- MCP服务器:通过标准化的Model Context Protocol暴露特定功能的轻量级程序
- 本地数据源:MCP服务器可以安全访问的计算机文件、数据库和服务
- 远程服务:通过互联网可用的外部系统(例如API),MCP服务器可以连接到这些系统
MCP工作流程
MCP的实际工作流程遵循以下步骤:
-
服务准备:首先,你需要一个或多个遵循MCP标准的MCP服务器,每个服务器为特定领域暴露一个功能接口(工具)和数据资源。这些服务器可以是本地的或远程的。
-
用户应用:用户通过集成了MCP客户端的应用程序(如聊天界面、IDE插件等)发送请求,MCP客户端负责与MCP服务器通信。
- 请求处理:
- 用户发送自然语言请求(例如”查询明天北京的天气”)
- 应用程序收集所有已注册的MCP服务器及其工具信息
- 应用程序调用大语言模型分析用户意图,并将其映射到适当的MCP服务和工具
- 模型返回结构化调用信息(服务名称、工具名称、参数等)
- 服务调用:
- 应用程序根据模型的决定,调用指定MCP服务器的相关工具
- MCP服务器处理请求并返回结构化数据
- 结果处理:
- 应用程序从服务器接收专业数据
- 再次调用模型将专业数据转换为用户友好的自然语言回复
- 向用户呈现最终回复
下图展示了MCP的工作流程:
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ │ │ │ │ │
│ 用户 │───────▶│ 应用程序 │◀──────▶│ 大语言模型 │
│ │ │ (MCP客户端) │ │ │
└───────────────┘ └───────▲───────┘ └───────────────┘
│
│
┌───────▼───────┐
│ MCP服务注册 │
│ 和发现 │
└───────┬───────┘
│
┌───────────────┼───────────────┐
│ │ │
┌───────▼───────┐┌──────▼────────┐┌─────▼─────────┐
│ ││ ││ │
│ MCP服务器 A ││ MCP服务器 B ││ MCP服务器 C │
│ (天气服务) ││ (知识库) ││ (数据分析) │
│ ││ ││ │
└───────────────┘└───────────────┘└────────────────┘
这个工作流程展示了MCP的核心价值:允许大语言模型通过标准化协议无缝利用各种专业服务,同时保持一致的用户体验。用户只需通过自然语言表达需求,无需了解底层技术细节或服务架构。
MCP多服务器协调机制
MCP框架能够优雅地协调多个服务器,实现复杂功能集成。具体协调机制包括:
- 服务发现和注册:
- MCP主机在启动时扫描并发现本地或网络中的MCP服务器
- 每个服务器在启动时向主机注册其能力(工具、资源类型等)
- 主机维护服务器能力映射表,用于路由请求
- 能力描述和工具列表:
- 每个MCP服务器发布其支持的工具列表、参数规范和资源类型
- 主机可以通过
list_tools
和list_resources
等API获取每个服务器的能力 - 模型根据这些能力决定调用哪个服务器的哪个工具
- 上下文管理:
- MCP维护请求上下文,以确保多服务器调用之间的信息一致性
- 上下文可以包括会话信息、用户偏好、身份验证令牌等
- 服务器可以读取上下文以提供个性化响应
- 请求路由:
- 当应用程序或模型需要特定服务时,MCP客户端负责:
- 识别哪个服务器可以处理请求
- 将请求格式化为标准的MCP协议消息
- 与目标服务器建立连接
- 传输请求并等待响应
- 当应用程序或模型需要特定服务时,MCP客户端负责:
- 并行处理:
- MCP支持同时向多个服务器发送请求
- 可以并行获取不同数据源的信息
- 可以将多个服务器的结果聚合到一个响应中
- 错误处理和回退:
- 当特定服务器不可用时,MCP可以自动尝试备用服务器
- 错误报告机制帮助应用程序诊断问题
- 支持为服务中断定义回退策略
- 版本兼容性:
- MCP协议设计支持不同版本的服务器共存
- 客户端可以处理版本差异,以确保向后兼容性
- 新服务器可以提供增强功能,而无需更新整个环境
在实践中,例如,当用户问”分析上个月的销售数据并与天气比较”时,MCP将:
- 识别需要销售数据分析和天气查询服务
- 调用数据分析MCP服务器获取销售统计信息
- 调用天气MCP服务器获取历史天气数据
- 将两种数据组合并返回给模型
- 模型根据完整上下文生成综合分析
这种协调机制使MCP能够无缝结合多个专业服务器的能力,提供集成化的体验,而每个服务器只专注于自己的专业领域,大大提高了系统的模块化和可扩展性。
MCP框架的核心思想是为大语言模型应用提供结构化的上下文信息,包括:
- 资源:提供给模型的数据,如文件内容、API响应等
- 工具:模型可以调用的函数,用于执行操作和获取信息
- 提示:可重用的交互模板,用于引导模型响应
MCP实际应用场景
让我们通过几个生动的例子来看看MCP如何解决实际问题:
例1: 智能代码助手
问题:传统代码助手缺乏对代码仓库的深入理解,无法访问本地代码结构和版本控制信息。
MCP解决方案:
- 开发者安装支持MCP的IDE插件
- IDE创建MCP服务器,暴露本地文件系统、Git历史记录和代码索引
- 当开发者通过MCP向AI提问”这个bug可能的原因是什么?”时,AI可以:
- 读取当前打开文件的内容
- 查询错误日志
- 检索相关代码模块
- 分析Git提交历史以找到最近的更改
- 提供具体的、基于上下文的解决方案
效果:开发者获得基于项目实际情况的具体建议,而不是泛泛而谈的答案。
例2: 私密知识库问答
问题:企业希望员工能够询问内部文档和数据,但担心隐私泄露。
MCP解决方案:
- 企业在自己的基础设施上部署MCP服务器,连接内部知识库
- 员工在聊天界面中问”2023年第三季度我们的销售策略是什么?”
- MCP服务器在本地:
- 检索相关内部文档
- 提取所需信息
- 将内容发送给模型进行总结
- 员工收到基于内部数据的答案
效果:敏感数据留在企业内部,但员工仍然获得智能问答体验。
例3: 个人数据助手
问题:用户希望AI帮助管理个人数据,但担心隐私问题。
MCP解决方案:
- 用户在自己的设备上安装MCP应用程序
- 应用程序创建本地服务器,连接个人照片库、日历和文件
- 用户问”帮我找到去年夏天在海滩拍的照片,并创建一个相册”
- MCP服务器在本地处理:
- 在照片库中搜索相关图像
- 仅将照片缩略图发送给模型进行分析
- 根据模型建议在本地设备上创建相册
效果:用户获得AI辅助的个人数据管理能力。
例4: 多源研究助手
问题:研究人员需要处理多种不同格式的数据并切换工具耗时。
MCP解决方案:
- 研究人员部署多个MCP服务器,分别连接:
- 科学文献数据库
- 数据可视化工具
- 统计分析软件
- 笔记和引用管理系统
- 研究员可以问”分析这组基因数据与近期论文中的发现有何关联”
- MCP协调多个服务器:
- 检索并分析实验数据
- 搜索最新相关论文
- 运行统计比较
- 生成可视化图表
- 整合为一份综合报告
效果:研究人员通过一个统一界面完成跨数据源、跨工具的复杂工作流。
这些例子说明了MCP如何解决数据集成、隐私保护和工具互操作性等关键挑战,使AI应用能够安全地访问和处理各种数据源,同时提供丰富的上下文,让大语言模型发挥最大价值。
项目架构
本项目采用了模块化设计,主要包含以下组件:
- 聊天服务(Chat App):核心服务组件,负责
- 用户请求处理
- 大模型API调用
- 用户意图解析
- MCP服务调用协调
- 响应格式化
- MCP管理器:负责
- MCP服务发现和注册
- 工具列表管理
- 服务调用路由
- 天气MCP服务:提供天气信息查询功能
- 天气数据获取
- 温度范围查询
- 降水预测
- 天气图表生成
- 大语言模型服务(vLLM):提供大模型推理能力
- 模型托管和优化推理
- 用户意图解析和服务选择
- 结构化数据转自然语言描述
- OpenAI兼容API接口
架构图示:
┌─────────────────────────┐ ┌──────────────────────┐
│ │ │ │
│ 用户/客户端 │◀─HTTP────▶│ mcp_chat_app/ │
│ │ │ chat_app.py │
└─────────────────────────┘ │ (Flask应用) │
└──────────┬───────────┘
│
│
┌──────────────────────────────┼──────────────────────────────┐
│ │ │
┌────────────▼─────────────┐ ┌────────────▼─────────────┐ ┌────────────▼─────────────┐
│ mcp_chat_app/ │ │ mcp_chat_app/ │ │ vllm_server/ │
│ mcp_manager.py │ │ mock_mcp_manager.py │ │ run.py │
│ (MCP服务发现与管理) │ │ (测试用模拟MCP管理器) │ │ (大模型推理服务 │
└────────────┬─────────────┘ └──────────────────────────┘ │ 可替换为远程API) │
│ └──────────┬───────────────┘
│ MCP协议 │
│ │
┌────────────▼─────────────┐ ┌───────────▼───────────────┐
│ weather_mcp_server/ │◀─────────────────────────────────┤ 1. 意图解析 │
│ weather_server.py │ │ 2. 参数提取和验证 │
│ (天气服务MCP实现) │─────────────────────────────────▶│ 3. 结果格式化和润色 │
│ │ └───────────────────────────┘
└──────────────────────────┘ ▲
│ │ │
│ │ │
┌────────────▼──┐ ┌───▼────────────┐ ┌───────────────────────────┐ │
│ utils.py │ │ chart_generator.│ │ 双向交互流程 │ │
│ (数据处理) │ │ py (图表生成) │ │ │ │
└───────────────┘ └────────────────┘ │ 1. 用户查询意图理解 │ │
│ 2. MCP工具选择 │ │
│ 3. 参数解析和转换 │ │
│ 4. 结果数据自然语言化 │ │
│ 5. 多模态内容处理 │ │
└───────────────────────────┘ │
│
chat_app.py ──────────┘
大模型服务关键交互
大语言模型服务(vLLM)在整个系统中扮演着”大脑”角色,与其他组件有三个关键交互点:
- 与聊天服务(chat_app.py)的交互:
- 接收用户原始查询,分析用户意图
- 从可用工具列表中选择最合适的MCP服务和工具
- 提取和格式化调用参数
- 将MCP服务返回的结构化数据转化为自然语言回复
- 处理错误情况并提供友好响应
- 与MCP服务的间接交互:
- 通过聊天服务作为中介,大模型决定调用哪个MCP服务
- 根据MCP服务的工具文档信息,正确构造调用参数
- 理解MCP服务返回的数据结构,进行信息提取和整合
- 模型能力应用:
- 语义理解:将自然语言转化为结构化意图
- 上下文记忆:维持多轮对话的连贯性
- 格式转换:在自然语言和结构化数据间互相转换
- 多模态处理:支持文本、图表、结构化数据等混合内容
大模型服务采用vLLM加速推理,提供OpenAI兼容的API接口,使系统能够轻松替换底层模型,同时保持接口一致性。该服务不仅提供基础推理能力,还承担着整个系统的决策和协调角色,是连接用户需求与专业服务的关键桥梁。
值得注意的是,本架构中的vLLM服务器组件采用了模块化设计,可以灵活替换为:
- 本地部署模式:如当前的vllm_server部署,适合开发测试或对数据安全有较高要求的场景
- 云端API模式:可直接替换为OpenAI、Anthropic Claude、QianWen千问等商业API服务
- 自托管远程模式:可部署在专用GPU服务器或云端GPU实例上,通过API连接
- 混合模式:不同功能使用不同来源的模型服务,如意图理解使用轻量模型,内容生成使用更强大的模型
系统设计确保了无论使用哪种模型服务部署方式,聊天应用的核心功能和与MCP服务的交互方式都保持一致,只需修改配置即可切换,无需更改应用代码架构。这种灵活性使开发者可以根据实际需求、预算和计算资源选择最适合的部署策略。
系统工作流程:
- 用户发送HTTP请求到聊天服务(chat_app.py)
- 聊天服务使用vLLM大模型服务分析用户意图
- 根据分析结果,通过mcp_manager调用天气MCP服务的相关工具
- 天气服务处理请求,可能使用chart_generator生成图表
- 聊天服务接收MCP服务返回的专业数据
- 再次调用大模型服务将数据转化为自然语言回复
- 将最终回复返回给用户
用户使用方式
通过调用api, 在api中用户可以通过自然语言查询天气信息:
- “北京今天天气怎么样?”
- “上海未来三天的温度变化趋势”
- “广州今天会下雨吗?”
- “给我看看杭州的降水量图表”
系统会调用天气服务获取相关数据,并通过大模型将数据转化为易于理解的回复。
如何用cursor开发自己的MCP服务(以当前项目,天气查询服务为例)
- 创建一个新的文件夹
- 拷贝mcp的readme以及python sdk readme到当前的项目根目录以告诉cursor,mcp是什么以及怎么用
生成mcpserver
- 使用cursor agent开始第一个项目生成
请根据REAME中的MCP框架创建一个项目,这个项目是一个mcpserver,实现了mcpserver的所有功能,作天气查询
这样就会生成 weather_mcp_server
项目
- 运行mcp
为整个项目创建一个 venv
# 回到项目根目录
uv venv -p python3.12 .venv
source .venv/bin/activate
# 安装mcp
pip install mcp 'mcp[cli]'
# 安装依赖
pip install -r weather_mcp_server/requirements.txt
# 运行mcpserver
python weather_mcp_server/run.py --dev
# 或者使用mcp命令
mcp dev weather_mcp_server/weather_server.py
# 输出如下
Starting MCP inspector...
Proxy server listening on port 3000
🔍 MCP Inspector is up and running at http://localhost:5173 🚀
这样我们就可以在http://localhost:5173 这个mcp代理中访问mcpserver了
在claude和cursor中都可以使用,例如在cursor中使用
进行添加会帮我们创建一个文件,文件内容需要根据刚才创建的mcpserver来填写
{
"mcpServers": {
"server-name": {
"command": "python",
"args": ["/yourpath/weather_mcp_server/weather_server.py"]
}
}
}
注册上来之后在cursor agent中可以通过cursor使用mcpserver
生成用户程序
现在mcpserver使用依赖于cursor,mcp设计本身事为了作为大模型与应用的连接器的,所以我们能不能写个应用来连接大模型和应用呢,现在应用已经有了,需要
- 有一个大模型(本地启动的无论是deepseek还是、llama、qianwen都表现比较差,用阿里云百联的
qwen-plus
)- 可以使用项目中的vllm代码本地启动一个
- 使用在线大模型
- 有一个面向用户的程序,用户发送请求,例如”北京天气如何”,此程序通过大模型分析用户语义并和mcpserver暴露的服务做匹配,在调用对应服务获取返回,大模型加工之后返回给用户,可参考mcp_simple_chatbot
- 需要有mcpserver注册功能
- 解决上述业务流程
将上面这段话发送给cursor agent,便能生成项目 mcp_chat_app
, 经过调试基本可用
curl -X POST "http://localhost:8081/chat/test_user" -H "Content-Type: application/json" -d '{"message": "明天29以上,30以下的城市有哪些?", "use_tools": true}'
{"response":"根据天气预报,明天温度在29°C到30°C之间的城市有以下两个:\n\n1. **广州**:预计最高温度为30°C,天气以高温为主。\n2. **深圳**:预计温度为29.5°C,天气多云。\n\n如果你计划去这两个城市之一,记得根据天气情况做好准备哦! 😊"}%
curl -X POST "http://localhost:8081/chat/test_user" -H "Content-Type: application/json" -d '{"message": "西安今天天气如何?", "use_tools": true}'
{"response":"您好!关于西安今天的天气,目前MCP服务没有直接提供具体信息,但它给出了未来7天内部分城市的天气概况。从这些数据中,我们可以看到:\n\n- **最热的城市**是广州和深圳,分别达到30.0°C(高温)和29.5°C(多云)。 \n- **有降雨的城市**是成都,预报为小雨。\n\n虽然西安的天气未在上述列表中提及,但通常情况下,西安的天气以干燥和晴朗为主,建议您参考本地天气应用或稍后再查询以获取更准确的信息哦!如果需要进一步帮助,请告诉我! 😊"}%
项目扩展
本项目可以通过以下方式进行扩展:
- 添加更多MCP服务: 开发新的专业服务,如文档处理、代码生成等
- 增强聊天体验: 添加上下文管理、多轮对话支持
- 提升大模型能力: 接入更强大的模型、优化提示词工程
- 开发Web/移动前端: 构建用户友好的界面
- 添加身份验证: 实现用户管理和权限控制
MCP当前生态
MCP作为一项相对新兴的技术标准,其生态系统目前仍处于发展初期:
- 成熟应用:
- Claude桌面应用是目前集成MCP最完善的应用,提供了完整的MCP服务发现、管理和调用功能
- Cursor IDE已实现基础的MCP支持,允许开发者在编码过程中利用本地上下文
- 生态状况:
- 当前支持MCP的应用和工具相对有限,主要集中在开发工具和专业领域
- 官方SDK支持主流编程语言(Python、TypeScript、Java、Kotlin),但社区贡献的MCP服务库尚在起步阶段
- 大多数MCP服务需要开发者自行构建和部署
- 发展趋势:
- 随着Anthropic持续推动标准发展和生态建设,更多应用预计将添加MCP支持
- 厂商中立的特性使得MCP有潜力成为连接LLM和专业服务的通用标准
- 开发者社区对私有部署和数据安全的需求正在推动MCP在企业环境中的应用
对于开发者而言,现阶段是参与MCP生态建设的有利时机,可以通过构建专业领域的MCP服务来填补生态空白,也可以将现有工具和服务通过MCP协议进行包装,以便与大模型应用集成。
相关资源
贡献指南
欢迎为项目做出贡献! 您可以通过以下方式参与:
- 提交问题和功能请求
- 提交代码改进
- 贡献新的MCP服务
- 改进文档