Autopia

Autopia

Autopia は、OpenAPI 仕様を公開している HTTP API を実際にテストし、API が実際にどのように動作するかを明らかにします。各発見を再現して検証し、その結果をバージョン管理された検索可能なナレッジベースとして提供します。AI エージェントは MCP 経由でこのナレッジベースを参照でき、Claude Code プラグインは対象 API を呼び出す直前に、その内容をエージェントのコンテキストに挿入します。

これは、docs/compendium-spec.txt（設計書）と docs/compendium-stack.txt（スタックの選定）で説明されている「Discrimen Compendium」の MVP です。まず仕様書の用語集をお読みください。コードでは、そこに記載された用語をそのまま使用しています。HANDOFF.txt には、現在の進捗状況と決定事項が記載されています。

稼働中： ホスト型サーバーは https://autopia-mcp.onrender.com/mcp にあります（ユーザーごとのキーについては認証を参照）。データベースは Neon のマネージド Postgres です。GitHub Actions のスケジュールにより、各ターゲットが毎晩（ルールのみ）と毎週（モデルによる処理を含む）更新されます。現在のカタログには、GitHub REST、npm レジストリ、PyPI、Anthropic のモデルエンドポイント、Open-Meteo ファミリー、weather.gov、Binance、Frankfurter、Open Library、PokeAPI、Nager.Date など、16 個の API が登録されています。

エージェントが得られるもの

API ごとの動作シートです。検証済みの主張のみから生成され、重要度順に並んだ Markdown です。まず、実際の API が独自の仕様と矛盾する点、次に仕様に記載されていないルール、続いてすべてのエンドポイントに共通する動作、最後にエンドポイントごとの動作（レスポンスの形式、エラー本文の形式、ページネーション、検証、認証）が記載されています。すべての行の末尾には、根拠となる試行 ID が記載されています。シートに記録される内容の例を示します。いずれも実際の API で再現済みです。

• GitHub では、コミットに対する since=not-a-date が、何も一致しないフィルターとして暗黙に適用されます（200、空のリスト）。一方、イシューでは同じ値を拒否し、形式を明記した 422 を返します。
• GitHub は、公開データの読み取りではトークンがなくても受け付けますが、リクエストには 5000 回／時ではなく、60 回／時の枠が適用されます。また、per_page は 100 に制限されます（Link ヘッダーで確認済み）。
• npm の検索では、ドキュメントに記載された上限が 250 であるにもかかわらず、size=2500 が受け付けられます。また、スコアの重み付けパラメーターの型チェックは行われません。
• Anthropic の /v1/models のカーソルには、既存のモデル ID を指定する必要があります。存在しない ID は、カーソルとしては 400、パスとしては 404 になります。

パイプライン

discover -> exercise -> aggregate -> cross-ref -> verify -> write (+ diff)
 spec       TRIALS      rules +      spec +       evidence   CLAIMS
 fetch,     (no LLM)    shape rules  siblings +   check +    + DIFFS
 hash,                  + one LLM    self-        reproduce
 trim                   pass         consistency

