{ "markdown": "

\n \"Gecko\n

\n\n

Stop letting your agent guess

\n\n

\n Check the call before it counts. Gecko is open-source and runs on your machine:
\n one command maps any API — messy, paywalled, or on-chain — into a call graph your agent
\n checks instead of guesses from, and anything that spends is simulated to a\n receipt first.
\n No wallet, no payment rail, no key held — fifteen mainnet transactions, fifteen exact\n cost predictions.\n

\n\n

\n \"Python\n \"MCP\"\n \"tests\"\n \"Apache\n \"x402\"\n

\n\n

\n Quickstart ·\n Docs ·\n Architecture ·\n FAQ ·\n Security\n

\n\n\n\n> **Built for the calls your agent must not get wrong.** Two axes, either one qualifies:\n> a **messy surface** (paywalled, drifting, undocumented, on-chain) or a **high-stakes\n> action** (your agent runs unattended with credentials or money).\n\n## What Gecko is\n\nGecko is an **open-source knowledge graph built specifically for AI agents that call\nAPIs**. Point it at an OpenAPI spec, a docs site, or a Solana program's IDL and source,\nand it reads that surface into a graph your agent traverses — every fact tagged with\nwhere it came from, and anything it cannot establish **flagged rather than guessed**.\n\nA specification tells your agent what a call *looks like*. It cannot tell it whether the\ncall will *work*. That gap is in every spec, including a perfect one, and it is where\nagents fail expensively: not on the call that errors, but on the call that is accepted\nand wrong. Gecko closes it by handing back one specific call — and, for anything that\nspends, by simulating that call against real state first and returning a **receipt**.\n\nIt is not the agent and not an orchestrator. It holds no key, signs nothing, broadcasts\nnothing, and stores no response payload — it stores surfaces and correctness metadata,\nnever your data.\n\n## Quick start\n\nNo install:\n\n```bash\nnpx @geckovision/gecko doctor # 1. check your environment\nnpx @geckovision/gecko add # 2. comprehend it — $0, no live call\nnpx @geckovision/gecko report # 3. get the scorecard — grade + findings\nnpx @geckovision/gecko serve # 4. your agent uses it over MCP\n```\n\nOr install once:\n\n```bash\nnpm install -g @geckovision/gecko # prebuilt binary — no Python needed\nuv tool install \"gecko-surf[serve]\" # or pip, if you want the Python package\n\ngecko add \n```\n\nPlug into your agent:\n\n```bash\n# Claude Code\nclaude mcp add my-api -- npx -y @geckovision/gecko serve --stdio\n\n# Cursor / VS Code / any MCP client — mcp.json\n{ \"mcpServers\": { \"my-api\": { \"command\": \"npx\", \"args\": [\"-y\", \"@geckovision/gecko\", \"serve\", \"\", \"--stdio\"] } } }\n```\n\nGoing live is a separate, deliberate step:\n\n```bash\ngecko auth set # key goes to your OS keychain — never mcp.json\n```\n\nThen your agent asks questions, not endpoints:\n\n```\nWhich fixtures kick off in the next hour, and what are the current odds?\nWhat is the peg state of USDC right now?\nPlan a swap of SOL for USDC on Meteora, bin_step 4.\n```\n\n## Why\n\nAn OpenAPI says what exists. An IDL says what a program looks like. Neither is enough\nto act:\n\n- Docs drift. Working integrations broke twice in 2026 from silent layout changes.\n- IDLs drop facts. A required Pump.fun account never appears in the IDL at all.\n- Agents guess. A wrong guess posts a charge, reverts a transaction, burns fees.\n\nGecko replaces the guess with a graph:\n\n- **Every edge carries provenance** — `extracted` from the surface, `recovered` from\n source, or honestly `flagged` as unknown. Never fabricated.\n- **Every action can be verified first** — simulated on a $0 mainnet fork to a\n **receipt**: pass, or a classified revert, before any spend.\n- **Every failure teaches** — outcomes land in a categorical corpus; a drift series\n flags when a provider ships a change that breaks a working call.\n- **Auth is invisible to the agent** — keys injected at call time from your keychain.\n The model never sees a credential.\n\n## Under the hood\n\nMost agent-tool layers are thin wrappers. Gecko is a memory substrate, and three of\nits design choices are deliberately different from the textbook:\n\n| Choice | Why it matters |\n|---|---|\n| **Deterministic semantic memory** — lexical retrieval, no vector DB | the graph never \"approximately\" remembers; BM25 and vectors sit behind evidence gates |\n| **Self-generated episodic memory** — categorical outcomes + a drift series | Gecko re-simulates to create its own episodes; no dependence on your data plane, no payloads stored |\n| **Typed procedural memory** — plans as executable JSON | landing plans and derive orders a builder can run; text loses the join, ours can't |\n\nAnd the depth is measured, not asserted:\n\n- **The overlay artifact.** For every auto-comprehended program, Gecko emits the exact\n list of facts that could **not** be derived from any public surface\n ([`overlays/`](gecko/providers/configs/orquestra/overlays/)) — the value of\n comprehension, quantified per program.\n- **Seven security layers, fail-closed:** spec sanitizer · per-tool quarantine · image\n Skill Guard · SSRF netguard · out-of-band auth anchoring · verdict signing gate · an\n AST-enforced never-sign boundary.\n- **The numbers:** 2,400+ tests · 4 mainnet programs derivation-proven · 2 live\n receipt-pairs · −77%/−89% measured context cuts · a 4,500-program catalog listed ·\n 0 auth headers exposed across 14 real specs.\n\n**Explore the diagrams:** [architecture on docs.geckovision.tech](https://docs.geckovision.tech/architecture)\n(all three views, rendered) · [the map in this repo](docs/architecture.md)\n\n## Proof, not promises\n\nLive, on a mainnet fork, $0:\n\n| Case | Naive path | Gecko |\n|---|---|---|\n| Pump.fun buy | ❌ reverts — `AccountNotInitialized (3012)` | ✅ lands — 86,669 CU |\n| Pump.fun sell | ❌ transfers the tokens, then reverts — `InvalidBondingCurveV2 (6074)` | ✅ lands — 50,783 CU |\n| Meteora DLMM swap | ❌ reverts — derive-only, no ATA/wrap/bin-array preludes | ✅ wrap → swap → unwrap — 81,964 CU |\n| Meteora pool derivation | ❌ stale 3-seed scheme → the wrong pool, silently | ✅ correct 4-seed derivation, differential-proven |\n| Docs-only API (no spec) | agent invents endpoints | ✅ draft spec recovered, verified `VERIFIED/REFUTED` |\n\nThe facts behind those passes are not on any surface: a 4th PDA seed the SDK added in\n2024, an account the IDL only mentions in prose, a fee field resolved by a refuting\nsimulation. That is the graph your agent traverses.\n\n## Use cases\n\n**TxLINE (paywalled sports odds) — without vs with Gecko**\n\n![70-second demo — 18 first-call-correct tools, 8/8 poisoned attacks blocked, 32/32 correctness checks](docs/assets/launch.gif) · [MP4](docs/assets/launch.mp4)\n\n**Cross-API correlation — three APIs, one question**\n\nPegana × Birdeye × Jupiter joined on a declared entity; the agent plans across\nsurfaces first-try. Try it: `gecko graph svg ` renders any surface's call graph.\n\n**Solana programs — buy a coffee on mainnet**\n\nEverything above is a $0 fork. This one is not: **real mainnet, real USDC, a real\nespresso.**\n\n[`let_me_buy`](https://letmebuy.app) is a storefront program on Solana. A merchant\nstands up a store and lists products priced in USDC; a buyer scans a QR code and pays.\nOne account per store — `PDA([\"receipts\", store_name])` — holds the menu, the receipts,\nthe running count and the merchant's authority.\n\n

\n \"An\n

\n\n[MP4 version](docs/assets/coffee.mp4) — one unedited take. The receipt says **24,956 CU**\nbefore anything is signed; the chain charges **24,956 CU**\n([`4X8dCyZU…`](https://solscan.io/tx/4X8dCyZUNJHrFjFQqaNDjaLsya7ZLJ7gvjhAE6Zv7JV6AgeiGtGt9F5iJykJswvUb6MgdBcH5D6ERvxrjCFsbk5e),\nslot 439046190). The key never leaves its enclave.\n\n```bash\nuvx --from \"gecko-surf[serve,solana]\" gecko-orquestra --program let_me_buy --stdio\n```\n\n**Two facts the IDL does not carry, and both break the call:**\n\n- `mark_as_delivered` declares its `receipts` seed as `store_name`, but that\n instruction's own arguments are `_store_name` and `receipt_id`. The seed names an\n argument that does not exist, so a deriver resolving seeds by argument name gets\n nothing for the one seed that selects the store. Gecko binds by seed **value**.\n- In `make_purchase` the store's `authority` is writable but **not a signer**. The buyer\n pays from `ATA(signer, mint)`; the store is credited at `ATA(authority, mint)` — same\n mint, different owner. Derive both from one owner and you have built a purchase that\n pays the buyer back. Gecko refuses that plan before a builder is ever asked.\n\n**The prediction tracks state, not a memorised constant.** Three purchases at this one\nstorefront were charged 23,789 → 24,183 → 24,956 CU; the last two are the *same\nproduct*. Each sale appends a receipt to the store's account, so the program does more\nwork — and the receipt predicted the new number each time it was asked.\n\nGecko recovers what the surface drops, [Orquestra](https://orquestra.dev) builds the\ninstruction, and the receipt says whether it lands — before any signature.\n\n## Architecture\n\n

\n \"Gecko\n

\n\n**Control plane, never data plane.** Gecko stores surfaces + correctness metadata —\nnever response payloads, user data, or secrets.\n\n1. **Ingest** — OpenAPI / docs / IDL / program source → sanitized, quarantine-checked.\n2. **Comprehend** — normalized ops, recovered PDA seeds, generated configs + measured\n overlays.\n3. **Know** — the provenance graph (surface, program, cross-API joins).\n4. **Project** — question-shaped tools over MCP; auth stripped; −77%/−89% context cuts\n measured on two real specs.\n5. **Verify** — plan → external builder → simulate → **receipt** → fail-closed signing\n gate. Gecko never signs, never broadcasts.\n6. **Learn** — categorical outcomes → drift series → back into the graph.\n\n[Interactive diagrams](docs/architecture.md) · [llms.txt](architecture.llms.txt) ·\n[Receipt semantics](docs/receipt.md)\n\n## What you get\n\n| Capability | Entry point |\n|---|---|\n| Serve any API to agents over MCP | `gecko serve ` |\n| Scorecard: grade + fixable findings + Playground | `gecko report ` |\n| Recover a draft spec from human docs | `gecko from-docs ` |\n| First-call-correctness tests for CI | `gecko test ` |\n| The surface graph, rendered | `gecko graph svg ` |\n| Program Surface: recovered seeds + derive plans | `gecko orquestra --program ` |\n| find_start: intent → the right starting instruction | `gecko orquestra find-start \"...\"` |\n| Simulate → receipt on a built transaction | `gecko/simulate.py` (engine) |\n| Embed the SDK | `from gecko import AgentApiClient` |\n| Verify docs claims against reality | `gecko verify-docs ` |\n| Scan a skill image for hidden payloads | `gecko scan-image ` |\n\n## Skills\n\nThe engine is the product; the skills are how an agent learns to drive it. Six of them\nship as one plugin — markdown the agent reads, no executable logic of its own.\n\n```\n/plugin marketplace add GeckoVision/gecko-surf\n/plugin install gecko-surf@geckovision\n```\n\n| Skill | For | What it does |\n|---|---|---|\n| [`use-any-api`](skills/use-any-api/SKILL.md) | agent builder | Call an unfamiliar API first-call-correct — point Gecko at OpenAPI or docs, get intent-shaped MCP tools with auth hidden |\n| [`read-js-docs`](skills/read-js-docs/SKILL.md) | agent builder | Extract the API surface from JS-rendered docs, when `curl` returns an empty shell |\n| [`anti-poisoning`](skills/anti-poisoning/SKILL.md) | agent builder | Defend against a poisoned **spec** — one written to route your agent's arguments or exfiltrate your key |\n| [`skill-guard`](skills/skill-guard/SKILL.md) | agent builder | Defend against a poisoned **artifact** — an image or convention page carrying an instruction your agent will follow and your reviewer cannot see |\n| [`api-agent-ready`](skills/api-agent-ready/SKILL.md) | API provider | Make your own API's whole surface agent-usable, *alongside* whatever MCP you already ship |\n| [`x402-payai-setup`](skills/x402-payai-setup/SKILL.md) | API provider | Wire pay-per-call onto your API. You keep 100% — Gecko is not the rail and takes no cut |\n\nThe two defense skills are one disease with two deliveries: a poisoned *spec* aims at\nwhat your agent **calls**, a poisoned *artifact* aims at what your agent **does**. Full\nmap and status in [`skills/README.md`](skills/README.md).\n\n## Modes\n\n- **Recorded** (default): $0, schema-synthesized responses, fully offline. Falsify\n everything before any live call.\n- **Live**: same code path; credentials injected from your keychain at the edge.\n `gecko auth set ` — deliberate, never implicit.\n\n## Hosted\n\nThe engine in this repo also runs at [mcp.geckovision.tech](https://mcp.geckovision.tech)\n— comprehended surfaces served over Streamable-HTTP MCP, keys injected server-side.\nDevelopers never pay; providers pay a flat price per API.\nGecko takes no cut, holds no funds, signs nothing.\n→ [docs.geckovision.tech](https://docs.geckovision.tech)\n\n## Repo map\n\n| Path | What |\n|---|---|\n| `gecko/` | the engine — ingest, catalog, tools, graphs, simulate, corpus |\n| `gecko/providers/` | program surfaces (Meteora, Pump.fun, Jupiter, ORE, MetaDAO) + configs |\n| `scripts/`, `gecko/cli.py` | thin transport — parse, call the package, format |\n| `skills/` | the agent-facing plugin — six skills, agents, commands |\n| `docs/` | architecture, receipt semantics, specs, benchmarks |\n| `examples/` | forkable starters |\n\n## Development\n\n```bash\nuv run ruff format && uv run ruff check --fix\nuv run mypy gecko\nuv run pytest # 2,400+ passing\nuv run python -m gecko.demo # $0 recorded E2E\n```\n\n
\nFAQ\n\n**Is this a tool-generation wrapper?** No. Tool generation is the table stakes. The\nproduct is the verified graph (provenance on every edge), the receipt (simulate before\nmoney moves), and the drift series (know when a provider breaks you).\n\n**Who is it for?** Two axes — either one qualifies: a messy surface (paywalled,\ndrifting, undocumented, on-chain), or a high-stakes action (your agent runs unattended\nwith credentials or money). Clean API + a human reviewing the diff? You may not need us\n— and that's fine.\n\n**Does Gecko sign or hold funds?** Never. Gecko never signs, never broadcasts, never\nbuilds the production transaction — sim-only unsigned assembly is the documented\ncarve-out, AST-enforced at the sign/send boundary. Building belongs to builders\n(e.g. Orquestra), signing to signers (wallet / TEE / you).\n\n**What does Gecko store?** Surfaces and correctness metadata. Never payloads, balances,\npubkeys-in-outcomes, or secrets. The corpus is categorical, closed-vocabulary, audited.\n\n**Vector database?** No — retrieval is lexical and deterministic (token-overlap; BM25\nand semantic tiers both sit behind evidence gates that flip only on measured recall\nfailure — including one measured negative result on embeddings).\n\n**Is it free?** The engine is Apache-2.0, complete, self-hostable. The hosted layer is\nwhat an API provider buys. Developers never pay.\n\n
\n\n## Contributing\n\nPRs welcome. Run the toolchain above before pushing. Security findings →\n[SECURITY.md](SECURITY.md).\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE).\n", "bytes": 16641, "sha": "0bd93d1d5aea0d10b85496c4eedc7c9cd99caaadca767ac50a67384ce3f57a4b", "repo_slug": "geckovision/gecko-surf", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_tech_geckovision_surf_f69dabdb/readme" }