paywall-mcp

paywall-mcp

Lightning を使って、どんな stdio MCP サーバーにも、変更を加えずにペイウォールを設定できます。 paywall-mcp は汎用のサイドカーです。上流 MCP サーバーのコマンドとツールごとの料金マップを設定すると、次の処理を透過的に行います。

• 上流の tools/list を LLM クライアントに転送し、各ツールの説明に料金を追加します。
• tools/call をインターセプトします。無料ツールはそのまま通過し、有料ツールは呼び出しを転送する前に、Lightning 請求書による支払い（Nostr Wallet Connect / NIP-47 経由）が必要です。

上流サーバーのコードを変更する必要はありません。Anthropic のリファレンス MCP サーバー、自作のサーバー、または stdio に対応したサードパーティ製 MCP サーバーで動作します。

v0.1 — プロキシと支払いゲートが完成しました。 stdio の上流サーバーを子プロセスとして起動します。環境変数によるツールごとの料金設定、メモリ内の請求書キャッシュとリプレイ保護、監査ログ、読み取り専用モードに対応しています。永続キャッシュと HTTP/SSE 上流トランスポートは v0.2 以降に延期されています。

---

これが必要な理由

Lightning ペイウォール、L402、マイクロペイメントなどの最新の有料 API パターンは HTTP 向けには存在しますが、MCP エコシステムには有料ツール呼び出しの標準がありません。個々のサーバーに組み込むのは、繰り返しが多く、エラーも発生しやすくなります。paywall-mcp はその不足を補うサイドカーです。通常の MCP サーバーとしてツールを作成し、paywall-mcp でラップするだけで、呼び出しごとに sats を請求できます。

2 回呼び出すパターンの仕組み

料金が設定されたツールでは、次のように動作します。

1. 1 回目の呼び出し — LLM は payment_hash なしで priced_tool({...args}) を呼び出します。paywall-mcp は NWC ウォレット経由で bolt11 請求書を発行し、次の内容を返します。

   {
     "error": "payment_required",
     "invoice": "lnbc...",
     "payment_hash": "abc123...",
     "amount_sats": 21,
     "expires_in_seconds": 600,
     "next_step": "Pay this bolt11 ..."
   }
   

2. 支払い — LLM（またはその運用者）が請求書を支払います。最も簡単な方法は nwc-mcp を使うことです。同じ LLM から nwc_pay_invoice を呼び出して決済できます。
3. 2 回目の呼び出し — LLM は priced_tool({...args, payment_hash: "abc123..."}) を呼び出します。paywall-mcp は NWC の lookup_invoice を通じて決済を確認し、引数から payment_hash を取り除いて元の呼び出しを上流に転送し、上流の結果を返します。

リプレイ保護により、同じ payment_hash を 2 回引き換えることはできません。購入者は呼び出しごとに新しい請求書を支払います。

---

これを使ってできること

• プロセスを 1 つラップするだけで、既存の MCP サーバーのプレミアムツールに sats を課金できます。
• ツールごとに料金プランを設定できます — free_lookup: 0、premium_analysis: 100、rare_alpha_signal: 5000。購入者にはツールの説明に料金が表示されます。
• サードパーティ製 MCP サーバーをまとめて再販できます — 他の人のオープンソース MCP サーバーを自分のペイウォールでラップし、マネージド有料サービスとして提供できます。
• A/B テストで料金を調整できます — 環境変数の PAYWALL_PRICE_MAP を変更して再起動すれば、新しい料金が適用されます。
• 期間限定のプロモーション料金を設定できます — 21 sats から始め、利用実績で価値が証明されたら 100 sats に引き上げます。

---

必要条件

• Node 20+
• ラップする既存の stdio MCP サーバー（paywall-mcp 自体はツールをホストせず、上流サーバーのツールへのアクセスを制御します）。
• 販売者の受け取り用ウォレットの NIP-47 NWC 接続文字列。paywall-mcp が必要とする権限は make_invoice と lookup_invoice のみです。受け取り専用の NWC 接続で問題なく、推奨されています — paywall-mcp が支払いを行うことはありません。

インストール

# From npm
npx -y paywall-mcp

# From source
git clone <repo>
cd paywall-mcp
corepack enable pnpm
pnpm install
pnpm build

設定

cp .env.example .env
# edit .env: set PAYWALL_UPSTREAM_COMMAND/ARGS, NWC_CONNECTION_STRING, prices

サーバーは .env を自身のディレクトリ（dist/ の隣）から自動的に読み込みます。複数の MCP サーバーを同じ Claude Code セッションで実行する際に環境変数が衝突しないよう、cwd からは読み込みません。

必須

変数	用途
PAYWALL_UPSTREAM_COMMAND	上流 MCP サーバーとして起動する実行ファイル（例：node）。
PAYWALL_UPSTREAM_ARGS	上流コマンドに渡す引数の JSON 配列（例：["/path/to/upstream/dist/index.js"]）。

いずれかのツールに 0 以外の料金を設定する場合に必須

変数	用途
NWC_CONNECTION_STRING	販売者の受け取り用ウォレットの NIP-47 NWC URI。必要な権限は make_invoice と lookup_invoice のみです。paywall-mcp が支払いを行うことはありません。

料金

Var	デフォルト	目的
PAYWALL_DEFAULT_PRICE_SATS	0	価格マップにないツールのデフォルト価格です。0 = 無料でそのまま通過します。
PAYWALL_PRICE_MAP	{}	ツール名と sat 価格を対応付ける JSON オブジェクトです。ツールごとの 0 は無料、指定がない場合はデフォルトを使用します。例：{"premium_compliment":21,"rare_alpha_signal":5000}。

