LangChain MCP Client Streamlit App

LangChain MCP 客户端 Streamlit 应用

此 Streamlit 应用提供了一个用户界面，用于连接 MCP（Model Context Protocol）服务，并通过不同的 LLM 提供商（OpenAI、Anthropic、Google、Ollama）与其交互。

⚠️ 开发状态

此应用目前仍在积极开发中。 虽然已可使用，但您可能会遇到错误、功能不完整或意外行为。感谢您的耐心，也欢迎您提供反馈，帮助改进此应用。

功能

• 多提供商 LLM 支持：OpenAI、Anthropic Claude、Google Gemini 和 Ollama
• 支持 OpenAI 推理模型：针对 o3-mini、o4-mini 提供增强支持，并采用专门的参数处理方式
• 流式响应：为受支持的模型提供逐个令牌的实时流式响应
• 文件附件与多模态输入：在聊天消息中附加图像、PDF 和文本/Markdown 文件（仅支持具备视觉能力的模型处理图像）
• MCP（Model Context Protocol）集成：连接 MCP 服务以访问工具
• 高级记忆管理：短期会话记忆和跨会话持久记忆
• 多服务支持：同时连接多个 MCP 服务
• 工具测试界面：使用自定义参数测试单个工具
• 纯聊天模式：无需连接 MCP 服务即可进行简单对话
• 高级模型配置：自定义温度、最大令牌数、超时和系统提示词
• 智能模型验证：自动验证参数并检查兼容性
• 全面的日志记录：跟踪所有工具执行情况和对话
• 导出/导入：保存和加载对话历史记录
• 容器化部署：轻松使用 Docker 进行设置

新功能 - 文件附件（多模态输入）

此应用现在支持在聊天消息中附加文件。

支持的文件类型

• ✅ 图像：PNG、JPG、JPEG、GIF、WEBP（需要具备视觉能力的模型）
• ✅ 文档：PDF（在客户端提取文本）
• ✅ 文本：TXT、MD

如何附加文件

1. 将文件直接拖放到聊天输入框，或
2. 使用聊天上方的“📎 Attach files (PDF, TXT, images)”展开器选择多个文件。

附件会随您的下一条消息一起发送，并显示在对话元数据中。

工作原理

• 图像：以行内图像块的形式发送。OpenAI GPT-4o/o4 系列、Anthropic Claude 3.x 和 Google Gemini 模型支持此功能。此应用中的 Ollama 不支持。
• PDF：使用 pypdf 在本地提取文本，并将其作为上下文文本与提示词一起发送。
• 文本/Markdown：读取文件内容，并将其作为额外的文本上下文。

提供商支持说明

• OpenAI：处理图像时请使用具备视觉能力的模型（例如 gpt-4o、o4-*、gpt-4.1、gpt-4-turbo）。文本/PDF 适用于各种文本模型。
• Anthropic：Claude 3 系列（Sonnet/Opus/Haiku）支持图像和文本。
• Google：Gemini 模型支持图像、文本和 MCP 工具调用。
• Ollama：此应用不支持图像；PDF/文本会作为文本包含在内。

新功能 - 流式支持

此应用现在支持所有兼容模型的实时流式响应：

支持流式响应的模型

• ✅ OpenAI：所有 GPT 模型（GPT-4o、GPT-4、GPT-3.5-turbo）+ 推理模型（o3-mini、o4-mini）
• ✅ Anthropic：所有 Claude 模型（Claude-3.5-Sonnet、Claude-3-Opus、Claude-3-Haiku）
• ✅ Google：所有 Gemini 模型（Gemini-2.0-Flash、Gemini-2.5-Pro-Exp）
• ✅ Ollama：所有本地模型（Granite、Qwen 等）
• ❌ OpenAI o1 系列：o1、o1-mini、o1-preview（受 API 限制，不支持）

工作原理

1. 启用流式响应：在侧边栏的“🌊 Streaming Settings”区域中切换设置
2. 实时显示：响应会在生成过程中逐个令牌显示
3. 工具集成：实时查看工具执行状态
4. 回退支持：出现问题时自动回退到非流式响应

优势

• 更佳的用户体验：实时查看正在生成的回复
• 更快的感知响应速度：模型仍在生成时即可开始阅读
• 实时反馈：立即了解工具何时执行
• 交互感更强：带来更投入的对话体验