• 試行は、エッジケースの決定的なカタログであるバッテリー（src/worker/battery、バージョン 1.3.0）が生成する、固定されたリクエストです。ケースには、必須項目の省略、型違い、ドキュメントに記載された値の範囲外の列挙値、null 値と空の値、数値の境界（ゼロ、負の値、最大整数、最小値未満、最大値の直上および大幅超過、2048 文字の文字列）、パラメーターの重複、未知のフィールド、不正な認証情報および欠落した認証情報（スキームを維持）、ページ 0、非常に大きなページサイズ、最終ページを超えるページ、日時パラメーターに対する 4 種類の日付形式（日付のみ、タイムゾーンなし、エポック、無効な値）、不正なコンテンツタイプ、末尾のスラッシュ、HEAD が含まれます。ランダム性は一切ないため、2 回の実行で同一の試行入力が生成されます。保存されるすべてのレスポンスでは、切り詰め前の配列の長さが保持されるため、リストの意味が保存後も維持されます。
• クレームは、3 つのソースから得られます。試行に対する決定的なルール（無料）、成功したレスポンスに対する形状ルール（コンテンツタイプ、タイムスタンプ形式、null 値のフィールド、ページネーションフィールド、レート制限ヘッダーとキャッシュヘッダー）、そして自由形式の発見のための1 回のバッチ LLM パスです。LLM の出力は src/schemas/claim.schema.json に対して ajv で検証され、無効なオブジェクトは破棄されます。ルールが判定するのは、ステータスだけではなく、返ってきた内容です。不正な日付値に対する 200 について、比較用リクエストでは行があったのにリストが空なら「不可能なフィルターとして適用」、件数が一致するなら「明らかに無視」、それ以外なら「解釈された」と判定します。ページサイズの上限は、より多くの項目が存在することを確実に証明できる場合（Link の rel="next"、合計数のフィールド、またはドキュメントに記載された最大値に到達）にのみクレームされます。エラー形状のクレームでは、不正な値を送信したプローブのみを数え、認証、HEAD、コンテンツタイプのプローブは数えません。
• 検証がこの成果物の要です。すべてのクレームには、試行 ID と、それぞれで示されたステータスが記載されています。証拠のチェックは機械的に行われます。再現時には、正規化されたレスポンスのシグネチャ（ステータス、本文の種類、JSON の形状、エラーメッセージ）を比較し、完全なバイト列は比較しません。そのため、ライブデータが変化しても再現性は損なわれません。再現できないクレームは破棄されます。保存されるクレームでは、常に verified = true です。
• 相違点とは、ドキュメントに記載された事実（必須フラグ、型、列挙値、範囲）と矛盾するクレームです。ここが価値の源です。仕様に記載がないことは相違点にはなりません。仕様には記載がないものの API が強制するルール（同時に送信する必要があるパラメーター、暗黙のデフォルト値など）は、独自の種類 undocumented_constraint として保存されます。
• クレームの種類： required、type、auth、pagination、error_behavior、response_shape、undocumented_constraint、undocumented、other。
• 類似ツールとの比較。 同じ category を共有するツールをプローブごとに比較します。同じパラメーター名に対する同じルールで判定が異なる場合、そのクレームには divergence_type = sibling が設定され、他方のツール名を記した注記が付けられます。
• 前回分の引き継ぎ。 ルールのみの実行では、前回実行の LLM クレームを候補として再登録します。エンドポイントとプローブを基準に今夜の試行へ対応付けたうえで、同じ証拠チェックと再現処理にかけます。同じエンドポイントについて、同じプローブを引用する新たな LLM クレームがある場合（モデルが新しい表現で知見を言い換えた場合）、引き継いだクレームは破棄されます。重複する引き継ぎクレームは、より確信度の高いものを残します。
• 差分では、安定した claim_key を使って、ツールのバージョン間でクレームセットを比較します。仕様のハッシュが変わるたびに、ツールには新しいバージョンが割り当てられます。大きな仕様は、検証したパスに絞って切り詰めて保存されますが、ハッシュは引き続きドキュメント全体を対象とします。

クイックスタート

npm install
npm run autopia -- run targets/open-meteo-forecast.json     # full pipeline (LLM pass if a key is set)
npm run autopia -- docs open-meteo-forecast                 # the behavior sheet
npm run autopia -- claims open-meteo-forecast --divergences
npm run autopia -- search "is latitude required"
npm test

設定はローカルの .env ファイル（Git で追跡されません）に記述し、起動時に読み込まれます。

変数	用途
ANTHROPIC_API_KEY	LLM の処理を有効にします。設定しない場合、パイプラインはルールのみで実行され、その旨を通知します。また、anthropic-api ターゲットの認証情報でもあります
AUTOPIA_MODEL	LLM の処理に使うモデルです。デフォルトは claude-opus-5-5 です
DATABASE_URL	Postgres の接続文字列です。未設定の場合は、./data/pglite の組み込み PGlite が使われます
GITHUB_TOKEN	github-rest ターゲットの認証情報です（細粒度の読み取り専用公開トークンで十分です）
AUTOPIA_MCP_TOKEN	HTTP MCP サーバーの管理者トークンです（ユーザーごとのキーは、この設定なしで使えます）
AUTOPIA_MCP_OPEN	1 にすると、認証情報なしで /mcp を開きます。テスト専用であり、デプロイ環境では使用しないでください
AUTOPIA_MCP_PORT	HTTP サーバーのポートです。デフォルトは 4200 です
AUTOPIA_LOG	debug を指定すると、試行ごとのログを出力します
AUTOPIA_OFFLINE	1 にすると、データベースを開かずに、HTTP サーバーが /healthz 以外のすべてに 503 を返します（キルスイッチ）
RENDER_API_KEY、NEON_API_KEY	任意です。npm run kill / npm run revive を使って、1 つのコマンドでホスティングを一時停止・再開できます

