Muni MCP

🚀 Muni - MCP: 専門的な建築基準適合アシスタント

Muni - MCPは、Municode APIを通じて地方自治体の建築基準と連携する、専門的な建築基準適合アシスタントです。専門の請負業者、経験豊富な建設業者、上級のDIY愛好家が、複雑な建築基準要件を正確に理解し、規制遵守を図るのに役立ちます。

🚀 クイックスタート

Muni - MCPを使い始める前に、以下の準備が必要です。

セットアップチェックリスト

• Node.jsをインストールします（nodejs.orgからダウンロード）
• Cloudflareアカウントを作成します（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をコピーし、.dev.vars ファイルに追加します。

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

このステップが完了し、GitHubログインが必要ない場合は、直接ステップ5に進むことができます。

ステップ4b: GitHubログインの設定（任意）

Googleの代わりにGitHubでログインする場合は、以下の手順を実行します。

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 ツールをテストできます。
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ダッシュボードで、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..."）をクリックし、ユーザーが切り替えられるようにする他のサブスクリプション商品を追加します。
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: テストする

サーバーをAIアシスタントでテストすることができます。

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. ウェブインターフェイスを使用してツールをテストおよびデバッグします。
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
   • 次に、"APIs & Services" 内の "OAuth consent screen" ページに移動します。
   • "Publishing status" が "Testing" と表示されている場合、"Publish app" ボタンをクリックし、確認して "Production" に移行します。これにより、最初に "External" として設定した場合、GSuite組織外のユーザーもログインできるようになります。 3b. GitHub OAuth App設定を更新します（任意）。
   1. GitHub Developer settings > OAuth Appsに移動します。
   2. OAuth Appを選択します。
   3. "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 を使用します。

✨ 主な機能

概要

Muni - MCPは、Municode APIを通じて地方自治体の建築基準と連携する、専門的な建築基準適合アシスタントです。専門の請負業者、経験豊富な建設業者、上級のDIY愛好家が、複雑な建築基準要件を正確に理解し、規制遵守を図るのに役立ちます。

コア原則

• 常にコードの遵守を利便性よりも優先する - 疑問がある場合は、より制約の強い解釈を選択し、専門家の相談を推奨する
• ユーザーの専門的な能力を前提とする - ユーザーは中級から上級の建設知識を持ち（技能レベル3 - 5/5）、技術用語を理解している
• コードの解釈がプロジェクトの詳細によって異なる場合には、明確化のための質問をするが、規制に沿った決定的な推奨を行う

[!NOTE] このプロジェクトは、@iannuttallによるオープンソースのMCPボイラープレートに基づいています。

得られるもの

• 建築基準適合に特化したMCPサーバー
• Municode APIを通じた地方自治体の建築基準との統合
• GoogleまたはGitHubによるユーザー認証
• 有料の建築基準サービスの支払い処理
• 建築基準、許可証、ゾーニングデータ、および適合性検証にアクセスするための専門ツール

📦 インストール

インストール手順については、「クイックスタート」セクションを参照してください。

💻 使用例

無料の建築基準ツール

すべての認証済みユーザーには、以下のツールが利用可能です。

search_building_codes

特定のコード要件を見つけるための主要なツールです。

• 技術用語（IBCセクション、NEC条項など）を使用します。
• 可能な場合は、管轄区域を指定します。
• 曖昧なシナリオについては、明確化のための質問を要求します。

get_municipality_codes

完全な地方自治体のコード構造を取得します。

• モデルコードへの地域の修正案を理解するために不可欠です。
• 完全な規制フレームワークが必要な場合に使用します。

validate_code_compliance

プロジェクトの仕様を適用可能なコードと照合します。

• 地方、州、および全国の要件間の矛盾を特定します。
• 専門のエンジニア/建築家の印章が必要かどうかを判断します。

get_permit_requirements

詳細な許可証の要件、料金、および手続きを取得します。

• 検査官のスケジューリングと承認のワークフローを含みます。
• 専門プロジェクトのコストとタイムラインを計算します。

compare_jurisdictional_requirements

複数の管轄区域のコード要件を比較します。

• 境界をまたがるプロジェクトに不可欠です。
• 敷地選定の決定に役立ちます。

専門的な対話ガイドライン

各ツールの使用タイミング

• 特定の技術的な質問には、search_building_codes から始める
  • 例: "What are the IBC 2021 requirements for deck ledger attachment in residential construction?"
  • 例: "NEC 2020 requirements for GFCI protection in commercial kitchens"
  • 例: "Setback requirements for accessory structures in R - 1 zoning"
• 包括的な理解が必要な場合は、get_municipality_codes を使用する
  • 例: "Show me the complete building code structure for Atlanta, GA"
  • 例: "What local amendments does Miami - Dade have to the Florida Building Code?"
• プロジェクトのレビューには、validate_code_compliance を使用する
  • 例: "Review this 2,400 sq ft commercial addition for code compliance in Denver, CO"
  • 例: "Validate electrical service upgrade specs against local requirements"
• プロジェクトの計画には、get_permit_requirements を使用する
  • 例: "Permit requirements for 500 sq ft commercial tenant improvement"
  • 例: "Electrical permit fees and inspection schedule for service upgrade"
• 複数の場所のプロジェクトには、compare_jurisdictional_requirements を使用する
  • 例: "Compare parking requirements for retail spaces across three municipalities"
  • 例: "Height restrictions for commercial buildings in adjacent jurisdictions"

