surf

エージェントに推測させるのはやめましょう

実行前に呼び出しを確認しましょう。 Gecko はオープンソースで、あなたのマシン上で動作します。
1 つのコマンドで、どんな API でも — 複雑なもの、有料のもの、オンチェーンのものでも — エージェントが
推測ではなく確認できる呼び出しグラフに変換し、支出を伴う操作はまずシミュレーションして
レシートを返します。
ウォレットも、決済手段も、保持するキーもありません — メインネットの 64 件のトランザクションのうち、署名前にコストを予測したものは 49 件、そのうち 47 件は単位まで正確でした（チェーンから再読み込み、2026-09-19）。

クイックスタート · ドキュメント · アーキテクチャ · よくある質問 · セキュリティ

エージェントが間違えてはならない呼び出しのために作られています。 次の 2 つの軸のどちらかに当てはまれば対象です。 複雑なサーフェス（有料、変化し続ける、ドキュメントがない、オンチェーン）または重大な影響を伴う操作 （エージェントが認証情報や資金を使って無人で動作する）。

Gecko とは

Gecko は、API を呼び出す AI エージェント向けに特化して構築されたオープンソースのナレッジグラフです。OpenAPI 仕様、ドキュメントサイト、Solana プログラムの IDL とソースを指定すると、そのサーフェスを読み込み、エージェントがたどれるグラフに変換します。すべての事実には出典がタグ付けされ、確認できないものは推測せずにフラグが付けられます。

仕様からエージェントがわかるのは、呼び出しがどのような 形をしているか です。しかし、その呼び出しが 成功するかどうか はわかりません。この隔たりは、完璧な仕様を含むあらゆる仕様に存在し、エージェントが大きな損失を招く原因になります。エラーになる呼び出しではなく、受け付けられてはいるものの誤っている呼び出しで失敗するのです。Gecko は具体的な呼び出しを 1 つ返してこの隔たりを埋めます。さらに、支出を伴う操作については、実際の状態に対して呼び出しを先にシミュレーションし、レシートを返します。

Gecko はエージェントでもオーケストレーターでもありません。キーを保持せず、署名もブロードキャストも行わず、レスポンスのペイロードも保存しません。保存するのはサーフェスと正確性のメタデータだけであり、あなたのデータは保存しません。

クイックスタート

インストール不要：

npx @geckovision/gecko doctor              # 1. check your environment
npx @geckovision/gecko add <spec-or-docs>  # 2. comprehend it — $0, no live call
npx @geckovision/gecko report <spec>       # 3. get the scorecard — grade + findings
npx @geckovision/gecko serve <spec>        # 4. your agent uses it over MCP

または、1 回インストールする場合：

npm install -g @geckovision/gecko          # prebuilt binary — no Python needed
uv tool install "gecko-surf[serve]"        # or pip, if you want the Python package

gecko add <spec-or-docs>

エージェントに接続します：

# Claude Code
claude mcp add my-api -- npx -y @geckovision/gecko serve <spec> --stdio

# Cursor / VS Code / any MCP client — mcp.json
{ "mcpServers": { "my-api": { "command": "npx", "args": ["-y", "@geckovision/gecko", "serve", "<spec>", "--stdio"] } } }

本番環境での使用開始は、別途、意図的に行う手順です：

gecko auth set <provider>                  # key goes to your OS keychain — never mcp.json

すると、エージェントはエンドポイントではなく質問をします：

Which fixtures kick off in the next hour, and what are the current odds?
What is the peg state of USDC right now?
Plan a swap of SOL for USDC on Meteora, bin_step 4.

理由

OpenAPI からわかるのは、何が存在するかです。IDL からわかるのは、プログラムの構造です。どちらも、操作を実行するには十分ではありません。

• ドキュメントは実態からずれていきます。2026 年には、レイアウトの予告のない変更によって、動作していたインテグレーションが 2 度壊れました。
• IDL には抜け落ちる事実があります。必須の Pump.fun アカウントが、IDL にまったく記載されていないことがあります。
• エージェントは推測します。誤った推測は、課金の発生、トランザクションのリバート、手数料の浪費につながります。

Gecko は推測をグラフに置き換えます。