ターゲットファイルでは、ヘッダー内で ${ENV_VAR} として認証情報を参照するため、コミットされたターゲットにキーが含まれることはありません。

PGlite に関する注意点： デフォルトのデータベースは data/pglite にある組み込み Postgres（PGlite）で、一度に開けるプロセスは 1 つだけです。MCP サーバーまたはダッシュボードを起動する前に、ワーカーを停止してください。DATABASE_URL に実際の Postgres を指定すれば、この制限を解除できます（スキーマは同じで、コードの変更は不要です）。npx tsx scripts/whichdb.ts を実行すると、コマンドがどちらを使用するか確認できます。

要覧の提供

npm run mcp          # MCP server over stdio (register in Claude Code / any MCP client)
npm run mcp:http     # the same server over Streamable HTTP at http://localhost:4200/mcp
npm run dashboard    # read-only dashboard at http://localhost:4100 (local only; not deployed)

stdio サーバーは npx tsx <repo>/src/server/mcp.ts としてクライアントに登録するか、HTTP 対応クライアントから HTTP サーバーの /mcp に接続してください（稼働確認には GET /healthz を使用します）。このサーバーには、エージェントがいつ参照すべきかを伝える指示ブロックが含まれています。対象ホストへのセッション内の最初のリクエストの前、および API 呼び出しが失敗した場合や予想外の結果になった場合に参照するよう指示します。

MCP ツール	用途
get_tool_docs	動作説明です。対象 API への最初のリクエストの前に呼び出してください。brief: true を指定すると、相違点、未文書化のルール、認証、ページネーション、エラーのみを返します
search_claims	エラー発生時の検索です。ホストと症状を指定して全文検索します。例：「github per_page 500」
get_divergences	実際の API が仕様と矛盾する主張のみを返します
get_tool_knowledge	検証済みの主張をすべて、種類で絞り込める構造化レコードとしてページネーション付きで返します
list_tools	カタログです。各ツールについて、試行対象となったホストを表示します
list_versions、get_version_diff	仕様のバージョンと、2 つのバージョン間で動作がどのように変わったかを返します
request_target、get_request_status	まだ対象になっていない API をリクエストします（キーが必要です）

すべてのツールの tool 引数には、ツール名、ホスト、またはこれから呼び出す URL（api.github.com、https://registry.npmjs.org/-/v1/search）を指定できます。この要覧はダンプではなく、ディレクトリです。URL または path を指定して get_tool_docs を呼び出すと、そのパスに一致するエンドポイントのみと、同じツールの他のエンドポイントへの 1 行のインデックスが返されます。これにより、エージェントはすべてを受け取るのではなく、必要な情報へと絞り込めます。各シートの末尾にはカバレッジのセクションがあり、調査済みの API エンドポイント、存在する他の API（ホスト別）、まだどこでも調査されていない項目、追加情報の取得に使えるツールを示します。これにより、1 つのシートを見た読者も、他に何を問い合わせられるかがわかります。証拠は、verbose=true を指定してレスポンスのプレビューを求めない限り、コンパクトに表示されます（試行 ID、プローブ、ステータス、リクエスト行）。保存されたリクエスト入力は保存前に秘匿化されるため、認証情報が証拠として提供されることはありません。npx tsx scripts/scan-stored-secrets.ts を実行すると、データベースにすり抜けた情報がないか監査できます。

Claude Code プラグイン：必要なときにシートを表示

