mcp-模板框架

Name: mcp-模板框架
Author: iannuttall

作者：iannuttall981 星标更新：2025-05-20

安装使用来源：spider==github.com

项目介绍

MCP 模板：简易设置指南

本项目帮助你在 Cloudflare 上创建自己的远程 MCP 服务器，并支持用户登录和支付选项。你不需要是技术专家就能运行它。

[!NOTE] 该项目现在免费使用且开源。如果你想支持我，请在 X 上关注我 @iannuttall，并订阅我的时事通讯。

你会得到什么

一个与 Cursor、Claude 和其他 AI 助手兼容的 MCP 服务器
使用 Google 或 GitHub 登录
使用 Stripe 进行支付处理
创建免费和付费 MCP 工具的能力

设置检查表

开始之前，请确保你有：

安装了 Node.js（从nodejs.org下载）
一个 Cloudflare 账户（在dash.cloudflare.com/sign-up注册）
一个用于设置登录的 Google 账户（或 GitHub 如果你喜欢）
一个用于支付的 Stripe 账户（在dashboard.stripe.com/register注册）

分步设置

第一步：获取代码

将此仓库克隆到你的计算机上：

git clone https://github.com/iannuttall/mcp-boilerplate.git
cd mcp-boilerplate

安装所有需要的内容：

npm install

第二步：设置数据库

如果尚未安装，请安装 Wrangler（Cloudflare 的工具）：

npm install -g wrangler

为用户登录创建一个数据库：

npx wrangler kv namespace create "OAUTH_KV"

注意：你不能为此数据库使用不同的名称。必须是 "OAUTH_KV"。

