1. 项目概述一个为MCP协议而生的全栈TypeScript框架如果你正在构建基于大语言模型LLM的智能体应用并且厌倦了在工具集成、协议实现和调试工具之间反复折腾那么mcp-use这个项目很可能就是你一直在找的“瑞士军刀”。简单来说它是一个围绕Model Context Protocol构建的、功能完整的TypeScript框架。MCP协议本身是一个由Anthropic提出的开放标准旨在为LLM提供一个标准化的方式来发现和使用外部工具与资源。而mcp-use则更进一步它不仅提供了符合协议的客户端和服务器SDK还附赠了一整套开箱即用的开发体验从快速创建项目的脚手架、支持热重载和内置调试器的CLI到可以直接嵌入UI组件的服务器框架一应俱全。这个框架的核心价值在于它极大地降低了构建“可行动的AI智能体”的门槛。过去要让一个LLM调用文件系统、操作数据库或者查询天气你需要写大量的胶水代码来处理工具注册、参数解析、错误处理和状态管理。现在借助mcp-use你可以用声明式的方式定义工具然后立刻获得一个功能完备的MCP服务器并且自带一个类似Swagger UI的交互式调试界面。对于前端和全栈开发者而言其最大的亮点在于“UI组件即资源”的理念——你可以用React编写一个数据看板或配置面板直接作为MCP资源挂载到服务器上智能体不仅能调用工具还能“看到”并与之交互。2. 核心架构与设计哲学拆解2.1 为什么是MCP协议层抽象的价值在深入mcp-use之前有必要先理解MCP协议要解决的根本问题。在AI智能体领域一个核心挑战是工具使用的标准化。不同的LLM提供商如OpenAI的Function Calling、Anthropic的Tools、Google的Tool Calling各有其实现方式而外部工具如数据库、API、文件系统更是千差万别。如果没有一个中间层开发者就需要为每一对“LLM-工具”组合编写特定的适配器导致代码重复、维护困难且难以扩展。MCP协议的出现正是在LLM和工具之间插入了一个标准化的抽象层。它定义了三个核心概念工具LLM可以调用的函数有明确的输入输出模式。资源LLM可以读取的静态或动态内容如文档、网页、数据流。提示词模板可复用的提示结构。mcp-use框架完全拥抱了这一协议并将其价值最大化。它的设计哲学是“一次定义处处可用”。你只需用TypeScript和Zod模式定义一次你的工具这个工具就能被任何兼容MCP的客户端如Claude Desktop、Cursor等直接使用。通过mcp-use提供的MCPAgent被集成到基于LangChain、AI SDK或其他任何LLM库的自主智能体中。通过内置的Inspector进行可视化测试和调试。以UI组件的形式提供一个富交互的前端界面。这种设计将开发者从繁琐的集成工作中解放出来使其能专注于工具本身的业务逻辑。2.2 一体化框架 vs. 拼装式方案在mcp-use出现之前搭建一个类似的智能体系统通常是一个“拼装”过程你可能需要选择modelcontextprotocol/sdk来创建基础服务器用langchain来构建智能体逻辑自己实现一个简单的HTTP服务器来提供UI再用nodemon实现热重载。这个过程中模块间的接口定义、类型安全、开发工作流都是巨大的挑战。mcp-use采用了一体化框架的思路提供了从开发到部署的完整工具链mcp-use(核心库)统一的客户端与服务器SDK类型安全贯穿始终。mcp-use/cli集成了构建、开发服务器、热重载和自动打开调试器的功能。mcp-use/inspector一个专为MCP协议优化的Web调试器替代了手写curl命令或Postman脚本的原始方式。create-mcp-use-app项目生成器一键搭建包含示例的最佳实践项目结构。这种一体化设计带来了几个显著优势极佳的开发者体验npm run dev一条命令你就同时启动了服务器、开启了热重载、并打开了调试页面。强类型保障从工具的参数定义使用Zod到客户端的调用全程享受TypeScript的类型推断和自动补全。一致性所有工具都遵循相同的模式和生命周期降低了认知负担。开箱即用的高级功能如OAuth流处理、资源UI化、服务器健康监控等无需从零实现。3. 核心包深度解析与实操要点3.1mcp-use核心框架客户端与服务器的双重奏mcp-use是整个生态系统的基石它巧妙地用一个包提供了构建MCP客户端和服务器的全部能力。作为MCP客户端构建强大的智能体客户端的核心是MCPClient和MCPAgent类。MCPClient负责管理与一个或多个MCP服务器的连接、协议通信和工具发现。它的配置非常灵活支持通过子进程命令启动服务器也支持直接连接到现有的SSE或WebSocket端点。import { MCPClient, MCPAgent } from mcp-use; import { ChatOpenAI } from langchain/openai; import { Anthropic } from anthropic-ai/sdk; // 方案一通过CLI命令动态启动服务器适合本地工具 const client1 MCPClient.fromDict({ mcpServers: { filesystem: { command: npx, args: [modelcontextprotocol/server-filesystem, /path/to/project], }, }, }); // 方案二连接到远程或已存在的服务器端点 const client2 new MCPClient({ transport: await createSSETransport(new URL(http://remote-server/sse)), }); // 创建智能体。MCPAgent是对LangChain Agent的封装提供了与MCP工具无缝集成的能力。 const agent new MCPAgent({ llm: new ChatOpenAI({ model: gpt-4-turbo }), // 也可以使用Anthropic、Google Gemini等 client: client1, maxSteps: 15, // 限制最大推理步骤防止无限循环 // useServerManager: true, // 启用服务器管理器智能体自动选择拥有所需工具的服务器 }); // 运行任务 const result await agent.run( 请分析src目录下的所有TypeScript文件找出未使用的导入语句并列出文件名。 );实操心得maxSteps参数是关键安全阀。在复杂任务中智能体可能会陷入“思考-调用-再思考”的循环。根据任务复杂度合理设置此值通常10-20并在关键工具调用后加入agent.stop()的逻辑可以有效控制成本和执行时间。作为MCP服务器框架声明式构建工具与资源服务器端使用createMCPServer工厂函数其设计非常直观。你只需要关注三件事服务器元信息、工具定义、资源定义。import { createMCPServer } from mcp-use/server; import { z } from zod; import { weatherApi } from ./lib/weather; const server createMCPServer(my-weather-service, { version: 1.0.0, description: 提供天气查询和预警信息的MCP服务器, // 可选的服务器能力声明帮助客户端优化 capabilities: { tools: {}, resources: { subscribe: true }, // 支持资源订阅 prompts: {}, }, }); // 1. 定义工具使用Zod确保输入类型安全并自动生成JSON Schema供LLM理解。 server.tool(get_current_weather, { name: 获取当前天气, // 可选提供更友好的名称 description: 根据城市名称查询实时天气状况包括温度、湿度和天气现象。, parameters: z.object({ city: z.string().min(1).describe(要查询的城市名称例如“北京”或“New York”), unit: z.enum([celsius, fahrenheit]).default(celsius).describe(温度单位), }), execute: async ({ city, unit }) { // 这里是你的业务逻辑 const data await weatherApi.fetchCurrent(city); return { content: [ { type: text, text: 城市${city}\n温度${data.temp}°${unit celsius ? C : F}\n天气${data.condition}\n湿度${data.humidity}%, }, ], }; }, }); // 2. 定义资源可以是静态文本、动态生成的HTML或数据流。 server.resource(weather_dashboard, { uri: dashboard://weather/overview, name: 天气概览仪表板, description: 一个展示多个城市天气状况的交互式仪表板。, mimeType: text/html, // 可以是 application/json, text/plain 等 fetch: async () { // 可以在这里生成HTML或者返回JSON数据 const html await generateDashboardHTML(); return { contents: [ { uri: dashboard://weather/overview, mimeType: text/html, text: html, }, ], }; }, }); // 3. 启动服务器 const port process.env.PORT || 3000; server.listen(port, () { console.log( MCP服务器运行在 http://localhost:${port}); console.log( 调试器地址 http://localhost:${port}/inspector); });注意事项工具execute方法的返回值。必须返回一个符合MCP协议ToolResult格式的对象。content数组是核心它可以包含text、image、resource等多种类型。确保返回的数据结构清晰便于LLM理解和后续处理。复杂的嵌套对象建议转换成易于阅读的文本格式。3.2mcp-use/cli提升开发效率的引擎CLI工具是流畅开发体验的核心。它不仅仅是一个启动脚本而是一个集成了构建、开发服务器、文件监听和工具链的完整环境。核心工作流解析当你运行mcp-use dev时CLI在背后做了以下几件事类型检查与编译使用tsup或esbuild可配置在内存中编译TypeScript速度极快。启动开发服务器启动一个支持SSE和HTTP的服务器承载你的MCP端点(/mcp)和调试器(/inspector)。注入热重载中间件监听项目文件.ts,.tsx,.js,.jsx的变化。一旦检测到更改会优雅地重启MCP服务器进程保持SSE连接不断开如果可能。通过WebSocket向前端调试器(/inspector)发送更新通知实现UI的实时刷新。自动打开浏览器启动后自动在默认浏览器中打开调试器页面。生产构建与优化mcp-use build命令负责生成可用于生产环境的代码。Tree Shaking只打包你实际用到的mcp-useAPI减小捆绑包体积。资源处理将resources/目录下的React组件单独构建为优化的、自包含的HTML或JavaScript文件。环境变量注入安全地处理process.env。输出结构生成清晰的dist/目录包含服务器入口文件和静态资源。一个高级的mcp-use.config.ts配置示例可能如下import { defineConfig } from mcp-use/cli; export default defineConfig({ server: { entry: ./src/server.ts, outDir: ./dist, format: esm, // 或 cjs minify: true, sourcemap: process.env.NODE_ENV development, // 开发环境生成sourcemap }, resources: { entryDir: ./resources, outDir: ./dist/resources, // 将React组件构建为静态HTML render: static, }, inspector: { enabled: process.env.NODE_ENV ! production, // 生产环境关闭调试器 path: /_debug, // 自定义调试器路径 }, });3.3mcp-use/inspector可视化的协议调试器Inspector是开发过程中不可或缺的“眼睛”。它提供了一个图形化界面来探索、测试和监控你的MCP服务器。核心功能深度体验工具交互式测试界面左侧会列出服务器注册的所有工具。点击任一工具右侧会基于Zod schema自动生成一个参数表单。填写参数并点击“Execute”下方会实时显示原始的协议请求、响应以及工具执行结果。这对于调试复杂参数和验证工具逻辑是否正确至关重要。资源预览与订阅可以查看所有已声明的资源列表。对于text/html或text/plain类型的资源可以直接在界面内预览内容。如果资源支持订阅subscribe可以建立实时数据流观察数据变化。连接与会话管理清晰显示当前连接的传输方式SSE/WebSocket和状态。会话信息如OAuth token会保存在浏览器的localStorage中刷新页面后依然存在。可以手动初始化连接、断开连接模拟客户端行为。请求/响应日志所有通过Inspector发起的MCP协议消息都会被记录下来形成一个可追溯的日志面板。可以查看每条消息的详细JSON结构对于理解协议交互细节非常有帮助。集成方式除了框架自动挂载你也可以手动将其集成到任何Express或类似框架的应用中import express from express; import { mountInspector } from mcp-use/inspector/express; const app express(); // ... 你的其他路由和中间件 // 将Inspector挂载到特定路径 mountInspector(app, { path: /admin/debug, // 自定义访问路径 // 可以添加认证中间件保护调试界面 authMiddleware: (req, res, next) { if (req.headers[x-debug-key] process.env.DEBUG_SECRET) { next(); } else { res.status(403).send(Forbidden); } }, }); app.listen(3000);3.4create-mcp-use-app标准化项目起点这个脚手架工具解决了“如何开始”的问题。它提供了预设的项目模板确保最佳实践从第一天起就被遵循。npx create-mcp-use-app my-ai-assistant执行后你会得到一个结构清晰、配置完备的项目my-ai-assistant/ ├── src/ │ ├── index.ts # MCP服务器主入口 │ ├── tools/ # 工具定义模块 │ │ ├── weather.ts │ │ └── calculator.ts │ └── resources/ # UI资源组件 │ └── dashboard.tsx ├── resources/ # 同src/resources/CLI会从这里构建 ├── public/ # 静态资源如图片 ├── mcp-use.config.ts # 框架配置文件 ├── package.json # 预置了dev, build, start脚本 ├── tsconfig.json # 优化的TypeScript配置 └── .env.example # 环境变量示例模板选择脚手架通常提供basic和advanced两种模板。basic模板包含最简化的工具和资源示例适合快速上手。advanced模板则可能包含数据库集成Prisma/Drizzle、用户认证NextAuth.js、Docker配置和CI/CD流水线示例适合用于启动正式项目。4. 实战构建一个智能数据分析助手让我们通过一个完整的例子串联起mcp-use的所有核心概念。我们将构建一个“智能数据分析助手”它能够连接数据库执行查询并将结果通过一个交互式图表UI展示出来。4.1 项目初始化与架构设计首先创建项目并选择高级模板npx create-mcp-use-app>import { z } from zod; import { pool } from ../lib/db; // 假设使用pg库 import { tool } from mcp-use/server; // 使用工具工厂函数便于组织和管理 export const databaseTools { run_sql_query: tool({ name: 执行SQL查询, description: 在指定的数据库上执行一个只读的SQL查询语句。禁止执行DROP, DELETE, UPDATE等写操作。, parameters: z.object({ query: z.string().describe(只读的SQL SELECT查询语句。), database: z.enum([analytics, production]).describe(目标数据库。), }), execute: async ({ query, database }) { // 安全校验阻止写操作 const lowerQuery query.toLowerCase().trim(); const writeKeywords [insert, update, delete, drop, alter, create, truncate]; if (writeKeywords.some(keyword lowerQuery.startsWith(keyword))) { throw new Error(安全策略禁止执行写操作${query}); } const client await pool.connect(); try { // 在实际项目中这里会根据 database 参数切换到不同的连接池 const result await client.query(query); return { content: [{ type: text, text: 查询成功返回 ${result.rowCount} 行数据。\n 列名${result.fields.map(f f.name).join(, )}\n 前5行示例\n${JSON.stringify(result.rows.slice(0, 5), null, 2)} }], // 也可以将原始数据作为结构化内容返回供UI资源使用 _meta: { rows: result.rows, fields: result.fields } }; } finally { client.release(); } }, }), get_table_schema: tool({ name: 获取表结构, description: 获取指定数据表的列名、数据类型和描述信息。, parameters: z.object({ tableName: z.string().describe(需要查看结构的表名。), }), execute: async ({ tableName }) { // 查询系统表或信息模式来获取表结构 const schemaQuery SELECT column_name, data_type, is_nullable, column_default FROM information_schema.columns WHERE table_name $1 ORDER BY ordinal_position; ; const result await pool.query(schemaQuery, [tableName]); // ... 格式化输出 }, }), };src/index.ts- 服务器主文件import { createMCPServer } from mcp-use/server; import { databaseTools } from ./tools/database; import { chartTools } from ./tools/chart; import AnalyticsDashboard from ../resources/AnalyticsDashboard; // 这是一个React组件 const server createMCPServer(data-analyst-server, { version: 1.0.0, description: 智能数据分析助手后端服务, }); // 注册所有工具 Object.values(databaseTools).forEach(toolDef server.registerTool(toolDef)); Object.values(chartTools).forEach(toolDef server.registerTool(toolDef)); // 注册一个动态资源数据分析仪表板 // 注意这里传递的是组件引用CLI在构建时会处理它 server.resource(analytics_dashboard, { uri: resource://analytics/dashboard, name: 数据分析仪表板, mimeType: text/html, // fetch 方法在资源被请求时调用。在开发模式下它可能返回一个指向热重载开发服务器的URL。 // 在生产构建后它会返回构建好的静态HTML。 fetch: async () { // 在实际框架中这里通常由CLI的构建插件自动处理。 // 我们返回一个指示告诉客户端这是一个UI资源。 return { contents: [{ uri: resource://analytics/dashboard, mimeType: text/html, // 这里可以嵌入初始数据或配置 text: div idroot/divscript src/resources/analytics_dashboard.js/script }] }; }, }); // 启动服务器 const PORT process.env.PORT || 3000; server.listen(PORT, () { console.log(✅ MCP服务器已启动: http://localhost:${PORT}); console.log( 调试器: http://localhost:${PORT}/inspector); console.log( 仪表板: http://localhost:${PORT}/resources/analytics_dashboard); });4.3 实现UI资源组件resources/AnalyticsDashboard.tsx这是一个React组件它使用mcp-use/react包提供的钩子来与MCP服务器通信。import React, { useState, useEffect } from react; import { useMcp, useMcpResource } from mcp-use/react; import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, Legend } from recharts; const AnalyticsDashboard: React.FC () { const { callTool, status: connectionStatus } useMcp(); const [query, setQuery] useState(SELECT date, revenue FROM daily_sales ORDER BY date); const [chartData, setChartData] useStateany[]([]); const [loading, setLoading] useState(false); const [error, setError] useStatestring | null(null); const executeQuery async () { setLoading(true); setError(null); try { const result await callTool(run_sql_query, { query, database: analytics }); // 假设result._meta.rows包含了查询结果 if (result._meta?.rows) { setChartData(result._meta.rows); } } catch (err: any) { setError(err.message); } finally { setLoading(false); } }; useEffect(() { // 组件加载时执行一个默认查询 executeQuery(); }, []); return ( div style{{ padding: 2rem, fontFamily: sans-serif }} h1智能数据分析仪表板/h1 p连接状态: {connectionStatus}/p div style{{ marginBottom: 2rem }} textarea value{query} onChange{(e) setQuery(e.target.value)} rows{4} style{{ width: 100%, fontFamily: monospace }} / button onClick{executeQuery} disabled{loading} {loading ? 执行中... : 执行查询} /button {error div style{{ color: red }}错误: {error}/div} /div {chartData.length 0 ( div h2销售趋势图/h2 LineChart width{800} height{400} data{chartData} CartesianGrid strokeDasharray3 3 / XAxis dataKeydate / YAxis / Tooltip / Legend / Line typemonotone dataKeyrevenue stroke#8884d8 / /LineChart div h3数据预览 ({chartData.length} 行)/h3 pre{JSON.stringify(chartData.slice(0, 5), null, 2)}/pre /div /div )} /div ); }; export default AnalyticsDashboard;4.4 创建与运行智能体src/agent/index.tsimport { MCPClient, MCPAgent } from mcp-use; import { ChatOpenAI } from langchain/openai; import * as dotenv from dotenv; dotenv.config(); async function main() { // 连接到我们刚刚创建的本地服务器 const client new MCPClient({ transport: await createSSETransport(new URL(http://localhost:3000/sse)), }); const agent new MCPAgent({ llm: new ChatOpenAI({ model: gpt-4, temperature: 0.1, // 较低的温度使输出更确定适合执行操作 apiKey: process.env.OPENAI_API_KEY, }), client, maxSteps: 8, // 可以配置系统提示词引导智能体行为 systemPrompt: 你是一个专业的数据分析师助手。你可以使用SQL查询工具来获取数据。 用户可能会用自然语言描述他们的需求你需要将其转化为合适的SQL查询。 注意你只能执行只读查询SELECT。如果用户要求修改数据请礼貌拒绝并解释。 在返回结果时尽量将数据以清晰、易于理解的方式总结给用户。 }); console.log( 智能数据分析助手已启动。输入您的问题输入“退出”结束:); // 简单的命令行交互循环 const readline require(readline).createInterface({ input: process.stdin, output: process.stdout }); const askQuestion () { readline.question( , async (userInput: string) { if (userInput.toLowerCase() 退出) { readline.close(); process.exit(0); } try { console.log(思考中...); const result await agent.run(userInput); console.log(助手:, result.finalOutput); } catch (error) { console.error(执行出错:, error); } askQuestion(); // 继续下一个问题 }); }; askQuestion(); } main().catch(console.error);现在你可以打开三个终端npm run dev启动MCP服务器和调试器。运行node dist/agent/index.js启动智能体交互命令行。打开浏览器访问http://localhost:3000/resources/analytics_dashboard查看交互式仪表板。在智能体终端你可以输入“帮我查看最近一周的每日销售额趋势。” 智能体会自动调用run_sql_query工具获取数据并生成回答。同时仪表板页面也会因为工具调用而更新图表数据。5. 高级特性、问题排查与性能优化5.1 流式响应与AI SDK集成对于需要长时间运行或逐步返回结果的任务流式响应至关重要。mcp-use与Vercel的AI SDK等现代流式响应库深度集成。// 在Next.js API Route中的示例 import { streamEventsToAISDKWithTools } from mcp-use; import { MCPAgent } from mcp-use; import { ChatOpenAI } from langchain/openai; import { streamText } from ai; export async function POST(req: Request) { const { messages } await req.json(); const agent new MCPAgent({ llm: new ChatOpenAI({ model: gpt-4, streaming: true }), client: yourMCPClient, }); // 1. 使用LangChain的streamEvents const eventStream await agent.streamEvents(messages, { version: v2 }); // 2. 转换为AI SDK兼容的流 const toolStream streamEventsToAISDKWithTools(eventStream); // 3. 使用AI SDK的streamText返回流式响应 return streamText({ model: yourAISDKModel, // 这里可能需要一个适配器 messages, // 将工具流注入到AI SDK的响应中 experimental_transform: async (input) { // ... 处理工具调用和流式文本的合并逻辑 return input; }, }); }注意事项流式传输的复杂性。合并工具调用事件和文本生成流需要仔细处理。streamEventsToAISDKWithTools这个工具函数帮你处理了大部分脏活但你仍需理解底层的事件结构如on_chat_model_streamon_tool_starton_tool_end以便在UI前端正确解析和渲染。5.2 错误处理与健壮性设计在生产环境中健壮的错误处理是必须的。服务器端工具错误处理server.tool(risky_operation, { // ... execute: async (params) { try { // 业务逻辑 const result await someExternalAPI(params); return { content: [{ type: text, text: 成功: ${result} }] }; } catch (error: any) { // 返回结构化的错误信息而非抛出异常让客户端能优雅处理 return { content: [{ type: text, text: 操作失败。原因: ${error.message} }], isError: true, // MCP协议中的错误标志 // 可附加调试信息生产环境应过滤敏感信息 _meta: { errorCode: error.code } }; } } });客户端调用错误处理try { const result await agent.run(执行一个可能失败的任务); if (result.isError) { console.warn(工具执行报错:, result.content[0].text); // 可以尝试备用方案或通知用户 } } catch (agentError) { // 这里是智能体层面的错误如LLM调用失败、超时、步骤超限等 console.error(智能体运行失败:, agentError); // 实现降级策略例如返回一个缓存结果或通用回复 }5.3 常见问题排查实录问题1启动npm run dev后Inspector页面空白或无法连接。检查点1端口占用。确认3000端口未被其他程序占用。可通过lsof -i :3000Mac/Linux或netstat -ano | findstr :3000Windows检查。检查点2服务器日志。查看运行dev命令的终端输出确认MCP服务器是否成功启动以及SSE端点(/sse)和Inspector端点(/inspector)是否正常注册。检查点3浏览器控制台。打开浏览器开发者工具查看Network和Console标签页确认是否有JS加载错误或网络请求失败。解决方案通常重启开发服务器或清除浏览器缓存即可解决。确保你的src/index.ts中没有语法错误导致服务器启动失败。问题2智能体无法识别或调用我定义的工具。检查点1工具注册。确认在服务器代码中正确调用了server.tool()或server.registerTool()并且没有在listen()之后才注册工具。检查点2工具描述和参数Schema。检查description是否清晰parameters的Zod Schema是否正确。过于模糊的描述或复杂的嵌套Schema可能导致LLM无法正确理解和使用工具。检查点3客户端连接。确认MCPClient连接到了正确的服务器URL。使用Inspector页面测试工具是否能被手动调用成功。检查点4LLM的系统提示词。有时需要在给智能体的系统提示词中明确告知可用的工具列表及其用途。问题3UI资源组件React热重载不工作。检查点1文件位置。确保React组件文件放在resources/目录或mcp-use.config.ts中配置的对应目录下。检查点2导入方式。在服务器代码中注册资源时确保导入的是组件本身如import MyWidget from ../resources/MyWidget而不是字符串路径。检查点3CLI配置。检查mcp-use.config.ts中resources部分的配置是否正确特别是entryDir和outDir。解决方案尝试手动停止dev进程并重新运行。确保你使用的是mcp-use的最新版本。问题4生产环境构建后资源路径404。检查点1构建输出。运行npm run build后检查dist/resources/目录下是否有生成的.html或.js文件。检查点2服务器静态文件服务。mcp-use的生产服务器默认会服务dist/resources/下的文件。确认你的生产服务器如Nginx、Docker容器正确地将静态资源请求代理到了该目录。检查点3资源URI。在代码中定义的资源uri如resource://my/widget与最终访问的URL路径如/resources/my_widget之间的映射关系由框架内部处理。如果自定义了服务器或路由需要确保映射关系一致。5.4 性能优化与部署建议连接池与复用对于数据库、外部API客户端等在服务器生命周期内创建连接池并复用避免为每个工具调用创建新连接。工具懒加载如果工具数量很多可以考虑动态加载工具模块减少服务器启动时的初始化时间。智能体超时与限流在MCPAgent配置中设置合理的timeout和maxSteps。在服务器层面考虑对工具调用进行限流Rate Limiting防止滥用。生产环境关闭Inspector通过环境变量NODE_ENVproduction或配置inspector: { enabled: false }来禁用调试界面避免安全风险。使用Docker容器化advanced项目模板通常包含Dockerfile。使用多阶段构建可以减小镜像体积。# Dockerfile 示例 FROM node:20-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build FROM node:20-alpine AS runner WORKDIR /app COPY --frombuilder /app/dist ./dist COPY --frombuilder /app/package.json ./ # 只安装生产依赖 RUN npm ci --onlyproduction ENV NODE_ENVproduction EXPOSE 3000 CMD [node, dist/index.js]监控与日志集成像Langfuse这样的LLM可观测性平台或者使用pino、winston等日志库记录工具调用、智能体决策过程便于问题追溯和性能分析。mcp-use框架通过将MCP协议的强大能力与一流的开发者体验相结合为构建生产级的AI智能体应用提供了一个坚实、高效且愉悦的基础。从快速原型到复杂系统它都能显著降低开发复杂度让你更专注于创造价值本身。