エージェントがシートを読むのは、何かが読み取るよう指示した場合だけです。plugin/ 内のプラグインを使えば、これを確実に実行できます。Bash と WebFetch に対するPreToolUse フックが、コマンドまたは URL を対象ホストと照合し、呼び出しの前にそのエンドポイント用の動作シートをモデルのコンテキストに挿入します。また、対象ホストへの呼び出しが失敗した場合は、PostToolUse フックが 4xx/5xx に該当する検証済みの主張を挿入します。どちらもエラーが発生した場合は処理を続行します。さらに、詳細を調べるためのホスト型 MCP サーバーを登録し、同じトリガーテキストを含むスキルも提供します。

claude plugin install autopia --marketplace MaydayTrey/autopia
claude plugin configure autopia        # optional: a per-user key raises your quota; reads work without one

フックが動作するのは、URL 形式の記述（https://host/... または host/path）に対してのみです。URL に含まれるエンドポイントの簡潔なシートを挿入します。このシートには、そのエンドポイントに関する仕様の矛盾、文書化されていないルール、認証、ページネーション、エラーの動作、ツール全体の認証の動作、およびその他のエンドポイントの概要が 1 行で記載されています。セッション中、ホストとエンドポイントごとに 1 回だけ挿入され、サイズは 5KB を大きく下回ります。

プロジェクトレベルの指示。 リポジトリの CLAUDE.md または AGENTS.md に記載された行は、サーバーの指示ブロックよりも確実に従われます。対象 API と統合するプロジェクトでは、次を追加します。

Before the first call to api.github.com (or registry.npmjs.org, pypi.org, api.anthropic.com) in a
session, read its verified behavior sheet: Autopia MCP tool get_tool_docs {"tool":"<host>","brief":true}.
On an unexpected 4xx/5xx or an empty result from one of those hosts, call search_claims with the host
and the symptom before retrying.

チェックアウトしたリポジトリでセッション限定の試用を行うには、claude --plugin-dir ./plugin を実行します。キーを設定するまでは、セッションで autopia MCP サーバーが接続失敗（401）として表示され、フックはシートの代わりにセットアップに関する注記を挿入します。claude plugin configure autopia を実行して新しいセッションを開始すると、どちらも解消されます。詳細、状態の保存場所、プライバシーに関する注記は plugin/README.md に記載されています。

静的ページ：エージェントがすでに参照する場所

エラー文字列をウェブ検索したとき、プラグインも MCP 接続も使わずに、再現試験を引用したページが表示されるべきです。npx tsx scripts/build-site.ts --out site --base <url> は、カタログ、API ごとのページ、エンドポイントごとのページ、観測されたすべてのエラーメッセージとその発生条件のインデックス、llms.txt（AI クローラー向けインデックス）、サイトマップ、robots.txt を含む静的サイトとして資料集を生成します。ページは最小限の HTML でラップした動作シートです。各ページにはプレーンテキスト版の .md ファイルもあり、同じ内容をその場で取得する MCP 呼び出し名が記載されています。

.github/workflows/pages.yml は、ホストされているデータベースから更新後に毎日（および手動で）サイトをビルドし、GitHub Pages に公開します。初回のみ、リポジトリの Settings -> Pages -> Source で GitHub Actions を選択してください。サイトは https://<owner>.github.io/<repo>/ にあります。

緊急停止スイッチ

トラフィックが手に負えなくなった場合に備えて、元に戻せる段階が 3 つ用意されており、いずれも料金は発生しません（Render と Neon にはカードが登録されていません。有料アカウントは、週次の LLM 処理に使用する Anthropic キーのみで、Anthropic コンソールに独自の利用上限を設定できます）。

1. 配信を停止し、プロセスは維持する： Render サービスの環境変数に AUTOPIA_OFFLINE=1 を設定します。/healthz 以外のすべてのリクエストに retry-after 付きの 503 を返し、データベースは開きません。静的サイトは引き続き配信されます。再開するには、この変数を削除します。
2. ホスティングを停止する： npm run kill は、API を通じて Render ウェブサービスと Neon コンピュートエンドポイントを一時停止します（.env に RENDER_API_KEY と NEON_API_KEY が必要です。サービスとエンドポイントは自動検出されます）。npm run revive で両方を再開し、npm run kill:status で状態を確認できます。キーがない場合、コマンドはダッシュボードでの手順を表示します。
3. 利用料金の発生を停止する： Actions で run-all-llm ワークフローを無効にします。有料 API を呼び出すジョブはこれだけです。

