# https://github.com/mcp-use/mcp-use 项目说明书

生成时间：2026-06-13 15:45:58 UTC

## 目录

- [项目概览与快速入门](#page-overview)
- [MCP Server 与 MCP Apps 开发](#page-server-apps)
- [客户端、AI Agent 与 Inspector](#page-client-agent)
- [架构、可扩展性与运维](#page-architecture-ops)

<a id='page-overview'></a>

## 项目概览与快速入门

### 相关页面

相关主题：[MCP Server 与 MCP Apps 开发](#page-server-apps), [客户端、AI Agent 与 Inspector](#page-client-agent)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/mcp-use/mcp-use/blob/main/README.md)
- [libraries/python/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/python/README.md)
- [libraries/typescript/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/README.md)
- [libraries/typescript/packages/mcp-use/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/README.md)
- [libraries/typescript/packages/cli/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/cli/README.md)
- [libraries/typescript/packages/inspector/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/inspector/README.md)
- [libraries/typescript/packages/create-mcp-use-app/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/create-mcp-use-app/README.md)
- [libraries/typescript/packages/create-mcp-use-app/src/templates/starter/index.ts](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/create-mcp-use-app/src/templates/starter/index.ts)
- [libraries/typescript/packages/mcp-use/examples/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/examples/README.md)
- [libraries/typescript/packages/mcp-use/examples/server/features/elicitation/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/examples/server/features/elicitation/README.md)
- [examples/README.md](https://github.com/mcp-use/mcp-use/blob/main/examples/README.md)
</details>

# 项目概览与快速入门

## 项目定位与核心能力

`mcp-use` 是面向 **Model Context Protocol（MCP）** 的全栈框架，同时提供 **Python** 与 **TypeScript** 双实现，目标是让开发者用最少的代码将 LLM 与工具、资源、交互式界面连接起来。框架围绕两个核心角色展开：

- **Agent / Client**：能调用任意 MCP 服务的 AI 智能体，支持多步推理与工具选择。
- **Server**：暴露工具（tool）、资源（resource）、提示（prompt）以及可嵌入 LLM 客户端的交互式 Widget（也称 MCP Apps）。

资料来源：[README.md](https://github.com/mcp-use/mcp-use/blob/main/README.md)

在 TypeScript 端，`mcp-use` 强调 "**Write once, run everywhere**" 的 MCP Apps 理念——同一个 React Widget 可在 Claude、ChatGPT 等多种客户端渲染。Python 端则通过 LangChain 集成任意支持工具调用的 LLM（OpenAI、Anthropic、Groq 等）。资料来源：[libraries/typescript/packages/mcp-use/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/README.md)、[libraries/python/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/python/README.md)

## 生态系统与包结构

`mcp-use` 采用 monorepo 布局，TypeScript 端拆分为多个职责单一的 npm 包：

| 包名 | 职责 | 关键能力 |
|------|------|----------|
| `mcp-use` | 核心框架 | Server/Client/Agent API、Widget SDK（`mcp-use/react`）、Elicitation |
| `@mcp-use/cli` | 构建与开发工具 | `dev`/`build`/`start`/`deploy` 命令、热重载、Inspector 自动挂载 |
| `@mcp-use/inspector` | 浏览器调试器 | 工具浏览、资源浏览、Prompt 管理、BYOK Chat、Widget 预览 |
| `create-mcp-use-app` | 项目脚手架 | 交互式创建新项目，支持内置与 GitHub 仓库模板 |

资料来源：[libraries/typescript/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/README.md)、[libraries/typescript/packages/cli/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/cli/README.md)、[libraries/typescript/packages/inspector/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/inspector/README.md)

下图为整体架构关系：

```mermaid
graph LR
  User[开发者] --> Scaff[create-mcp-use-app]
  Scaff --> Server[TS MCP Server<br/>mcp-use]
  Server --> CLI[mcp-use dev/build]
  Server --> Widgets[resources/*.tsx<br/>MCP Apps]
  Server --> Inspector[mcp-use/inspector]
  Agent[Python MCPAgent] --> Tools[远端 MCP Servers]
  Widgets --> Claude[Claude / ChatGPT]
  Inspector -.调试.-> Server
```

## 快速入门

### TypeScript：30 秒创建 MCP Server

最简方式是通过脚手架生成完整项目：

```bash
npx create-mcp-use-app@latest my-server
cd my-server
npm run dev
```

脚手架会预置 `src/index.ts`、`resources/` 目录、`.env.example` 以及包含 `dev`、`build`、`start`、`deploy` 的 npm 脚本，并默认打开 `http://localhost:3000/inspector`。资料来源：[libraries/typescript/packages/create-mcp-use-app/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/create-mcp-use-app/README.md)

若希望手工搭建，核心只需几行代码：

```typescript
import { MCPServer, text } from "mcp-use/server";
import { z } from "zod";

const server = new MCPServer({ name: "my-server", version: "1.0.0" });

server.tool({
  name: "get_weather",
  description: "Get weather for a city",
  schema: z.object({ city: z.string() }),
}, async ({ city }) => text(`Temperature: 72°F, City: ${city}`));

await server.listen(3000);
```

资料来源：[libraries/typescript/packages/create-mcp-use-app/src/templates/starter/index.ts](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/create-mcp-use-app/src/templates/starter/index.ts)

### Python：6 行代码启动 Agent

Python 端的入口是 `MCPAgent` + `MCPClient`：

```bash
pip install mcp-use langchain-openai
```

```python
import asyncio
from langchain_openai import ChatOpenAI
from mcp_use import MCPAgent, MCPClient

async def main():
    client = MCPClient.from_config_file("mcp-config.json")
    agent = MCPAgent(llm=ChatOpenAI(model="gpt-4o"), client=client)
    result = await agent.run("Find the latest news about MCP")
    print(result)

asyncio.run(main())
```

注意：所选 LLM **必须**支持工具调用（tool calling / function calling），并且需要单独安装对应 LangChain provider 包并配置 `OPENAI_API_KEY` 等环境变量。资料来源：[libraries/python/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/python/README.md)

### CLI 常用命令

`@mcp-use/cli` 提供与 `mcp-use` 同名的本地命令：

| 命令 | 作用 | 关键选项 |
|------|------|----------|
| `mcp-use dev` | 监听 TS 变更、热重载、启动 Inspector | `-p <path>`、`--port <port>`、`--no-open` |
| `mcp-use build` | 生产构建，hash 化静态资源 | — |
| `mcp-use start` | 启动已构建的服务 | — |
| `mcp-use deploy` | 部署到托管平台 | — |

资料来源：[libraries/typescript/packages/cli/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/cli/README.md)

## 关键特性与社区关注点

### MCP Apps（交互式 Widget）

将 `*.tsx` 放入 `resources/` 即可被自动注册为可被 LLM 调用的 Widget。组件通过 `useWidget<Props>()` 拿到 schema 校验后的 props、主题、工具输入与输出，并可在 Claude、ChatGPT 等客户端中复用同一份实现。资料来源：[libraries/typescript/packages/mcp-use/examples/server/ui/mcp-apps/apps-sdk/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/examples/server/ui/mcp-apps/apps-sdk/README.md)

### Elicitation（结构化用户输入）

`ctx.elicit(message, zodSchema)` 提供 Zod 校验、表单模式与 URL 模式两种用法，可安全收集配置或引导用户完成 OAuth。资料来源：[libraries/typescript/packages/mcp-use/examples/server/features/elicitation/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/examples/server/features/elicitation/README.md)

### 社区已知的坑与改进

- **空 `resources/` 目录日志混乱**（[#1727](https://github.com/mcp-use/mcp-use/issues/1727)）：未使用 Widget 的项目在 `mcp-use dev` 时仍会触发挂载流程。
- **StreamableHTTP 有状态传输在 `mcp-use dev` 中挂起**（[#1724](https://github.com/mcp-use/mcp-use/issues/1724)）：SSE 响应被丢弃，启用 `enableJsonResponse` 可绕过。
- **`@mcp-use/inspector` 拖入 LangChain 硬依赖**（[#1371](https://github.com/mcp-use/mcp-use/issues/1371)）：影响 Next.js 等对依赖敏感的打包器。
- **适配器代码重复**（[#1726](https://github.com/mcp-use/mcp-use/issues/1726)）：Anthropic / OpenAI / Google 三家 Adapter 存在复制粘贴的工具名 sanitize 与 prompt schema 逻辑，等待抽象复用。
- **OAuth 元数据发现修复**（v1.32.1-canary.2）：对带路径后缀的 issuer 正确构造 RFC 8414 元数据 URL。

### 调试与示例

- 浏览器调试：[inspector.mcp-use.com](https://inspector.mcp-use.com/inspector) 或 `npx @mcp-use/inspector`。资料来源：[libraries/typescript/packages/inspector/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/inspector/README.md)
- 一键部署模板：Chart Builder、Diagram Builder、Slide Deck、Maps Explorer、Widget Gallery 等独立仓库。
- 仓库内代码示例：`libraries/python/examples/` 与 `libraries/typescript/packages/mcp-use/examples/`。资料来源：[examples/README.md](https://github.com/mcp-use/mcp-use/blob/main/examples/README.md)

---

## See Also

- [TypeScript Server 文档](https://mcp-use.com/docs/typescript/server)
- [Python Quickstart](https://mcp-use.com/docs/python/getting-started/quickstart)
- [@mcp-use/cli 参考](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/cli/README.md)
- [@mcp-use/inspector 参考](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/inspector/README.md)

---

<a id='page-server-apps'></a>

## MCP Server 与 MCP Apps 开发

### 相关页面

相关主题：[项目概览与快速入门](#page-overview), [架构、可扩展性与运维](#page-architecture-ops)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [libraries/typescript/packages/mcp-use/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/README.md)
- [libraries/typescript/packages/mcp-use/src/server/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/server/README.md)
- [libraries/typescript/packages/create-mcp-use-app/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/create-mcp-use-app/README.md)
- [libraries/typescript/packages/create-mcp-use-app/package.json](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/create-mcp-use-app/package.json)
- [libraries/typescript/packages/create-mcp-use-app/src/templates/starter/package.json](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/create-mcp-use-app/src/templates/starter/package.json)
- [libraries/typescript/packages/cli/package.json](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/cli/package.json)
- [libraries/typescript/packages/inspector/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/inspector/README.md)
- [libraries/typescript/packages/mcp-use/examples/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/examples/README.md)
- [libraries/typescript/packages/mcp-use/examples/server/features/elicitation/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/examples/server/features/elicitation/README.md)
- [examples/README.md](https://github.com/mcp-use/mcp-use/blob/main/examples/README.md)
- [libraries/typescript/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/README.md)
- [libraries/python/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/python/README.md)
</details>

# MCP Server 与 MCP Apps 开发

## 一、概述

`mcp-use` 是一个面向 [Model Context Protocol（MCP）](https://modelcontextprotocol.io) 的全栈开发框架，覆盖 **Server、Client、Agent、Inspector、CLI** 五大组件。项目以 TypeScript 与 Python 双语言并行发布，分别位于 `libraries/typescript/` 与 `libraries/python/` 目录下；其中 TypeScript 端侧重于 **MCP Server 与 MCP Apps（带交互式 UI 的 MCP 应用）** 的构建与部署，Python 端侧重于 **Agent / Client** 侧的 LLM 工具调用。

> MCP Apps 的核心卖点是"**一次编写，多端运行**"——同一份 Widget 代码可以在 Claude、ChatGPT 等不同 MCP 客户端中直接渲染，避免重复适配。资料来源：[libraries/typescript/packages/mcp-use/README.md:1-15]()

### 生态包一览

| 包名 | 角色 | 关键能力 |
| --- | --- | --- |
| `mcp-use` | 核心框架 | Server/Client/Agent/Auth/Adapters 多入口导出 |
| `@mcp-use/cli` | 构建工具 | `mcp-use dev` / `build` / `start` / `deploy` 子命令 |
| `@mcp-use/inspector` | Web 调试器 | 内嵌 Inspector UI，支持 OAuth 与多传输 |
| `create-mcp-use-app` | 脚手架 | 基于模板一键创建 MCP 项目 |

资料来源：[libraries/typescript/README.md:15-30]()、[libraries/typescript/packages/mcp-use/package.json:1-50]()、[libraries/typescript/packages/cli/package.json:1-30]()

---

## 二、项目脚手架与目录结构

### 2.1 快速创建项目

使用 `create-mcp-use-app` 可以在一条命令内拉起一个完整 MCP Server + MCP Apps 项目：

```bash
# 交互式创建
npx create-mcp-use-app@latest

# 直接指定模板
npx create-mcp-use-app my-project --template owner/repo
npx create-mcp-use-app my-project --template https://github.com/owner/repo#branch
```

模板来源支持 **本地预置模板** 与 **任意 GitHub 仓库**（短格式或完整 URL）；后者需要本地已安装 `git`。资料来源：[libraries/typescript/packages/create-mcp-use-app/README.md:1-25]()

### 2.2 脚手架生成的关键依赖

`starter` 模板（位于 [`libraries/typescript/packages/create-mcp-use-app/src/templates/starter/package.json`](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/create-mcp-use-app/src/templates/starter/package.json)）预设了以下依赖：

- **运行时**：`mcp-use`、`react@^19.2.4`、`react-dom`、`react-router`、`tailwindcss@^4.2.0`、`zod@4.3.5`
- **开发工具**：`tsx`、`typescript@^5.9.3`、`@types/node`
- **生命周期脚本**：`postinstall` 自动调用 `mcp-use generate-types`，让用户在编辑器内立即获得完整类型推断

模板自带 `dev` / `build` / `start` / `deploy` 四个 npm scripts，分别对应 CLI 的四个核心子命令。资料来源：[libraries/typescript/packages/create-mcp-use-app/src/templates/starter/package.json:15-40]()

### 2.3 工作流示意

```mermaid
flowchart LR
    A[npx create-mcp-use-app] --> B[脚手架项目]
    B --> C{选择模板}
    C -->|starter| D[基础 MCP Server]
    C -->|GitHub 仓库| E[自定义模板]
    B --> F[npm install]
    F --> G[mcp-use generate-types]
    G --> H[mcp-use dev]
    H --> I[Inspector UI]
    H --> J[StreamableHTTP 服务]
    I --> K[Claude / ChatGPT 客户端]
    J --> K
```

---

## 三、MCP Server 核心开发

### 3.1 最小可运行 Server

```typescript
import { MCPServer, text } from "mcp-use/server";
import { z } from "zod";

const server = new MCPServer({
  name: "my-server",
  version: "1.0.0",
});

server.tool({
  name: "get_weather",
  description: "Get weather for a city",
  schema: z.object({ city: z.string() }),
}, async ({ city }) => {
  return text(`Temperature: 72°F, Condition: sunny, City: ${city}`);
});

await server.listen(3000);
// Inspector 自动挂在 http://localhost:3000/inspector
```

资料来源：[libraries/typescript/packages/mcp-use/README.md:30-50]()

### 3.2 三大原语（Primitives）

`mcp-use` 把 MCP 规范中的三大原语都封装成了高阶函数：

- `server.tool({...}, callback)`：工具，签名内嵌 Zod schema，输出走 `text()` / `image()` / `resource()` 等辅助函数。
- `server.resource({...})`：资源，用 URI 标识，支持 `readCallback` 与 `mimeType`。
- `server.prompt({...})`：提示模板，参数化复用。
- `server.resourceTemplate({...})`：参数化资源 URI 模板。

资料来源：[libraries/typescript/packages/mcp-use/src/server/README.md:1-40]()

### 3.3 高阶能力：Elicitation / Sampling / Notifications

`mcp-use/examples/server/features/` 下提供了大量参考实现，涵盖：

| 特性 | 示例路径 | 用途 |
| --- | --- | --- |
| Elicitation | `examples/server/features/elicitation/` | 表单 / URL 两种收集用户输入的模式 |
| Sampling | `examples/server/features/sampling/` | 由服务端主动发起 LLM 采样 |
| Notifications | `examples/server/features/notifications/` | 服务端 ↔ 客户端双向通知 |
| Streaming Props | `examples/server/features/streaming-props/` | 流式输出 → Widget props |
| Middleware | `examples/server/features/middleware/` | 内置中间件管线 |
| Proxy | `examples/server/features/proxy/` | 代理其他 MCP Server |
| OpenAPI | `examples/server/features/openapi/` | 从 OpenAPI 规范生成工具 |

资料来源：[libraries/typescript/packages/mcp-use/examples/README.md:15-60]()

以 **Elicitation** 为例，TypeScript API 提供了强类型推断：

```typescript
const result = await ctx.elicit(
  "Please provide your info",
  z.object({
    name: z.string().default("Anonymous"),
    age: z.number().min(0).max(150),
  })
);
// result.data 类型为 { name: string; age: number }
```

URL 模式（用于 OAuth、API key 等敏感场景）只需把第二个参数改为字符串 URL 即可。资料来源：[libraries/typescript/packages/mcp-use/examples/server/features/elicitation/README.md:1-50]()

---

## 四、MCP Apps 与 Widgets 开发

### 4.1 概念

MCP Apps 是把 **MCP Tool 输出 + 交互式 UI** 组合成"应用"形态的标准。当 Tool 返回的是 `UIResource` 时，客户端会把它渲染为 Widget —— 这正是 ChatGPT Apps 与 Claude Apps 的底层机理。

### 4.2 资源目录约定

CLI 在 `mcp-use dev` 启动时会执行 **Widget 挂载管线**：扫描 `resources/` 目录，自动打包并暴露给 Inspector 与远程客户端。**如果项目未使用 Widget**，CLI 仍会跑一遍管线并输出：

```
[WIDGETS] Mounting widgets in development mode
[WIDGETS] No resources/ directory found - creating it for widget walking
```

社区反馈（[issue #1727](https://github.com/mcp-use/mcp-use/issues/1727)）认为该日志在"完全不用 Widget"的场景下具有误导性 —— 当前版本会在没有 `resources/` 时自动建一个空目录，导致日志与意图不一致。后续版本计划通过新增 `--no-widgets` 标志或在 `mcp-use.config.ts` 里显式禁用管线来抑制输出。

### 4.3 流式 Widget props

针对 **Tool 输出 → Widget props** 的流式传输，社区已有明确诉求（[issue #1296](https://github.com/mcp-use/mcp-use/issues/1296)）：当前 SDK 仅支持"模型 token → 工具输入"的方向；将工具执行结果流式灌入 Widget 仍在路线图内。可参考的参考实现是 [`examples/server/features/streaming-props/`](https://github.com/mcp-use/mcp-use/tree/main/libraries/typescript/packages/mcp-use/examples/server/features/streaming-props)。

### 4.4 适配器层

Python 端的 `AnthropicMCPAdapter` / `OpenAIMCPAdapter` / `GoogleMCPAdapter` 都包含重复的 `_sanitize_for_tool_name` 与 `_convert_prompt` 代码，社区已在 [issue #1726](https://github.com/mcp-use/mcp-use/issues/1726) 提议抽公共基类。TypeScript 端则把多 LLM 适配放在 `mcp-use/adapters` 子入口导出。

---

## 五、调试、部署与已知陷阱

### 5.1 Inspector 与 OAuth

`@mcp-use/inspector` 同时提供 **客户端（Vite dev）** 与 **服务端（Express）** 双入口；OAuth 流程目前已支持 RFC 8414 `/.well-known/oauth-authorization-server` 路由，修复了 issuer 路径后缀场景下的元数据发现（[release 1.32.1-canary.2](https://github.com/mcp-use/mcp-use/releases/tag/mcp-use%401.32.1-canary.2)）。但错误回跳仍存在问题：OAuth 授权失败时，Inspector 会直接渲染原始错误页而不是回到原页面（[issue #1362](https://github.com/mcp-use/mcp-use/issues/1362)）。

### 5.2 传输层陷阱

Stateful `StreamableHTTP` 在 `mcp-use dev` 模式下偶尔会让 SSE 响应被丢弃，导致工具调用挂起；临时绕过办法是开启 `enableJsonResponse`，详见 [issue #1724](https://github.com/mcp-use/mcp-use/issues/1724)。

### 5.3 依赖面收窄

历史版本（1.24.1）中 `@mcp-use/inspector@2.1.0` 会把 `@langchain/*` 系列作为硬依赖带入，破坏 Next.js 等打包器（[issue #1371](https://github.com/mcp-use/mcp-use/issues/1371)）。当前版本（`mcp-use@1.32.x` + `@mcp-use/inspector@10.x`）已不再把 langchain 作为 Server 端硬依赖；如需 Agent / 工具调用，再按需安装 `langchain-openai` / `langchain-anthropic`。资料来源：[libraries/python/README.md:40-65]()

### 5.4 CLI 资源订阅

`mcp-use resources subscribe` 在 `Ctrl+C` 退出时偶尔不发送 `unsubscribe` 帧，污染服务端会话表 —— 已在 [issue #1723](https://github.com/mcp-use/mcp-use/issues/1723) 中修复，建议升级到 `@mcp-use/cli@3.5.2-canary.2` 或更新版本。

### 5.5 服务器配置更新（v3.5.0 起）

CLI 自 `@mcp-use/cli@3.5.0` 起新增 `mcp-use servers update <id-or-slug>`，可在不删除重建的前提下修改生产分支、名称、构建/启动命令，并保留 URL slug 与环境变量；`--branch` 标志可锁定特定分支进行环境管理。资料来源：[release notes @mcp-use/cli@3.5.0](https://github.com/mcp-use/mcp-use/releases/tag/%40mcp-use/cli%403.5.0)

---

## 六、See Also

- [libraries/typescript/packages/mcp-use/src/server/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/server/README.md) — `MCPServer` 类的完整 API 文档
- [libraries/typescript/packages/mcp-use/examples/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/examples/README.md) — Server / Agent / Code Mode 全量示例索引
- [libraries/typescript/packages/inspector/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/inspector/README.md) — Inspector 自托管与使用指南
- [libraries/python/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/python/README.md) — Python 端 `MCPAgent` / `MCPClient` 快速上手
- [examples/README.md](https://github.com/mcp-use/mcp-use/blob/main/examples/README.md) — 可一键部署的 Templates 与仓库内示例的边界说明

---

<a id='page-client-agent'></a>

## 客户端、AI Agent 与 Inspector

### 相关页面

相关主题：[项目概览与快速入门](#page-overview), [MCP Server 与 MCP Apps 开发](#page-server-apps)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/mcp-use/mcp-use/blob/main/README.md)
- [libraries/python/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/python/README.md)
- [libraries/typescript/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/README.md)
- [libraries/typescript/packages/mcp-use/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/README.md)
- [libraries/typescript/packages/cli/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/cli/README.md)
- [libraries/typescript/packages/inspector/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/inspector/README.md)
- [libraries/typescript/packages/inspector/package.json](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/inspector/package.json)
- [libraries/typescript/packages/create-mcp-use-app/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/create-mcp-use-app/README.md)
- [libraries/typescript/packages/mcp-use/examples/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/examples/README.md)
- [libraries/typescript/packages/mcp-use/examples/server/ui/mcp-apps/apps-sdk/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/examples/server/ui/mcp-apps/apps-sdk/README.md)
</details>

# 客户端、AI Agent 与 Inspector

mcp-use 是一个面向 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 的全栈框架，提供 AI Agent 运行时、MCP 客户端/服务端开发框架以及配套的调试工具链。本页聚焦三类核心组件：**Python AI Agent / Client**、**TypeScript MCP Server / Apps**、以及 **@mcp-use/inspector** 调试器。

## 一、整体定位与生态构成

mcp-use 同时提供两条主线：Python 侧以 LangChain 为 LLM 适配层、面向 Agent 与客户端场景；TypeScript 侧则覆盖服务器开发、UI 部件（MCP Apps）以及 CLI/Inspector 工具链 资料来源：[README.md:1-40]()。

| 组件 | 语言/形态 | 主要职责 |
|------|-----------|----------|
| `mcp-use` (Python) | pip 包 | `MCPAgent` + `MCPClient`，驱动多步工具调用 资料来源：[libraries/python/README.md:1-30]() |
| `mcp-use` (TS) | npm 包 | `MCPServer` 框架 + MCP Apps（交互部件） 资料来源：[libraries/typescript/packages/mcp-use/README.md:1-40]() |
| `@mcp-use/cli` | npm 包 | 开发/构建/部署命令行（`dev`/`build`/`start`/`deploy`） 资料来源：[libraries/typescript/packages/cli/README.md:1-60]() |
| `@mcp-use/inspector` | npm 包 | Web 调试器，可在线、本地或随服务器挂载 资料来源：[libraries/typescript/packages/inspector/README.md:1-60]() |
| `create-mcp-use-app` | npm 包 | 项目脚手架，支持官方与 GitHub 模板 资料来源：[libraries/typescript/packages/create-mcp-use-app/README.md:1-40]() |

三者关系可以由下图概括：

```mermaid
flowchart LR
  User[开发者] --> CLI["@mcp-use/cli"]
  CLI --> Dev["开发模式 (dev)"]
  CLI --> Build["生产构建 (build)"]
  Dev --> Inspector["@mcp-use/inspector<br/>/inspector 端点"]
  Dev --> Server["MCPServer"]
  Server -->|MCP over HTTP/SSE| Agent["Python MCPAgent"]
  Agent -->|工具调用| Server
```

## 二、Python AI Agent 与 MCP Client

Python 包 `mcp-use` 提供了 AI Agent 与底层客户端两套入口。`MCPAgent` 负责多步推理并按需挑选工具，`MCPClient` 用于以编程方式直接连接一个或多个 MCP 服务器 资料来源：[libraries/python/README.md:1-30]()。

快速启动仅需六行核心代码：安装 `pip install mcp-use langchain-openai`，然后用配置字典描述 MCP 服务器即可。LLM 适配通过 LangChain 完成，因此任何支持工具调用的模型（OpenAI、Anthropic、Groq 等）都可接入 资料来源：[libraries/python/README.md:1-40]()。

Python 侧提供丰富的示例，覆盖从基础对话、代码模式（Code Mode，包括 E2B 沙箱）、结构化输出、流式中间步骤，到 Langfuse 可观测性集成等高级模式 资料来源：[libraries/typescript/packages/mcp-use/examples/README.md:1-40]()。运行要求为 Python 3.11+ 且 LLM 必须支持 function calling 资料来源：[libraries/python/README.md:1-60]()。

## 三、TypeScript Server、CLI 与 MCP Apps

TypeScript 侧的核心是 `MCPServer` 框架与 MCP Apps 部件体系。最小服务器示例只需导入 `MCPServer` 与 `text`，注册带 Zod schema 的工具，再调用 `server.listen(3000)` 即可暴露 `/mcp` 端点和 `/inspector` 调试页 资料来源：[libraries/typescript/packages/mcp-use/README.md:1-40]()。

**CLI 工作流**通过 `mcp-use dev` 一行命令即可启动开发服务器：TypeScript 进入 watch 模式、UI 部件启用热重载、服务端通过 `tsx` 自动重启、浏览器自动打开 `http://localhost:3000/inspector`。生产构建由 `mcp-use build` 完成，会编译 TypeScript 并把所有 `resources/` 下的 `.tsx` 部件打包为带哈希的静态资源 资料来源：[libraries/typescript/packages/cli/README.md:1-60]()。

**MCP Apps** 是 TypeScript 生态的差异化能力，允许构建跨 Claude、ChatGPT 等客户端复用的交互部件。示例 `apps-sdk` 演示了通过 `useWidget()` Hook 访问经过 Zod 校验的 `props` 与 `theme`，并在 `resources/` 目录下新增 `.tsx` 文件即自动注册 资料来源：[libraries/typescript/packages/mcp-use/examples/server/ui/mcp-apps/apps-sdk/README.md:1-60]()。官方还在 `model-context` 示例中演示 `ModelContext` / `modelContext` API，用于让部件感知 AI 模型状态 资料来源：[libraries/typescript/packages/mcp-use/examples/server/ui/model-context/package.json:1-30]()。

## 四、Inspector 调试能力与近期变化

`@mcp-use/inspector` 提供三种使用方式：访问在线版 `inspector.mcp-use.com`、本地 `npx @mcp-use/inspector` 启动（默认 `:8080`），或在 `mcp-use dev` 启动的服务器上通过 `/inspector` 自动挂载 资料来源：[libraries/typescript/packages/inspector/README.md:1-60]()。其主要面板包括 Tool Explorer、Resource Browser、Prompt Manager、BYOK Chat、Saved Tool Calls 与 Cmd+K 快捷键 资料来源：[libraries/typescript/packages/inspector/README.md:1-40]()。当前发布的 `@mcp-use/inspector` 10.0.x 已支持 MCP-UI 与 OpenAI Apps SDK 部件的调试 资料来源：[libraries/typescript/packages/inspector/package.json:1-30]()。

近期的客户端与 Agent 相关发布带来若干重要改进：

- **OAuth 元数据发现**：1.32.1-canary.2 修复了带路径后缀 issuer 的授权服务器发现（RFC 8414），并挂载规范的 `/.well-known/oauth-authorization-server{issuer-path}` 路由（#1576）。
- **OAuth token_endpoint 暴露**：1.32.0 将解析后的 `token_endpoint` 暴露在 `useMcp().authTokens` 与浏览器 Provider 的 `getTokenEndpoint()`，便于后端提前刷新令牌。
- **CLI 服务器管理**：`@mcp-use/cli` 3.5.0 新增 `servers update <id-or-slug>` 与分支级环境变量管理，可在不删除/重建的前提下更新生产分支、构建/启动命令等配置。
- **服务端通知日志**：1.32.1-canary.1 增加 outgoing notifications 的服务端日志，便于追踪会话级错误。

社区还反馈了几个值得关注的痛点：`@mcp-use/inspector` 早期版本曾把 LangChain 套件作为硬依赖引入，破坏 Next.js 等打包器（#1371）；Inspector 在 OAuth 错误（如 `access_denied`）时显示原始错误页而非回跳（#1362）；`mcp-use dev` 在有状态 StreamableHTTP 传输下偶发 SSE 响应被丢弃、导致工具调用挂起（#1724）；以及重复的 Provider 适配器代码（Anthropic / OpenAI / Google）正在被合并（#1726）。

## See Also

- [README.md](https://github.com/mcp-use/mcp-use/blob/main/README.md) — 仓库总览与快速开始
- [libraries/python/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/python/README.md) — Python Agent 与 Client
- [libraries/typescript/packages/cli/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/cli/README.md) — `mcp-use dev` / `build` CLI
- [libraries/typescript/packages/inspector/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/inspector/README.md) — Inspector 使用与自托管
- [官方文档](https://mcp-use.com/docs) — 完整 API 与教程

---

<a id='page-architecture-ops'></a>

## 架构、可扩展性与运维

### 相关页面

相关主题：[MCP Server 与 MCP Apps 开发](#page-server-apps), [客户端、AI Agent 与 Inspector](#page-client-agent)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [libraries/typescript/packages/mcp-use/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/README.md)
- [libraries/typescript/packages/cli/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/cli/README.md)
- [libraries/typescript/packages/inspector/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/inspector/README.md)
- [libraries/typescript/packages/create-mcp-use-app/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/create-mcp-use-app/README.md)
- [libraries/python/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/python/README.md)
- [libraries/typescript/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/README.md)
- [libraries/typescript/packages/mcp-use/examples/server/features/elicitation/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/examples/server/features/elicitation/README.md)
- [libraries/typescript/packages/mcp-use/examples/server/features/everything/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/examples/server/features/everything/README.md)
</details>

# 架构、可扩展性与运维

## 1. 概述与定位

`mcp-use` 是一个面向 **Model Context Protocol（MCP）** 的全栈框架，覆盖 **服务端（MCP Server / MCP Apps）** 与 **客户端/Agent（MCPClient、MCPAgent）** 两个角色。该仓库采用 monorepo 结构，分别在 `libraries/typescript/` 与 `libraries/python/` 下提供两套实现，二者共享同一套协议语义与开发心智模型。资料来源：[libraries/typescript/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/README.md)。

仓库顶层可划分为三类工件：

| 工件类型 | 说明 |
| --- | --- |
| 核心运行时 | `mcp-use`（服务端 + 客户端 SDK） |
| 工程化 CLI | `@mcp-use/cli`（dev / build / start / deploy） |
| 调试工具 | `@mcp-use/inspector`（Web 调试器） |
| 项目脚手架 | `create-mcp-use-app`（交互式/模板化项目初始化） |

整体定位可以理解为：**MCP 协议之上的"应用框架 + 工具链"**，让开发者可以同时构建带有富交互 Widget（MCP Apps）的服务端，以及能够消费任意 MCP 工具的 LLM Agent。

## 2. 运行时架构

### 2.1 服务端运行时

TypeScript 服务端通过 `MCPServer` 暴露符合 MCP 协议的端点，并原生支持三类核心能力：**Tools（工具）、Resources（资源）、Prompts（提示）**。在最新版本中，`MCPServer` 还封装了对 MCP Apps（UI Widgets）、Elicitation（`ctx.elicit` 表单 / URL 两种模式）以及 `modelContext` / `ModelContext` 状态管线的支持，使前端 React 组件可作为工具调用结果的一部分被返回。

```mermaid
flowchart LR
    A[LLM Agent / Inspector] -->|MCP over HTTP/SSE/StdIO| B[MCPServer]
    B --> T[Tools]
    B --> R[Resources]
    B --> P[Prompts]
    B --> W[Widgets / MCP Apps]
    B --> E[Elicitation ctx.elicit]
    W -->|React props| A
```

资料来源：[libraries/typescript/packages/mcp-use/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/README.md)、[libraries/typescript/packages/mcp-use/examples/server/features/elicitation/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/examples/server/features/elicitation/README.md)。

### 2.2 客户端与 Agent

Python 端通过 `MCPClient` 管理多服务器连接（HTTP、Stdio 等），并由 `MCPAgent` 在 LangChain 模型驱动下完成工具选择与多步推理。客户端侧的设计强调三点：**易用性（6 行代码起步）**、**LLM 灵活性（兼容任意支持 tool calling 的 LangChat 模型）** 与 **多服务器动态选择（Server Manager）**。资料来源：[libraries/python/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/python/README.md)。

## 3. 可扩展性机制

### 3.1 适配器层（Adapter）

在 Python 端，针对不同 LLM 提供方的 MCP 适配被抽象为独立的 `AnthropicMCPAdapter`、`OpenAIMCPAdapter`、`GoogleMCPAdapter` 等。当前社区已识别出明显的重复代码（`_sanitize_for_tool_name` 与 `_convert_prompt` 内部的 prompt-schema 构造循环），属于正在被推动的重构方向（issue #1726）。这一抽象层决定了：**当上游 LLM 协议变化时，只需调整对应适配器即可**。

### 3.2 连接器层（Connector）

传输层由 `HttpConnector`、`StdioConnector` 等连接器承载。根据 issue #947 的设计意图，连接器将进一步支持**每个连接器独立的回调、认证（`auth=...`）与中间件**，从而允许在同一 `MCPAgent` 中混合不同鉴权、不同中间件策略的 MCP 服务器。该模型对于**多租户场景**与**统一接入网关**尤为关键。

### 3.3 传输层（Transport）

在底层，连接器可选用 stdio、SSE、StreamableHTTP 等传输。其中 **StreamableHTTP** 在有状态模式下的行为已多次成为事故源（如 issue #1724：`mcp-use dev` 下工具结果通过 SSE 返回时偶发丢失，必须切换到 `enableJsonResponse` 才能正常工作）。运维上需要明确：**对可靠性敏感的链路，应优先开启 JSON 响应模式或升级到无状态 StreamableHTTP**。

### 3.4 Widget 扩展

服务端可通过在 `resources/` 目录下放置 `.tsx` 文件注册 UI Widget，并在工具返回中携带 `widget` 引用。MCP Apps 通过 `mcp-use/react` 的 `useWidget`、`useWidgetProps`、`useWidgetState`、`useWidgetTheme` 等 Hook 将 props、state、theme、callTool 能力暴露给前端组件，从而在 Claude、ChatGPT 等宿主中复用同一份 React 代码。资料来源：[libraries/typescript/packages/mcp-use/examples/server/features/everything/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/examples/server/features/everything/README.md)。

## 4. 工程化与运维

### 4.1 CLI 工具链

`@mcp-use/cli` 提供 `dev`、`build`、`start`、`deploy` 四个核心子命令，并内置 TypeScript 监听编译、Widget 热更新、自动重启（`tsx`）以及**自动打开 Inspector**。在最近的 `mcp-use servers update` 与分支级环境管理能力加入后（参见 `@mcp-use/cli@3.5.0`），运维人员可以在不重建 URL slug 与环境变量的情况下原地更新服务配置。

### 4.2 Inspector 与可观测性

`@mcp-use/inspector` 既可作为独立服务（`npx @mcp-use/inspector`）运行，也可由 `mcp-use dev` 自动挂载在 `/inspector` 路径下。除工具/资源/提示调试外，Inspector 还支持 **OAuth 流程调试**（`getTokenEndpoint()` 已在 1.32.0 中暴露）与 **BYOK Chat**。需要注意的是：**OAuth 错误页目前仍存在"原始错误页"回退问题**（issue #1362），在生产对接 OAuth 提供方时需自行处理错误重定向。

### 4.3 已知运维陷阱

- **空 `resources/` 目录的迷惑日志**（issue #1727）：即使项目不使用 Widget，`dev` 模式仍会执行 widget mounting 流水线，输出看似"出错了"的 `[WIDGETS]` 日志。这是预期行为，但应在文档与日志级别上消歧。
- **CLI 资源订阅未发送 unsubscribe**（issue #1723）：在 Ctrl+C 终止 `mcp-use resources subscribe` 时，旧版本不会发送 unsubscribe，导致上游订阅残留。已在后续版本修复。
- **传输层挂起**（issue #1724）：有状态 StreamableHTTP 在 dev 模式下偶发 SSE 响应丢弃，需在 transport 配置中开启 `enableJsonResponse` 或迁移到无状态模式。
- **依赖收缩**（issue #1371）：历史上 `@mcp-use/inspector` 曾作为硬依赖拉入 `@langchain/*`，对 Next.js 等打包器造成影响；在升级时建议显式审计 `inspector` 子依赖。

### 4.4 安全与认证

OAuth 元数据发现已按照 **RFC 8414** 进行修正，支持 path-suffix issuer 场景（`mcp-use 1.32.1-canary.2`）。同时 `useMcp().authTokens` 现在返回解析后的 `token_endpoint`，允许后端在访问令牌过期前主动刷新。在生产部署中建议**将 OAuth 元数据与 token 端点同时持久化**，避免依赖发现接口的瞬时不可用。

## 5. 小结

`mcp-use` 的可扩展性来自**清晰的协议分层**：MCP 协议 → 传输层（stdio/SSE/StreamableHTTP）→ 连接器（per-connector auth/middleware）→ 适配器（per-LLM）→ 业务工具与 Widget。其运维模型由 **CLI + Inspector + 模板** 共同支撑，开发者可以在数分钟内搭建一个可调试、可部署、并能在多种 LLM 宿主中复用的 MCP 应用。

## See Also

- MCP 协议核心：[libraries/typescript/packages/mcp-use/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/README.md)
- Python Agent 快速入门：[libraries/python/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/python/README.md)
- CLI 使用文档：[libraries/typescript/packages/cli/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/cli/README.md)
- Inspector 自托管与调试：[libraries/typescript/packages/inspector/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/inspector/README.md)
- 项目脚手架与模板：[libraries/typescript/packages/create-mcp-use-app/README.md](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/create-mcp-use-app/README.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：mcp-use/mcp-use

摘要：发现 29 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Confusing Logs for empty `resources/` folder。

## 1. 安装坑 · 来源证据：Confusing Logs for empty `resources/` folder

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Confusing Logs for empty `resources/` folder
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/mcp-use/mcp-use/issues/1727 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：Refactor: adaptor deduplicate across MCP adapters

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Refactor: adaptor deduplicate across MCP adapters
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/mcp-use/mcp-use/issues/1726 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 配置坑 · 来源证据：Stateful StreamableHTTP transport hangs in mcp-use dev — tool result never reaches client (SSE response dropped, works…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Stateful StreamableHTTP transport hangs in mcp-use dev — tool result never reaches client (SSE response dropped, works with enableJsonResponse)
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/mcp-use/mcp-use/issues/1724 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 4. 安全/权限坑 · 来源证据：Refactor HttpConnector and StdioConnector with per-connector configuration

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Refactor HttpConnector and StdioConnector with per-connector configuration
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/mcp-use/mcp-use/issues/947 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 5. 安装坑 · 失败模式：installation: Example: Chart Library MCP for financial pattern analysis

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Example: Chart Library MCP for financial pattern analysis
- 对用户的影响：Developers may fail before the first successful local run: Example: Chart Library MCP for financial pattern analysis
- 证据：failure_mode_cluster:github_issue | https://github.com/mcp-use/mcp-use/issues/1286 | Example: Chart Library MCP for financial pattern analysis

## 6. 安装坑 · 来源证据：Example: Chart Library MCP for financial pattern analysis

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Example: Chart Library MCP for financial pattern analysis
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/mcp-use/mcp-use/issues/1286 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 7. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | github_repo:956472076 | https://github.com/mcp-use/mcp-use | host_targets=mcp_host, claude_code, claude, chatgpt, cursor

## 8. 配置坑 · 失败模式：configuration: @mcp-use/cli 3.5.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: @mcp-use/cli 3.5.0
- 对用户的影响：Upgrade or migration may change expected behavior: @mcp-use/cli 3.5.0
- 证据：failure_mode_cluster:github_release | https://github.com/mcp-use/mcp-use/releases/tag/%40mcp-use/cli%403.5.0 | @mcp-use/cli 3.5.0

## 9. 配置坑 · 失败模式：configuration: Refactor HttpConnector and StdioConnector with per-connector configuration

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Refactor HttpConnector and StdioConnector with per-connector configuration
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Refactor HttpConnector and StdioConnector with per-connector configuration
- 证据：failure_mode_cluster:github_issue | https://github.com/mcp-use/mcp-use/issues/947 | Refactor HttpConnector and StdioConnector with per-connector configuration

## 10. 配置坑 · 失败模式：configuration: mcp-use 1.32.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: mcp-use 1.32.0
- 对用户的影响：Upgrade or migration may change expected behavior: mcp-use 1.32.0
- 证据：failure_mode_cluster:github_release | https://github.com/mcp-use/mcp-use/releases/tag/mcp-use%401.32.0 | mcp-use 1.32.0

## 11. 配置坑 · 失败模式：configuration: mcp-use 1.32.1-canary.2

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: mcp-use 1.32.1-canary.2
- 对用户的影响：Upgrade or migration may change expected behavior: mcp-use 1.32.1-canary.2
- 证据：failure_mode_cluster:github_release | https://github.com/mcp-use/mcp-use/releases/tag/mcp-use%401.32.1-canary.2 | mcp-use 1.32.1-canary.2

## 12. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | github_repo:956472076 | https://github.com/mcp-use/mcp-use | README/documentation is current enough for a first validation pass.

## 13. 运行坑 · 来源证据：fix(cli): send unsubscribe on Ctrl+C in resources subscribe

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：fix(cli): send unsubscribe on Ctrl+C in resources subscribe
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/mcp-use/mcp-use/issues/1723 | 来源类型 github_issue 暴露的待验证使用条件。

## 14. 维护坑 · 失败模式：migration: Stateful StreamableHTTP transport hangs in mcp-use dev — tool result never reaches client (SS...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: Stateful StreamableHTTP transport hangs in mcp-use dev — tool result never reaches client (SSE response dropped, works with enableJsonResponse)
- 对用户的影响：Developers may hit a documented source-backed failure mode: Stateful StreamableHTTP transport hangs in mcp-use dev — tool result never reaches client (SSE response dropped, works with enableJsonResponse)
- 证据：failure_mode_cluster:github_issue | https://github.com/mcp-use/mcp-use/issues/1724 | Stateful StreamableHTTP transport hangs in mcp-use dev — tool result never reaches client (SSE response dropped, works with enableJsonResponse)

## 15. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | github_repo:956472076 | https://github.com/mcp-use/mcp-use | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | github_repo:956472076 | https://github.com/mcp-use/mcp-use | no_demo; severity=medium

## 17. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | github_repo:956472076 | https://github.com/mcp-use/mcp-use | no_demo; severity=medium

## 18. 能力坑 · 失败模式：capability: Confusing Logs for empty `resources/` folder

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Confusing Logs for empty `resources/` folder
- 对用户的影响：Developers may hit a documented source-backed failure mode: Confusing Logs for empty `resources/` folder
- 证据：failure_mode_cluster:github_issue | https://github.com/mcp-use/mcp-use/issues/1727 | Confusing Logs for empty `resources/` folder

## 19. 能力坑 · 失败模式：capability: Refactor: adaptor deduplicate across MCP adapters

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Refactor: adaptor deduplicate across MCP adapters
- 对用户的影响：Developers may hit a documented source-backed failure mode: Refactor: adaptor deduplicate across MCP adapters
- 证据：failure_mode_cluster:github_issue | https://github.com/mcp-use/mcp-use/issues/1726 | Refactor: adaptor deduplicate across MCP adapters

## 20. 能力坑 · 失败模式：capability: fix(cli): send unsubscribe on Ctrl+C in resources subscribe

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: fix(cli): send unsubscribe on Ctrl+C in resources subscribe
- 对用户的影响：Developers may hit a documented source-backed failure mode: fix(cli): send unsubscribe on Ctrl+C in resources subscribe
- 证据：failure_mode_cluster:github_issue | https://github.com/mcp-use/mcp-use/issues/1723 | fix(cli): send unsubscribe on Ctrl+C in resources subscribe

## 21. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | github_repo:956472076 | https://github.com/mcp-use/mcp-use | issue_or_pr_quality=unknown

## 22. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | github_repo:956472076 | https://github.com/mcp-use/mcp-use | release_recency=unknown

## 23. 维护坑 · 失败模式：maintenance: @mcp-use/cli 3.5.1

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: @mcp-use/cli 3.5.1
- 对用户的影响：Upgrade or migration may change expected behavior: @mcp-use/cli 3.5.1
- 证据：failure_mode_cluster:github_release | https://github.com/mcp-use/mcp-use/releases/tag/%40mcp-use/cli%403.5.1 | @mcp-use/cli 3.5.1

## 24. 维护坑 · 失败模式：maintenance: @mcp-use/cli 3.5.2-canary.2

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: @mcp-use/cli 3.5.2-canary.2
- 对用户的影响：Upgrade or migration may change expected behavior: @mcp-use/cli 3.5.2-canary.2
- 证据：failure_mode_cluster:github_release | https://github.com/mcp-use/mcp-use/releases/tag/%40mcp-use/cli%403.5.2-canary.2 | @mcp-use/cli 3.5.2-canary.2

## 25. 维护坑 · 失败模式：maintenance: @mcp-use/inspector 10.0.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: @mcp-use/inspector 10.0.0
- 对用户的影响：Upgrade or migration may change expected behavior: @mcp-use/inspector 10.0.0
- 证据：failure_mode_cluster:github_release | https://github.com/mcp-use/mcp-use/releases/tag/%40mcp-use/inspector%4010.0.0 | @mcp-use/inspector 10.0.0

## 26. 维护坑 · 失败模式：maintenance: @mcp-use/inspector 10.0.1-canary.2

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: @mcp-use/inspector 10.0.1-canary.2
- 对用户的影响：Upgrade or migration may change expected behavior: @mcp-use/inspector 10.0.1-canary.2
- 证据：failure_mode_cluster:github_release | https://github.com/mcp-use/mcp-use/releases/tag/%40mcp-use/inspector%4010.0.1-canary.2 | @mcp-use/inspector 10.0.1-canary.2

## 27. 维护坑 · 失败模式：maintenance: @mcp-use/inspector 9.0.1

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: @mcp-use/inspector 9.0.1
- 对用户的影响：Upgrade or migration may change expected behavior: @mcp-use/inspector 9.0.1
- 证据：failure_mode_cluster:github_release | https://github.com/mcp-use/mcp-use/releases/tag/%40mcp-use/inspector%409.0.1 | @mcp-use/inspector 9.0.1

## 28. 维护坑 · 失败模式：maintenance: mcp-use 1.31.1

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: mcp-use 1.31.1
- 对用户的影响：Upgrade or migration may change expected behavior: mcp-use 1.31.1
- 证据：failure_mode_cluster:github_release | https://github.com/mcp-use/mcp-use/releases/tag/mcp-use%401.31.1 | mcp-use 1.31.1

## 29. 维护坑 · 失败模式：maintenance: mcp-use 1.32.1-canary.1

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: mcp-use 1.32.1-canary.1
- 对用户的影响：Upgrade or migration may change expected behavior: mcp-use 1.32.1-canary.1
- 证据：failure_mode_cluster:github_release | https://github.com/mcp-use/mcp-use/releases/tag/mcp-use%401.32.1-canary.1 | mcp-use 1.32.1-canary.1

<!-- canonical_name: mcp-use/mcp-use; human_manual_source: deepwiki_human_wiki -->