任意の設定

Var	デフォルト	目的
PAYWALL_UPSTREAM_CWD	(親の cwd)	上流の子プロセスの作業ディレクトリです。
PAYWALL_UPSTREAM_ENV	(継承)	上流に適用する環境変数の上書きを格納した JSON オブジェクトです。
PAYWALL_READ_ONLY	false	有料ツールの呼び出しをすべて無効にします（tools/list は引き続き利用できます）。メンテナンスに便利です。
PAYWALL_INVOICE_TTL_SECONDS	600	インボイスの TTL です。この期間を過ぎると、payment_hash はキャッシュから削除され、購入者は再発行する必要があります。
PAYWALL_PRICE_LABEL_TEMPLATE	"(💰 {price} sats)"	価格が設定された各ツールの説明に tools/list で追加するラベルです。{price} は sat の金額に置き換えられます。
PAYWALL_LOG_PATH	./paywall-mcp.log	サーバーログです。
PAYWALL_AUDIT_PATH	./paywall-mcp-audit.log	NDJSON 監査ログ（呼び出しごとに 1 行）です。

---

エンドツーエンドの例：同梱の paywall-mcp-test サーバーにペイウォールを設定する

付属の paywall-mcp-test パッケージは、単一のツール premium_compliment を公開します。このツールは内部で独自のペイウォールパターンを実装していますが、「任意の上流 MCP サーバー」の代わりとして、paywall-mcp 自体の動作を示すのにも便利です。

.env：

PAYWALL_UPSTREAM_COMMAND=node
PAYWALL_UPSTREAM_ARGS=["/abs/path/to/paywall-mcp-test/dist/index.js"]

NWC_CONNECTION_STRING=nostr+walletconnect://...

PAYWALL_DEFAULT_PRICE_SATS=21
PAYWALL_PRICE_MAP={"premium_compliment":21}

上流サーバーを直接ではなく、paywall-mcp を MCP クライアントに接続します：

{
  "mcpServers": {
    "paywall": {
      "command": "npx",
      "args": ["-y", "paywall-mcp"],
      "env": {}
    }
  }
}

エージェントから：

1. tools/list  → premium_compliment ... (💰 21 sats) This tool requires ...
2. premium_compliment({})  → returns invoice + payment_hash
3. nwc_pay_invoice(invoice)  → buyer pays
4. premium_compliment({ payment_hash: "..." })  → upstream's result returned

---

安全性モデル

tools/list      → upstream.listTools() → augment descriptions with prices → return
tools/call:
  if price == 0           → upstream.callTool(args)                  (passthrough)
  elif PAYWALL_READ_ONLY  → refuse with paywall_read_only            (block)
  elif no payment_hash    → gate.issue() → return bolt11 + hash      (issue)
  elif bad hash format    → refuse with invalid_payment_hash         (block)
  else (have hash):
      gate.verify() ──┬─ unknown_payment_hash         → block
                      ├─ payment_hash_already_redeemed → block (replay)
                      ├─ payment_hash_tool_mismatch    → block
                      ├─ payment_not_settled           → block
                      └─ ok → strip hash → upstream.callTool()      (paid passthrough)

監査ログのエントリー（NDJSON、リクエストごとに 1 行）：

• outcome: "ok" — インボイスの発行、無料でのそのまま通過、または有料リクエストのそのまま通過が完了しました
• outcome: "blocked" — 読み取り専用による拒否、無効なハッシュ、リプレイ、不一致、未決済
• outcome: "error" — 上流の呼び出し失敗、NWC の lookup_invoice 失敗など

LLM の応答に関係なく事実を確認できるよう、監査ログを追跡してください。

tail -f paywall-mcp-audit.log | jq .

---

Claude Desktop／Claude Code／Cursor への接続

{
  "mcpServers": {
    "paywall": {
      "command": "npx",
      "args": ["-y", "paywall-mcp"],
      "env": {}
    }
  }
}

他の基盤と同じ、バイナリのディレクトリ経由で .env を読み込むパターンです。クライアント設定の env は空のままにし、シークレットは paywall-mcp/.env に保存してください。

---

テスト

pnpm typecheck
pnpm test        # 13 vitest cases (config resolution + payment-gate state machine)
pnpm build       # ~18 KB ESM bundle

---

関連サーバー

• nwc-mcp — 購入者向けの Lightning ウォレットです。エージェントが paywall-mcp の発行するインボイスを支払えるようにします。エージェントが有料ツールの料金を支払う一連の流れを構成する、対応するもう一方のサーバーです。
• nostr-ops-mcp — NOSTR のアイデンティティ、公開、暗号化 DM に対応します。
• marketplace-mcp — エージェントから NIP-15／Shopstr のストアフロントを運営します。
• albyhub-admin-mcp — HTTP API 経由で Alby Hub のノードを管理します。

---

ライセンス

MIT — LICENSE を参照してください。

お問い合わせ／問題の報告

LLMOps.Pro によって開発されました。

• NOSTR： npub1hdg932jvwc3jdvkqywgqv0ue4nn60exrf92asy8mtazt3hjg7d2s2yw0nw — フォロー、DM、zap をお送りください。
• Lightning アドレス： [email protected] — サポートへの zap や「役に立った」というチップにご利用ください。
• バグ報告／機能リクエスト： GitHub issue を作成してください（リンクは後日掲載）。
• セキュリティ上の問題： 公開 issue を作成する前に、NOSTR の DM で非公開にご報告ください。