支持 OpenAI 推理模型

应用现已增强对 OpenAI 推理模型的支持，并针对这些模型进行了专门处理：

支持的推理模型

• ✅ o3-mini：支持流式传输的快速推理模型
• ✅ o4-mini：支持流式传输的高级推理模型
• ❌ o1 系列：o1、o1-mini、o1-preview（因 API 要求特殊，暂不支持）

推理模型功能

• 自动优化参数：使用 max_completion_tokens 替代 max_tokens
• 温度处理：自动为推理模型停用温度设置（这类模型使用固定温度）
• 推理力度：自动将推理力度设为“medium”，以获得最佳性能
• 流式传输支持：o3/o4 系列支持实时流式传输（o1 系列不支持）
• 智能校验：防止不兼容的参数组合，并提供清晰的错误消息

用户体验

• 明确警告：选择推理模型时显示视觉提示
• 替代方案建议：选择 o1 系列时推荐兼容的模型
• 无缝集成：支持所有现有功能（记忆、工具、流式传输）

配置系统

大模型提供商与参数

• OpenAI：
  • 常规模型：GPT-4o、GPT-4、GPT-3.5-turbo，温度（0.0-2.0）、最大令牌数（1-16384）、超时（10-600s）
  • 推理模型：o3-mini、o4-mini，采用专门的参数处理方式（无温度、max_completion_tokens、reasoning_effort）
  • 不支持：o1、o1-mini、o1-preview（API 要求不兼容）
• Anthropic：Claude-3.5-Sonnet、Claude-3-Opus、Claude-3-Haiku，温度（0.0-1.0）、最大令牌数（1-8192）、超时（10-600s）
• Google：Gemini-2.5-Flash-Lite、Gemini-2.5-Pro，温度（0.0-2.0）、最大令牌数（1-32768）、超时（10-600s）
• Ollama：本地模型（Granite3.3:8b、Qwen3:4b），温度（0.0-2.0）、最大令牌数（1-32768）、超时（10-600s）

自定义模型支持

现在，所有提供商都支持 “Other” 选项，可用于指定自定义模型名称：

• OpenAI：输入任意 OpenAI 模型名称（例如 gpt-4-turbo、o3-mini、自定义微调模型）
• Anthropic：输入任意 Anthropic 模型名称（例如 claude-3-sonnet-20240229）
• Google：输入任意 Google 模型名称（例如 gemini-pro、gemini-1.5-pro）
• Ollama：输入任意本地可用的模型名称（例如 llama3、codellama、自定义模型）

系统提示词

• 内置预设：为不同使用场景提供五种专用系统提示词
• 自定义提示词：创建并保存自己的系统提示词
• 实时应用：应用配置更改并即时获得反馈
• 配置状态：通过视觉提示显示已应用、更改中和默认状态

配置管理

• 应用配置：智能按钮，可检测更改并应用设置
• 导出/导入：将配置保存为 JSON 文件，以便备份或分享
• 重置选项：重置为默认设置或先前应用的设置
• 更改检测：实时跟踪配置修改

记忆系统

记忆类型

1. 短期（会话）：

   • 对话存储在浏览器会话内存中
   • 关闭浏览器或重启应用后，对话将丢失
   • 使用 LangGraph 的 InMemorySaver

2. 持久化（跨会话）：

   • 对话存储在 SQLite 数据库（conversations.db）中
   • 浏览器会话之间及应用重启后均可保留
   • 使用 LangGraph 的 SqliteSaver，并通过自定义元数据进行管理
   • 聊天过程中自动保存对话
   • 浏览、加载和管理已保存的对话

高级记忆功能

• 对话导入/导出：导入之前的对话，并提供预览和确认机制
• 线程管理：通过唯一 ID 在不同对话线程间切换
• 记忆分析：跟踪消息数量、记忆用量、对话统计信息和数据库大小
• 对话浏览器：查看和管理所有已存储的对话，并支持查看元数据和搜索
• 历史记录工具集成：启用记忆后，Agent 可使用 get_conversation_history 工具，以便：
  • 按类型或内容搜索之前的对话
  • 引用先前的讨论并保持上下文
  • 总结对话主题并筛选消息
  • 通过简洁、格式清晰的输出访问对话历史记录中的特定部分

记忆安全性与性能

