mcp-use：让 AI Agent 真正睁开眼看世界

图1：mcp-use 官方 Logo

你是否有这样的经历：让 AI 写了一段数据分析代码，但 AI 不知道你本地有什么数据文件；让 AI 查询库存，它却只能假装查数据？这种 AI 与现实世界的割裂感，正是 MCP（Model Context Protocol） 要解决的问题——而 mcp-use 正是目前 TypeScript 生态中体验最友好的 MCP 框架。

一、被归档的 TypeScript 先行者：项目起源与现状

mcp-use/mcp-use-ts 仓库于 2025 年 5 月 21 日被官方归档（archive），转为只读状态。归档的原因并不是项目失败，而是团队将所有开发资源合并到了新的 monorepo 仓库 mcp-use/mcp-use，支持 TypeScript 和 Python 双语言 SDK。这意味着当前分析的 ts 仓库更多是历史版本，但其核心架构设计完整保留了下来，理解它依然有助于掌握 mcp-use 的设计哲学。

mcp-use 由 Manufact 团队维护，定位为 DX 最好的 MCP 框架（Best DX = Developer Experience）。Discord 社区活跃，提供了完整的文档、示例和在线 Inspector 工具。2024 年底 MCP 协议正式发布后，该项目迅速跟进，是最早一批提供 LangChain.js 集成的 MCP 客户端库之一。

二、MCP 协议是什么？先上一节科普课

Model Context Protocol（MCP） 可以理解为 AI 领域的 USB-C 接口：在 USB-C 出现之前，每种设备都需要自己的专用线缆和适配器；MCP 出现之前，每个 AI Agent 要接入外部工具（如访问文件系统、调用 API）都需要单独写适配代码，碎片化严重。MCP 定义了统一的标准，让任何支持 MCP 的 AI Agent 可以无缝调用任何 MCP Server 提供的工具和数据。

打个比方：如果把 AI Agent 比作一位专业医生，MCP 就是它随身携带的万能诊室——医生不需要自己带全套设备，只需要插入符合标准的模块，就能使用血糖仪、心电图机、化验系统等所有设备。MCP 生态已经有 GitHub、AWS、ClickHouse 等主流平台的 MCP Server 加入。

三、mcp-use 的核心能力：四个子包的协同生态

mcp-use-ts 是一个 pnpm monorepo，包含四个核心子包，协同提供完整能力：

1. mcp-use（核心包）

这是整个框架的心脏，提供两套核心 API：

MCP Client（连接端）：基于 LangChain.js 的适配层，MCPAgent 和 MCPClient 类让开发者用几行 TypeScript 就能把任何 LangChain.js 支持的 LLM（如 GPT-4、Claude、Gemini）连接到 MCP Server 池。关键特性包括：

• 动态 Server 选择：Agent 在运行时根据任务需求自动选择最合适的 MCP Server，不需要硬编码
• 多 Server 并行：一个 Agent 可以同时连接多个 MCP Server，取各家之长
• 工具白名单/黑名单：内置安全机制，可以限制 Agent 访问危险的系统级工具（如文件系统写入、网络请求）
• Langfuse 可观测性：无缝集成 Langfuse 监控，跟踪 Agent 的思维链路和工具调用情况

MCP Server（服务端）：除了作为客户端，mcp-use 也能让你快速构建自己的 MCP Server，定义工具、资源和 Prompt，用 Zod 做 schema 校验，代码简洁直观。

2. @mcp-use/cli（构建工具）

开发 MCP Server 的瑞士军刀。它提供：

• 热重载开发模式：修改代码后 MCP Server 自动重启，UI 组件即时刷新
• 内置 Inspector 集成：开发服务器启动时自动在浏览器打开 Inspector
• Widget 编译：将 React 组件编译为独立 HTML 页面，作为 MCP Server 的 UI 界面返回给 AI

这一套开发-调试-预览闭环，极大降低了 MCP Server 的开发门槛。

3. @mcp-use/inspector（调试工具）

MCP 界的 Swagger UI。这是一个 Web 应用，提供：

• 多连接管理：同时连接多个 MCP Server，统一管理
• 工具交互测试：实时执行工具调用，查看返回结果，无需写测试代码
• OAuth 流程支持：内置 OAuth 认证处理，对接需要授权的 MCP Server
• 实时状态监控：连接状态、错误日志、服务健康度一目了然

对于 MCP 生态的新手来说，Inspector 是最好的学习工具——不需要理解任何代码，直接在 UI 上探索每个 MCP Server 能做什么。

4. create-mcp-use-app（脚手架工具）

一行命令生成完整 MCP 应用：

npx create-mcp-use-app my-mcp-server
cd my-mcp-server
npm run dev

创建后的项目包含 TypeScript 配置、热重载脚本、预置的 Inspector 路由，所有最佳实践开箱即用。

四、技术架构：从零设计的模块化体系

