Muni MCP

🚀 Muni - MCP：专业建筑规范合规助手

Muni - MCP是一款专业的建筑规范合规助手，它通过Municode API与市政建筑规范对接。旨在帮助专业承包商、经验丰富的建筑商和高级DIY爱好者精准且合规地应对复杂的建筑规范要求。

🚀 快速开始

Muni - MCP能让你轻松访问市政建筑规范和合规数据，以下为你详细介绍如何开启使用之旅。

✨ 主要特性

• 专为建筑规范合规打造的MCP服务器。
• 通过Municode API与市政建筑规范集成。
• 支持使用Google或GitHub进行用户认证。
• 具备高级建筑规范服务的支付处理功能。
• 提供专业工具，可用于访问建筑规范、许可证、分区数据和进行合规验证。

📦 安装指南

在开始之前，请确保你已完成以下准备：

• 安装Node.js（可从 nodejs.org 下载）
• 拥有一个Cloudflare账户（可在 [dash.cloudflare.com/sign - up](https://dash.cloudflare.com/sign - up) 注册）
• 准备一个Google账户用于设置登录（也可选择GitHub）
• 拥有一个Stripe账户用于支付（可在 dashboard.stripe.com/register 注册）

步骤1：获取代码

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

git clone https://github.com/yourusername/muni - mcp.git
cd muni - mcp

2. 安装所需的一切：

npm install

步骤2：设置数据库

1. 若尚未安装Wrangler（Cloudflare的工具），请进行安装：

npm install -g wrangler

2. 创建一个用于用户登录的数据库：

npx wrangler kv namespace create "OAUTH_KV"

⚠️ 重要提示

此数据库名称必须为 "OAUTH_KV"，不能使用其他名称。

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

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

步骤3：设置本地配置

1. 创建一个配置文件：

cp .dev.vars.example .dev.vars

2. 在代码编辑器中打开 .dev.vars 文件。
3. 你需要在此处添加几个值（后续步骤将获取这些值）。

步骤4a：设置Google登录（推荐）

1. 访问 Google Cloud Console。
2. 创建一个任意名称的新项目。
3. 转到 “APIs & Services” > “Credentials”。
4. 点击 “+ CREATE CREDENTIALS” 并选择 “OAuth client ID”。
5. 若系统提示，设置同意屏幕：
   • 用户类型选择 “External”。
   • 添加应用名称（如 “My AI Tool”）。
   • 在需要的地方添加你的电子邮件地址。
   • 可跳过 “Scopes” 和 “Test users” 部分。
6. 对于OAuth客户端：
   • 应用类型选择 “Web application”。
   • 为其命名。
   • 在 “Authorized redirect URIs” 下添加以下内容：

http://localhost:8787/callback/google

7. 点击 “CREATE”。
8. 此时你将看到你的Client ID和Client Secret，请复制这些值。
9. 将它们添加到你的 .dev.vars 文件中：

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

完成此步骤后，若你不需要GitHub登录，可直接进入步骤5。

步骤4b：设置GitHub登录（可选）

若你更喜欢使用GitHub进行登录，而非Google：

1. 访问你的GitHub账户。
2. 点击右上角的个人资料图片，然后转到 “Settings”。
3. 在左侧侧边栏中，向下滚动并点击 “Developer settings”。
4. 点击 “OAuth Apps”，然后点击 “New OAuth App” 按钮。
5. 填写表单：
   • 应用名称：为其命名（如 “My AI Tool”）。
   • 主页URL：http://localhost:8787。
   • 应用描述：对应用的简要描述（可选）。
   • 授权回调URL：http://localhost:8787/callback/github。
6. 点击 “Register application”。
7. 在下一页，你将看到你的Client ID。
8. 点击 “Generate a new client secret”。
9. 立即复制你的Client Secret（你将无法再次查看它）。
10. 将这些值添加到你的 .dev.vars 文件中：

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

11. 你还需要更新代码中的默认认证：
    • 打开 src/index.ts。
    • 找到导入Google处理程序的行：import { GoogleHandler } from "./auth/google - handler";。
    • 将其替换为：import { GitHubHandler } from "./auth/github - handler";。
    • 找到包含 defaultHandler: GoogleHandler as any, 的行。
    • 将其更改为：defaultHandler: GitHubHandler as any,。 完成步骤4a或4b后，进入步骤5。

步骤5：设置Stripe支付

1. 登录到你的 Stripe Dashboard。
2. 获取你的测试API密钥：
   • 转到Developers > API keys。
   • 复制你的 “Secret key”（以 sk_test_ 开头）。
3. 创建一个产品和价格：
   • 转到Products > Add Product。
   • 为其命名并添加描述。
   • 添加价格（这是用户需要支付的金额）。
   • 保存产品。
   • 保存后，找到并复制 “Price ID”（以 price_ 开头）。
4. 将这些值添加到你的 .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"

步骤5a：配置Stripe客户计费门户

此模板包含一个工具（check_user_subscription_status），可向最终用户提供其Stripe客户计费门户的链接。此门户允许用户管理其订阅，例如取消订阅或切换不同的计划（如果你进行了相应配置）。

初始设置（重要）： 默认情况下，Stripe客户计费门户可能未在你的Stripe账户中完全配置，尤其是在测试环境中。

1. 设置好Stripe密钥和产品（步骤5）并运行服务器后，你可以测试 check_user_subscription_status 工具（例如，通过MCP Inspector或通过AI助手触发它）。
2. 如果该工具返回的JSON响应中，billingPortal.message 包含类似如下的错误："Could not generate a link to the customer billing portal: No configuration provided and your test mode default configuration has not been created. Provide a configuration or create your default by saving your customer portal settings in test mode at https://dashboard.stripe.com/test/settings/billing/portal."
3. 你 必须 访问该错误消息中提供的URL（通常为 https://dashboard.stripe.com/test/settings/billing/portal），并在Stripe中保存你的门户设置。这将为你的测试环境激活该门户。你需要为生产环境进行类似的检查和配置。 激活后，check_user_subscription_status 工具将在其JSON响应的 billingPortal.url 字段中提供一个直接链接，用户可以使用该链接。

允许用户切换计划（可选）： 默认情况下，计费门户允许用户取消其现有订阅。如果你为MCP服务器提供多个订阅产品，并希望允许用户在它们之间切换：

1. 在你的Stripe Dashboard中，导航到 Settings（点击右上角的齿轮图标），然后在 “Billing” 下找到 Customer portal。（或者，使用直接链接：https://dashboard.stripe.com/settings/billing/portal 用于生产模式，或 https://dashboard.stripe.com/test/settings/billing/portal 用于测试模式）。
2. 在客户门户设置页面的 “Products” 部分，找到 “Subscription products”。
3. 启用 “Customers can switch plans” 开关。
4. 在出现的 “Choose the eligible products that customers can update” 子部分中，点击 “Find a test product...”（或在生产模式下为 “Find a product...”），并添加你希望用户能够切换到的其他订阅产品。你之前提供的图片显示了Stripe中的此用户界面。
5. 你还可以在此处配置其他选项，例如，如果适用，允许客户更改其计划的数量。 此配置使你的用户能够通过Stripe托管的门户更灵活地管理其订阅。

步骤6：完善你的设置

确保你的 .dev.vars 文件包含以下所有值：

BASE_URL="http://localhost:8787"
COOKIE_ENCRYPTION_KEY="generate - a - random - string - at - least - 32 - characters"
GOOGLE_CLIENT_ID="your - google - client - id"
GOOGLE_CLIENT_SECRET="your - google - client - secret"
STRIPE_SECRET_KEY="your - stripe - secret - key"
STRIPE_SUBSCRIPTION_PRICE_ID="your - stripe - price - id"
STRIPE_METERED_PRICE_ID="your - stripe - metered - price - id"

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

openssl rand -hex 32

步骤7：在本地启动服务器

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

npx wrangler dev

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

步骤8：进行测试

你可以通过以下方式连接到服务器进行测试：

使用Cloudflare AI Playground

1. 访问 Cloudflare AI Playground。
2. 输入你的服务器URL：http://localhost:8787/sse。
3. 你将被重定向到使用Google登录。
4. 登录后，即可开始测试工具。

使用Claude Desktop

1. 打开Claude Desktop。
2. 转到Settings > Developer > Edit Config。
3. 添加你的服务器：

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

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

使用MCP Inspector

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

npx @modelcontextprotocol/inspector@0.11.0 

⚠️ 重要提示

MCP Inspector的最新版本是0.12.0，但目前使用 npx @modelcontextprotocol/inspector@latest 无法正常工作，正在处理此问题。

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

步骤9：上线部署

当你准备好将服务器上线时：

1. 部署到Cloudflare：

npx wrangler deploy

2. 部署后，你将获得一个类似 https://your - worker - name.your - account.workers.dev 的URL。 3a. 更新你的Google OAuth设置：
   • 返回Google Cloud Console > APIs & Services > Credentials。
   • 编辑你的OAuth客户端。
   • 添加另一个重定向URI：https://your - worker - name.your - account.workers.dev/callback/google。
   • 接下来，导航到 “OAuth consent screen” 页面（仍在 “APIs & Services” 内）。
   • 在 “Publishing status” 下，如果当前显示 “Testing”，点击 “Publish app” 按钮并确认将其切换到 “Production”。这允许你的GSuite组织外部的用户使用登录（如果你最初将其设置为 “External”）。 3b. 更新你的GitHub OAuth App设置（可选）：
   • 转到你的GitHub Developer settings > OAuth Apps。
   • 选择你的OAuth App。
   • 将 “Authorization callback URL” 更新为：https://your - worker - name.your - account.workers.dev/callback/github。
3. 通过运行以下命令将你的设置添加到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。

💻 使用示例

免费建筑规范工具

以下工具可供所有经过身份验证的用户使用：

search_building_codes

这是查找特定规范要求的主要工具。

• 使用专业术语（如IBC章节、NEC条款等）。
• 尽可能指定管辖区域。
• 对于模糊场景，请求澄清问题。

get_municipality_codes

用于检索完整的市政规范结构。

• 对于理解模型规范的本地修订至关重要。
• 当你需要完整的监管框架时使用。

validate_code_compliance

将项目规格与适用规范进行交叉引用。

• 识别本地、州和国家要求之间的冲突。
• 确定是否需要专业工程师/建筑师的印章。

get_permit_requirements

提供详细的许可证要求、费用和流程。

• 包括检查员调度和审批工作流程。
• 计算专业项目的成本和时间线。

compare_jurisdictional_requirements

比较多个管辖区域的规范要求。

• 对于跨越边界的项目至关重要。
• 对选址决策很有用。

专业交互指南

何时使用每个工具

• 对于特定的技术问题，从 search_building_codes 开始：
  • 例如：“2021版IBC中，佛罗里达州杰克逊维尔市12' x 20'、活荷载40 PSF的甲板，其甲板托梁间距和 ledger 连接的规定要求是什么？”
  • “2020版NEC中，德克萨斯州奥斯汀市商业厨房的240V 100A子面板安装，对GFCI保护有哪些要求？”
  • “华盛顿州西雅图市C - 2分区中，混合用途开发的最大建筑高度限制和FAR要求是什么？”
• 当你需要全面了解时，使用 get_municipality_codes：
  • 例如：“显示佐治亚州亚特兰大市的完整建筑规范结构。”
  • “迈阿密 - 戴德郡对佛罗里达州建筑规范有哪些本地修订？”
• 对于项目审查，使用 validate_code_compliance：
  • 例如：“审查科罗拉多州丹佛市一个2400平方英尺的商业扩建项目是否符合规范。”
  • “根据当地要求验证电气服务升级规格。”
• 对于项目规划，使用 get_permit_requirements：
  • 例如：“佛罗里达州杰克逊维尔市一个12' x 20'的甲板需要哪些许可证和专业印章？”
  • “德克萨斯州奥斯汀市商业厨房的240V 100A子面板安装需要哪些许可证和费用？”
• 对于多地点项目，使用 compare_jurisdictional_requirements：
  • 例如：“比较三个市政区域内零售空间的停车要求。”
  • “相邻管辖区域内商业建筑的高度限制。”

专业沟通风格

• 精确：使用准确的规范章节、测量值和专业术语。
• 果断：根据规范要求做出明确的建议。
• 全面：包括所有适用的规范和标准。
• 实用：考虑实际实施中的挑战。

专业查询示例

• 不要问：“我可以建造一个甲板吗？” 而要问：“佛罗里达州杰克逊维尔市一个12' x 20'、活荷载40 PSF的甲板，IRC规定的甲板托梁间距和ledger连接要求是什么？”
• 不要问：“我需要许可证吗？” 而要问：“德克萨斯州奥斯汀市一个为商业厨房服务的240V 100A子面板安装需要哪些许可证和专业印章？”
• 不要问：“高度限制是多少？” 而要问：“华盛顿州西雅图市C - 2分区中，混合用途开发的最大建筑高度限制和FAR要求是什么？”

规范层级理解

始终考虑监管层级：

1. 地方法规（最严格）
2. 州规范（可能比国家规范更严格）
3. 国家模型规范（如IBC、IRC、NEC、IPC等）
4. 行业标准（如ASTM、ANSI等） 当存在冲突时，通常适用最严格的要求。

专业责任提醒

• 验证当前规范版本：规范会定期更新。
• 确认本地采用情况：市政当局可能采用不同的版本。
• 考虑专业要求：某些工作需要持牌专业人员。
• 记录合规情况：保留记录以备检查和承担责任。
• 保持更新：规范解释和修订会发生变化。

何时寻求专业咨询

对于以下情况，建议寻求专业咨询：

• 结构工程计算
• 复杂的占用分类
• 具有重大责任的规范解释
• 需要变更或特殊例外的项目
• 多个规范要求之间的冲突 请记住：此工具提供规范研究和解释帮助，但最终的合规责任由持牌专业人员或许可证持有人承担。

📚 详细文档

创建你自己的工具

你可以通过在 src/tools 文件夹中添加新文件来轻松创建自己的AI工具。该项目提供了免费和付费工具的示例，包括专门的建筑规范合规工具。

创建免费工具

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

1. 在 src/tools 文件夹中创建一个新文件（例如：myTool.ts）。
2. 从现有的 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",                      // 工具名称
    "This tool does something cool.",    // 工具功能描述
    {                                    // 输入参数
      input1: z.string(),                // 使用Zod定义参数
      input2: z.number()                 // 例如，字符串、数字、布尔值
    },
    async ({ input1, input2 }: { input1: string; input2: number }) => ({
      // 工具调用时运行的函数
      content: [{ type: "text", text: `You provided: ${input1} and ${input2}` }],
    })
  );
}

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

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

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

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