执行此命令后，你会看到包含 id 和 preview_id 值的文本
打开项目文件夹中的 wrangler.jsonc 文件
查找 "kv_namespaces": [ 部分
在那里添加你的数据库信息：

"kv_namespaces": [
  {
    "binding": "OAUTH_KV",
    "id": "paste-your-id-here",
    "preview_id": "paste-your-preview-id-here"
  }
]

第三步：设置本地设置

创建一个设置文件：

cp .dev.vars.example .dev.vars

在代码编辑器中打开 .dev.vars 文件
你需要在这里添加几个值（我们将在接下来的步骤中获取它们）

第四步A：设置 Google 登录（推荐）

转到 Google Cloud 控制台
使用任何你喜欢的名字创建一个新的项目
转到 "APIs & Services" > "Credentials"
点击 "+ CREATE CREDENTIALS" 并选择 "OAuth client ID"
如果提示，请设置同意屏幕：
- 对于用户类型，选择 "External"
- 添加应用名称（如 "我的 AI 工具"）
- 在需要的地方添加你的电子邮件地址
- 可以跳过 "Scopes" 和 "Test users" 部分
对于 OAuth 客户端：
- 选择 "Web application" 作为应用类型
- 给它命名
- 在 "Authorized redirect URIs" 中添加以下内容：

http://localhost:8787/callback/google

点击 "CREATE"
现在你会看到你的 Client ID 和 Client Secret - 复制这些值
将它们添加到你的 .dev.vars 文件中：

GOOGLE_CLIENT_ID="paste-your-client-id-here"
GOOGLE_CLIENT_SECRET="paste-your-client-secret-here"

完成这一步后，如果你不需要 GitHub 登录，可以直接进入第五步。

第四步B：设置 GitHub 登录（可选）

如果你更喜欢使用 GitHub 登录而不是 Google：

转到你的 GitHub 账户
点击右上角的个人资料图片，然后转到 "Settings"
在左侧边栏中向下滚动并点击 "Developer settings"
点击 "OAuth Apps"，然后点击 "New OAuth App" 按钮
填写表单：
- 应用名称：给它命名（如 "我的 AI 工具"）
- 主页 URL：http://localhost:8787
- 应用描述：对你的应用进行简要描述（可选）
- 授权回调 URL：http://localhost:8787/callback/github
点击 "Register application"
在下一页，你会看到你的 Client ID
点击 "Generate a new client secret"
立即复制你的 Client Secret（你不会再看到它）
将这些值添加到你的 .dev.vars 文件中：

GITHUB_CLIENT_ID="paste-your-client-id-here"
GITHUB_CLIENT_SECRET="paste-your-client-secret-here"

你还需更新默认的身份验证：
- 打开 src/index.ts
- 查找导入 Google 处理程序的语句：import { GoogleHandler } from "./auth/google-handler";
- 替换为：import { GitHubHandler } from "./auth/github-handler";
- 查找 defaultHandler: GoogleHandler as any, 行
- 更改为：defaultHandler: GitHubHandler as any,

完成第四步A或第四步B后，继续第五步。

第五步：设置 Stripe 支付

登录到你的 Stripe 仪表盘
获取你的测试 API 密钥：
- 转到 Developers > API keys
- 复制你的 "Secret key"（以 sk_test_ 开头）
创建产品和价格：
- 转到 Products > 添加产品
- 给它命名并描述
- 添加价格（这是用户将支付的价格）
- 保存产品
- 保存后，找到并复制 "Price ID"（以 price_ 开头）
将这些值添加到你的 .dev.vars 文件中：

STRIPE_SECRET_KEY="sk_test_your-key-here"
STRIPE_SUBSCRIPTION_PRICE_ID="price_your-price-id-here"
STRIPE_METERED_PRICE_ID="your-stripe-metered-price-id"

第五步A：配置 Stripe 客户账单门户

此模板包括一个工具 (check_user_subscription_status)，可以为最终用户提供一个链接到他们的 Stripe 客户账单门户。该门户允许他们管理他们的订阅，例如取消订阅或（如果配置的话）在不同计划之间切换。

初始设置（重要）：

默认情况下，Stripe 客户账单门户可能没有完全配置在你的 Stripe 账户中，特别是在测试环境中。

设置好你的 Stripe 密钥和产品（第五步）并运行你的服务器后，你可以测试 check_user_subscription_status 工具（例如通过 MCP Inspector，或通过 AI 助手触发它）。
如果工具返回的 JSON 响应中 billingPortal.message 包含类似错误："无法生成客户账单门户的链接：未提供配置且您的测试模式默认配置尚未创建。提供配置或通过在测试模式下保存客户门户设置来创建默认配置，网址为 https://dashboard.stripe.com/test/settings/billing/portal。"
你必须访问错误消息提供的 URL（通常为 https://dashboard.stripe.com/test/settings/billing/portal），并在 Stripe 中保存你的门户设置。这将激活你的测试环境中的门户。你还需要对生产环境进行类似的检查和配置。

一旦激活，check_user_subscription_status 工具将在其 JSON 响应的 billingPortal.url 字段中提供一个直接链接，用户可以使用它。

允许用户切换计划（可选）：

默认情况下，账单门户允许用户取消现有订阅。如果你为你的 MCP 服务器提供了多个订阅产品，并希望允许用户在它们之间切换：

在你的 Stripe 仪表盘中，导航到设置（点击右上角的齿轮图标），然后在 "Billing" 下找到 客户门户。（或者使用直接链接：https://dashboard.stripe.com/settings/billing/portal 用于生产模式，或 https://dashboard.stripe.com/test/settings/billing/portal 用于测试模式）。
在客户门户设置页面的“产品”部分中，找到“订阅产品”。
启用“客户可以切换计划”的开关。
在出现的“选择客户可以更新的合格产品”子部分中，点击“查找测试产品...”（或在生产模式下点击“查找产品...”）并添加你希望用户可以切换到的其他订阅产品。你之前提供的图像显示了 Stripe 中的这个界面。
你还可以在此处配置其他选项，例如允许客户更改其计划的数量（如果适用）。

这种配置使用户能够通过 Stripe 托管的门户更灵活地管理他们的订阅。

第六步：完成你的设置

确保你的 .dev.vars 文件包含所有这些值：

BASE_URL="http://localhost:8787"
COOKIE_ENCRYPTION_KEY="生成至少32个字符的随机字符串"
GOOGLE_CLIENT_ID="你的Google客户端ID"
GOOGLE_CLIENT_SECRET="你的Google客户端密钥"
STRIPE_SECRET_KEY="你的Stripe密钥"
STRIPE_SUBSCRIPTION_PRICE_ID="你的Stripe价格ID"
STRIPE_METERED_PRICE_ID="你的Stripe计量价格ID"

对于 COOKIE_ENCRYPTION_KEY，你可以使用以下命令生成一个随机字符串：

openssl rand -hex 32

第七步：本地启动服务器

运行以下命令启动服务器：

npx wrangler dev

你的服务器将在 http://localhost:8787 启动
AI 工具的主要端点位于 http://localhost:8787/sse

第八步：试一试

你可以通过连接到 AI 助手来测试你的服务器：

转到 Cloudflare AI Playground
输入你的服务器 URL：http://localhost:8787/sse
你将被重定向到 Google 登录
登录后，你可以开始测试工具

或者使用 Claude Desktop：

打开 Claude Desktop
转到 Settings > Developer > 编辑 Config
添加你的服务器：

{
  "mcpServers": {
    "my_server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/sse"
      ]
    }
  }
}

