excalibur-mcp

eXcalibur MCP

AI エージェントを介して、見栄えのよいツイートをX（Twitter）に素早く投稿し、DPYC(TM) Tollbooth プロトコル経由のBitcoin Lightningマイクロペイメントで収益化します。

eXcaliburは、AI エージェントがリッチなUnicode書式と任意の画像を使ってX（Twitter）に投稿できるFastMCPサーバーです。Xの利用者認証にはOAuth2 Authorization Code + PKCEを使用するため、チャットに認証情報が表示されることはありません。運用者の認証情報（Xアプリのキー、BTCPay）は、人間が介在するSecure Courier経由で届き、運用者ごとのNeonボールトスキーマに保存されます。ツール呼び出しは、Tollbooth DPYC(TM)の事前入金式Lightning残高で課金されます。お客様を煩わせない仕組みです。

DPYC(TM) Social Contractの一部です。

はじめに

Horizon経由で接続できます。ローカルへのインストールは不要です。

https://excalibur-mcp.fastmcp.app/mcp

https://excalibur.tollbooth-dpyc.comのウェブエディターから、ブラウザーで同じツールを利用できます。

ステップ1：セッションを確認する

excalibur_session_statusを呼び出して、現在のセッション状態を確認します。クレジットが入金済みのアクティブなセッションがあれば、投稿を開始できます。

ステップ2：接続上でNpubを証明する

IDはツールの引数ではなく、接続に紐づきます。AI アシスタントから接続する場合はOAuthホルダー接続となります。excalibur_request_npub_proof(patron_npub=<npub>)を呼び出し、送られてきたNostr DMに返信してから、excalibur_receive_npub_proof(patron_npub=<npub>, nonce=<nonce>)を1回呼び出します。これにより、返信で選択した期間（最大30日間）、接続がnpubを保持し、すべてのツール呼び出しではnpubだけが渡されます。nsecを保持する呼び出し元は、各HTTPリクエストに署名する方法（NIP-98）も利用できます。

ステップ3：X OAuth2 + PKCE（Xの利用者認証情報）

1. Nostrのnpubを取得します。dpyc-oracleのhow_to_join()ツール、または任意のNostrクライアントを使用してください。
2. excalibur_begin_oauth(npub=<npub>)を呼び出すと、authorize_urlが返されます。ブラウザーで短縮リンクではなく、主のauthorize_urlを開き、Xでアプリを認証します。
3. excalibur_check_oauth_status(npub=<npub>)を呼び出すと、コード交換が完了し、トークンがボールトに保存され、セッションが有効になります。

セッションはnpubをキーとして管理されます。トークンはNeonボールトに保存され、有効期限が切れると自動的に更新されます。

ステップ4：Secure Courier（運用者の認証情報）

運用者の認証情報（X OAuth2アプリのキー、BTCPay接続）は、Secure Courier（service="excalibur-operator"）経由で届けられます。これは人間が介在するフローです。運用者はNostrクライアントを使って、認証情報の配信を毎回明示的に承認します。receive_credentialsの実行時に、リレーのDMは読み取り後に削除されるため、受信後の認証情報はNeonボールトにのみ存在します。

クレジットモデル

ツール呼び出しごとにapi_satsがかかります。購入ごとに1つのトランシェが作成され、運用者の料金モデルでtranche_lifetimeが設定されている場合にのみ、有効期限が切れます。認証ツールと残高確認ツールは常に無料です。残高とトランシェの有効期限はexcalibur_check_balanceで確認できます。excalibur_purchase_creditsでクレジットを追加できます。

利用可能なツール

標準ツール（wheel に含まれるもの）

標準の DPYC(TM) ツールは、tollbooth-dpyc の register_standard_tools() によって登録されます。これには、セッション管理、クレジット操作、Secure Courier、価格設定、公証、Oracle への委任が含まれます。各ツールは、決定論的な UUID v5 で識別されます。

カテゴリ	ツール
セッションと請求	session_status, check_balance, account_statement, account_statement_infographic, restore_credits, service_status, check_price, check_authority_balance
Secure Courier	request_credential_channel, receive_credentials, forget_credentials, update_operator_credential, delete_operator_credential, update_patron_credential, delete_patron_credential, get_patron_credential_fields
Npub 証明	request_npub_proof, receive_npub_proof, check_proof_status, held_identities
購入とクーポン	purchase_credits, check_payment, mint_coupon, list_coupons, update_coupon, delete_coupon, redeem_coupon, list_my_coupons, forget_coupon
価格設定と制約	get_pricing_model, set_pricing_model, reset_pricing_model, list_constraint_types, list_canonical_identities
公証	notarize_ledger, list_notarizations, get_notarization_proof
オンボーディングと導入	get_operator_onboarding_status, get_patron_onboarding_status, request_adoption, adoption_status, restore_neon_schema
Nostr と診断	get_nostr_profile, publish_nostr_profile, request_echo, report_issue
OAuth（X）	begin_oauth, check_oauth_status
Oracle（委任）	oracle_about, oracle_how_to_join, oracle_lookup_member, oracle_get_tax_rate, oracle_network_advisory