最新状態の維持（自動化）

npm run run-all                        # every targets/*.json in sequence, one summary line per tool
npm run run-all -- --no-llm --prune-days 14

run-all はまず保留中のユーザーリクエストを処理し、次に各仕様を再取得します。仕様のハッシュが変わっていれば新しいツールバージョンを作成し、再度テストと検証を行い、前のバージョンとの差分を算出します。いずれかの対象で失敗すると、ゼロ以外の終了コードを返します。到達不能な対象は、試行ごとにタイムアウトを待つのではなく、早い段階で打ち切られます。

スケジュール。 .github/workflows/run-all.yml はルールのみの実行を毎晩行います（無料）。run-all-llm.yml はモデルを使用した実行を毎週行います。どちらもリポジトリのシークレットから DATABASE_URL、ANTHROPIC_API_KEY、組み込みの GITHUB_TOKEN を読み込み、Actions タブから手動で実行することもできます。対象数に応じてコストが増えるのはモデルを使う実行だけです。引き継ぎ処理により、週次実行の間もその主張は維持されます。保持期間： --prune-days N（または autopia prune N）は、バージョンごとの最新の完了済み実行と、差分で参照されている実行を除き、N 日より古い実行を削除します。--dry-run は削除せずに内容を報告します。それ以外の場合は、お使いのスケジューラー（タスク スケジューラ、cron、ホスト上のスケジュール済みジョブなど）を使って、同じコマンドを実行してください。

ユーザーリクエストによる対象

キーを持つ人なら誰でも、エージェント内から request_target MCP ツールを使って、まだ登録されていない API のテストをコンペンディウムに依頼できます。リクエストはその場で検証されます。仕様を取得して解析し、テスト項目を計画したうえで、必要なエンドポイント数と試行回数がユーザーに返されます。対象範囲の制限はレビュー時ではなく、送信時に適用されます。

• 仕様と、その仕様に記載されたすべてのサーバーについて、パブリックな http(s) ホストのみを許可します（localhost、プライベートアドレス範囲、IP リテラル、.internal 形式の名前は不可。ワーカーが実行環境内のどこかへのプロキシになってはなりません）
• キー不要：ヘッダーを含む対象は拒否されます。認証情報の管理はコントリビューター層の役割です
• 制御可能な範囲で適切な負荷に制限します：同時実行数は 1、呼び出し間隔は 300ms 以上、試行は最大 300 回
• 空いているツール名を使用し、キーごとのリクエスト数は 1 日あたり 3 件まで

保留中のリクエストは、次回の run-all の実行開始時にルールのみで処理されます。または、npm run autopia -- requests process で手動処理できます。処理が完了すると、保存された対象はファイルベースの対象と同様に、それ以降のすべての実行に含まれます。get_request_status は pending／running／done／failed を報告し、npm run autopia -- requests list はすべてのリクエストを表示します。

キーが必要な対象：2 つの方法

サーバー層、認証情報は Actions のシークレットに保存。 github-rest と anthropic-api は、サーバーが自ら実行するキー付きの対象です。対象ファイルではヘッダーを ${GITHUB_TOKEN} または ${ANTHROPIC_API_KEY} として指定し、ワークフローがシークレットを渡します。保存された試行入力ではヘッダー名に基づいて値が伏せられ、再現時にはメモリ内の対象から実際の値が復元されます。シークレットが送信されるのは API に対してのみで、それ以外に渡ることはありません。認証失敗のテスト用にテスト項目が使う偽の認証情報は、実際のキーと区別できるよう、意図的に伏せられません。

コントリビューター層、認証情報はコントリビューターの手元から出ません。 キーをこのリポジトリのシークレットに保存できない API については、同じオープンソースのワーカーをコントリビューターのマシンで実行します。コントリビューター自身の API キー、モデルのキー、データベースを使って結果をアップロードします。