専門的なコミュニケーションスタイル

• 正確であること - 正確なコードセクション、測定値、および技術用語を使用する
• 決定的であること - コード要件に基づいて明確な推奨を行う
• 徹底的であること - すべての適用可能なコードと標準を含める
• 実用的であること - 現実の実装における課題を考慮する

専門的なクエリの例

• 代わりに、"Can I build a deck?" の代わりに、"What are the IRC prescriptive requirements for deck joist spacing and ledger attachment for a 12' x 20' deck with 40 PSF live load in Jacksonville, FL?" と尋ねる
• 代わりに、"Do I need a permit?" の代わりに、"What permits and professional stamps are required for a 240V 100A subpanel installation serving a commercial kitchen in Austin, TX?" と尋ねる
• 代わりに、"What's the height limit?" の代わりに、"What are the maximum building height restrictions and FAR requirements for mixed - use development in C - 2 zoning in Seattle, WA?" と尋ねる

コードの階層構造の理解

常に規制の階層構造を考慮してください。

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）との統合
• 専門的なエラー処理とユーザーガイダンス

有料ツールの作成: サブスクリプション、従量制、または一回払い

ユーザーに支払いを要求するツールを、定期的なサブスクリプション、従量制使用料、または一回払いの3つの方法で作成できます。

サブスクリプションベースの有料ツールの作成

ユーザーに定期的な料金（例: 月額）を請求して、ツールまたはツールセットにアクセスさせる場合に適しています。

Stripeのサブスクリプション請求の設定

1. Stripeダッシュボードで、新しい商品を作成します。
2. 商品に名前を付けます（例: "Pro Access Tier"）。
3. この商品に価格を追加します。
   • 価格モデルに "Recurring" を選択します。
   • 価格と請求間隔を設定します（例: 月額$10）。
   • 価格を保存します。
4. 価格を作成した後、StripeはPrice 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 Price 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, // サブスクリプションPrice IDと一致することを確認
  BASE_URL: this.env.BASE_URL
});

従量制使用料の有料ツールの作成

ユーザーがMCPツールを使用する量に応じて料金を請求する場合に適しています。

Stripeの従量制請求の設定

1. Stripeダッシュボードで、新しい商品を作成します。
2. この商品に価格を追加します。
   • 適切な価格モデルとして "Standard pricing" または "Package pricing" を選択します。
   • "Price options" の下で、"Usage is metered" をチェックします。
   • 次に、使用量の報告方法を定義できます（例: "per unit"）。
   • 無料枠を提供したい場合（例: 最初の3回の使用は無料）、"Graduated pricing" を設定できます。例えば、
     • 最初の3ユニット: 単位あたり$0.00
     • 次のユニット（4以上）: 単位あたり$0.10
3. 価格を作成した後、StripeはPrice ID（例: price_xxxxxxxxxxxxxx）を表示します。
4. まだ定義していない場合は、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 Price 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メーターの設定で構成したイベント名を使用 **
                                                       // 例: "metered_add_usage"
       }
     );
   }
   

3. コードを変更します。
   • 関数名 (myMeteredTool) を変更します。
   • ツール名 (my_metered_tool_name) を変更します。
   • 入力パラメータとツールのコアロジックを更新します。
   • 重要なことは、meterEvent をStripeメーターで構成したイベント名に更新することです。
   • 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, // 従量制Price IDと一致することを確認
  BASE_URL: this.env.BASE_URL
});

一回払いの有料ツールの作成

ユーザーにツールへのアクセスに対して単一の料金を請求する場合に適しています。

Stripeの一回払いの設定

1. Stripeダッシュボードで、新しい商品を作成します。
2. 商品に名前を付けます（例: "Single Report Generation"）。
3. この商品に価格を追加します。
   • 価格モデルに "One time" を選択します。
   • 価格を設定します。
   • 価格を保存します。
4. 価格を作成した後、StripeはPrice 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 Price 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, // 一回払いのPrice IDと一致することを確認
     BASE_URL: this.env.BASE_URL
   });
   

6. .dev.vars ファイルとCloudflareシークレットに STRIPE_ONE_TIME_PRICE_ID を追加することを忘れないでください。 .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で支払いを完了した後、ユーザーはすぐにツールを使用できるはずです。

🔧 技術詳細

Stripe Webhookの設定

上記の基本的な設定で始めることができます。組み込まれたStripe統合は、ユーザーが有料ツールにアクセスしようとするときに自動的に支払いを検証します。一回払いとサブスクリプションの両方を自動的にチェックします。

Webhookは完全に任意ですが、将来的により複雑な支払いシナリオに役立つ場合があります。例えば、

• サブスクリプションの状態を表示する顧客ダッシュボードの構築
• 従量制による使用料の請求の実装
• サブスクリプションの作成またはキャンセル時のカスタムワークフローの作成
• 返金と紛争の特殊なロジックによる処理

Webhookサポートを追加する場合は、以下の手順を実行します。

1. Stripeダッシュボード > 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

📄 ライセンス

このプロジェクトに関する具体的なライセンス情報は提供されていません。

Need Help?

このボイラープレートにバグがあったり、問題があったりする場合は、GitHubリポジトリに問題を報告してください。このプロジェクトは現状のまま提供されており、直接のサポートは含まれていません。