建筑规范合规工具

该项目包含专门的建筑规范合规工具，展示了专业级别的工具开发：

• searchBuildingCodesTool：使用专业术语搜索建筑规范。
• getMunicipalityCodesTool：检索完整的市政规范结构。
• validateCodeComplianceTool：将项目规格与规范进行交叉引用。
• getPermitRequirementsTool：获取详细的许可证要求和费用。
• compareJurisdictionalRequirementsTool：比较多个管辖区域的要求。 这些工具展示了如何创建专业级工具，具有以下特点：
• 使用Zod进行全面的参数验证。
• 专业的文档和描述。
• 复杂数据的结构化响应。
• 与外部API（Municode）集成。
• 专业的错误处理和用户指导。

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

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

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

如果你想向用户收取定期费用（例如每月）以访问某个工具或一组工具，此选项很合适。

Stripe订阅计费设置

1. 在你的Stripe Dashboard中，创建一个新产品。
2. 为你的产品命名（例如 “Pro Access Tier”）。
3. 为该产品添加一个价格：
   • 选择 “Recurring” 作为定价模型。
   • 设置价格金额和计费间隔（例如每月10美元）。
   • 保存价格。
4. 创建价格后，Stripe将显示价格ID（例如 price_xxxxxxxxxxxxxx）。这是你将在 .dev.vars 文件中用于 STRIPE_SUBSCRIPTION_PRICE_ID 以及注册工具时使用的ID。

