Cicadas local MCP

Cicadas ローカル MCP

Cicadas.ai の顧客 API 用の実験的なローカル stdio ブリッジです。

認証が必要な機能は、本番環境での動作確認がまだ完了していません。 このリリースでは、ローカルのコントラクトテストと、パッケージ化した MCP のハンドシェイク／ツール一覧の確認に合格しました。受け入れテストに実際の顧客 API キーは使用していません。アカウントに紐づくカタログ、残高、見積もり、ジョブ検索、キーの失効、生成、ダウンロード、返金の各フローは、このリリースでは未検証です。有料生成テストは実施していません。

提供する機能

デフォルトのツール	対応する顧客 API 操作
list_video_models	利用可能なテキストから動画を生成するモデルのカタログを読み取ります
get_credit_balance	アカウント残高とキーの予算を読み取ります
quote_video	ジョブを作成せずにリクエストを検証し、クレジット費用を見積もります
get_video_job	所有するジョブのステータスを取得します
get_video_request	生成を再送信せずに、元の UUID で所有するリクエストを復元します

すべてのツールで、有効な Cicadas 顧客 API キーが必要です。ブラウザーセッション、プロバイダーキー、管理者キーでは代用できません。アカウントへのアクセスはこのパッケージに含まれていません。既存ジョブのステータス読み取りによって、プロバイダーのステータス確認や返金処理が行われることがあります。詳しくは顧客 API の詳細をご覧ください。

MCPB バンドルをインストールする

このリポジトリの v0.1.0 リリースから cicadas-local-mcp-0.1.0.mcpb をダウンロードします。MCPB Node バンドルと Node.js 22 以降に対応する MCP ホストを使用してください。バンドルをインポートし、機密設定フィールドに、非公開で保管した顧客 API キーを入力します。読み取り専用のキーを推奨します。

付属の MCPB 設定では CICADAS_ENABLE_GENERATION=0 が設定されており、上記の5つのツールのみが公開されます。キーをプロンプト、課題報告、ログ、スクリーンショット、コミットする設定ファイルに記載しないでください。

ソースから実行する

Node.js 22 以降が必要です。

npm ci --ignore-scripts
npm test
npm start

MCP ホストを設定し、node /absolute/path/to/src/server.mjs を実行するようにして、ホストの非公開環境設定を使って CICADAS_API_KEY を指定してください。API のベース URL のデフォルトは https://cicadas.ai/api/v1/ です。これはローカルの stdio プログラムであり、ホスト型のリモート MCP エンドポイントや OAuth コネクターではありません。

任意のソース設定

基盤となるブリッジでは CICADAS_ENABLE_GENERATION=1 を設定すると、create_video が公開されます。付属のバンドルでは無効になっています。生成には、生成が有効な顧客キー、明示的な confirmSpend: true、UUID リクエスト ID、クレジット上限も必要です。このリリースでは、有料生成とその配信はテストされていません。

CICADAS_DOWNLOAD_DIRECTORY を設定すると、既存のローカルディレクトリを対象とする download_video が任意で公開されます。ダウンロードには UUID ファイル名が使われ、上書きは拒否されます。また、ローカルパスと SHA-256 が報告されます。このリリースでは、ダウンロードの配信は本番環境で検証されていません。

カスタム HTTPS ベース URL を使用するには CICADAS_ALLOW_CUSTOM_ORIGIN=1 が必要です。ループバック HTTP には、さらに CICADAS_ALLOW_HTTP_LOOPBACK=1 が必要です。これらはローカルの運用者が設定するものであり、ツールの入力値ではありません。リダイレクトと Cookie 認証は拒否されます。ブリッジは、不確実な状況が発生した後に有料生成を自動で再試行しません。元のリクエスト UUID を使って復元してください。

検証と対象範囲

• 既存のブリッジコントラクトテスト：Node.js 22.23.2 で6件合格しました。
• 展開した MCPB：SDK のハンドシェイクとデフォルトの5つのツールの一覧表示に合格しました。生成機能は公開されませんでした。
• 2つのブリッジソースファイルは、既存の Cicadas ダウンロード可能ブリッジから変更されていません。
• ローカルテストではフィクスチャサーバーを使用します。認証を伴う本番環境での利用可能性、プロバイダーの出力、ストレージへの配信、支払い／返金の動作、視覚的な品質は確認できません。
• このリポジトリに含まれるのはスタンドアロンのブリッジとそのドキュメントのみであり、Cicadas のウェブサイトアプリケーションは含まれていません。

ウェブサイト · 顧客 API の詳細 · プライバシーポリシー