Ruflo に CAPTCHA ソルバーツールを追加する方法

リカバリ試行 1 回、ポーリング回数制限、構造化バリデーション、人間への引き継ぎを備えた、実行可能でフィクスチャ優先の stdio MCP コンパニオンツールです。

English · 简体中文 · 日本語 · Español · Português · 한국어

はじめに

承認済みの Ruflo ワークフローが CAPTCHA による中断に遭遇した場合、検証済みの結果を返すか、人間による確認のために停止する、制限付きのリカバリツールが必要です。このコンパニオン MCP サーバーは、Ruflo タスクが明示的な承認とサポート対象のチャレンジシグナルを経た場合にのみ CapSolver を呼び出す方法を示しています。これは Ruflo を変更するものではなく、公式パートナーシップを主張するものでもありません。API タスクオブジェクトは呼び出し元によるレビュー対象のままであり、この例が製品フィールドを独自に発明することはありません。

特徴

• MCP ツール 1 つ: captcha_solver_recover_once

• 明示的な承認とチャレンジのゲート

• 冪等性のための安定したリカバリ ID

• 作成呼び出し 1 回と結果ポーリング最大 5 回

• タイムアウト、構造化エラー、人間への引き継ぎ

• オフラインフィクスチャ。実際のキーやターゲットは不要

仕組み

Ruflo は承認済みタスクをローカルの stdio サーバーにルーティングします。ツールは、公式のタスク作成コントラクトを使用する前に、承認、チャレンジ状態、コンテキスト、予算を検証します。準備完了のソリューションのみを受け入れ、それ以外の場合は設定された予算内でポーリングし、安全に停止します。

アーキテクチャ

Ruflo → MCP tools/call → policy gates → CapSolver client → result validator → resume or human handoff

クイックスタート

npm test
npm run smoke
CAPSOLVER_API_KEY=replace_me npm start

Ruflo の Web UI で MCP (n) → Add Server を開き、stdio サーバーを選択して、ローカルコマンドに node src/server.js を使用します。Ruflo は HTTP および SSE エンドポイントも文書化していますが、このリポジトリは意図的に stdio のみを実装しています。

使用方法

examples/tool-call.json をフィクスチャの雛形として使用します。task は、公式の createTask リクエストコントラクト に照らしてレビューされたタスクオブジェクトのみに置き換えてください。結果のポーリングは 公式の getTaskResult ライフサイクル に従います。

出力例

{"ok":true,"status":"ready","recoveryId":"qa-run-0001","polls":1,"solution":{"fixtureResult":"ok"}}

サポート対象シナリオ

所有するテストフィクスチャ、明示的に承認された QA、承認済みターゲットに対する適切な規模の自動化。サポート対象外の状態は人間によるレビューのために停止します。

プロジェクト構造

• src/server.js — stdio JSON-RPC ルーター

• src/tool.js — MCP ツール定義と安全なエラーマッピング

• src/recovery.js — 制限付きリカバリコントラクト

• tests/ — オフライン単体テスト

• examples/ — フィクスチャのみのツール呼び出し

テスト

npm test
npm run smoke

テストは注入されたクライアントを使用し、ライブ API を呼び出すことはありません。

トラブルシューティング

AUTHORIZATION_REQUIRED、NO_SUPPORTED_CHALLENGE、DUPLICATE_RECOVERY、TIMEOUT、BUDGET_EXHAUSTED は停止シグナルです。タスクをレビューし、無期限に再試行する代わりに人間に引き継いでください。

責任ある使用

公開データ、所有するシステム、または明示的な書面による承認の対象となるターゲットのみを使用してください。アクセスポリシー、利用規約、レート制限、保持制限、人間による停止判断を尊重してください。この例を、プライベートデータ、認証情報、機密性の高い個人情報、無制限の収集、または不正アクセスに使用しないでください。

コントリビューション

変更はフィクスチャ優先、制限付き、フェイルクローズに保ってください。プルリクエストの前に両方のチェックを実行してください。

セキュリティ

キー、クッキー、ブラウザプロファイル、プライベートなターゲット URL、本番レスポンスをコミットしないでください。SECURITY.md を参照してください。

まとめ

このコンパニオンツールは、ルーティング、予算、検証、人間による制御を明示的に保ちながら、Ruflo に小さく監査可能なリカバリ境界を提供します。承認済みの本番アダプターでは、使用前にすべてのタスクフィールドを CapSolver のドキュメントに照らして確認してください。

メンテナー注記

CapSolver 統合の例を共有する開発者。

ライセンス

MIT