npm run autopia -- contribute my-keyed-api --to https://autopia-mcp.onrender.com --key ak_... --yes

アップロードされるのは、仕組み上、主張と、ステータスコードおよびレスポンスシグネチャ（値を含まない型の形状）としての証拠だけです。リクエスト入力、ヘッダー、レスポンス本文、エラーメッセージのテキストはアップロードされません。主張の文言はローカルとサーバーで二重にサニタイズされます。メールアドレス、トークン、ベアラー認証情報、長い 16 進文字列、長い識別番号のように見えるものが含まれていれば、その主張は除外されます。--yes を付けない場合、コマンドはアップロードするすべての文言を表示して停止します。コントリビューターのツールは、信頼レベルが明示された対象です。そのシートには、コントリビューターのキーのプレフィックスと、主張が最後に再現された日付を示すバナーが表示されます。また、このサーバーではそれ以降に再検証されていないことも明記されます。このサーバーが自ら検証するツールが、コントリビューションによって上書きされることはありません。

ホスティング：マネージド Postgres ＋ HTTP MCP サーバー

組み込みデータベースは、1 台のノート PC での使用を想定しています。ホスト型のコンペンディウムでは、ワーカーとサーバーを同時に実行できるようマネージド Postgres を使用し、常時稼働する場所で HTTP MCP サーバーを実行します。 コードパスは同じです。DATABASE_URL によってドライバーが切り替わり、接続時にマイグレーションが適用されます。また、tests/integration/postgres-path.test.ts では実際の Postgres ワイヤープロトコルを使用してテストします。

1. データベース（Neon または Supabase。どちらも pgvector を含みます）。 プロジェクトを作成して接続文字列をコピーし、既存のコンペンディウムを移行します。

npx tsx scripts/db-export.ts data/export.json

DATABASE_URL="postgres://..." npx tsx scripts/db-import.ts data/export.json

インポートでは ID が保持され、既存の行はスキップされ、シーケンスがリセットされるため、安全に再実行できます。.env に同じ DATABASE_URL を設定すれば、ノート PC で実行するすべてのコマンドがホスト型データベースに接続します。

2a. Render 上のサーバー（無料プラン、カード不要。現在のデプロイ先）。 render.yaml は Blueprint です。Render で「New」->「Blueprint」を選択し、リポジトリを指定します。Dockerfile がビルドされ、DATABASE_URL の入力を求められ、AUTOPIA_MCP_TOKEN が生成されます（サービスの Environment タブからコピーしてください）。 無料サービスは約 15 分間操作がないとスリープし、最初のリクエストで起動するため、最初の呼び出しには時間がかかることがあります。プラグインのフックはフェイルオープンして次の呼び出しで再試行するため、これに対応できます。 Render は main から自動デプロイします。

2b. Fly.io 上のサーバー（有料アカウント、常時稼働）。 fly.toml と Dockerfile はリポジトリにあります。

fly launch --copy-config --no-deploy

fly secrets set DATABASE_URL="postgres://..." AUTOPIA_MCP_TOKEN="$(openssl rand -hex 24)"

fly deploy

サーバーは /mcp でリッスンし、プラットフォームのチェックには GET /healthz を使用します。イメージにはワーカーも含まれているため、run-all はスケジュールされたマシンとして、または手動で実行できます。Railway も同じ Dockerfile を使用して同様に動作します。

ID：匿名での読み取り、書き込みにはキーが必要

読み取りは予算内であれば誰でも利用できます。 7 つの読み取りツールは認証情報なしで応答します。IP ごとの制限（AUTOPIA_ANON_PER_MINUTE の既定値は 30、AUTOPIA_ANON_PER_DAY の既定値は 300）と、全体の日次上限（AUTOPIA_ANON_DAILY_CAP の既定値は 5,000）が適用されます。匿名の呼び出し元には応答プレビューは返されず、ページサイズにも上限が設けられます。読み取り応答（シート、カタログ、検索、クレーム）は 10 分間メモリ内キャッシュから提供されるため、同じ匿名呼び出しがデータベースに到達することはありません。既定値は、基盤となる無料プランに合わせて設定されています。1 日あたり 5,000 件の簡易シートは、送信データ量が約 75 MB、データベースへのラウンドトリップが数百回程度であり、Render と Neon の無料枠に十分収まります。ホスティング環境に余裕があれば数値を引き上げてください。上限に達すると、匿名の呼び出し元には再試行までの時間を示すヘッダー付きで 429 が返されますが、キーを持つ呼び出し元には影響しません。公開 API での読み取りにユーザーごとの ID は必要ありません。AUTOPIA_ANON_READS=0 にすると、キーが必要なアクセスに戻ります。request_target と /contribute には、常にキーが必要です。

