当前位置：首页 > news >正文

【MCP Node.js SDK 全栈进阶指南】中级篇（6）：MCP与Web框架集成

news 来源：原创 2025/6/8 19:14:17

背景

在现代Web开发生态中，框架已成为构建高效、可维护应用的核心基础设施。将MCP TypeScript-SDK与流行的Web框架集成，能够充分发挥两者的优势，构建功能丰富、交互智能的现代应用。本文将深入探讨MCP与主流Web框架的集成方法、最佳实践和架构设计，帮助开发者构建强大而灵活的全栈MCP应用。

Express集成最佳实践
1.1 Express与MCP的架构契合点
1.2 基于Express构建MCP API服务
1.3 中间件开发与集成
1.4 性能优化与部署策略
Next.js中的MCP服务
2.1 Next.js与MCP的架构融合
2.2 服务器端组件中的MCP集成
2.3 API路由与MCP服务
2.4 Edge运行时与MCP
前端组件与MCP交互
3.1 React组件设计模式
3.2 Vue.js集成方案
3.3 状态管理与MCP数据流
3.4 响应式UI与实时更新
全栈MCP应用架构
4.1 架构设计原则与模式
4.2 数据流设计
4.3 认证与权限设计
4.4 部署与DevOps策略

1. Express集成最佳实践

Express作为Node.js生态中使用最广泛的Web框架之一，其简洁、灵活的特性与MCP TypeScript-SDK有着天然的契合点。在本节中，我们将探讨如何将MCP服务优雅地集成到Express应用中，并分享一系列实用的最佳实践。

1.1 Express与MCP的架构契合点

Express和MCP在架构设计上有多个契合点，使它们能够无缝协作：

import express from 'express';
import { McpServer } from '@modelcontextprotocol/sdk';
import { createServer } from 'http';// 架构契合点分析
interface ArchitecturalCompatibilityPoint {aspect: string;expressFeature: string;mcpFeature: string;synergy: string;
}const compatibilityPoints: ArchitecturalCompatibilityPoint[] = [{aspect: "中间件模式",expressFeature: "请求处理管道",mcpFeature: "MCP中间件支持",synergy: "可通过Express中间件预处理MCP请求，处理认证、日志等横切关注点"},{aspect: "路由机制",expressFeature: "URL路由系统",mcpFeature: "资源与工具路由",synergy: "可将MCP资源映射到Express路由系统，实现统一的API架构"},{aspect: "错误处理",expressFeature: "集中式错误处理中间件",mcpFeature: "标准化错误响应",synergy: "在Express错误处理中集成MCP错误，提供一致的错误响应"},{aspect: "可扩展性",expressFeature: "插件生态系统",mcpFeature: "动态资源与工具注册",synergy: "可动态扩展MCP功能并通过Express路由暴露"}
];// Express应用实例
const app = express();
const httpServer = createServer(app);// MCP服务器实例
const mcpServer = new McpServer({name: "express-mcp-integration",description: "MCP服务与Express框架的集成演示",version: "1.0.0"
});// 两者的生命周期管理可以协调一致
async function startServers() {// 先初始化MCP服务await mcpServer.initialize();// 启动HTTP服务器const PORT = process.env.PORT || 3000;httpServer.listen(PORT, () => {console.log(`Express服务器运行在 http://localhost:${PORT}`);console.log(`MCP服务已初始化并集成`);});
}// 优雅关闭
process.on('SIGTERM', async () => {console.log('正在关闭服务...');await mcpServer.shutdown();httpServer.close(() => {console.log('服务已安全关闭');process.exit(0);});
});startServers().catch(console.error);

这种集成方式使Express可以处理常规HTTP请求，而MCP可以处理AI相关的交互，两者互不干扰又能协同工作。

1.2 基于Express构建MCP API服务

下面我们将展示如何构建一个结合Express和MCP的API服务，包括路由设计、请求处理和响应格式化：

