使用说明

MCP服务器模板

用于构建的生产就绪模板模型上下文协议（MCP）使用Next.js和 mcp-handler 适配器。

概述

此模板提供了一种简化的方法来创建MCP服务器，这些服务器可以被ChatGPT、Claude、Cursor和其他MCP兼容客户端等AI代理使用。部署一次，连接到任何地方。

主要特点

🚀 一键部署 前往Vercel
🔧 轻松创建工具 使用Zod模式进行类型安全输入
🌐 可流式HTTP传输 实现高效的实时通信
📦 预配置 使用TypeScript、Tailwind CSS和Next.js 16
🎨 内置登录页面 带有设置说明

建筑学

┌─────────────────────────────────────────────────────────────────┐
│                        MCP Clients                              │
│  (ChatGPT, Claude, Cursor, Custom Agents)                       │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           │ HTTP (Streamable HTTP Transport)
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Next.js Application                          │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                     /mcp endpoint                         │  │
│  │  ┌─────────────────────────────────────────────────────┐  │  │
│  │  │              mcp-handler adapter                    │  │  │
│  │  │  • Tool registration                                │  │  │
│  │  │  • Request/response handling                        │  │  │
│  │  │  • Schema validation (Zod)                          │  │  │
│  │  └─────────────────────────────────────────────────────┘  │  │
│  │                          │                                │  │
│  │           ┌──────────────┴──────────────┐                 │  │
│  │           ▼                             ▼                 │  │
│  │    ┌────────────┐               ┌────────────────┐        │  │
│  │    │   echo     │               │ get_server_time│        │  │
│  │    │   tool     │               │     tool       │        │  │
│  │    └────────────┘               └────────────────┘        │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    / (Landing Page)                       │  │
│  │         Setup guide & MCP URL display                     │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

项目结构

mcp-server-template/
├── app/
│   ├── globals.css          # Global styles
│   ├── layout.tsx           # Root layout
│   ├── page.tsx             # Landing page with setup instructions
│   └── mcp/
│       └── route.ts         # ⭐ MCP server endpoint (add tools here)
├── components/
│   ├── theme-provider.tsx   # Dark/light theme support
│   └── ui/                  # Reusable UI components (shadcn/ui)
├── scripts/
│   └── test-streamable-http-client.ts   # Test client for local development
├── public/
│   └── images/              # Setup guide screenshots
├── package.json
└── README.md

快速开始

1.克隆和安装

git clone https://github.com/RitualChain/mcp-server-template.git
cd mcp-server-template
bun install

2.本地运行

bun dev

访问 http://localhost:3030 查看登录页面。

3.部署到Vercel

或者手动部署：

npx vercel

添加工具

工具定义见 app/mcp/route.tsThe createMcpHandler 函数有三个参数：

刀具注册功能 -异步功能，您可以使用该功能注册工具 server.tool()
能力 -服务器功能配置
选项 -运行时选项，如 maxDuration 和 basePath

工具定义

每个工具需要四个参数：

参数	类型	说明
`name`	string	工具的唯一标识符
`description`	string	工具的功能（显示给AI代理）
`schema`	object	Zod模式定义输入参数
`handler`	function	执行工具的异步函数

当前实施情况

这是完整的 app/mcp/route.ts 结构：

import { createMcpHandler } from "mcp-handler";
import { z } from "zod";

// StreamableHttp server
const handler = createMcpHandler(
  // 1. Tool Registration Function
  async (server) => {
    server.tool(
      "echo",
      "Echo back a message to verify input/output communication",
      {
        message: z.string(),
      },
      async ({ message }) => ({
        content: [{ type: "text", text: `Tool echo: ${message}` }],
      })
    );

    server.tool(
      "get_server_time",
      "Returns the current server time and timezone information",
      {},
      async () => ({
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                serverTime: new Date().toISOString(),
                timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
                timestamp: Date.now(),
              },
              null,
              2
            ),
          },
        ],
      })
    );
  },
  // 2. Capabilities — declare server supports tools
  {
    capabilities: {
      tools: {},
    },
  },
  // 3. Options — runtime configuration
  {
    basePath: "",
    verboseLogs: true,
    maxDuration: 60,
    disableSse: true,
  }
);

export { handler as GET, handler as POST, handler as DELETE };

示例：添加新工具

要添加新工具，请将其插入工具注册功能中：