ドメインツール（eXcalibur 専用）

ドメインツールは server.py で定義されており、ストレージハンドラーは tools/ にあります。価格は運営者の料金モデルによって設定されます。各呼び出しの料金は check_price で事前に確認できます。読み取りツールと認証ツールは無料です。

X への投稿

ツール	説明
post_tweet	Markdown から Unicode へのリッチテキスト形式で、テキストのツイートを投稿します
post_tweet_image	ヒーローバナー画像（画像 URL、または PNG にレンダリングされた SVG）付きのツイートを投稿します
get_x_profile	この利用者に接続された X アカウントのハンドルと名前を取得します（無料）
post_nostr_message	実績が確認された npub の公開 Nostr ノート（kind 1）を公開します。ノートには、利用者を p タグ付けする一時的な署名用キーを使います

保存済み投稿（下書きとスケジュール設定）

ツール	説明
create_post	新しい投稿（下書きまたはスケジュール済み）を保存し、その post_id を返します
get_post	ID を指定して保存済みの投稿を 1 件読み取ります（所有者の範囲内）
list_posts	保存済みの投稿を一覧表示します。サーバー側で並べ替え、フィルタリング、ページネーションを行います
update_post	保存済みの投稿（doc、publish_at、recurrence、status）を部分更新します
delete_post	保存済みの投稿を削除します（既定では論理削除）

スニペットと文体

ツール	説明
list_snippets	保存済みの投稿スニペットを一覧表示します（サーバー側で並べ替え、フィルタリング、ページネーションを行います）
get_snippet	ID を指定して保存済みのスニペットを 1 件読み取ります
save_snippet	再利用可能なスニペット（冒頭、フッター、CTA）を保存します
delete_snippet	保存済みのスニペットを削除します（無料、所有者の範囲内）
get_voice	保存済みの執筆文体（プロフィール紹介文と禁止語）を読み取ります
save_voice	npub ごとの執筆文体を保存します

AI 編集と動的ブロック

ツール	説明
refine_post_region	LLM を使い、フラグが付いた投稿領域をサーバー側で修正します
resolve_dynamic_block	動的な（プロンプトに基づく）投稿ブロックの解決を開始し、請求チェックを返します
fetch_dynamic_block	resolve_dynamic_block の請求チェックを引き換えます（無料、証明が必要）

会話の見込み客

ツール	説明
find_conversations	回答できそうな質問をしている人を X で検索し、スコアを付けて見込み客として保存します
list_conversations	保存済みの見込み客をページ単位で取得します（無料）
reply_to_conversation	見込み客の X 上のスレッドに返信を投稿し、見込み客を対応済みにします
set_conversation_status	見込み客を新規、確認済み、対応済み、または対象外としてマークします（無料）
list_conversation_queries	保存済みの会話検索クエリを一覧表示します（無料）
save_conversation_query	保存済みの会話検索クエリを作成または更新します（無料）
delete_conversation_query	保存済みの検索クエリを削除します。関連する見込み客は保持されます（無料）

投稿の指標

ツール	説明
harvest_metrics	送信済み投稿の X 指標をスナップショットとして取得する、実行間隔を考慮した一括処理です（運営者専用）
get_post_metrics	投稿 1 件の指標スナップショット系列を読み取ります
post_performance	取得済みの投稿指標からリーチスコアを算出します
post_performance_infographic	投稿のパフォーマンスを示す SVG インフォグラフィックです

スケジューラー

ツール	説明
process_scheduled_posts	期限が到来したスケジュール済み投稿をすべて公開します（運営者専用）
get_scheduler_log	最近のスケジューラー実行結果を読み取ります
scheduler_status	スケジューラーの設定と現在の状態を確認します（無料、実績が確認された利用者なら誰でも利用可能）
scheduler_pending	スケジュール済み投稿の cron Worker が待機している内容を確認します（運営者専用）
scheduler_check_now	スケジューラーを今すぐ 1 回実行します（実績が確認された利用者なら誰でも利用可能）
scheduler_reissue	スケジューラーの証明リクエストを今すぐ再送します（運営者専用）

OAuth フローツール（begin_oauth、check_oauth_status）は、wheel が提供する 標準ツールになりました（上記の標準ツールの表を参照してください）。