import express from 'express';
import { json, urlencoded } from 'body-parser';
import cors from 'cors';
import { McpServer, ResourceTemplate, Tool } from '@modelcontextprotocol/sdk';
import { z } from 'zod';const app = express();
const mcpServer = new McpServer({name: "mcp-express-api",description: "MCP与Express集成的API服务",version: "1.0.0"
});// 配置Express中间件
app.use(cors());
app.use(json());
app.use(urlencoded({ extended: true }));// MCP资源模板定义
const userResourceTemplate: ResourceTemplate = {name: "users",description: "用户资源",schema: z.object({id: z.string(),name: z.string(),email: z.string().email(),role: z.enum(["admin", "user", "guest"])})
};// MCP工具定义
const calculatorTool: Tool = {name: "calculator",description: "执行基本数学计算",parameters: z.object({operation: z.enum(["add", "subtract", "multiply", "divide"]),a: z.number(),b: z.number()}),execute: async ({ operation, a, b }) => {switch (operation) {case "add": return { result: a + b };case "subtract": return { result: a - b };case "multiply": return { result: a * b };case "divide": if (b === 0) throw new Error("除数不能为零");return { result: a / b };}}
};// 注册MCP资源和工具
mcpServer.registerResourceTemplate(userResourceTemplate);
mcpServer.registerTool(calculatorTool);// 用户数据存储（示例）
const users = [{ id: "1", name: "张三", email: "zhangsan@example.com", role: "admin" },{ id: "2", name: "李四", email: "lisi@example.com", role: "user" }
];// Express路由 - REST API端点
app.get('/api/users', (req, res) => {res.json({ users });
});app.get('/api/users/:id', (req, res) => {const user = users.find(u => u.id === req.params.id);if (!user) return res.status(404).json({ error: "用户不存在" });res.json({ user });
});// Express路由 - MCP API端点
app.post('/api/mcp/resources/:name', async (req, res) => {try {const resourceName = req.params.name;let result;// 根据资源名称处理不同资源if (resourceName === "users") {result = users;} else {return res.status(404).json({ error: "资源不存在" });}res.json({ success: true, data: result });} catch (error) {res.status(500).json({ success: false, error: error instanceof Error ? error.message : "未知错误" });}
});app.post('/api/mcp/tools/:name', async (req, res) => {try {const toolName = req.params.name;const params = req.body;if (toolName === "calculator") {// 直接使用MCP工具const result = await mcpServer.executeTool(toolName, params);res.json({ success: true, data: result });} else {res.status(404).json({ error: "工具不存在" });}} catch (error) {res.status(500).json({ success: false, error: error instanceof Error ? error.message : "未知错误" });}
});// 启动服务
const PORT = process.env.PORT || 3000;async function startServer() {await mcpServer.initialize();app.listen(PORT, () => {console.log(`Express-MCP API服务运行在 http://localhost:${PORT}`);});
}startServer().catch(console.error);

这个示例展示了如何通过Express路由暴露MCP资源和工具，使它们可以通过RESTful API访问。对于前端应用，这提供了一种统一的方式来与MCP服务交互。

1.3 中间件开发与集成

Express的中间件架构是其最强大的特性之一，我们可以开发专用的中间件来增强MCP服务的功能：

import express from 'express';
import { McpServer } from '@modelcontextprotocol/sdk';
import { createServer } from 'http';
import morgan from 'morgan';
import helmet from 'helmet';
import rateLimit from 'express-rate-limit';const app = express();
const mcpServer = new McpServer({name: "mcp-middleware-demo",description: "演示MCP与Express中间件的集成",version: "1.0.0"
});// 1. 基础安全中间件
app.use(helmet()); // 设置各种HTTP头以增强安全性// 2. 日志中间件
app.use(morgan('combined')); // HTTP请求日志// 3. 请求限流中间件
const apiLimiter = rateLimit({windowMs: 15 * 60 * 1000, // 15分钟max: 100, // 每个IP在windowMs内的最大请求数standardHeaders: true,legacyHeaders: false
});
app.use('/api/', apiLimiter);// 4. MCP认证中间件
const mcpAuthMiddleware = (req, res, next) => {const apiKey = req.headers['x-api-key'];if (!apiKey || apiKey !== process.env.MCP_API_KEY) {return res.status(401).json({success: false,error: "未授权的访问"});}// 将认证信息附加到请求对象req.mcpAuth = { authenticated: true, timestamp: new Date() };next();
};// 5. MCP请求验证中间件
const mcpValidationMiddleware = (req, res, next) => {if (!req.body || typeof req.body !== 'object') {return res.status(400).json({success: false,error: "无效的请求格式"});}next();
};// 6. MCP性能监控中间件
const mcpPerformanceMiddleware = (req, res, next) => {const start = Date.now();// 在响应完成后记录性能指标res.on('finish', () => {const duration = Date.now() - start;console.log(`MCP请求 ${req.method} ${req.originalUrl} 耗时 ${duration}ms`);// 这里可以将性能数据发送到监控系统if (duration > 1000) {console.warn(`警告: MCP请求耗时超过1秒`);}});next();
};// 7. MCP错误处理中间件
const mcpErrorHandler = (err, req, res, next) => {console.error('MCP错误:', err);// 格式化错误响应res.status(err.status || 500).json({success: false,error: {message: err.message || "服务器内部错误",code: err.code || "INTERNAL_ERROR",details: process.env.NODE_ENV === 'production' ? undefined : err.stack}});
};// 应用MCP专用中间件到MCP路由
app.use('/api/mcp', [mcpAuthMiddleware,mcpValidationMiddleware, mcpPerformanceMiddleware
]);// MCP资源路由
app.post('/api/mcp/resources/:name', async (req, res, next) => {try {const resourceName = req.params.name;// 使用MCP服务器处理资源请求const result = await mcpServer.getResource(resourceName, req.body);res.json({ success: true, data: result });} catch (error) {next(error); // 传递给错误处理中间件

背景

目录

1. Express集成最佳实践

1.1 Express与MCP的架构契合点

1.2 基于Express构建MCP API服务

1.3 中间件开发与集成

相关文章：