server.tool(
  "get_pokemon",
  "Fetches Pokemon data from the PokeAPI",
  {
    name: z.string().describe("Name of the Pokemon"),
  },
  async ({ name }) => {
    const response = await fetch(
      `https://pokeapi.co/api/v2/pokemon/${name}`
    );
    const data = await response.json();

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            {
              name: data.name,
              types: data.types.map((t: { type: { name: string } }) => t.type.name),
              height: data.height,
              weight: data.weight,
            },
            null,
            2
          ),
        },
      ],
    };
  }
);

Zod模式

使用Zod为您的工具定义类型安全的输入模式：

import { z } from "zod";

// Required string
{ message: z.string() }

// String with description (shown to AI)
{ name: z.string().describe("The user's full name") }

// Optional parameter
{ limit: z.number().optional() }

// With default value
{ count: z.number().default(10) }

// Enum choices
{ format: z.enum(["json", "text", "markdown"]) }

// No parameters
{}

工具响应格式

工具必须返回一个带有 content 阵列。每个内容项都有一个 type 以及相应的数据：

// Text response
return {
  content: [{ type: "text", text: "Your response here" }],
};

// JSON response (stringify for readability)
return {
  content: [
    {
      type: "text",
      text: JSON.stringify({ key: "value" }, null, 2),
    },
  ],
};

// Multiple content items
return {
  content: [
    { type: "text", text: "First part" },
    { type: "text", text: "Second part" },
  ],
};

内置工具

工具	说明
`echo`	回显消息（对测试连接有用）
`get_server_time`	返回当前服务器时间和时区

端点发现

访问 /mcp 在浏览器中（GET请求）以JSON格式返回服务器信息：

{
  "name": "MCP Server Template",
  "version": "0.1.0",
  "protocol": "Model Context Protocol (MCP)",
  "transport": "Streamable HTTP",
  "status": "running",
  "tools": [...],
  "usage": {
    "note": "This endpoint uses POST for MCP communication",
    "test": "npx tsx scripts/test-streamable-http-client.ts <origin>",
    "docs": "https://modelcontextprotocol.io"
  }
}

MCP客户端通过以下方式进行通信发布请求到此端点。

连接MCP客户端

ChatGPT

首选设置 → 应用程序和连接器
点击创建添加新连接器
输入您的MCP URL： https://your-app.vercel.app/mcp
选择“无身份验证”并确认

看着陆页有关截图的详细分步说明。

光标

添加到您的 .cursor/mcp.json:

{
  "mcpServers": {
    "my-mcp-server": {
      "url": "https://your-app.vercel.app/mcp"
    }
  }
}

克劳德桌面版

添加到您的Claude配置文件中：

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-app.vercel.app/mcp"]
    }
  }
}

测试

使用测试客户端

npx tsx scripts/test-streamable-http-client.ts https://your-app.vercel.app

这将连接到您的MCP服务器并列出可用的工具。

加 --verbose 或 -v 有关包括工具模式在内的详细输出：

npx tsx scripts/test-streamable-http-client.ts https://your-app.vercel.app --verbose

本地开发

# Terminal 1: Start the dev server
bun dev

# Terminal 2: Test the MCP endpoint
npx tsx scripts/test-streamable-http-client.ts http://localhost:3030

配置参考

处理程序选项

第三个论点 createMcpHandler 配置运行时行为：

{
  basePath: "",        // Base path for MCP routes (empty = /mcp)
  verboseLogs: true,   // Enable detailed logging for debugging
  maxDuration: 60,     // Max execution time in seconds
  disableSse: true,    // Use Streamable HTTP instead of SSE
}

选项	类型	默认值	描述
`basePath`	字符串	`""`	MCP端点的基本路径前缀
`verboseLogs`	布尔值	`false`	启用详细日志记录以进行调试
`maxDuration`	编号	`60`	最大函数执行时间（秒）
`disableSse`	布尔值	`false`	使用流式HTTP传输而不是SSE

Vercel配置

为了在Vercel上获得最佳性能：

启用流体计算 在项目设置中实现高效执行
调整 maxDuration 根据您的计划：

计划	最长持续时间
爱好	60秒
专业版	800秒
企业版	800秒

// For Pro/Enterprise accounts
{
  basePath: "",
  verboseLogs: true,
  maxDuration: 800, // Increase from default 60
  disableSse: true,
}

环境变量

变量	描述	必填
`NEXT_PUBLIC_APP_URL`	您的生产URL（用于登录页面显示）	可选

技术栈

框架: Next.js 16
MCP适配器: mcp处理器
MCP-SDK: @模型上下文协议/sdk
验证: 佐德
样式: 顺风CSS 4
组件: shadcn/ui

MCP服务器模板

使用说明