基于MCP协议的全栈TypeScript框架：构建AI智能体应用

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和工具之间插入了一个标准化的抽象层。它定义了三个核心概念：

1. 工具：LLM可以调用的函数，有明确的输入输出模式。
2. 资源：LLM可以读取的静态或动态内容，如文档、网页、数据流。
3. 提示词模板：可复用的提示结构。

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：项目生成器，一键搭建包含示例的最佳实践项目结构。

这种一体化设计带来了几个显著优势：

1. 极佳的开发者体验：npm run dev一条命令，你就同时启动了服务器、开启了热重载、并打开了调试页面。
2. 强类型保障：从工具的参数定义（使用Zod）到客户端的调用，全程享受TypeScript的类型推断和自动补全。
3. 一致性：所有工具都遵循相同的模式和生命周期，降低了认知负担。
4. 开箱即用的高级功能：如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.2@mcp-use/cli：提升开发效率的引擎

CLI工具是流畅开发体验的核心。它不仅仅是一个启动脚本，而是一个集成了构建、开发服务器、文件监听和工具链的完整环境。

核心工作流解析

当你运行mcp-use dev时，CLI在背后做了以下几件事：

1. 类型检查与编译：使用tsup或esbuild（可配置）在内存中编译TypeScript，速度极快。
2. 启动开发服务器：启动一个支持SSE和HTTP的服务器，承载你的MCP端点(/mcp)和调试器(/inspector)。
3. 注入热重载中间件：监听项目文件（.ts,.tsx,.js,.jsx）的变化。一旦检测到更改，会：
   • 优雅地重启MCP服务器进程，保持SSE连接不断开（如果可能）。
   • 通过WebSocket向前端调试器(/inspector)发送更新通知，实现UI的实时刷新。
4. 自动打开浏览器：启动后自动在默认浏览器中打开调试器页面。

生产构建与优化

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.3@mcp-use/inspector：可视化的协议调试器

Inspector是开发过程中不可或缺的“眼睛”。它提供了一个图形化界面来探索、测试和监控你的MCP服务器。

核心功能深度体验：

1. 工具交互式测试：

   • 界面左侧会列出服务器注册的所有工具。
   • 点击任一工具，右侧会基于Zod schema自动生成一个参数表单。
   • 填写参数并点击“Execute”，下方会实时显示原始的协议请求、响应以及工具执行结果。
   • 这对于调试复杂参数和验证工具逻辑是否正确至关重要。

2. 资源预览与订阅：

   • 可以查看所有已声明的资源列表。
   • 对于text/html或text/plain类型的资源，可以直接在界面内预览内容。
   • 如果资源支持订阅（subscribe），可以建立实时数据流，观察数据变化。

3. 连接与会话管理：

   • 清晰显示当前连接的传输方式（SSE/WebSocket）和状态。
   • 会话信息（如OAuth token）会保存在浏览器的localStorage中，刷新页面后依然存在。
   • 可以手动初始化连接、断开连接，模拟客户端行为。

4. 请求/响应日志：

   • 所有通过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 id="root"></div><script 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] = useState<any[]>([]); const [loading, setLoading] = useState(false); const [error, setError] = useState<string | 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 strokeDasharray="3 3" /> <XAxis dataKey="date" /> <YAxis /> <Tooltip /> <Legend /> <Line type="monotone" dataKey="revenue" 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.ts

import { 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);

现在，你可以打开三个终端：

1. npm run dev：启动MCP服务器和调试器。
2. 运行node dist/agent/index.js：启动智能体交互命令行。
3. 打开浏览器访问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_stream，on_tool_start，on_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 :3000（Mac/Linux）或netstat -ano | findstr :3000（Windows）检查。
• 检查点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页面测试工具是否能被手动调用成功。
• 检查点4：LLM的系统提示词。有时需要在给智能体的系统提示词中明确告知可用的工具列表及其用途。

问题3：UI资源组件（React）热重载不工作。

• 检查点1：文件位置。确保React组件文件放在resources/目录（或mcp-use.config.ts中配置的对应目录）下。
• 检查点2：导入方式。在服务器代码中注册资源时，确保导入的是组件本身（如import MyWidget from '../resources/MyWidget'），而不是字符串路径。
• 检查点3：CLI配置。检查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 性能优化与部署建议

1. 连接池与复用：对于数据库、外部API客户端等，在服务器生命周期内创建连接池并复用，避免为每个工具调用创建新连接。
2. 工具懒加载：如果工具数量很多，可以考虑动态加载工具模块，减少服务器启动时的初始化时间。
3. 智能体超时与限流：在MCPAgent配置中设置合理的timeout和maxSteps。在服务器层面，考虑对工具调用进行限流（Rate Limiting），防止滥用。
4. 生产环境关闭Inspector：通过环境变量NODE_ENV=production或配置inspector: { enabled: false }来禁用调试界面，避免安全风险。
5. 使用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 --from=builder /app/dist ./dist COPY --from=builder /app/package.json ./ # 只安装生产依赖 RUN npm ci --only=production ENV NODE_ENV=production EXPOSE 3000 CMD ["node", "dist/index.js"]

6. 监控与日志：集成像Langfuse这样的LLM可观测性平台，或者使用pino、winston等日志库，记录工具调用、智能体决策过程，便于问题追溯和性能分析。

mcp-use框架通过将MCP协议的强大能力与一流的开发者体验相结合，为构建生产级的AI智能体应用提供了一个坚实、高效且愉悦的基础。从快速原型到复杂系统，它都能显著降低开发复杂度，让你更专注于创造价值本身。