工具实现

1. 在 src/tools 文件夹中创建一个新文件（例如：mySubscriptionTool.ts）。
2. 从现有的 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 and Base URL must be provided for paid tools");
  }

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

3. 修改代码：
   • 更改函数名称（mySubscriptionTool）。
   • 更改工具名称（my_subscription_tool_name）。
   • 更新输入参数和工具逻辑。
4. 将你的工具添加到 src/tools/index.ts：

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

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

// 在init()方法内添加：
tools.mySubscriptionTool(this, {
  STRIPE_SUBSCRIPTION_PRICE_ID: this.env.STRIPE_SUBSCRIPTION_PRICE_ID, // 确保这与订阅价格ID匹配
  BASE_URL: this.env.BASE_URL
});

选项2：创建计量使用的付费工具

如果你想根据用户对MCP工具的使用量收费，此选项很合适。

Stripe计量计费设置

1. 在你的Stripe Dashboard中，创建一个新产品。
2. 为该产品添加一个价格：
   • 根据你的模型选择 “Standard pricing” 或 “Package pricing”。
   • 在 “Price options” 下，勾选 “Usage is metered”。
   • 然后你可以定义如何报告使用量（例如 “per unit”）。
   • 如果你想提供免费试用（例如前3次使用免费），可以设置 “Graduated pricing”。例如：
     • 前3个单位：每单位0.00美元。
     • 后续单位（4及以上）：每单位0.10美元。
3. 创建价格后，Stripe将显示价格ID（例如 price_xxxxxxxxxxxxxx）。
4. 如果你还没有为该产品/价格定义 “meter”，则需要在Stripe中定义。这个meter将有一个事件名称（例如 metered_add_usage），你将在工具代码中使用它。你通常可以在产品的 “Usage” 标签下或定义计量价格时设置这个。

工具实现

1. 在 src/tools 文件夹中创建一个新文件（例如：myMeteredTool.ts）。
2. 使用以下受 meteredAdd.ts 示例启发的模板：

import { z } from "zod";
import { experimental_PaidMcpAgent as PaidMcpAgent } from "@stripe/agent - toolkit/cloudflare";
import { METERED_TOOL_PAYMENT_REASON } from "../helpers/constants"; // 你可能需要一个特定的常量

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

  if (!priceId || !baseUrl) {
    throw new Error("Stripe Metered Price ID and Base URL must be provided for metered tools");
  }

  agent.paidTool(
    "my_metered_tool_name", // 工具名称
    {
      // 输入参数
      a: z.number(),
      b: z.number(),
    },
    async ({ a, b }: { a: number; b: number }) => {
      // 工具调用时运行的函数
      // 重要：你的工具的业务逻辑
      const result = a + b; // 示例逻辑
      return {
        content: [{ type: "text", text: String(result) }],
      };
    },
    {
      checkout: {
        success_url: `${baseUrl}/payment/success`,
        line_items: [
          {
            price: priceId, // 使用Stripe计量产品的价格ID
          },
        ],
        mode: 'subscription', // 计量计划通常设置为订阅
      },
      paymentReason:
        "METER INFO: Details about your metered usage. E.g., Your first X uses are free, then $Y per use. " +
        METERED_TOOL_PAYMENT_REASON, // 自定义此消息
      meterEvent: "your_meter_event_name_from_stripe", // ** 重要：使用你在Stripe meter设置中的事件名称 **
                                                        // 例如，"metered_add_usage"
    }
  );
}

3. 修改代码：
   • 更改函数名称（myMeteredTool）。
   • 更改工具名称（my_metered_tool_name）。
   • 更新输入参数和工具的核心逻辑。
   • 至关重要的是，更新 meterEvent 以匹配你在Stripe meter中配置的事件名称。
   • 自定义 paymentReason 以向用户清楚解释计量计费。
4. 将你的工具添加到 src/tools/index.ts：

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

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

// 在init()方法内添加：
tools.myMeteredTool(this, {
  STRIPE_METERED_PRICE_ID: this.env.STRIPE_METERED_PRICE_ID, // 确保这与你的计量价格ID匹配
  BASE_URL: this.env.BASE_URL
});

选项3：创建一次性支付工具

如果你想向用户收取一次性费用以访问某个工具，而不是定期订阅或基于使用量计费，此选项很合适。

Stripe一次性支付设置

1. 在你的Stripe Dashboard中，创建一个新产品。
2. 为你的产品命名（例如 “Single Report Generation”）。
3. 为该产品添加一个价格：
   • 选择 “One time” 作为定价模型。
   • 设置价格金额。
   • 保存价格。
4. 创建价格后，Stripe将显示价格ID（例如 price_xxxxxxxxxxxxxx）。这是你将用于新环境变量（例如 STRIPE_ONE_TIME_PRICE_ID）的ID。

工具实现

1. 在 src/tools 文件夹中创建一个新文件（例如：myOnetimeTool.ts）。
2. 使用以下受 onetimeAdd.ts 示例启发的模板：

import { z } from "zod";
import { experimental_PaidMcpAgent as PaidMcpAgent } from "@stripe/agent - toolkit/cloudflare";
import { REUSABLE_PAYMENT_REASON } from "../helpers/constants"; // 或更具体的原因

export function myOnetimeTool(
  agent: PaidMcpAgent<Env, any, any>, // 根据需要调整AgentProps
  env?: { STRIPE_ONE_TIME_PRICE_ID: string; BASE_URL: string }
) {
  const priceId = env?.STRIPE_ONE_TIME_PRICE_ID || null;
  const baseUrl = env?.BASE_URL || null;

  if (!priceId || !baseUrl) {
    throw new Error("Stripe One - Time Price ID and Base URL must be provided for this tool");
  }

  agent.paidTool(
    "my_onetime_tool_name", // 工具名称
    {
      // 输入参数
      input1: z.string(), // 使用Zod定义参数
    },
    async ({ input1 }: { input1: string }) => ({
      // 工具调用时运行的函数
      content: [
        { type: "text", text: `You processed: ${input1}` },
      ],
    }),
    {
      checkout: { // 定义一次性支付结账会话
        success_url: `${baseUrl}/payment/success`,
        line_items: [
          {
            price: priceId, // 使用Stripe一次性支付产品的价格ID
            quantity: 1,
          },
        ],
        mode: 'payment', // 指定这是一次性支付，不是订阅
      },
      paymentReason: "Enter a clear reason for this one - time charge. E.g., 'Unlock premium feature X for a single use.'", // 自定义此消息
    }
  );
}

3. 修改代码：
   • 更改函数名称（myOnetimeTool）。
   • 更改工具名称（my_onetime_tool_name）。
   • 更新输入参数和工具的核心逻辑。
   • 确保 checkout.mode 设置为 'payment'。
   • 自定义 paymentReason 以向用户清楚解释一次性收费。
4. 将你的工具添加到 src/tools/index.ts：

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

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

// 在init()方法内添加：
tools.myOnetimeTool(this, {
  STRIPE_ONE_TIME_PRICE_ID: this.env.STRIPE_ONE_TIME_PRICE_ID, // 确保这与你的一次性支付价格ID匹配
  BASE_URL: this.env.BASE_URL
});

6. 记得将 STRIPE_ONE_TIME_PRICE_ID 添加到你的 .dev.vars 文件和Cloudflare秘密中： 在 .dev.vars 中：

STRIPE_ONE_TIME_PRICE_ID="price_your - onetime - price - id - here"

对于生产环境：

npx wrangler secret put STRIPE_ONE_TIME_PRICE_ID

你可以通过在Stripe仪表板中创建额外的价格ID并将它们作为环境变量传递，来使用不同的Stripe产品（订阅或计量）创建不同的付费工具。

免费用户尝试付费工具时会发生什么

当用户尝试访问未购买的付费工具时：

1. 服务器检查他们是否已经支付。
2. 如果没有，AI助手将自动向他们提供结账链接。
3. 在Stripe上完成支付后，他们应该能够立即使用该工具。

🔧 技术细节

本项目基于 @iannuttall 的开源MCP模板构建，具备用户认证、支付处理等功能，并通过Municode API与市政建筑规范集成。在开发过程中，运用了Zod进行参数验证，确保输入数据的准确性；对于不同类型的付费工具，在Stripe中进行了相应的设置，以实现订阅、计量和一次性支付的功能。同时，项目在处理用户请求时，会根据规范层级考虑不同规范的优先级，确保提供的建议符合最严格的要求。

📄 许可证

文档未提及相关许可证信息。

未来增强功能（可选）

设置Stripe Webhooks

上述基本设置足以让你开始使用。内置的Stripe集成在用户尝试访问付费工具时会直接验证支付，自动检查一次性支付和订阅情况。 Webhooks是完全可选的，但在未来更复杂的支付场景中可能会有用，例如：

• 构建客户仪表板以显示订阅状态。
• 实现基于使用量的计费。
• 创建订阅创建或取消时的自定义工作流程。
• 使用特殊逻辑处理退款和纠纷。 如果你想添加Webhook支持：

1. 转到你的Stripe Dashboard > Developers > Webhooks。
2. 点击 “Add endpoint”。
3. 对于端点URL：
   • 本地开发：http://localhost:8787/webhooks/stripe。
   • 生产环境：https://your - worker - name.your - account.workers.dev/webhooks/stripe。
4. 对于 “Events to send”，选择与你需求相关的事件，例如：
   • checkout.session.completed
   • invoice.payment_succeeded
   • customer.subscription.updated
5. 创建Webhook后，复制 “Signing secret”。
6. 将此值添加到你的设置中：
   • 本地开发时，添加到 .dev.vars：

STRIPE_WEBHOOK_SECRET="whsec_your - webhook - secret - here"

• 生产环境中，使用Wrangler设置：

npx wrangler secret put STRIPE_WEBHOOK_SECRET

需要帮助？

如果你遇到任何错误或在使用模板时遇到问题，请在GitHub仓库上提交一个issue。请注意，此项目按原样提供，不提供直接支持。