npub を受け取るツールで必要なのは npub だけです。接続によって証明されます（ 「セキュリティ」を参照してください）。

セキュリティ

• Npub ID -- パトロンはメールアドレスやパスワードではなく、Nostr の公開鍵（npub）によって識別されます。ユーザーが管理するキー ペアを、役割ごとに 1 つ使用します。
• 接続時の ID 確認 -- 接続では、次の 2 つの方法のいずれかで npub を証明します。各 HTTP リクエストに npub の鍵で署名する方法（NIP-98、kind 27235）か、OAuth ホルダー接続に request_npub_proof / receive_npub_proof を通じて取得したオペレーター署名付きの許可証を持たせる方法です。パトロンは許可証の有効期間を最長 30 日まで設定できます。held_identities と check_proof_status で、接続が保持している内容を確認できます。
• Human-in-the-loop Secure Courier -- 認証情報の送信には、Nostr DM を介したオペレーターの明示的な承認が必要です。受信後、リレーメッセージは破壊的に読み出され、シークレットは暗号化された Neon ボルト内にのみ存在します。
• オペレーターごとの Neon スキーマ -- 各オペレーターの認証情報は、専用の LOGIN ロールを持つ分離された Postgres スキーマに保存されます。オペレーター間でアクセスが共有されることはありません。

アーキテクチャ

src/excalibur_mcp/
  server.py        FastMCP server -- domain tools + register_standard_tools()
  config.py        Pydantic settings from environment variables
  oauth_flow.py    X-specific OAuth2 Authorization Code + PKCE wrapper
  x_client.py      X API v2 client with OAuth 2.0 Bearer token auth
  formatter.py     Markdown -> Unicode rich text (bold, italic, headers)
  refine.py        Server-side editorial refinement for the post editor
  resolve.py       Server-side resolution of dynamic (prompt-backed) post blocks
  resolver.py      Builds one post's finished body (the slow half: dynamic blocks)
  publisher.py     Carries a finished body to X (the fast half: bill, post, record)
  scheduler.py     Scheduled-post firing (publishes due posts on the owner's behalf)
  conversation_scoring.py  Pure scoring + query composition for conversation leads
  metrics_harvest.py       Post-metrics harvest cadence and derived reach scores
  nostr_note.py    Public Nostr notes signed by an ephemeral scribe key
  tools/           Domain storage handlers (posts, snippets, voices, conversations, metrics)
  db/              eXcalibur persistence on the wheel's NeonVault (posts, snippets, voices,
                   conversations, metrics, scheduler runs, migrations)
modal_app.py       Detached runner for long dynamic-block resolves (Modal)
scheduler-worker/  Cloudflare Worker cron that fires due scheduled posts
frontend/          The web editor (excalibur.tollbooth-dpyc.com)

主な設計上の選択：

• OAuth2 Authorization Code + PKCE -- パトロンのトークンはブラウザーフローを通じて取得します。begin_oauth はプライマリの authorize_url（短縮リンクではありません）を返し、check_oauth_status がトークン交換を完了します。トークンは Neon ボルトに保存され、有効期限が切れると自動更新されます。OAuth 1.0a は使用しません。
• UUID v5 によるツール ID -- すべてのツール（標準ツールとドメイン固有ツール）には、機能名から導出された決定的な UUID が割り当てられます。料金、制約、課金はいずれも UUID に基づきます。
• wheel に含まれる標準ツール -- register_standard_tools() は、すべての DPYC(TM) インフラストラクチャツールを提供します。server.py で定義されるのは、ドメイン固有の X/Twitter ツールのみです。
• Markdown から Unicode への変換 -- **bold**、*italic*、# headers を、マークアップ構文なしでツイート上に表示できる Unicode 文字に変換します。

セルフホスティング

環境変数

DPYC(TM) ID（起動に必須）

変数	必須	説明
TOLLBOOTH_NOSTR_OPERATOR_NSEC	はい	ID の初期設定と DM の暗号化に使用する、オペレーターの Nostr 秘密鍵

起動に必要な環境変数はこれだけです。その他すべてのシークレット（X アプリのキー、BTCPay 認証情報）は、Secure Courier の認証情報テンプレートを通じて受信し、オペレーターごとの Neon ボルトスキーマに保存されます。

オペレーターの認証情報（Secure Courier 経由）

これらは環境変数として設定せず、Secure Courier（service="excalibur-operator"）を通じて配信されます。

