关键词

LLM应用开发AI工具接入Next.js后端上下文服务Vercel部署

项目简介

@vercel/mcp-adapter 是一个专为 Vercel 和 Next.js 环境设计的适配器，旨在帮助开发者轻松地将 Model Context Protocol (MCP) 服务器集成到他们的现代 Web 应用中。它提供了一个标准化的方式来注册和暴露应用程序的工具 (Tools)、资源 (Resources) 和 Prompt 模板 (Prompts)，以便 LLM 客户端（如 Claude Desktop, Cursor, Windsurf 等）能够发现和使用这些能力。

主要功能点

  • 框架集成: 紧密集成 Next.js 的 App Router 路由处理机制，简化 MCP 服务器的部署流程。
  • 多传输协议支持: 支持 Streamable HTTP 和 Server-Sent Events (SSE) 两种 MCP 客户端常用的通信协议。
  • 工具注册: 允许您定义和注册自定义的工具，LLM 可以通过 MCP 协议调用这些工具来执行特定任务（例如查询数据、执行操作）。
  • 状态管理优化: 可选地集成 Redis，为 SSE 传输提供更稳定的连接和消息处理能力，适用于无状态的环境如 Vercel Functions。
  • 会话与请求处理: 负责接收和处理来自 MCP 客户端的 JSON-RPC 请求，并调度到您注册的功能实现。
  • 能力声明: 根据您注册的工具、资源等，向客户端声明服务器提供的能力。

安装步骤

在您的 Next.js 项目根目录下，使用以下任一包管理器命令安装 '@vercel/mcp-adapter' 和必要的依赖 'zod'：

npm install @vercel/mcp-adapter zod
# 或者
yarn add @vercel/mcp-adapter zod
# 或者
pnpm add @vercel/mcp-adapter zod
# 或者
bun add @vercel/mcp-adapter zod

服务器配置 (给MCP客户端用的)

MCP 客户端（如 Claude Desktop, Cursor, Windsurf）需要知道如何连接到您的 MCP 服务器。通常，这通过在客户端的配置文件中指定服务器的启动命令和参数来完成。对于使用 '@vercel/mcp-adapter' 构建的服务器，标准的连接方式是通过 'npx mcp-remote' 这个辅助工具，它负责将客户端的通信桥接到您的 HTTP/SSE MCP 接口。

您需要在客户端的配置文件中添加一个服务器条目，示例如下（具体格式请参考您的 MCP 客户端文档）：

{
  // ... 其他配置
  "remote-example": { // "remote-example" 是您给这个服务器起的名字
    "command": "npx",
    "args": [
      "mcp-remote",
      "http://localhost:3000/api/mcp" // **重要**: 这是您的 MCP 服务器实际运行的 URL
    ]
  }
  // ... 其他服务器条目
}
  • 'command': 设置为 '"npx"'。
  • 'args': 这是一个数组。第一个元素是 '"mcp-remote"'，第二个元素是您的 MCP 服务器的访问 URL。
    • 本地开发时: 通常是 'http://localhost:端口/您的basePath'。例如，如果您的 Next.js 开发服务器运行在 3000 端口，并且您在路由中设置了 'basePath: '/api''，则 URL 可能是 'http://localhost:3000/api/mcp'。
    • 部署到 Vercel 后: 这是您的 Vercel 应用的实际部署 URL 加上您配置的 'basePath'。例如 'https://您的应用名.vercel.app/api/mcp'。

客户端通过执行这个 'command' 和 'args' 来启动一个进程，该进程会连接到您指定的服务器 URL。

基本使用方法

  1. 在您的 Next.js 项目中，创建 MCP 路由文件。推荐使用 App Router 并在 'app/api/[transport]/route.ts' 创建文件。'[transport]' 是一个动态路由参数，用于处理 '/api/mcp', '/api/sse', '/api/message' 等不同的传输路径。
  2. 在该路由文件中，导入 'createMcpHandler' 函数。
  3. 调用 'createMcpHandler'，传入一个函数来初始化您的 MCP 服务器（在此注册工具、资源等），以及可选的服务器和适配器配置。
  4. 将返回的 'handler' 函数导出为 'GET' 和 'POST' 方法。

示例 ('app/api/[transport]/route.ts'):

import { createMcpHandler } from '@vercel/mcp-adapter';
import { z } from 'zod'; // MCP SDK 通常与 zod 配合用于参数校验

const handler = createMcpHandler(
  // 这个函数用于初始化服务器实例
  server => {
    // 在这里注册您的工具、资源、Prompt等
    server.tool(
      'roll_dice', // 工具名称
      'Rolls an N-sided die', // 工具描述
      { // 输入参数 schema (使用 zod 定义)
        sides: z.number().int().min(2).describe('The number of sides on the die')
      },
      async ({ sides }) => { // 工具的实现函数
        const value = 1 + Math.floor(Math.random() * sides);
        // 返回结果，通常是 content 数组
        return {
          content: [{ type: 'text', text: '🎲 You rolled a ${value}!' }],
        };
      }
    );

    // 您可以在这里注册更多工具、资源、Prompt等
    // server.resource(...)
    // server.prompt(...)
  },
  // 可选：McpServer 自身的配置选项
  {
    // 例如：capabilities: { streams: true }
  },
  // 可选：@vercel/mcp-adapter 适配器的配置
  {
    redisUrl: process.env.REDIS_URL, // 如果使用 SSE 且需要 Redis，配置 Redis URL
    basePath: '/api', // 与您的路由路径匹配，例如 /app/api/[transport]/route.ts -> '/api'
    maxDuration: 60, // 请求的最大时长 (秒)
    verboseLogs: true, // 开启详细日志
  }
);

// 将 handler 导出，以处理 GET 和 POST 请求
export { handler as GET, handler as POST };

配置 'basePath' 是一个重要选项。它定义了 MCP 接口的根路径。如果您将文件放在 'app/api/[transport]/route.ts'，通常 'basePath' 就应该设置为 '/api'。适配器会根据 'basePath' 自动推导出 Streamable HTTP ('/api/mcp')、SSE ('/api/sse') 和 SSE Message ('/api/message') 的具体访问路径。

部署到 Vercel 后，您的 MCP 服务器将通过 'https://您的应用名.vercel.app/api/[transport]' 提供服务（根据您的 'basePath' 设置）。您需要将这个最终 URL 配置到您的 MCP 客户端中。

信息

分类

AI与计算

访问项目