项目定位与核心能力

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

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

资料来源：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、libraries/python/README.md

生态系统与包结构

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

资料来源：libraries/typescript/README.md、libraries/typescript/packages/cli/README.md、libraries/typescript/packages/inspector/README.md

下图为整体架构关系：

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

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

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

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

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

Python：6 行代码启动 Agent

Python 端的入口是 MCPAgent + MCPClient：

pip install mcp-use langchain-openai

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

CLI 常用命令

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

资料来源：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

Elicitation（结构化用户输入）

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

社区已知的坑与改进

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

调试与示例

• 浏览器调试：inspector.mcp-use.com 或 npx @mcp-use/inspector。资料来源：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

一、概述

mcp-use 是一个面向 Model Context Protocol（MCP） 的全栈开发框架，覆盖 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

生态包一览

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

一、整体定位与生态构成

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

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

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 — 仓库总览与快速开始
• libraries/python/README.md — Python Agent 与 Client
• libraries/typescript/packages/cli/README.md — mcp-use dev / build CLI
• libraries/typescript/packages/inspector/README.md — Inspector 使用与自托管
• 官方文档 — 完整 API 与教程

1. 概述与定位

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

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

整体定位可以理解为：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 组件可作为工具调用结果的一部分被返回。

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、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。

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。

4. 工程化与运维

4.1 CLI 工具链

@mcp-use/cli 提供 dev、build、start、deploy 四个核心子命令，并内置 TypeScript 监听编译、Widget 热更新、自动重启（tsx）以及自动打开 Inspector。在最近的 mcp-use servers update 与分支级环境管理能力加入后（参见 @mcp-use/[email protected]），运维人员可以在不重建 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
• Python Agent 快速入门：libraries/python/README.md
• CLI 使用文档：libraries/typescript/packages/cli/README.md
• Inspector 自托管与调试：libraries/typescript/packages/inspector/README.md
• 项目脚手架与模板：libraries/typescript/packages/create-mcp-use-app/README.md

Pitfall Log / 踩坑日志

项目：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