基于 mcp-use 打造 MCP 驱动的全能 AI 助手：Streamlit 聊天界面与多 MCP 服务器编排实战

基于 mcp-use 打造 MCP 驱动的全能 AI 助手：Streamlit 聊天界面与多 MCP 服务器编排实战

【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub

本文以ultimate-ai-assitant-using-mcp项目为对象，系统讲解如何基于 [mcp-use] 与 Streamlit 构建一个可同时挂载浏览器、网页抓取、多模态 RAG、长期记忆、终端与代码仓库等多种 MCP 服务器的"全能 AI 助手"。读完本文，你将掌握 MCP 客户端/Agent 的初始化方式、MCP 服务器 JSON 配置的完整写法、侧边栏配置激活流程以及聊天界面的交互实现，可直接复制运行并扩展为自己的工具集合。

项目概览：一个聊天气泡接入全部 MCP 工具

ultimate-ai-assitant-using-mcp是一个 Streamlit 应用，它为 MCP（Model Context Protocol）服务器提供统一的自然语言聊天界面：用户在侧边栏粘贴 JSON 格式的 MCP 服务器配置，点击激活后即可通过对话框指挥多个 MCP 工具协同工作，应用内部由mcp-use库负责把 LLM 与各个 MCP 服务器连接起来（见 README.md）。

从 mcp_streamlit_app.py 可以看到，应用的页面标题被设定为 "MCP-powered Perplexity Clone"、主标题为 "100% local Ultimate AI Assistant using mcp-use"，直观体现了"聚合多个 MCP 能力于单一聊天入口"的定位。

技术栈组成

项目按功能职责选用了一套完整的 MCP 生态工具：

依赖版本在 pyproject.toml 中锁定：mcp-use>=1.3.7、streamlit>=1.47.1、langchain-openai>=0.3.28、langchain-ollama>=0.3.5，要求Python >= 3.12；另外还预装了assemblyai（语音转录）与ipykernel，为后续扩展语音类 MCP 能力预留了空间。

环境准备与依赖安装

项目采用 uv 作为包管理工具，安装依赖只需一条命令（README 第 15-18 行）：

uv sync

该命令会依据 pyproject.toml 与 uv.lock 创建虚拟环境并安装全部锁定版本依赖；若你习惯 pip，也可参考 requirements.txt（其中同样声明了streamlit、python-dotenv、langchain-openai、langchain-ollama、mcp-use、asyncio等最小依赖集）。

环境变量配置

在项目根目录创建.env文件，填入各服务所需的 API Key（README 第 20-26 行）：

OPENAI_API_KEY=your-openai-api-key FIRECRAWL_API_KEY=your-firecrawl-api-key RAGIE_API_KEY=your-ragie-api-key

OPENAI_API_KEY用于驱动 Agent 的推理模型（也可改为本地 Ollama 模型）；FIRECRAWL_API_KEY与RAGIE_API_KEY分别对应 Firecrawl 抓取服务与 Ragie 多模态 RAG 服务。应用与 server.py 均在启动时调用load_dotenv()加载这些变量，配置里通过os.getenv()动态引用，避免把密钥硬编码进 JSON。

编排 MCP 服务器：server.py 中的完整配置

项目把"多 MCP 服务器编排"沉淀为一份完整的配置字典，集中在 server.py。这是理解整个项目能力的核心素材，覆盖了 MCP 配置的三种典型形态：

1. 本地 node 脚本型（Stagehand）

"stagehand": { "command": "node", "args": ["/path/to/mcp-server-browserbase/stagehand/dist/index.js"], "env": { "OPENAI_API_KEY": os.getenv("OPENAI_API_KEY"), "LOCAL_CDP_URL": "http://localhost:9222", "DOWNLOADS_DIR": "/path/to/downloads/stagehand" } }

• command指定启动方式（node），args指向 MCP 服务器入口脚本；
• LOCAL_CDP_URL指向本地 Chrome DevTools Protocol 端点，用于连接已启动的浏览器实例；
• DOWNLOADS_DIR指定浏览器下载目录。

2. npx 拉取型（Firecrawl / Ragie / DesktopCommander）

"mcp-server-firecrawl": { "command": "npx", "args": ["-y", "firecrawl-mcp"], "env": {"FIRECRAWL_API_KEY": os.getenv("FIRECRAWL_API_KEY")} }, "ragie": { "command": "npx", "args": ["-y", "@ragieai/mcp-server", "--partition", "default"], "env": {"RAGIE_API_KEY": os.getenv("RAGIE_API_KEY")} }, "desktop-commander": { "command": "npx", "args": ["-y", "@wonderwhy-er/desktop-commander"] }