重启 Claude Desktop
你的工具应该现在可以在 Claude 中使用

或者使用 MCP Inspector：

运行 MCP Inspector 并连接到你的服务器：

npx @modelcontextprotocol/inspector@0.11.0

[!WARNING] 最新版本的 MCP Inspector 是 0.12.0，但目前使用 npx @modelcontextprotocol/inspector@latest 不起作用。正在解决这个问题。

输入你的服务器 URL：http://localhost:8787/sse
使用 Web 界面测试和调试你的工具
你可以直接调用你的工具，查看请求/响应数据，并在开发过程中快速迭代

第九步：上线（部署）

当你准备好让你的服务器在线可用时：

部署到 Cloudflare：

npx wrangler deploy

部署后，你会得到一个 URL，如 https://your-worker-name.your-account.workers.dev

3a. 更新你的 Google OAuth 设置：

返回到 Google Cloud Console > APIs & Services > Credentials。
编辑你的 OAuth 客户端。
添加另一个重定向 URI：https://your-worker-name.your-account.workers.dev/callback/google。
接下来，导航到“OAuth 同意屏幕”页面（仍在“APIs & Services”内）。
在“发布状态”下，如果当前显示“测试”，点击“发布应用”按钮并确认将其移动到“生产”。这允许非 GSuite 组织的用户使用登录，如果你最初将其设置为“外部”。

3b. 更新你的 GitHub OAuth 应用设置：（可选）

转到你的 GitHub 开发者设置 > OAuth Apps
选择你的 OAuth 应用
更新“授权回调 URL”为：https://your-worker-name.your-account.workers.dev/callback/github

通过运行以下命令将设置添加到 Cloudflare（系统会提示你输入每个值）：

npx wrangler secret put BASE_URL
npx wrangler secret put COOKIE_ENCRYPTION_KEY
npx wrangler secret put GOOGLE_CLIENT_ID
npx wrangler secret put GOOGLE_CLIENT_SECRET
npx wrangler secret put STRIPE_SECRET_KEY
npx wrangler secret put STRIPE_SUBSCRIPTION_PRICE_ID
npx wrangler secret put STRIPE_METERED_PRICE_ID

对于 BASE_URL，使用你的 Cloudflare URL：https://your-worker-name.your-account.workers.dev

创建你自己的工具

你可以轻松地通过向 src/tools 文件夹添加新文件来创建自己的 AI 工具。该项目附带了免费和付费工具的例子。

创建一个免费工具

要创建一个免费工具（用户无需支付即可访问）：

在 src/tools 文件夹中创建一个新文件（例如：myTool.ts）
从现有的 add.ts 示例中复制此模板：