キーを使うと、呼び出し元ごとのクォータ、使用ログに記録される名前、書き込みツールが利用できるようになります。

npm run autopia -- keys create alice --quota 2000

キー（ak_...）は一度だけ表示され、保存されるのはそのハッシュのみです。ユーザーは Authorization: Bearer ak_... として送信します。keys list ではプレフィックス、クォータ、呼び出し回数を確認できます。keys revoke <name-or-prefix> でキーを無効化できます。日次クォータを超えたキーには 429 が返されます。各ツール呼び出しでは、キー、ツール、対象として指定されたもの、成功の有無、レイテンシが記録されます。また、npm run autopia -- usage --days 7 で、キーごと、および最も多く問い合わせられたツールごとに利用状況を集計できます。

AUTOPIA_MCP_TOKEN が設定されている場合、管理者トークンとして機能します（クォータなし。定数時間で比較し、キーなしで呼び出しを記録します）。AUTOPIA_MCP_OPEN=1 にすると、匿名利用の制限がすべて無効になります（テスト専用）。現時点ではメンテナーがキーを発行していますが、セルフサービスでの発行はロードマップに含まれています。

CLI

コマンド	機能
run <target.json> [--no-llm] [--max-trials N] [--no-reproduce]	1 つのターゲットに対する全パイプラインを実行します
run-all [dir] [--no-llm] [--prune-days N] [--dry-run]	保留中のリクエストを処理した後、dir 内のすべてのターゲットを実行します（デフォルトは targets/）
plan <target.json>	何も送信せずに試行計画を表示します
tools、versions <tool>、runs <tool>	カタログ
docs <tool> [--version ID]	動作シートを Markdown 形式で表示します
claims <tool> [--divergences] [--version ID] [--json]	エビデンス付きの検証済みクレーム
search "<question>" [--tool NAME]	クレームをテキスト検索します
diff <tool> <fromVersionId> <toVersionId>	バージョン間の変更履歴
trial <id>	1 件の試行の詳細
compare-runs <tool>	直近 2 回の実行を対象とした決定性チェック
requests list、requests process [--llm]	ユーザーからリクエストされたターゲット
keys create <name> [--quota N]、keys list、keys revoke <name-or-prefix>	ユーザーごとのキー
usage [--days N]	キーごと、ツールごとの呼び出し数
contribute <tool> [--to URL --key ak_... --yes] [--out file]	コントリビューターバンドルを作成（およびアップロード）します
prune [days] [--dry-run]	データ保持

AUTOPIA_LOG=debug を設定すると、すべての試行と検証判断が出力されます。補助スクリプトは scripts/ にあります：run-progress.ts（実行を監視）、fail-stale-runs.ts（中断された実行をマーク）、 inspect-repro.ts と auth-probe-check.ts（再現と認証プローブをデバッグ）、 plan-dry-run.ts、db-smoke.ts、whichdb.ts、scan-stored-secrets.ts。

ターゲットの追加

targets/<name>.json を作成します（ファイル名がツール名です）。

{
  "name": "my-api",
  "category": "weather",
  "spec_url": "https://example.com/openapi.yml",
  "include_paths": ["/v1/path"],
  "baseline": { "/v1/path": { "required_param": "known good value" } },
  "optional_values": { "/v1/path": { "optional_param": "known good value", "since": "2026-01-01T00:00:00Z" } },
  "headers": { "x-api-key": "${MY_API_KEY}" },
  "rate": { "concurrency": 1, "min_interval_ms": 500 },
  "rate_overrides": { "/v1/search": { "min_interval_ms": 2500 } },
  "server": "https://api.example.com",
  "max_trials": 300
}