• 导入验证：安全的导入系统，应用前会验证格式并提供预览
• 循环防护：提供可靠的防护措施，避免记忆操作陷入无限循环
• 灵活限制：可配置消息数量限制和记忆约束
• 实时状态：通过可视化指示器显示记忆状态、线程信息和更改情况

工具测试与分析

• 单独测试工具：通过“🔧 测试工具”选项卡访问
• 动态参数表单：根据工具架构自动生成表单，并实时验证
• 性能跟踪：执行计时、成功/失败率和详细统计信息
• 测试历史记录：完整的测试结果历史记录，并支持导出
• 结果分析：计算成功率和平均执行时间指标
• JSON 导出：导出测试结果和性能数据，以便进行外部分析

未来改进

• STDIO MCP 服务：支持使用标准输入/输出（STDIO）连接 MCP 服务，实现更灵活的服务配置
• RAG（文档索引）：跨会话索引并检索已上传的文档（目前已支持附件；完整检索功能仍在规划中）
• 增强工具验证：为 MCP 工具提供高级参数验证和架构检查
• 多线程处理：并行处理多个工具执行和服务连接

安装

1. 克隆此仓库：

git clone https://github.com/guinacio/langchain-mcp-client.git
cd langchain-mcp-client

推荐：使用 UV 安装

UV 会管理项目本地的 .venv，并根据 pyproject.toml/uv.lock 固定依赖版本。

uv sync --all-extras --dev

使用 UV 运行应用：

uv run streamlit run app.py

应用将在 http://localhost:8501 上运行。

安全与部署

此应用采用本地优先设计，不包含多用户身份验证功能。 因此，随附的 Docker Compose 配置仅在 127.0.0.1 上发布 Streamlit 和示例 MCP 服务。除非在可信反向代理处添加身份验证，否则请勿将此绑定改为 0.0.0.0，也不要通过隧道/公共入口暴露应用。

持久化对话通过服务端签发的会话专属命名空间进行隔离。 升级前作用域为全局的对话记录会在迁移期间被隔离，不会向新会话公开。 如果可信的单用户部署需要在浏览器重启后保留存储，请设置强度足够的 MCP_CLIENT_STORAGE_KEY；该部署的所有用户都会共享此命名空间，因此请勿在多用户托管环境中使用此模式。

出站 MCP 和 Ollama URL 会在服务端进行验证。本地开发仍允许使用环回 URL；始终会阻止链路本地地址、云元数据地址和保留地址。要访问可信的 RFC1918/专用网络服务，部署运维人员必须设置 MCP_ALLOW_PRIVATE_URLS=true（此变量已在仅限本地的 Docker Compose 服务中设置）。

本地环境配置示例：

MCP_CLIENT_STORAGE_KEY="generate-a-long-random-value"
MCP_ALLOW_PRIVATE_URLS=true  # only when trusted LAN MCP/Ollama hosts are needed

备选方案：使用 pip 和 requirements.txt 安装

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
streamlit run app.py

设置 MCP 服务

要使用此应用，你需要运行一个 MCP 服务，或提供 MCP 服务的有效 URL。 如需快速测试，请使用 weather_server.py 上提供的简易 MCP 服务：

使用 UV 运行（推荐）：

uv run python weather_server.py

替代方案（pip/venv）：

python weather_server.py

默认情况下，服务将在端口 8000 上启动。在 Streamlit 应用中，你可以使用 URL http://localhost:8000/sse 连接到它。

故障排除

• 连接问题：确保 MCP 服务正在运行且可访问
• API 密钥错误：确认输入的 API 密钥与所选大模型提供商匹配
• 工具错误：查看服务日志，了解使用工具时发生的错误详情
• 推理模型问题：
  • 如果看到“o1 Series Models Not Supported”，请改用 o3-mini 或 o4-mini
  • 推理模型不支持自定义温度设置
  • 某些推理模型可能不支持流式传输（请查看特定模型的警告）
• 自定义模型名称：使用“Other”选项时，请确保模型名称与提供商 API 所要求的完全一致，并且你有权访问该模型。
• 文件附件：
  • 图片需要具备视觉能力的模型（例如 GPT-4o/o4、Claude 3.x、Gemini）。此处的 Ollama 仅支持文本。
  • PDF 文本提取效果取决于 PDF 的质量；扫描图像可能只能提取有限的文本。

资源

• LangChain MCP 适配器
• Model Context Protocol
• Streamlit 文档