cookie-mcp: Instructions file for Codex

Contributing to cookie-mcp

A local stdio MCP server that exposes Cookie Chain actions to any AI agent. It runs on the contributor's machine and signs with their key — non-custodial by design. This is a community/ecosystem project for all Cookie Chain developers: Cookiebox, Candy Shop, CookieSwap, Baked Bazaar and Hyperlane are venues it uses, not owners. Keep code and docs venue-neutral.

Layout

src/
  mcp/server.ts        # the ONLY entry point: registers every tool, thin wrappers over core/
  core/                # all logic lives here — pure, testable, framework-agnostic
    config.ts          #   constants, program IDs, endpoints
    rpc.ts             #   getConnection()
    wallet.ts          #   key loading, signer resolution: requireSigner() / getSigner()
    spendGuard.ts      #   hold an API-built tx's simulated effect on our wallet to the request
    errors.ts          #   CookieMcpError — the one error type surfaced to agents
    format.ts          #   rawToUi / uiToRaw / shortAddr — always go through these
    http.ts            #   fetchJson with retry policy
    txVerify.ts        #   decode + refuse an aggregator-built tx before signing (shared by escrow flows)
    limitOrders.ts     #   Cookiebox limit / stop orders (+ curveOrders.ts for curve pairs)
    dca.ts             #   Cookiebox DCA schedules (separate program, same build-verify-sign shape)
    zip/           #   Cookiebox Zip: trailing range orders on CLMM positions — decision (keeper rules, pure)
                       #   + program (PDAs, decoders, owner-signed enable/disable) + index (the three tools)
    launchpad/         #   MomoSwap launchpad: api (HTTP client) + curve (quote math) + positions (PDAs)
                       #   + program (which deployment: PDA scope + error-code build)
    nftLaunchpad/      #   MomoSwap NFT drops: api + verify (builds held to the vendored IDL) + curve
                       #   (drop design + graduation target) + art (local art folder) + chain (escrow,
                       #   fee wallet read from program accounts) + index (tools)
    domains/           #   CookOven `.cook` names: names (rules + pricing) + program (ixs/PDAs/decode)
                       #   + marketplace (market.cookoven.xyz ixs/PDAs/decode) + market (listings, buy/
                       #   sell ops) + shared (reads both halves need — escrow awareness lives here)
    liquidity/         #   create/add/remove/lock/claim across damm, cpAmm, clmm, cookieswap
    nft/               #   Baked Bazaar: auctionHouse (writes) + bazaar (reads) + momoListing (MomoSwap's
                       #   listing build, verified, list_nft's `via: "momoswap"`)
  idl/                 # committed IDLs (cp_amm, whirlpool, cookie_domains, momo_nft_launchpad, …)
scripts/               # smoke.ts (boots server, asserts tool count) + verify-*.ts (live checks)