关键词

AI模型集成LLM上下文服务Next.js后端Nuxt后端工具API

项目简介

'mcp-handler' 是一个功能强大的库，旨在帮助开发者在 Vercel 平台上，特别是针对 Next.js 和 Nuxt 等流行的 Web 框架，轻松构建和部署 Model Context Protocol (MCP) 服务器。它将您的应用程序转变为一个能够向大型语言模型 (LLM) 提供标准化上下文信息和功能的服务后端，实现 AI 模型与应用程序之间的高效实时通信。

主要功能点

  • 工具注册与调用： 允许您在服务器端定义和注册各种工具（Functions），AI 模型可以通过这些工具调用外部功能，例如执行数据库查询、API 请求或任何自定义业务逻辑。
  • 上下文提供： 以结构化和标准化的方式，向 LLM 客户端提供丰富的上下文信息，确保 AI 模型在交互中拥有准确和最新的数据。
  • 多传输协议支持： 支持多种通信协议，包括基于 HTTP Stream 的传输和 Server-Sent Events (SSE)，以适应不同的客户端和部署场景。
  • 会话管理： 维护 AI 模型与您的服务器之间的会话状态，支持更长、更复杂的交互。
  • 授权与安全： 提供符合 OAuth 2.0 规范的认证和权限管理机制，确保只有授权的客户端才能访问您的 MCP 服务和工具。
  • 框架集成： 提供针对 Next.js (App Router) 和 Nuxt 的开箱即用适配器，未来计划支持更多 Web 框架。

安装步骤

在您的 Next.js 或 Nuxt 项目中，打开终端并运行以下命令，使用您偏好的包管理器安装 'mcp-handler' 及其必要的依赖：

npm install mcp-handler @modelcontextprotocol/sdk zod@^3
# 或
yarn add mcp-handler @modelcontextprotocol/sdk zod@^3
# 或
pnpm add mcp-handler @modelcontextprotocol/sdk zod@^3
# 或
bun add mcp-handler @modelcontextprotocol/sdk zod@^3

服务器配置（MCP客户端视角）

要让 MCP 客户端（例如 Claude Desktop、Cursor、Windsurf 等）连接到您的 'mcp-handler' 服务器，您需要向客户端提供连接信息。以下是一个配置示例的说明，它指导客户端如何通过 'mcp-remote' 代理工具连接到您的 MCP 服务器。

请将 'http://localhost:3000/api/mcp' 替换为您的实际服务器部署地址和 MCP 接口路径。

MCP 客户端配置说明：

  • 服务器名称 (e.g., "remote-example")： 您为这个 MCP 服务器实例定义的易于识别的名称，客户端会使用此名称来显示和管理您的服务器。
  • 命令 (command)： 客户端用于启动 MCP 服务器（或其代理）的执行命令。通常推荐使用 'npx'，因为它能够执行未全局安装的 Node.js 包。
  • 参数 (args)： 传递给 'command' 的参数列表。
    • '-y'：这是一个 'npx' 参数，表示在执行时自动确认，避免命令行提示。
    • 'mcp-remote'：这是一个由 MCP 官方提供的代理工具，它的作用是将基于 Streamable HTTP 的 MCP 服务器通信转换为 MCP 客户端通常所需的标准输入/输出 (stdio) 方式。
    • 'http://localhost:3000/api/mcp'：这是您的 'mcp-handler' 服务器的实际网络地址，客户端的 'mcp-remote' 代理将连接到这个地址。您需要将 'localhost:3000' 替换为您应用部署后的实际域名或 IP 地址，并确保 '/api/mcp' 与您在 Next.js 或 Nuxt 中配置的路由路径相匹配。

请注意： 某些最新版本的 MCP 客户端可能已直接支持连接到 HTTP Streamable 或 SSE 端点，不再强制需要 'mcp-remote' 代理。在这种情况下，客户端配置中可能只需直接提供服务器的 URL 即可。

基本使用方法

以下是在 Next.js (App Router) 项目中创建一个 MCP 服务器路由的示例。您可以在 'app/api/[transport]/route.ts' 文件中实现它：

// app/api/[transport]/route.ts
import { createMcpHandler } from "mcp-handler";
import { z } from "zod"; // Zod 用于定义和验证工具参数

const handler = createMcpHandler(
  (server) => {
    // 在这里，您可以注册 MCP 服务器的各种功能，例如工具、资源、Prompt模板。
    // 以下是一个注册“掷骰子”工具的示例：
    server.tool(
      "roll_dice", // 工具的唯一名称
      "Rolls an N-sided die", // 工具的简要描述，供 AI 模型理解其功能
      {
        sides: z.number().int().min(2), // 定义工具接受的参数及其数据类型和验证规则
      },
      async ({ sides }) => { // 这是工具被调用时执行的异步函数
        const value = 1 + Math.floor(Math.random() * sides);
        return {
          content: [{ type: "text", text: '🎲 您掷出了 ${value} 点!' }], // 工具返回的结果
        };
      }
    );
    // 您可以在此处继续注册更多的工具、资源和Prompt。
  },
  {
    // 可选的 MCP 服务器配置选项，例如声明服务器的能力。
    // capabilities: { /* ... */ },
  },
  {
    // 可选的 mcp-handler 特定配置，例如 Redis 连接、日志设置和路由基础路径。
    redisUrl: process.env.REDIS_URL, // 用于 SSE 传输的 Redis 连接 URL
    basePath: "/api", // 您的 MCP 路由的基础路径，需要与文件结构保持一致
    maxDuration: 60, // MCP 请求的最大持续时间（秒）
    verboseLogs: true, // 启用详细的调试日志输出
  }
);

// 导出处理程序以响应客户端的 GET 和 POST 请求
export { handler as GET, handler as POST };

完成上述设置后，您的 MCP 客户端就可以通过配置中提供的 URL 连接到此服务器，并调用您定义的 'roll_dice' 等工具。

信息

分类

AI与计算

访问项目