• 这类服务器无需本地安装，npx -y <包名>直接拉取并运行；
• Ragie 通过--partition default指定检索分区；
• DesktopCommander 未传env，说明它不依赖 API Key，直接暴露本地终端能力。

3. uv 运行型（Graphiti 记忆服务器）

Graphiti 是最复杂的一个，使用 uv 以隔离模式启动位于本地路径的 MCP 服务器：

"graphiti": { "transport": "stdio", "command": "/Users/your-username/.local/bin/uv", "args": [ "run", "--isolated", "--directory", "/path/to/graphiti/mcp_server", "--project", ".", "graphiti_mcp_server.py", "--transport", "stdio" ], "env": { "NEO4J_URI": "bolt://localhost:7687", "NEO4J_USER": "neo4j", "NEO4J_PASSWORD": "demodemo", "OPENAI_API_KEY": os.getenv("OPENAI_API_KEY"), "MODEL_NAME": "gpt-4o-mini" } }

要点：

• 显式声明"transport": "stdio"，指明与 Graphiti 服务器走标准输入输出管道通信；
• --isolated表示 uv 在隔离环境运行，不污染全局依赖；--directory指向 graphiti mcp_server 源码目录；
• 记忆存储依赖本地 Neo4j 图数据库，需要NEO4J_URI/NEO4J_USER/NEO4J_PASSWORD三个环境变量；
• 记忆向量化与实体抽取复用OPENAI_API_KEY，MODEL_NAME默认gpt-4o-mini以控制成本。

4. uvx 安装型（GitIngest）

"mcp-git-ingest": { "command": "/path/to/.local/bin/uvx", "args": ["--from", "git+https://github.com/adhikasp/mcp-git-ingest", "mcp-git-ingest"] }

uvx直接从 Git 仓库安装并运行工具，--from指定来源，让 LLM 具备"读取任意代码仓库并理解其结构"的能力。

配置完成后立即验证

server.py末尾使用一句探测性提问来验证整条链路是否打通（server.py）：

prompt = "What tools do you have from MCP?" result = await agent.run(prompt) print(f"\nResult: {result}")

运行python server.py，如果返回各 MCP 服务器暴露的工具清单，说明客户端与所有服务器握手成功。这也是排查配置错误（路径、环境变量、服务未启动）最直接的手段。

mcp-use 核心 API：MCPClient 与 MCPAgent

整个应用建立在mcp-use的两个核心类之上（mcp_streamlit_app.py）：

from mcp_use import MCPAgent, MCPClient # 1. 从配置字典构建客户端 client = MCPClient.from_dict(config_dict) # 2. 绑定 LLM 与客户端，创建 Agent llm = ChatOpenAI(model="gpt-4o") agent = MCPAgent(llm=llm, client=client, max_steps=100)

• MCPClient.from_dict()接受符合 MCP 规范的{"mcpServers": {...}}结构，自动为每个 server 创建子进程并通过 stdio 通信，屏蔽了底层进程管理细节；
• MCPAgent是推理循环的载体：它把各服务器暴露的 MCP 工具聚合为 LLM 可调用的工具集，max_steps=100限制了单轮任务内最多执行的推理-调用轮数，防止工具循环失控；
• LLM 通过 LangChain 统一接口注入，ChatOpenAI(model="gpt-4o")是默认选择，代码中同时保留了本地模型注释：# llm = ChatOllama(model="qwen3:1.7b")，切换注释即可在云端模型与本地 Ollama 模型之间切换（这就是 README 中 "100% local" 的由来）。

查询执行则是一条异步方法：

async def run_agent_query(agent, query): result = await agent.run(query) return result

agent.run()内部完成"理解用户请求 → 挑选 MCP 工具 → 调用并观察结果 → 生成最终答复"的完整 Agent 循环。

Streamlit 界面：从配置到聊天的完整交互流

mcp_streamlit_app.py 是完整的可运行前端，交互流程与 README 的 Usage 章节一一对应。

会话状态管理

应用用st.session_state保存三样关键状态（源码 L29-L41）：messages（聊天记录）、mcp_client（已构建的 MCP 客户端）、agent（已构建的 Agent）。reset_chat()一键清空三者，实现"清空聊天与配置"。

侧边栏三步走