認証情報	説明
client_id	X OAuth2 クライアント ID（X Developer Portal から取得）
client_secret	X OAuth2 クライアントシークレット（X Developer Portal から取得）
btcpay_host	BTCPay Server の URL
btcpay_store_id	請求書用のストア ID
btcpay_api_key	請求書の権限を持つ API キー
llm_api_key	任意。refine_post_region と動的ブロック用のモデルルーターキー（デフォルトは OpenRouter）。これがなくても投稿できます
modal_token_id, modal_token_secret, modal_app_name	任意。MCP ホストとは独立して、時間のかかる動的ブロックの解決を実行する Modal ワークスペース
github_repo, github_token	任意。report_issue がパトロンのフィールドレポートを登録する場所（トークンに必要なのは issues:write 権限のみ）

認定オペレーターは、暗号化された Nostr DM を通じて Authority から Neon データベース URL を初期設定します。NEON_DATABASE_URL は環境変数から読み込まれません。

任意の調整項目

変数	説明
SCHEDULER_WORKER_URL	定期投稿を実行する cron Worker の公開 URL（デフォルト：https://excalibur-scheduler.lonniev.workers.dev）
RESOLVE_BLOCK_BUDGET_MAX_S	1 つの動的ブロックでの LLM 実行時間の上限（秒、デフォルト：1800）。ジョブ、リース、ランナーのタイムアウトは、この値に基づいて設定されます

トラブルシューティング

コールドスタート

デプロイ後の最初のリクエストでは、Neon 接続の初期化と料金モデルの読み込みに数秒かかることがあります。ランタイムはインライン再試行でこれに対応します。ウォームアップが完了すると、呼び出し元には結果が返され、「サービスを利用できません」というエラーは返されません。

ツール呼び出しでよくある状況

レスポンスでは、単なるエラーメッセージではなく、現在のライフサイクル状態と次の手順のガイダンスを示します。

• proof_required -- 接続で npub の証明が行われていないか、付与された権限の期限が切れています。request_npub_proof を呼び出して DM に返信し、その後 receive_npub_proof を一度呼び出してください。check_proof_status で権限の残り期間を確認できます。
• 「クレジット残高が不足しています」 -- purchase_credits を呼び出してチャージしてください。check_balance でトランシェの有効期限を確認できます。
• 「オペレーターの認証情報が設定されていません」 -- オペレーター側の設定に関する問題であり、パトロン側の問題ではありません。

お客様に何度も要求しないでください： レスポンスに上流トークンの期限切れまたは無効が明記されていない限り、パトロンに再認証、再承認、または OAuth のやり直しを求めないでください。

開発

# Install in development mode
cd excalibur-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
.venv/bin/pytest tests/

# Type checking
mypy src/excalibur_mcp/

# Formatting
black src/ tests/
ruff check src/ tests/

DPYC(TM) エコシステム

• tollbooth-dpyc -- Tollbooth の収益化機能向け Python SDK（ボールト、認証、料金設定、Lightning 決済、Nostr アイデンティティ）
• dpyc-community -- ガバナンスレジストリ：メンバーシップ、勧告、脅威モデル
• dpyc-oracle -- コミュニティコンシェルジュ（無料のオンボーディング＋メンバー検索）
• tollbooth-authority -- 認証基盤（Schnorr 署名付き発注証明書）
• tollbooth-sample -- サンプルオペレーター（標準テンプレート）
• tollbooth-pricing-studio -- iOS 料金モデルエディター／オペレーターコンソール
• cypher-mcp -- 収益化されたグラフ回答：Neo4j/AuraDB 上で名前付き Cypher テンプレートを使用
• schwab-mcp -- Charles Schwab の証券データ
• thebrain-mcp -- TheBrain の個人用ナレッジグラフ
• excalibur-mcp -- X/Twitter への投稿
• taxsort-mcp -- 税務分類＋Cloudflare Pages UI
• optionality-mcp -- オプション取引の練習ゲーム
• goodearth-mcp -- 小規模農場向けの地域限定気候分析
• beesknees-mcp -- The Bee's Knees レースゲーム
• roastify-mcp -- Roastify のコーヒーカタログとパッケージアートワーク
• ChartRemotely-mcp -- デスクトップのチャートに証券をリモートで表示
• tollbooth-web -- オペレーターのフロントエンド向け共有ブラウザー SDK
• tollbooth-oauth2-collector -- OAuth2 コールバックハンドラー（アドボケートサービス）
• tollbooth-shortlinks -- URL 短縮ユーティリティ

商標

DPYC、Tollbooth DPYC、および Don't Pester Your Customer は、Lonnie VanZandt の商標です。使用ガイドラインについては、dpyc-community リポジトリの TRADEMARKS.md をご覧ください。

ライセンス

Apache License 2.0 -- 詳細については LICENSE をご覧ください。