• すべてのエッジに出典情報が付与されます — サーフェスから抽出されたもの、ソースから復元されたもの、または不明として正直にフラグ付けされたものです。捏造は一切ありません。
• すべての操作を事前に検証できます — 0 ドルのメインネットフォーク上でシミュレーションし、支出前に成功、または分類済みのリバートをレシートとして返します。
• すべての失敗が学びにつながります — 結果はカテゴリ別コーパスに記録されます。ドリフトの連続的な監視により、プロバイダーによる変更が動作していた呼び出しを壊した場合にフラグが立ちます。
• 認証はエージェントから見えません — 呼び出し時に、あなたのキーチェーンからキーが注入されます。モデルが認証情報を見ることはありません。

内部の仕組み

エージェント向けツールレイヤーの多くは薄いラッパーです。Gecko はメモリ基盤であり、その設計には教科書的な考え方とは意図的に異なる点が3つあります。

選択	重要である理由
決定論的な意味メモリ — 語彙検索、ベクトル DB なし	グラフが「おおよそ」記憶することはありません。BM25 とベクトルはエビデンスゲートの背後にあります
自己生成型のエピソードメモリ — カテゴリ別の結果とドリフト系列	Gecko は再シミュレーションして独自のエピソードを生成します。データプレーンに依存せず、ペイロードも保存しません
型付き手続きメモリ — 実行可能な JSON としてのプラン	ランディングプランと導出順序はビルダーが実行できます。テキストでは結合関係が失われますが、こちらでは失われません

そして、その深さは主張ではなく、測定によって示されています。

• オーバーレイ成果物。 自動的に理解したプログラムごとに、Gecko は公開されているあらゆるインターフェースからは導出できなかった事実の正確なリストを出力します（overlays/）。プログラムごとに定量化された、理解の価値です。
• 7層のセキュリティ、フェイルクローズ方式： 仕様サニタイザー · ツールごとの隔離 · 画像 Skill Guard · SSRF ネットガード · 帯域外認証アンカリング · 判定署名ゲート · AST によって強制される署名禁止境界。
• 数値： 5,043件のテスト · メインネットでのトランザクション64件、49件中47件で予測が完全一致 · 手数料リレー経由で5件を支払い、購入者は SOL を保有せず、最後の4件は USDG→USDC→購入のルート · Solana プログラム8件を接続、4件を差分検証済み · ライブのレシートペア2件 · 測定済みコンテキスト削減率−77%／−89% · 4,534件のプログラムを掲載したカタログ · 実際の仕様書14件で認証ヘッダーの露出0件。

図を確認する： docs.geckovision.tech のアーキテクチャ（3つのビューすべてを描画） · このリポジトリ内のマップ

約束ではなく、証拠

メインネットのフォーク上でライブ実行、$0：

ケース	単純な方法	Gecko
Pump.fun の購入	❌ リバート — AccountNotInitialized (3012)	✅ 成功 — 86,669 CU
Pump.fun の売却	❌ トークンを転送してからリバート — InvalidBondingCurveV2 (6074)	✅ 成功 — 50,783 CU
Meteora DLMM スワップ	❌ リバート — 導出のみで、ATA／ラップ／ビン配列の前処理なし	✅ ラップ → スワップ → アンラップ — 81,964 CU
Meteora のプール導出	❌ 古い3シード方式 → 知らないうちに誤ったプールを選択	✅ 正しい4シード導出、差分検証済み
ドキュメントのみの API（仕様書なし）	エージェントがエンドポイントを捏造	✅ 仕様書のドラフトを復元し、VERIFIED/REFUTED を検証

これらの成功を支える事実は、どのインターフェースにも載っていません。2024年に SDK が追加した4つ目の PDA シード、IDL が文章でしか言及していないアカウント、反証シミュレーションによって解決された手数料フィールド。エージェントがたどるのは、このグラフです。

ユースケース

TxLINE（有料スポーツオッズ）— Gecko なしの場合とありの場合

· MP4

API 間の相関 — 3 つの API にまたがる 1 つの質問

Pegana × Birdeye × Jupiter を宣言済みのエンティティで結合し、エージェントが 最初の試行で複数のサーフェスを横断して計画します。お試しください：gecko graph svg <spec> で任意のサーフェスの呼び出しグラフをレンダリングできます。

Solana プログラム — メインネットでコーヒーを購入

ここまでの内容はすべて無料のフォークです。これは違います。実際のメインネット、実際の USDC、本物の エスプレッソです。

let_me_buy は Solana 上のストアフロントプログラムです。販売者は ストアを立ち上げ、USDC 建ての商品を登録します。購入者は QR コードをスキャンして支払います。 ストアごとに 1 つのアカウント — PDA(["receipts", store_name]) — がメニュー、レシート、 累計数、販売者の権限を保持します。

