mcp-use TypeScript 全栈 MCP 框架实战：构建 Agent、MCP Server 与跨客户端 MCP Apps

后端MCP 服务MCP ClientsAI Agent人工智能【免费下载链接】mcp-useThe fullstack MCP framework to develop MCP Apps for ChatGPT / Claude MCP Servers for AI Agents.项目地址https://gitcode.com/gh_mirrors/mc/mcp-use点击查看免费下载mcp-use 的 TypeScript 实现是一套覆盖模型上下文协议Model Context ProtocolMCP完整链路的全栈框架从连接任意 MCP 服务器的客户端、可自主调用工具的多步 Agent到支持 UI 组件MCP Apps的服务端框架与 Web 调试器一应俱全。本文以 libraries/typescript/README.md 为主线结合仓库源码剖析mcp-use、mcp-use/client、mcp-use/agent、mcp-use/inspector、mcp-use/tunnel、create-mcp-use-app六大包的定位、配置项与真实用法读完你可以在几分钟内从零搭建一个自带 Inspector 与交互式视图的 MCP 服务并写出能连接多个 MCP 服务器的 LLM Agent。mcp-use 是什么一套完整的 TypeScript MCP 技术栈mcp-use 是一个用 TypeScript 构建与使用 MCP 应用的综合性框架。它属于 mcp-use monorepo仓库根目录 README.md的 TypeScript 实现部分另有独立的 Python 实现见 libraries/python/README.md。它的设计目标是通过统一 API 覆盖 MCP 开发的全部环节让开发者不必在客户端 SDK、服务端框架、调试工具之间来回拼接。从 libraries/typescript/README.md 的组件清单看TypeScript 实现提供五层能力能力定位对应包MCP Agent构建可多步推理、调用工具的 AI Agentmcp-use/agentMCP Client以编程方式直连 MCP 服务器mcp-use/clientMCP Server Framework创建带工具、资源、提示词的服务端mcp-useMCP Apps构建可在 Claude、ChatGPT 等客户端运行的交互式组件mcp-use/react视图MCP Inspector基于 Web 的调试与监控工具mcp-use/inspector配套还有mcp-use/tunnelWebSocket 隧道与create-mcp-use-app项目脚手架两个工具包。一分钟快速开始脚手架与开发服务器框架提供了零配置脚手架一条命令即可生成完整可运行的 TypeScript MCP 项目# 创建新的 MCP 应用 npx create-mcp-use-app my-mcp-app # 进入项目目录 cd my-mcp-app # 启动开发模式热重载 自动打开 Inspector npm run dev启动后 MCP 服务器默认运行在http://localhost:3000Inspector 会自动在浏览器中打开。从 create-mcp-use-app 文档 可以看到脚手架生成的项目结构my-mcp-server/ ├── index.ts # MCP server entry point ├── package.json # Scripts and dependencies ├── tsconfig.json # TypeScript configuration ├── mcp-env.d.ts # Managed view typing bridge ├── public/ # Static assets └── views/ # Included by the mcp-apps template └── product-search-result/ └── view.tsx # React view entry point脚手架默认预置了 TypeScript 完整配置、热重载、自动 Inspector、React 视图发现与打包、示例工具/资源/提示词、开发与生产构建脚本、类型检查以及生产级构建优化。交互模式与直连模式两种创建方式# 交互模式 npx create-mcp-use-app # 直连模式指定模板 npx create-mcp-use-app my-app --template advancedadvanced模板额外包含 Docker 与 CI/CD 配置。MCP Apps构建跨客户端运行的交互式视图MCP Apps 是 mcp-use 的差异化能力——它允许开发者构建在 Claude、ChatGPT 以及任何自定义 MCP 客户端中都能渲染的交互式界面而不仅仅是纯文本工具输出。MCP Apps 的设计动机交互式界面可以渲染仪表盘、看板、表单、可视化图表等富 UI工具集成视图通过useToolContext读取自身渲染结果通过useCallTool回调服务器工具自包含视图由 MCP 服务器自动打包并提供无需单独部署前端框架无关兼容 Claude Desktop、ChatGPT、自定义客户端等任意 MCP 客户端热重载开发期改动即时生效。视图组件与渲染工具绑定视图是一个 React 组件从mcp-use/react导入useCallTool与useToolContext两个 Hook// views/analytics-dashboard/view.tsx import { useCallTool, useToolContext } from mcp-use/react; interface Analytics { period: string; visitors: number; } export default function AnalyticsDashboard() { const view useToolContext(); const refresh useCallTool(show-analytics); if (view.status pending) return pLoading analytics…/p; if (view.status error) return p{view.error.message}/p; const analytics refresh.data?.structuredContent ?? (view.toolOutput as Analytics); return ( main h1Analytics Dashboard/h1 p{analytics.visitors} visitors/p button disabled{refresh.isPending} onClick{() void refresh.callTool({ period: analytics.period })} Refresh /button /main ); }useToolContext返回的view携带statuspending / error / 就绪、toolOutput与错误信息useCallTool返回的refresh提供isPending、data含structuredContent与callTool(args)方法调用时携带view.status的加载与错误状态处理。接着在服务器中通过工具的view字段把渲染工具绑定到视图export const showAnalytics server.tool( { name: show-analytics, description: Show analytics for a reporting period, inputSchema: z.object({ period: z.string() }), outputSchema: z.object({ period: z.string(), visitors: z.number() }), view: { name: analytics-dashboard }, }, async ({ period }) { const analytics { period, visitors: 1_024 }; return { content: [{ type: text, text: JSON.stringify(analytics) }], structuredContent: analytics, }; } );view: { name: analytics-dashboard }将工具与views/analytics-dashboard/view.tsx建立映射工具返回的structuredContent是视图可消费的结构化数据。更简单的视图也可以只用useToolContext输出原始数据// views/analytics-dashboard/view.tsx import { useToolContext } from mcp-use/react; export default function AnalyticsDashboard() { const view useToolContext(); if (view.status pending) return pLoading analytics…/p; if (view.status error) return p{view.error.message}/p; return ( div h1Analytics Dashboard/h1 pre{JSON.stringify(view.toolOutput, null, 2)}/pre /div ); }从服务端源码结构看视图支持位于 libraries/typescript/packages/server/src/views/ 目录mcp-use dev会在开发期自动发现views/下的 React 组件并打包为 MCP 资源交付资源注册逻辑见 registerViews。此外 libraries/typescript/packages/create-mcp-use-app/README.md 提到视图类型由mcp-env.d.ts桥接保证 TSX 视图中的 Hook 类型完整。作为 MCP 客户端mcp-use/client 连接任意服务器mcp-use/client用于把任意 LLM 连接到任意 MCP 服务器。核心类MCPClient的实现位于 libraries/typescript/packages/client/src/core/node.ts支持三种初始化方式构造函数直接传配置、MCPClient.fromDict()传内联配置、MCPClient.fromConfigFile()读取 JSON 配置文件。基础连接与 Agent 装配import { MCPClient } from mcp-use/client; import { MCPAgent } from mcp-use/agent; import { ChatOpenAI } from langchain/openai; // 配置 MCP 服务器 const client MCPClient.fromDict({ mcpServers: { filesystem: { command: npx, args: [modelcontextprotocol/server-filesystem], }, github: { command: npx, args: [modelcontextprotocol/server-github], env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN }, }, }, }); // 创建 AI Agent const agent new MCPAgent({ llm: new ChatOpenAI({ model: gpt-4 }), client, maxSteps: 10, }); // 用自然语言驱动 Agent const result await agent.run( Search for TypeScript files in the project and create a summary );服务器配置类型stdio 与 HTTP从 libraries/typescript/packages/client/src/core/config.ts 可以看清ServerConfig的两类分支StdioServerConfig本地进程服务器字段包括字段说明command启动服务器的可执行文件args传给命令的参数数组env与当前进程环境合并的环境变量cwd启动子进程的工作目录stderrstderr 处理模式pipe默认转发到连接器 errlog、inherit保留父进程 stderr保持 TTY 与颜色、ignore丢弃protocolNegotiation协议版本协商模式stdio 默认legacySDK 不建议为每次调用探测 spawn 工具clientInfo/roots/clientOptions/defaultRequestOptions公共可选字段见下文HttpServerConfig远程 streamable HTTP 服务器字段包括字段说明urlMCP 端点 URLheaders随 MCP 传输请求携带的请求头authToken以Authorization头发送的 Bearer 令牌timeout连接超时毫秒authProvider服务器要求授权时使用的 OAuth provideroauth自动 OAuth 选项省略或{}时客户端在连接时创建平台 providerfalse禁用如 CLI--no-oauth对象则转发给createOAuthProvider。当已设置authProvider、authToken或 headers 含Authorization时被忽略detectMixedAuth匿名连接后是否通过官方 SDK 的 RFC 9728 受保护资源元数据发现检测混合鉴权服务器默认trueprotocolNegotiation默认auto同时协商 v1 与 v2 MCP 服务器顶层MCPClientConfigShape还支持clientInfo默认客户端身份可被单服务器覆盖与全局回调onSampling、onElicitation、onNotification。normalizeClientInfo会为缺少name/version的身份回填默认值resolveClientOptions会把capabilities.views: true展开为 MCP Apps 扩展io.modelcontextprotocol/ui扩展MIME 类型text/html;profilemcp-app。从源码结构看连接器实现在 libraries/typescript/packages/client/src/transport/createConnectorFromConfig在 Node 环境按配置自动选择StdioConnector或HttpConnector。高级客户端能力MCPClient的构造选项MCPClientOptions包含codeMode布尔值或{ enabled, executor, executorOptions }对象启用代码执行模式onSampling处理服务器sampling/createMessage请求2026 协议已弃用仅保留兼容onElicitation处理elicitation/create请求支持表单模式结构化数据 JSON Schema 校验与 URL 模式onNotification处理服务器通知作为未单独配置时的全局默认。客户端关键方法Node 专属能力// 从配置文件加载 const client MCPClient.fromConfigFile(./mcp-config.json); await client.createAllSessions(); // 保存配置自动创建目录 client.saveConfig(./mcp-config.json); // 代码执行模式VM 或 E2B 沙箱 const client2 new MCPClient(./config.json, { codeMode: true }); const result await client2.executeCode( console.log(Hello, world!); return 2 2; ); console.log(result.stdout); // Hello, world!\n console.log(result.returnValue); // 4 // 跨服务器工具搜索 const fileTools await client2.searchTools(file, descriptions); // 完整清理先关代码执行器再关所有会话 await client.close();代码执行器的选择逻辑在_ensureCodeExecutor()中默认vmNode 内置 VM 沙箱本地执行超时默认 30 秒e2b需要apiKey超时默认 5 分钟VM 不可用且无 E2B key 时会抛出明确错误提示。getServerNames()会过滤掉内部code_mode元服务器。客户端核心特性LLM 无关兼容 OpenAI、Anthropic、Google 及任意 LangChain 支持的 LLM流式支持通过stream()与streamEvents()实时流式输出多服务器同时连接多个 MCP 服务器工具控制通过disallowedTools限制模型可访问的工具可观测性内置 Langfuse 集成用于监控服务器管理Server Manager 根据可用工具自动选择服务器。作为 MCP 服务器框架mcp-use 构建服务端mcp-use主包用于构建自带 Inspector 与 UI 能力的 MCP 服务器。从 libraries/typescript/packages/server/src/index.ts 可见核心导出为MCPServer底层基于 Hono 应用与 Web 标准 Fetch 边界构建无状态服务器。定义工具、资源并启动import { MCPServer, text } from mcp-use; import { z } from zod; // 创建 MCP 服务器 const server new MCPServer({ name: weather-server, version: 1.0.0, description: Weather information MCP server, }); // 用 Zod schema 定义工具 export const getWeather server.tool( { name: get_weather, description: Get current weather for a city, schema: z.object({ city: z.string().describe(City name), units: z.enum([celsius, fahrenheit]).optional(), }), }, async ({ city, units celsius }) { const weather await fetchWeather(city, units); return text( Temperature: ${weather.temp}, Condition: ${weather.condition}, Humidity: ${weather.humidity} ); } ); // 定义资源 server.resource( { name: weather_map, description: Interactive weather map, uri: weather://map, mimeType: text/html, }, async () { return { contents: [ { uri: weather://map, mimeType: text/html, text: generateWeatherMapHTML(), }, ], }; } ); // 启动服务器 server.listen(3000); // MCP endpoint at http://localhost:3000/mcp工具定义使用schema字段README 的 MCP Apps 示例中写作inputSchema二者皆为 schema 契约入口text()是便捷的文本响应助手。从源码看libraries/typescript/packages/server/src/server.ts 中server.tool/server.resource返回带类型的注册入口schema 契约支持StandardSchemaWithJSON——由 zod v4、ArkType、Valibot 等实现类型定义见 index.ts。仓库中另有 schema-validators 示例 演示 arktype / typebox / zod 三种校验器的等价写法。服务器框架核心特性开发 Inspectormcp-use dev将项目级 Inspector 挂载到/mcp/inspectorMCP Apps 视图构建与 MCP 工具一起托管的 React 组件OAuth 支持内置鉴权流程处理多传输HTTP/SSE 与 WebSocketTypeScript 优先完整的类型安全与推断热重载开发模式自动重启。服务端进阶能力服务端还支持server.resource资源模板、server.prompt提示词、OpenAPI 工具导入registerOpenAPITools、Skills 运行时registerSkillsRuntime见 libraries/typescript/packages/server/src/skills/、OAuth 资源保护libraries/typescript/packages/server/src/oauth/与中间件系统libraries/typescript/packages/server/src/middleware/。完整参考见 服务器包文档。AI SDK 流式集成mcp-use/agent提供streamEventsToAISDKWithTools可直接对接 Vercel AI SDK 构建流式 API 路由import { streamEventsToAISDKWithTools } from mcp-use/agent; import { createTextStreamResponse } from ai; // 在你的 Next.js API 路由中 export async function POST(req: Request) { const { prompt } await req.json(); const streamEvents agent.streamEvents(prompt); const enhancedStream streamEventsToAISDKWithTools(streamEvents); const readableStream createReadableStreamFromGenerator(enhancedStream); return createTextStreamResponse({ textStream: readableStream }); }对应适配器实现在 libraries/typescript/packages/client/src/adapters/ai-sdk.ts 与 libraries/typescript/packages/agent/src/agents/utils/ai_sdk.ts。mcp-use CLI开发与构建工具链mcp-use包内置 CLI入口见 libraries/typescript/packages/cli/src/bin.ts提供三个核心命令# 开发模式热重载 mcp-use dev # 生产构建 mcp-use build # 启动生产服务器 mcp-use startCLI 职责开发模式自动打开 Inspector服务器与 MCP Apps 视图双热重载打包 React 视图用于 MCP 资源交付生产构建优化资源哈希TypeScript 编译 watch 模式。典型开发流程# 启动开发 mcp-use dev # Server running at http://localhost:3000 # Inspector opened at http://localhost:3000/mcp/inspector # Watching for changes... # 修改代码后 # 服务器自动重启 # MCP Apps 视图热重载 # Inspector 实时更新完整 CLI 文档见 libraries/typescript/packages/cli。mcp-use/tunnel内网穿透与远程调试mcp-use/tunnel通过托管 WebSocket 中继暴露本地 HTTP、WebSocket 或 MCP 服务器便于把本地开发中的服务器临时共享给远端客户端如 ChatGPT / Claude 的远程连接。同一实现也内置于mcp-use dev --tunnel与mcp-use start --tunnelnpx mcp-use/tunnel 3000隧道包源码见 libraries/typescript/packages/tunnel。mcp-use/inspectorMCP 的 Swagger UIInspector 是基于 Web 的 MCP 服务器调试工具官方定位like Swagger UI but for MCP见 libraries/typescript/packages/inspector/README.md。功能包括交互式工具测试实时执行、连接状态与服务器健康监控、自动处理 OAuth 流程、localStorage 持久化会话、响应式 UI。还支持 MCP-UI 与 OpenAI Apps SDK 组件调试。三种使用方式1. 开发模式自动挂载使用脚手架生成的项目npm run dev # Inspector at http://localhost:3000/mcp/inspector2. 独立 CLInpx mcp-use/inspector --url https://mcp.example.com/sse3. 自定义挂载编程方式集成到任意应用import { mountInspector } from mcp-use/inspector; mountInspector(app, { basePath: /debug });Inspector 前端实现在 libraries/typescript/packages/inspector/src含完整的工具列表、RPC 日志与 OAuth 流程处理组件。真实场景示例示例 1AI 文件管理器// 创建能管理文件的 Agent const agent new MCPAgent({ llm: new ChatOpenAI(), client: MCPClient.fromDict({ mcpServers: { filesystem: { command: npx, args: [ modelcontextprotocol/server-filesystem, /Users/me/documents, ], }, }, }), }); // 自然语言文件操作 await agent.run(Organize all PDF files into a PDFs folder sorted by date); await agent.run(Find all TypeScript files and create a project summary); await agent.run(Delete all temporary files older than 30 days);示例 2多工具研究助手// 连接多个 MCP 服务器 const client MCPClient.fromDict({ mcpServers: { browser: { command: npx, args: [playwright/mcp] }, search: { command: npx, args: [mcp/server-search] }, memory: { command: npx, args: [mcp/server-memory] }, }, }); const researcher new MCPAgent({ llm: new ChatAnthropic(), client, useServerManager: true, // 自动选择合适的服务器 }); // 复杂研究任务 const report await researcher.run( Research the latest developments in quantum computing. Search for recent papers, visit official websites, and create a comprehensive summary with sources. );示例 3数据库管理助手const server new MCPServer({ name: db-admin, version: 1.0.0, }); export const executeQuery server.tool( { name: execute_query, description: Execute SQL query safely, schema: z.object({ query: z.string(), database: z.string(), }), }, async ({ query, database }) { // Validate and execute query const results await db.query(query, { database }); return text(Query executed: ${results.length} rows returned); } ); // 创建 AI 驱动的 DBA const dba new MCPAgent({ llm: new ChatOpenAI({ model: gpt-4 }), client: new MCPClient({ url: http://localhost:3000/mcp }), }); await dba.run(Show me all users who signed up this week); await dba.run(Optimize the slow queries in the performance log);MCPAgent 选项深度解析从 libraries/typescript/packages/agent/src/agents/agent_options.ts 可以看到MCPAgentOptions的完整字段字段默认值说明llm必填模型标识符字符串如openai/gpt-4o或完整 provider 配置llmConfig—字符串模型标识符的凭据与采样覆盖client—复用已有 MCPClientAgent 不再创建connectors—已有 MCP 连接器初始化为工具暴露mcpServers—命名服务器配置或浏览器环境下的实时连接数组maxSteps10单次运行的最大模型/工具循环步数autoInitializefalse是否在首次运行时自动初始化字符串 LLM 简化模式下默认开启memoryEnabledtrue是否在多次运行间保留用户与助手消息systemPrompt默认系统指令本地运行的系统指令传null使用默认disallowedTools[]不得暴露给模型的 MCP 工具名列表exposeResourcesAsToolstrue是否把 MCP 资源暴露为可调用工具exposePromptsAsToolstrue是否把 MCP 提示词暴露为可调用工具agentId—远程 Agent 标识设置后走远程 API 执行从 libraries/typescript/packages/agent/src/agents/mcp_agent.ts 的实现看MCPAgent支持两种执行路径简化模式llm传字符串如openai/gpt-4oAgent 通过parseLLMStringToProviderConfig创建内部 LLM driverautoInitialize自动开启run()可直接执行显式模式llm传完整 provider 配置配合已有client或connectors。loadTools()会在无实时连接时自动创建会话并通过NativeAdapter把连接器中的工具可选资源、提示词转换为 provider 工具列表bindConnections()对同名工具做name、name_2式去重路由并应用disallowedTools过滤。Agent 的核心循环LLM 工具调用 → 执行 → 观测回填实现在 libraries/typescript/packages/agent/src/llm/native_runner.ts内置 OpenAI、Anthropic、Google、Ollama 等 provider 驱动libraries/typescript/packages/agent/src/llm/providers/也支持 LangChain 适配器。项目结构与开发工作流一个典型 mcp-use 项目的目录结构my-mcp-app/ ├── src/ │ └── index.ts # MCP server definition ├── views/ # MCP Apps views │ ├── dashboard/ │ │ └── view.tsx # Dashboard view entry │ └── settings/ │ └── view.tsx # Settings view entry ├── package.json # Dependencies and scripts ├── tsconfig.json # TypeScript configuration ├── .env # Environment variables └── .mcp-use/ # Generated build output └── build/ ├── index.js # Compiled server └── views/ # Compiled view assets本地开发# 1. 创建项目 npx create-mcp-use-app my-project # 2. 启动开发 cd my-project npm run dev # 3. 修改代码热重载处理其余 # 4. 用自动打开的 Inspector 测试生产部署# 生产构建 npm run build # Docker 部署 docker build -t my-mcp-server . docker run -p 3000:3000 my-mcp-server # 或部署到任意 Node.js 主机 npm run start版本管理与发布渠道monorepo 使用 Changesets 自动化版本管理与发布配置见 libraries/typescript。稳定版main 分支携带 changeset 的改动推送到main分支CI 自动创建/更新 Version Packages PR合并后发布latesttag 到 npm。Canary 预发布canary 分支推送后 CI 自动发布预发布版本版本形如x.y.z-canary.0、x.y.z-canary.1使用canarydist tag# 安装 canary 版本 npm install mcp-usecanary贡献与开发环境克隆仓库后进入 TypeScript 目录即可开发git clone https://github.com/mcp-use/mcp-use.git cd mcp-use/libraries/typescript # 安装依赖 pnpm install # 构建所有包 pnpm build # 运行测试 pnpm test # 启动开发 pnpm devmonorepo 使用 Knip# 完整报告文件、导出、依赖、类型等 pnpm knip # 仅未使用依赖非阻塞 pnpm knip:deps # 生产模式排除测试、stories、devDependencies pnpm knip:production出现误报时优先精调entry/project模式或使用基于 tag 的覆盖规则而非宽泛的ignore规则。总结mcp-use 的 TypeScript 实现以统一的 API 覆盖 MCP 全链路mcp-use/client负责连接与协议协商stdio / HTTP / WebSocket、OAuth、code modemcp-use/agent提供 provider 无关的多步工具循环mcp-use服务端框架支持工具、资源、提示词、MCP Apps 视图与中间件mcp-use/inspector与mcp-use/tunnel补齐调试与远程暴露能力create-mcp-use-app则把这一切打包成一分钟可运行的开箱项目。对于需要同时服务客户端消费 MCP与服务端提供 MCP两种角色的团队这是一个可以在 TypeScript 单技术栈内闭环的完整方案。赞分享后端MCP 服务MCP ClientsAI Agent人工智能【免费下载链接】mcp-useThe fullstack MCP framework to develop MCP Apps for ChatGPT / Claude MCP Servers for AI Agents.项目地址https://gitcode.com/gh_mirrors/mc/mcp-use点击查看免费下载相关推荐Czkawka 免费磁盘清理教程一条命令扫描重复文件与 14 类冗余快速释放硬盘空间Czkawka 免费磁盘清理教程一条命令扫描重复文件与 14 类冗余快速释放硬盘空间 把几百 GB 素材备份到磁盘后系统突然提示空间不足却分不清哪些文件后端MCP 服务MCP ClientsAI Agent人工智能RedisInsight macOS 指南从官方安装包到自编译 Apple Silicon 版本RedisInsight macOS 指南从官方安装包到自编译 Apple Silicon 版本 RedisInsight 是 Redis 官方出品的 GUI数据库客户端桌面应用后端前端数据可视化LightGBM 参数完全指南核心参数、学习控制、IO、目标函数与分布式调优手册LightGBM 参数完全指南核心参数、学习控制、IO、目标函数与分布式调优手册 本文是 LightGBM 官方参数参考文档 docs/Parameters后端MCP 服务MCP ClientsAI Agent人工智能上一篇抖音视频下载终极指南10分钟掌握无水印批量下载技巧下一篇Windows窗口置顶终极指南如何用PinWin实现零干扰多任务工作创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考