mcp-use-ts 采用 pnpm workspace monorepo 架构，根目录 package.json 统一管理构建脚本和依赖版本。子包之间通过 workspace 协议互相引用，保证源码级别的版本一致性。

构建工具使用 tsup（基于 esbuild + Rollup），而非传统的 tsc + webpack 组合，这使得打包速度极快（秒级）。类型系统使用 TypeScript 5.x 配合 ESLint 9 + TypeScript ESLint Plugin，代码风格检查严格执行，commit 前自动 lint。

LangChain.js 是 mcp-use 的核心依赖，充当 LLM 和工具层之间的桥梁。LangChain.js 负责处理工具调用的序列化、ReAct 推理循环、Token 预算管理；mcp-use 则负责 MCP 协议的适配层，将 LangChain.js 的 tool-calling 能力桥接到 MCP 生态。

五、上手体验：从安装到第一个 Agent

前置要求：Node.js >= 22.0.0（注意不是 18，这是较高的版本要求），推荐 pnpm 作为包管理器。

安装成本：纯 npm 安装，无 Dockerfile，不支持容器化一键部署。对于个人开发者和小型团队来说这不是问题（npm install mcp-use 即可），但对于需要在服务器环境统一部署多个 MCP 应用的 DevOps 场景，目前缺乏开箱即用的容器化支持，需要自己编写 Dockerfile。

上手难度：对于熟悉 TypeScript 和 LangChain.js 的开发者，5 分钟内可以跑通第一个示例。官方 Quick Start 非常清晰，从安装到运行第一个 Agent 只需 6 步。对于 AI 爱好者而言，门槛比直接写 LangChain Expression Language (LEAL) 低很多——mcp-use 屏蔽了底层复杂性，暴露的是直觉化的 API。

Web UI 支持：框架内置 Inspector UI（监听 /inspector 路由），这是框架自带的 Web 界面，不需要额外安装任何 UI 库。

六、局限与挑战：不回避的问题

1. TypeScript only：该仓库是纯 TypeScript 项目，Python 开发者需要使用 monorepo 中的 Python SDK（pip install mcp_use）。两个 SDK 能力不完全对称，Python 版本可能缺少部分 TypeScript 特有功能（如 React hooks）。

2. 容器化缺失：没有 Dockerfile 或 docker-compose.yml，团队 DevOps 场景需要自行处理容器化。对于想快速在云服务器上部署 MCP Server 的用户，这增加了一定的工作量。

3. 已归档现状：mcp-use-ts 仓库已被归档，后续更新在 monorepo 中进行。这意味着新的 issues/PRs 不会被处理，使用者需要切换到新的 monorepo 仓库追踪开发动态。

4. MCP 协议年轻：MCP 协议本身在 2024 年底才发布，生态尚在快速演进中，API 可能在未来版本中发生变化。mcp-use 作为早期跟进者，架构设计考虑了可扩展性，但短期内的 breaking changes 风险需要评估。

七、行业意义：站在 MCP 浪潮的潮头

mcp-use 的出现反映了一个更大的趋势：AI Agent 从对话助手向执行者的转变。仅仅能生成文字的 AI 已经不够用了，市场需要 AI 能够真实地操作工具、访问数据、完成任务。MCP 作为 Anthropic 官方背书的协议，已经吸引了 GitHub、AWS、ClickHouse 等主流平台加入，形成了良性生态。

mcp-use 的价值在于：它不仅连接 Agent 和 Server，还提供了完整的开发工具链（Inspector + CLI + 脚手架），降低了整个 MCP 生态的入场门槛。这与 Vercel 对 Next.js 的生态建设思路类似——好的框架不仅要让代码跑起来，还要让开发者用得舒服。

从增长角度看，随着更多企业将 MCP Server 集成到内部系统（如飞书、钉钉、Salesforce），能够快速构建和调试 MCP Server 的开发者需求将持续增长。mcp-use 的工具链设计恰好填补了这一空白。

八、总结：一句话定位

mcp-use 是 TypeScript 生态中 DX 最好的 MCP 框架，适合想快速将 AI Agent 接入真实世界的开发者。它用 LangChain.js 作为推理引擎，用 Inspector 作为调试工具，用 CLI 作为开发加速器，组成了一套完整但不失简洁的 MCP 开发工具链。虽然容器化支持缺失，但 NPM 包分发的轻量化特性反而适合大多数个人和小团队使用场景。

推荐人群：有 LangChain.js 基础的 AI 应用开发者、需要快速构建 MCP Server 的全栈工程师、对 AI Agent 可观测性有需求的团队。

非推荐人群：需要 Python-only 方案的团队（改用 monorepo 的 Python SDK）、追求生产级容器化部署的 DevOps 团队。

---

本文基于已归档的 mcp-use/mcp-use-ts（v1.x）分析。最新开发已迁移至 mcp-use/mcp-use monorepo，支持 TypeScript + Python 双 SDK。