1. 输入 JSON 配置：st.text_area提供一个预填 Stagehand 示例的文本框，高度 400px（源码 L85-L101）；
2. Load Example Config：点击后以编程方式注入一份包含 stagehand、firecrawl、ragie 三件套的示例配置（源码 L104-L133），并复用.env中的真实 Key：

{ "mcpServers": { "stagehand": { "command": "node", "args": ["/path/to/mcp-server-browserbase/stagehand/dist/index.js"], "env": { "OPENAI_API_KEY": "your-api-key", "LOCAL_CDP_URL": "http://localhost:9222", "DOWNLOADS_DIR": "/path/to/downloads/stagehand" } }, "mcp-server-firecrawl": { "command": "npx", "args": ["-y", "firecrawl-mcp"], "env": { "FIRECRAWL_API_KEY": "your-firecrawl-key" } }, "ragie": { "command": "npx", "args": ["-y", "@ragieai/mcp-server", "--partition", "default"], "env": { "RAGIE_API_KEY": "your-ragie-api-key" } } } }

3. Activate Configuration：点击后依次执行（源码 L142-L176）：

• json.loads()校验 JSON 合法性，非法时提示 "Invalid JSON configuration"；
• create_mcp_client()调用MCPClient.from_dict()启动所有 MCP 服务器子进程；
• create_agent()绑定 LLM 与 Agent；
• 成功后以st.info列出已注册的服务器名，并在底部 Status 区域显示两条绿色状态：✅ MCP Client Active与✅ Agent Ready。

这个"JSON 即配置"的设计意味着：无需改代码即可动态增删 MCP 服务器，新增一个工具只需要在文本框里追加一段 server 配置。

聊天主界面

聊天区采用标准的 Streamlit chat 组件（源码 L196-L227）：

• 历史消息通过st.chat_message(role)循环渲染；
• st.chat_input("Ask about your MCP tools...")获取用户输入；
• 若 Agent 未激活，提示 "Please activate the MCP configuration first!"；
• 已激活时，使用asyncio.new_event_loop()+loop.run_until_complete()在 Streamlit 的同步环境中驱动异步的agent.run()（Streamlit 脚本模型不原生支持 async，因此显式创建事件循环执行协程），结果以 markdown 渲染并追加进消息历史。

你可以这样提问：问"你现在有哪些工具"让 Agent 汇报工具清单；让它"抓取某网页并总结"（Firecrawl）；"打开某网站完成搜索"（Stagehand）；"从文档库检索 X 相关的资料"（Ragie）；或者结合记忆服务器追问"上次我们讨论过什么"。

启动与运行

依赖安装完毕、.env与server.py中的路径就绪后，运行（README 第 32-35 行）：

streamlit run mcp_streamlit_app.py

浏览器会自动打开 Streamlit 服务（默认http://localhost:8501）。注意 README 的 Setup 第 3 步特别强调："Go to server.py and update the paths to the MCP servers according to your system"——/path/to/...占位符必须替换为你的实际路径（Stagehand 脚本位置、Graphiti 源码目录、uv/uvx 二进制路径等），否则激活配置时子进程会启动失败。

注意事项与常见问题

• 路径必须真实：所有command/args中的占位路径都要指向本机真实存在的位置；Graphiti 依赖的 Neo4j 需先在本机localhost:7687启动并设置好账号密码；
• API Key 缺失：Firecrawl / Ragie / OpenAI 对应的 Key 未配置时，对应 server 的 env 会注入空值，工具调用将返回鉴权错误，请先检查.env；
• 模型选择：默认走gpt-4o（云端）；追求完全本地化时，将 server.py 与 mcp_streamlit_app.py 中ChatOpenAI的赋值切换为ChatOllama(model="qwen3:1.7b")之类的本地模型，并保证 Ollama 服务已启动；
• 首次启动耗时：npx -y型服务器首次调用需要下载对应 npm 包，请耐心等待并保持网络可用；
• 浏览器自动化前提：Stagehand 需要可用的 Chrome 实例与LOCAL_CDP_URL指向的调试端口。

小结

ultimate-ai-assitant-using-mcp展示了 MCP 时代构建"工具聚合型 AI 助手"的极简范式：一份 JSON 配置声明服务器，mcp-use负责连接与编排，Streamlit 提供对话外壳，LLM 负责理解与调度。从 server.py 的六服务器完整配置，到 mcp_streamlit_app.py 的可视化界面，本文已覆盖安装、配置、激活、对话与排错的全部环节；在此骨架之上，你只需在配置 JSON 中追加新的 server 条目，就能把任意 MCP 工具纳入你的"终极 AI 助手"。

【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub