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。請注意，此項目按原樣提供，不提供直接支持。