• include_paths は、大きな仕様からプローブ対象とするエンドポイントを絞り込みます（GitHub の仕様には 816 個の パスがあり、このターゲットでは 7 個を対象にします）。保存される仕様は、これらのパスと、それらが参照するコンポーネントに 絞り込まれますが、バージョンハッシュはドキュメント全体を対象とします。
• rate_overrides は、独自のクォータを持つ個々のパスの速度を落とします（GitHub の検索：30 回／分）。 エグゼキューターは x-ratelimit-remaining: 0 を伴う 403 もレート制限として扱い、リセットまで待機します。
• server は、仕様に定義されていない場合にベース URL を指定します。override_server: true は定義済みのサーバーを置き換えます（リージョナルミラー）。
• ターゲットは、URL ではなくリポジトリ内の仕様ファイルを参照できます。specs/ には、仕様を公開していない API（npm レジストリ、PyPI、Anthropic モデルエンドポイント）向けに手作業で作成した OpenAPI の説明が格納されています。これらに対して報告される相違は「API がこちらの説明と一致しない」という意味であり、 ファイルのヘッダーにもその旨が記載されています。
• targets/parked/ には、一時的に対象外となっているターゲットが格納されています（理由についてはその README を参照してください）。

対象範囲のルール（v1）：OpenAPI 3.x API の読み取り専用 GET エンドポイントが対象です。公開 API、または単一の 認証情報ヘッダーで保護された API が含まれます。書き込みエンドポイントと JSON リクエストボディは、まだプローブされません。ターゲットに 正式な仕様がない場合や副作用がある場合は対象範囲外となり、discover はエラーで停止します。

テスト

npm test はすべてのテストを実行します（130 件）。npm run test:unit と npm run test:integration で分割して実行できます。

• ユニットテストは tests/unit に各ステージ 1 ファイルずつあります：仕様の解析、バッテリー、シグネチャ、HTTP エグゼキューター （フェイク fetch）、ルール、形状ルール、相互参照、引き継ぎ、検証、差分、ドキュメントのレンダリング、 リダクション、キー、コントリビューションのサニタイズ、ホスト解決、プラグインフックのヘルパー。
• 統合テストは tests/integration にあります：使い捨てデータベース上の、仕込まれた癖のあるモック API（tests/mock-api/server.ts） に対する実際のパイプライン、stdio および HTTP 経由の MCP サーバー（オープン、管理者トークン、ユーザーごとのキー）、 ユーザーリクエスト、コントリビューション、データ保持、到達不能なターゲット、PGlite を介した Postgres ワイヤーパス、 および実際の HTTP サーバーを対象に子プロセスとして実行するプラグインフック。
• npm run mock-api は、手動で確認するためのモック API を起動します。

Postgres パスのテストは、全テストを並列実行した場合にセットアップで失敗することがまれにありますが、単独では成功します。変更を疑う前に再実行してください。

構成

docs/                  spec + stack docs
targets/               one JSON per API under study (parked/ for the ones on hold)
specs/                 hand-authored OpenAPI docs for APIs that publish none
drizzle/               generated SQL migrations (npm run db:generate after editing schema.ts)
src/db/                schema.ts (source of truth), client.ts (PGlite or Postgres), queries.ts,
                       docs.ts (behavior sheets), keys.ts, requests.ts, contributions.ts, retention.ts
src/worker/            pipeline stages: discover, exercise, aggregate/{rules,shape-rules,llm,carry},
                       crossref, verify, write, diff, pipeline.ts, cli.ts; battery/; signature,
                       http, redact, target, requests-runner, contribute
src/llm/               provider adapter (worker only, never the server)
src/schemas/           claim.schema.json
src/server/mcp.ts      MCP server (stdio and Streamable HTTP), instructions block, /contribute
src/dashboard/         Express + static page (local use)
plugin/                Claude Code plugin: PreToolUse hook, .mcp.json, skill, README
.claude-plugin/        marketplace.json (install source for the plugin)
.github/workflows/     test on push/PR; nightly rules-only and weekly LLM refresh
scripts/               export/import, audits, run helpers
tests/                 unit, integration, mock-api, helpers