MP4 版 — 編集なしのワンテイクです。何も署名する前に、レシートには 24,956 CU と記載されます。チェーンでの消費量も 24,956 CU (4X8dCyZU…、 スロット 439046190）です。キーがエンクレーブの外に出ることはありません。

uvx --from "gecko-surf[serve,solana]" gecko-orquestra --program let_me_buy --stdio

IDL に含まれていない 2 つの事実があり、どちらも呼び出しを失敗させます：

• mark_as_delivered は receipts シードを store_name として宣言していますが、 この命令自体の引数は _store_name と receipt_id です。シードが存在しない引数を 指定しているため、引数名でシードを解決する導出処理では、ストアを選択する唯一のシードの値を 取得できません。Gecko はシードの値でバインドします。
• make_purchase では、ストアの authority は書き込み可能ですが、署名者ではありません。購入者は ATA(signer, mint) から支払い、ストアには ATA(authority, mint) が入金されます。同じ mint でも所有者は異なります。両方を 1 つの所有者から導出すると、購入者に返金する購入処理を作ってしまいます。Gecko はビルダーに依頼する前に、その計画を拒否します。

予測は記憶された定数ではなく、状態を追跡します。 この ストアフロントで 3 回購入したところ、消費量は 23,789 → 24,183 → 24,956 CU でした。最後の 2 回は 同じ商品です。販売のたびにストアのアカウントにレシートが追加されるため、プログラムの処理量が増えます。そして、予測された値も、問い合わせるたびに新しい数値を示しました。

Gecko がサーフェスから抜け落ちた情報を復元し、Orquestra が命令を構築し、 レシートが実行されるかどうかを示します。署名する前に確認できます。

アーキテクチャ

制御プレーンであり、データプレーンではありません。 Gecko が保存するのはサーフェスと正確性のメタデータのみです — レスポンスのペイロード、ユーザーデータ、シークレットは保存しません。

1. 取り込み — OpenAPI／ドキュメント／IDL／プログラムソース → サニタイズし、隔離チェックを実施します。
2. 理解 — 正規化されたオペレーション、復元された PDA シード、生成された設定と計測済みの オーバーレイ。
3. 把握 — 来歴グラフ（サーフェス、プログラム、API 間の結合）。
4. 投影 — MCP 経由で質問に応じたツールを提供します。認証情報を除去し、実際の 2 つの仕様で コンテキストを −77%／−89% 削減できることを計測しました。
5. 検証 — 計画 → 外部ビルダー → シミュレーション → レシート → フェイルクローズ方式の署名 ゲート。Gecko が署名やブロードキャストを行うことはありません。
6. 学習 — カテゴリ別の結果 → ドリフト系列 → グラフに反映。

インタラクティブ図 · llms.txt · レシートの仕様

できること

機能	エントリーポイント
MCP 経由で任意の API をエージェントに提供	gecko serve <spec>
スコアカード：評価＋修正可能な指摘＋プレイグラウンド	gecko report <spec>
人間向けドキュメントから仕様の草案を復元	gecko from-docs <url>
CI 向けの初回呼び出し成功テスト	gecko test <spec>
サーフェスグラフをレンダリング	gecko graph svg <spec>
プログラムサーフェス：復元したシード＋導出プラン	gecko orquestra --program <name>
find_start：インテント → 適切な開始手順	gecko orquestra find-start "..."
構築済みトランザクションをシミュレーション → レシートを生成	gecko/simulate.py（エンジン）
SDK を埋め込み	from gecko import AgentApiClient
ドキュメントの主張を実際の動作と照合	gecko verify-docs <spec>
スキルの画像に隠れたペイロードがないかスキャン	gecko scan-image <path>

スキル

エンジンが製品であり、スキルはエージェントがその操作方法を学ぶためのものです。6 つのスキルが 1 つのプラグインとして提供されます。エージェントが読み込む Markdown であり、独自の実行ロジックはありません。

/plugin marketplace add GeckoVision/gecko-surf
/plugin install gecko-surf@geckovision

スキル	対象	機能
use-any-api	エージェントビルダー	初回から正しく未知の API を呼び出します。Gecko に OpenAPI またはドキュメントを指定すると、認証情報を隠したインテントに沿う MCP ツールを取得できます
read-js-docs	エージェントビルダー	curl が空のシェルを返す場合に、JavaScript でレンダリングされたドキュメントから API サーフェスを抽出します
anti-poisoning	エージェントビルダー	毒入りの仕様から保護します。エージェントの引数を誘導したり、キーを流出させたりするために作られた仕様が対象です
skill-guard	エージェントビルダー	毒入りのアーティファクトから保護します。エージェントが従う指示を含み、レビュー担当者には見えない画像や規約ページが対象です
api-agent-ready	API プロバイダー	すでに提供している MCP に加えて、自社 API のサーフェス全体をエージェントが利用できるようにします
x402-payai-setup	API プロバイダー	API に従量課金を組み込みます。収益は 100% そのまま受け取れます。Gecko は決済レールではなく、手数料も取りません

2 つの防御スキルは、同じ脅威が異なる形で現れるものです。毒入りの仕様はエージェントが呼び出すものを狙い、毒入りのアーティファクトはエージェントが行うことを狙います。全体像とステータスは skills/README.md をご覧ください。

モード

• 記録モード（デフォルト）：$0、スキーマから合成した応答を使用し、完全にオフラインで動作します。実際に呼び出す前に、すべてを反証できます。
• ライブモード：同じコードパスを使用し、エッジでキーリングから認証情報を注入します。 gecko auth set <provider> — 明示的な操作であり、暗黙には実行されません。

ホステッド

このリポジトリのエンジンは mcp.geckovision.tech でも稼働しています。理解済みのサーフェスを Streamable-HTTP MCP 経由で提供し、キーはサーバー側で注入されます。 開発者に費用はかかりません。プロバイダーは API ごとに定額料金を支払います。 Gecko は手数料を取らず、資金を保有せず、署名もしません。 → docs.geckovision.tech

リポジトリの構成

パス	内容
gecko/	エンジン — 取り込み、カタログ、ツール、グラフ、シミュレーション、コーパス
gecko/providers/	プログラムサーフェス（Meteora、Pump.fun、Jupiter、ORE、MetaDAO）＋設定
scripts/、gecko/cli.py	薄いトランスポート層 — 解析、パッケージの呼び出し、フォーマット
skills/	エージェント向けプラグイン — 6 つのスキル、エージェント、コマンド
docs/	アーキテクチャ、レシートのセマンティクス、仕様、ベンチマーク
examples/	フォークして使えるスターター

開発

uv run ruff format && uv run ruff check --fix
uv run mypy gecko
uv run pytest                # 5,043 passing
uv run python -m gecko.demo  # $0 recorded E2E

よくある質問

これはツール生成ラッパーですか？ いいえ。ツール生成は最低限の要件にすぎません。 この製品の価値は、検証済みのグラフ（すべてのエッジに出所情報があります）、レシート（資金が動く前にシミュレーションできます）、ドリフト系列（プロバイダーが機能しなくなったことを把握できます）にあります。

誰を対象としていますか？ 2つの軸のうち、どちらか一方に当てはまれば対象です。扱いにくいサーフェス（ペイウォールがある、変化し続ける、ドキュメントがない、オンチェーンである）、または重大な結果を伴うアクション（エージェントが認証情報や資金を使って無人で動作する）です。クリーンな API があり、人間が差分を確認していますか？ 私たちが必要ないかもしれません。それでも問題ありません。

Gecko は署名したり、資金を保管したりしますか？ いいえ。Gecko が署名、ブロードキャスト、本番トランザクションの構築を行うことはありません。文書化された例外は、シミュレーション専用の未署名アセンブリであり、署名／送信の境界で AST によって強制されます。構築はビルダー（例：Orquestra）、署名は署名サービス（ウォレット／TEE／お客様）が担います。

Gecko は何を保存しますか？ サーフェスと正確性に関するメタデータです。ペイロード、残高、結果に含まれる公開鍵、シークレットは保存しません。コーパスはカテゴリ型で、語彙が固定され、監査されています。

ベクトルデータベースですか？ いいえ。検索は字句ベースで決定論的です（トークンの重複に基づきます。BM25 とセマンティックの各層は、どちらも証拠ゲートの背後にあり、実測で再現率の低下が確認された場合にのみ有効になります。これには、埋め込みについて測定された否定的な結果が1つ含まれます）。

無料ですか？ エンジンは Apache-2.0 ライセンスで、機能が揃っており、セルフホスト可能です。ホスト型レイヤーは API プロバイダーが購入するものです。開発者に料金はかかりません。

コントリビューション

プルリクエストを歓迎します。プッシュする前に、上記のツールチェーンを実行してください。セキュリティ上の問題は → SECURITY.md。

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。