import { z } from "zod";
import { experimental_PaidMcpAgent as PaidMcpAgent } from "@stripe/agent-toolkit/cloudflare";

export function myTool(agent: PaidMcpAgent<Env, any, any>) {
  const server = agent.server;
  // @ts-ignore
  server.tool(
    "my_tool_name",                      // 工具名称
    "此工具执行一些很酷的操作。",    // 描述你的工具做什么
    {                                    // 输入参数
      input1: z.string(),                // 使用 Zod 定义参数
      input2: z.number()                 // 例如，字符串、数字、布尔值
    },
    async ({ input1, input2 }: { input1: string; input2: number }) => ({
      // 当调用工具时运行的函数
      content: [{ type: "text", text: `您提供了：${input1} 和 ${input2}` }],
    })
  );
}

修改代码以创建你自己的工具：
- 更改函数名（myTool）
- 更改工具名（my_tool_name）
- 更新描述
- 定义你的工具所需的输入参数
- 编写当调用工具时运行的代码
在 src/tools/index.ts 中添加你的工具：

// 添加这一行与其他导出一起
export * from './myTool';

在 src/index.ts 中注册你的工具：

// 在 init() 方法内部添加：
tools.myTool(this);

创建付费工具：订阅、计量或一次性付款

你可以通过三种方式创建需要支付的工具：定期订阅、计量使用或一次性付款。

选项1：创建基于订阅的付费工具

如果你想要按月等周期性费用收取用户访问工具或一组工具的费用，此选项适合你。

Stripe 订阅计费设置：

在你的 Stripe 仪表盘中，创建一个新的产品。
给你的产品命名（例如，“专业访问层”）。
为此产品添加一个价格：
- 选择“定期”作为定价模型。
- 设置价格金额和计费间隔（例如，每月10美元）。
- 保存价格。
创建价格后，Stripe 会显示 Price ID（例如，price_xxxxxxxxxxxxxx）。这就是你在 .dev.vars 文件和注册工具时使用的 STRIPE_SUBSCRIPTION_PRICE_ID。

工具实现：

在 src/tools 文件夹中创建一个新文件（例如：mySubscriptionTool.ts）
从现有的 subscriptionAdd.ts 示例中复制此模板：

import { z } from "zod";
import { experimental_PaidMcpAgent as PaidMcpAgent } from "@stripe/agent-toolkit/cloudflare";
import { REUSABLE_PAYMENT_REASON } from "../helpers/constants";

export function mySubscriptionTool(
  agent: PaidMcpAgent<Env, any, any>,
  env?: { STRIPE_SUBSCRIPTION_PRICE_ID: string; BASE_URL: string }
) {
  const priceId = env?.STRIPE_SUBSCRIPTION_PRICE_ID || null;
  const baseUrl = env?.BASE_URL || null;

  if (!priceId || !baseUrl) {
    throw new Error("付费工具必须提供 Stripe Price ID 和 Base URL");
  }

  agent.paidTool(
    "my_subscription_tool_name", // 工具名称
    {
      // 输入参数
      input1: z.string(), // 使用 Zod 定义参数
      input2: z.number(), // 例如，字符串、数字、布尔值
    },
    async ({ input1, input2 }: { input1: string; input2: number }) => ({
      // 当调用工具时运行的函数
      content: [
        { type: "text", text: `您提供了：${input1} 和 ${input2}` },
      ],
    }),
    {
      priceId, // 使用 Stripe 订阅产品的价格 ID
      successUrl: `${baseUrl}/payment/success`,
      paymentReason: REUSABLE_PAYMENT_REASON, // 显示给用户的通用原因
    }
  );
}

修改代码：
- 更改函数名（mySubscriptionTool）
- 更改工具名（my_subscription_tool_name）
- 更新输入参数和工具逻辑。
在 src/tools/index.ts 中添加你的工具：

// 添加这一行与其他导出一起
export * from './mySubscriptionTool';