@parabolicfamily/mcp 0.2.0 → 0.2.2

package/README.md

@@ -18,10 +18,26 @@ The ABIs ship with the package, so it works offline against any Arc RPC you poin
 
 One tool, `parabolic.check_ticker`, and nothing else moved: every call that worked in 0.1.7 works unchanged.
 Given a ticker it asks the Parabolic site whether a coin already carries it on **any** chain the site serves
-and whether `<ticker>.parabolic.family` is free. It is advice and not a gate — nothing on chain enforces a
-unique symbol — and the hostname is the one exclusive thing, held by the oldest coin with that ticker. The
+and whether `<ticker>.parabolic.family` is free. It is advice and not a gate (nothing on chain enforces a
+unique symbol), and the hostname is the one exclusive thing, held by the oldest coin with that ticker. The
 ticker is normalised the way the site normalises it, so an impossible one is refused before a request is spent.
 
+## What changed in 0.2.2
+
+Coins on other launchpads read as ours do. `list_coins` pages by cursor (`after`, answering `next`), through the
+indexer or the site's API. `get_coin` answers a venue ref (`rhc:pons:0x…`), and `list_venue_coins` lists from
+the site's own index of that launchpad when no subgraph is set. A new tool, `parabolic.venue_history`, reads a
+launchpad coin's candles, tape, holders and positions from the site (19 tools in all). A venue coin's price is
+taken from its own supply, an unnamed quote asset is published as such (never as fiat), a missing creator is
+`null`, and the fee split respects a coin whose buyback is off.
+
+## What changed in 0.2.1
+
+No tool changed. The dependency tree is refreshed (`@modelcontextprotocol/sdk` 1.32.1, and the patched
+`proxy-addr`, `ip-address` and `fast-uri` under it), so `npm audit` on an install reads clean, and a failed RPC
+call now writes the endpoint's host to stderr rather than its whole URL, so a keyed endpoint's key stays out of
+the server's own log as well as out of the answer.
+
 ## What changed in 0.2.0
 
 Five tools for coins made on **other launchpads** (pons on Robinhood Chain, SolonPad on Arc), traded through
@@ -66,7 +82,7 @@ unchanged and means the same chain it meant: an unqualified address is still Arc
 chain it meant**, because an unqualified identifier means Arc, permanently (`docs/20-multichain.md` §3).
 
 - **Added, optional, on every tool: `chain`.** A chain key (`"arc"`) or an id (`5042`). Left out, it is the
-  chain the server is configured for — Arc with no configuration at all. Arguments are strict, so this had
+  chain the server is configured for: Arc with no configuration at all. Arguments are strict, so this had
   to be declared rather than tolerated; passing nothing is what every existing caller does.
 - **Added: `address` accepts a reference.** `0x…` is still a coin on this server's chain. `rhc:0x…` names a
   coin on another one and is **refused by name** ("…is on Robinhood Chain (chain 4663); this server is
@@ -96,6 +112,9 @@ mainnet by mistake, and `protocol_stats` reports the chain and RPC host the serv
 | `PARABOLIC_MEMO_ROUTER` | `ParabolicMemoRouter`: the atomic launch-and-buy and the referral-carrying buy. Refused on a chain whose record deploys `ParabolicRouter` and no memo router, because the two share no function selector and a routed build against that address would revert | the deployment for the chain id |
 | `PARABOLIC_EURC` | EURC address, only for EURC-quoted coins | the deployment for the chain id |
 | `PARABOLIC_SUBGRAPH_URL` | Subgraph endpoint: richer listings, holders, 24h volume, protocol stats | unset (the public API is used instead) |
+| `PARABOLIC_API_URL` | Parabolic's public read API: listings, `check_ticker`, `referral_status`, `venue_history` and another launchpad's coins when no venue subgraph is set; `""` turns it off | the site that serves the chain (see below) |
+| `PARABOLIC_SUBGRAPH_URL_<VENUE>_<CHAIN>` | Another launchpad's subgraph for `list_venue_coins`: `PARABOLIC_SUBGRAPH_URL_PONS_RHC`, `PARABOLIC_SUBGRAPH_URL_SOLONPAD_ARC`, `PARABOLIC_SUBGRAPH_URL_AKA_ARC` | unset (the site's own index of that launchpad is read instead) |
+| `PARABOLIC_AGGREGATOR_ROUTER` | `ParabolicAggregatorRouter` for the four routed tools. Honoured only on Anvil (31337) and the testnets, and only where the chain's deployment record names no router; ignored on Arc (5042) and Robinhood Chain (4663), where the record's router is the only one | the router in the chain's deployment record (`aggregator`), none until it is deployed |
 | `PARABOLIC_EXPLORER_URL` | Block explorer the address and transaction links are built from | the explorer for the chain id |
 | `PARABOLIC_HOOK` | `ParabolicHook` address | read from `factory.memeHook()` |
 | `PARABOLIC_ARC_MEMO` | Arc `Memo` system contract | `0x5294E9927c3306DcBaDb03fe70b92e01cCede505` |
@@ -111,8 +130,9 @@ built-in address for the chain or `PARABOLIC_RPC_URL` points anywhere but the ch
 reads the chain instead. To force that for any other reason, set `PARABOLIC_API_URL=""`.
 
 Call `parabolic.docs` to print the exact addresses this server is using, including the memo router
-every launch with an opening buy is sent to. Check each one on Arcscan, where all of them are verified
-with source, before you sign anything:
+every launch with an opening buy is sent to, and check each one before you sign anything. The Arc
+Testnet contracts below are on Arc's testnet explorer; the mainnet and Robinhood Chain contracts match
+their source on Sourcify (graded `match`), because Arc's mainnet explorer was behind a login when they deployed:
 
 | Contract | Arc Testnet (5042002) |
 |---|---|
@@ -128,12 +148,12 @@ reads it (and builds the registration for your wallet to sign); nothing on the l
 
 Arc mainnet (5042), deployed 16 September 2026 at block 21,105,294: factory
 `0x27EAeC564fd049E6920C73323ffA7eb6a32A4B1e`, memo router `0x7d642150A222D0F6c98e2fC6bBe86E8Bb6DC90d0`,
-source verified on Sourcify. Arc has published no identity registry for mainnet, so on chain 5042
+both matching their source on Sourcify. Arc has published no identity registry for mainnet, so on chain 5042
 `agent_status` says there is no registry rather than reporting a wallet as unregistered.
 
 Robinhood Chain (4663), deployed 19 September 2026: factory
 `0x25c9cFa179256A29f84b9Fd0DcF7cB2ff24b473d`, quoted in USDG (`0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168`,
-six decimals, Paxos), gas paid in ETH, source verified on Sourcify. Gas there is not a dollar, so a launch
+six decimals, Paxos), gas paid in ETH, the factory matching its source on Sourcify. Gas there is not a dollar, so a launch
 fee or a balance on that chain is never a figure in dollars, and no identity registry exists. The chain's
 `ParabolicRouter` is deliberately not configured here; see 0.1.9 above.
 
@@ -143,10 +163,11 @@ fee or a balance on that chain is never a figure in dollars, and no identity reg
 claude mcp add parabolic -- npx -y @parabolicfamily/mcp
 ```
 
-That is enough to launch, quote and trade on Arc Testnet: `get_coin`, `quote_buy`, `quote_sell` and
-every `build_*` tool read the chain directly. `list_coins` is the exception — with no subgraph it can
-only scan the most recent blocks, because public Arc RPCs cap log queries, so it marks its result
-`partial` and names the range it covered. Point it at a subgraph for the full board:
+That is enough to launch, quote and trade on Arc mainnet (5042), the default: `get_coin`, `quote_buy`,
+`quote_sell` and every `build_*` tool read the chain directly, and `list_coins` reads Parabolic's public
+read API. Only when neither a subgraph nor that API is available does `list_coins` fall back to scanning
+`TokenLaunched` logs, which public Arc RPCs cap, so it then marks its result `partial` and names the range
+it covered. Point it at a subgraph for holders, 24h volume and 24h change:
 
 ```sh
 claude mcp add parabolic \
@@ -193,22 +214,29 @@ Arguments are strict: a key a tool does not know fails with `Unrecognized key` i
 
 | Tool | Purpose |
 |---|---|
-| `parabolic.list_coins` | `{ status?: "climbing" \| "graduated", sort?: "trending" \| "new" \| "near_graduation" \| "market_cap", limit?, pair?: "USDC" \| "EURC" \| "Agents" }`. Subgraph when configured, otherwise Parabolic's public read API; a `TokenLaunched` log scan only when both are unavailable. `pair` is the quote asset, except `"Agents"`, which means the coin's creator holds an ERC-8004 identity: that is read from Arc's registry (one `balanceOf` per creator, over the top 100 of the sort) whatever the listing source is. Without a registry for the chain the result sets `pairFilterApplied: false` and the `source` line says the filter did not run. |
-| `parabolic.get_coin` | `{ address }` (token or curve). Name, ticker, creator, curve, status/phase, raised/threshold/progress, price, market cap, holders, pool id, fee terms and 50/30/20 split, snipe-tax window and `currentSnipeTaxBps()`. |
+| `parabolic.list_coins` | `{ status?: "climbing" \| "graduated", sort?: "trending" \| "new" \| "near_graduation" \| "market_cap", limit?, after?, pair?: "USDC" \| "EURC" \| "Agents" }`. Pages by cursor: pass an earlier answer's `next` as `after` (or `""` to start at the newest coin); `next` is null on the last page. Subgraph when configured, otherwise Parabolic's public read API; a `TokenLaunched` log scan only when both are unavailable. `pair` is the quote asset, except `"Agents"`, which means the coin's creator holds an ERC-8004 identity: that is read from Arc's registry (one `balanceOf` per creator, over the top 100 of the sort) whatever the listing source is. Without a registry for the chain the result sets `pairFilterApplied: false` and the `source` line says the filter did not run. |
+| `parabolic.get_coin` | `{ address }` (token or curve). Name, ticker, creator, curve, status/phase, raised/threshold/progress, price, market cap, holders, pool id, fee terms and the coin's own split (creator / protocol / buyback as the curve snapshotted them at launch, the buyback leg only while the creator's `buybackEnabled` switch is on), snipe-tax window and `currentSnipeTaxBps()`. |
 | `parabolic.quote_buy` | `{ address, quoteIn, buyer?, slippageBps? }`. Exact curve math on live reserves: fee, creator tax and snipe tax legs, spot vs effective price, price impact, whether the buy graduates the coin, suggested `minTokensOut`. `buyer` checks the snipe-tax exemption. |
 | `parabolic.quote_sell` | `{ address, tokensIn, slippageBps? }`. Gross, fee, creator tax, effective price, price impact, suggested `minQuoteOut`. |
 | `parabolic.build_buy_tx` | `{ address, quoteIn, minTokensOut?, recipient, buyer?, slippageBps?, memo? }` → unsigned `curve.buy(...)` (value = quote on native-USDC curves; an approval step for EURC pairs). `memo: { referral, note? }` returns the memo-routed variant instead (see below). |
 | `parabolic.build_sell_tx` | `{ address, tokensIn, minQuoteOut?, recipient, slippageBps? }` → unsigned ERC-20 approval + `curve.sell(...)`. |
-| `parabolic.build_launch_tx` | `{ name, ticker, image?, description?, socials?, pair?, devBuy?, creatorTaxBps?, creator, buybackEnabled? }`. The `TokenParams` are built exactly like the web Create form (economics pinned with `previewLaunchEconomics`, random salt). With `devBuy` and `PARABOLIC_MEMO_ROUTER` set: one unsigned `ParabolicMemoRouter.launchAndBuy` (value = launch fee + dev buy, `creatorFeeRecipient` zero, `minTokensOut` from the curve math on the launch config; `launchAndBuyWithToken` plus an approval for EURC). Otherwise: unsigned `factory.launchToken(...)` with the launch fee as value and, for a `devBuy`, the follow-up buy calldata to send to the curve from the `TokenLaunched` event. |
+| `parabolic.build_launch_tx` | `{ name, ticker, image?, description?, socials?, pair?, devBuy?, creatorTaxBps?, creator, buybackEnabled? }` (`creatorTaxBps` 0 to 500, the factories' `maxCreatorTaxBps()`). The `TokenParams` are built exactly like the web Create form (economics pinned with `previewLaunchEconomics`, random salt). With `devBuy` and `PARABOLIC_MEMO_ROUTER` set: one unsigned `ParabolicMemoRouter.launchAndBuy` (value = launch fee + dev buy, `creatorFeeRecipient` zero, `minTokensOut` from the curve math on the launch config; `launchAndBuyWithToken` plus an approval for EURC). Otherwise: unsigned `factory.launchToken(...)` with the launch fee as value and, for a `devBuy`, the follow-up buy calldata to send to the curve from the `TokenLaunched` event. |
 | `parabolic.agent_status` | `{ address }`. Whether the wallet holds an ERC-8004 agent identity on Arc's `IdentityRegistry` (`balanceOf`), how many it holds, and the registry address and chain. On a chain where Arc has published no registry the answer is that fact, with `registered` and `identities` null. |
 | `parabolic.build_register_agent_tx` | `{ from, metadataURI? }` → unsigned `IdentityRegistry.register(metadataURI)` (no value). The registry mints the ERC-721 identity to the signer, so `from` is the wallet that sends it, and returns the agent id; read it from the `Transfer` log in the receipt. `metadataURI` is a pointer to the agent's metadata stored as `tokenURI` and may be empty. Warns when the wallet already holds an identity. |
 | `parabolic.protocol_stats` | Subgraph totals (launches, graduations, trades, volume, fees, daily series) plus the factory's live launch fee, curve preset, snipe-tax terms and contract addresses. |
 | `parabolic.check_ticker` | `{ ticker }`. Whether a Parabolic coin already carries the ticker on **any** chain the site serves, and whether `<ticker>.parabolic.family` is free, read from the site's own route (`/api/v1/studio/ticker` on `PARABOLIC_API_URL`'s site). **Advice, not a gate**: nothing on chain enforces a unique symbol, so `free: false` lists what exists (`taken[]`, each with a `ref` for `get_coin`) and does not stop a launch. The hostname is the one exclusive thing and belongs to the oldest coin carrying the ticker (`hostFree`). A name on the site's reserved list comes back as `reserved` and is not a coin. The ticker is normalised the way the site does it (A-Z and 0-9, case and punctuation ignored, 2 to 10 characters); one outside that is refused before the site is asked. Call it before `build_launch_tx`. |
-| `parabolic.docs` | The adopted parameters, curve mechanics, verified Arc facts and this server's configuration, as text. |
+| `parabolic.referral_status` | `{ account }`. One wallet's referral payouts on this server's chain, read from the site (`GET /api/v1/referrals/{account}`): per asset, what the indexer has credited, what the latest weekly root publishes, what the referral distributor has paid and what is claimable now, with the `claim(asset, account, cumulative, proof)` arguments when there is a leaf. Read-only; figures are never summed across assets. On a chain with no distributor recorded, referrals are paid by hand and the answer says so. |
+| `parabolic.list_venue_coins` | `{ venue: "pons" \| "solonpad" \| "aka", status?, sort?, limit? }`. Coins made on another launchpad (pons on Robinhood Chain; SolonPad and aka.fun on Arc), read from that launchpad's subgraph when `PARABOLIC_SUBGRAPH_URL_<VENUE>_<CHAIN>` is set and otherwise from the site's own index of it, with the figures `list_coins` returns plus `venue`, the site's `ref` and whether they can be routed here (`routedHere`). They live on that launchpad's contracts, not Parabolic's. `aka` is known and listed, and the four routed tools refuse it by name: the router is proved on aka.fun's pools, but this server does not build that trade. |
+| `parabolic.venue_history` | `{ part: "chart" \| "holders" \| "claimable" \| "position", coin?, wallet?, tf?, limit? }`. Another launchpad's coin as the Parabolic site reads it from the chain's logs: its candles from every fill read and its newest fills, its holders folded from its transfers since launch, its fee recipient's balance on that launchpad's own escrow (claimed there), or a wallet's positions across the launchpads the site indexes itself. Every answer says how far back it reaches. Read from the site (`PARABOLIC_API_URL`), never from a chain. |
+| `parabolic.quote_routed_buy` | `{ venue, address, quoteIn, from?, slippageBps? }`. Tokens received for `quoteIn` of the coin's own quote asset, bought through `ParabolicAggregatorRouter` on the launchpad's curve (the router's quote view) or its graduated v4 pool (the chain's V4Quoter), read now, with the launchpad's fee and Parabolic's routed fee (the router's `defaultFeeBps`) both shown. |
+| `parabolic.quote_routed_sell` | `{ venue, address, tokensIn, from?, slippageBps? }`. Money received, after Parabolic's routed fee, for `tokensIn` sold through the router, read now. |
+| `parabolic.build_routed_buy_tx` | `{ venue, address, quoteIn, from, slippageBps?, maxSnipeTaxBps? }` → unsigned `ParabolicAggregatorRouter.buy(trade, noVoucher, "0x", noPermit)`, encoded as the site encodes it: `minOut` from a fresh quote less slippage, recipient = `from`, a five-minute deadline; an ETH-quoted coin sends `quoteIn` as value, a USDG-quoted one returns an exact-amount approval of the router first. Inside a launch window the build is refused and names the tax unless `maxSnipeTaxBps` accepts it. |
+| `parabolic.build_routed_sell_tx` | `{ venue, address, tokensIn, from, slippageBps? }` → unsigned exact-amount approval of the router plus `ParabolicAggregatorRouter.sell(...)`; `minOut` is the money after Parabolic's fee. The four routed tools refuse, by name, until the chain's record carries the router (`aggregator`), when the router has the launchpad off, when the coin is not that launchpad's, and when any read fails. |
+| `parabolic.docs` | The adopted parameters, curve mechanics, confirmed Arc facts and this server's configuration, as text. |
 
 Every tool above also takes an optional `chain` (see "What changed in 0.1.7"), and every coin argument
 takes a reference: `0x…` for a coin on this server's chain, `rhc:0x…` for one elsewhere. A wallet argument
-(`recipient`, `buyer`, `creator`, `from`, `agent_status`'s `address`) stays a plain address — a wallet is
+(`recipient`, `buyer`, `creator`, `from`, `agent_status`'s `address`) stays a plain address: a wallet is
 the same person on every EVM chain. `check_ticker` accepts `chain` like the others and its verdict still
 covers every chain the site serves, because a ticker taken elsewhere is a collision the moment a link is shared.
 
@@ -252,7 +280,7 @@ Launch a coin with a $200 dev buy:
 { "name": "parabolic.build_launch_tx", "arguments": { "name": "Orange Pill", "ticker": "PILL", "image": "ipfs://…", "description": "a frog", "socials": { "twitter": "@robin" }, "creatorTaxBps": 250, "devBuy": "200", "creator": "0xYourWallet" } }
 ```
 
-With `PARABOLIC_MEMO_ROUTER` set the result is `kind: "launch_and_buy"`: one `tx` to the router (`value` = $1 launch fee + $200), the encoded `params` (`creatorFeeRecipient` zero, as the router requires), the curve `terms` (opening and fully diluted graduation market caps, reserved / pool-seed / locked token shares, snipe-tax window) and `devBuy` (expected and minimum tokens, snipe-tax exempt). Without the router it is `kind: "launch"`: `tx` to the factory (value = the launch fee) and `devBuy` with the calldata for the second, snipe-tax-exempt transaction to the new curve. There is no exemption list: only the creator's own address is exempt from the snipe tax.
+With `PARABOLIC_MEMO_ROUTER` set the result is `kind: "launch_and_buy"`: one `tx` to the router (`value` = the factory's `launchFee()`, 0 on both chains today, + $200), the encoded `params` (`creatorFeeRecipient` zero, as the router requires), the curve `terms` (opening and fully diluted graduation market caps, reserved / pool-seed / locked token shares, snipe-tax window) and `devBuy` (expected and minimum tokens, snipe-tax exempt). Without the router it is `kind: "launch"`: `tx` to the factory (value = the launch fee) and `devBuy` with the calldata for the second, snipe-tax-exempt transaction to the new curve. There is no exemption list: only the creator's own address is exempt from the snipe tax.
 
 Check whether a wallet is a registered agent, then register it:
 
@@ -315,21 +343,30 @@ asking, and it lags the site's indexer by however far that is behind.
 
 ```
 src/
-  index.ts      stdio entry point (bin: parabolic-mcp)
-  server.ts     createServer(): tools + resources on @modelcontextprotocol/sdk McpServer
-  parabolic.ts  the service: reads (RPC + subgraph) and unsigned tx builders
-  curve.ts      ported curve math
-  tx.ts         viem encodeFunctionData builders (buy, sell, approve, launchToken, memo buy)
-  agents.ts     ERC-8004 identity registry: balanceOf / ownerOf / tokenURI reads, register builder
-  chain.ts      viem RPC wrapper (batched HTTP) behind a small Rpc interface
-  subgraph.ts   GraphQL client and Coin/Protocol shapes
-  coins.ts      coin summaries, sorting
-  ticker.ts     check_ticker's rule: the site's normalisation, its verdict shape, the sentence
-  config.ts     PARABOLIC_* environment
-  abi.ts        loads abi/*.json
-  docs.ts       parameters + Arc facts text
-test/           vitest (curve parity, calldata decode, tools over an in-memory MCP transport)
-scripts/        sync-abis.mjs, smoke.mjs
+  index.ts          stdio entry point (bin: parabolic-mcp)
+  server.ts         createServer(): the 19 tools + resources on @modelcontextprotocol/sdk McpServer
+  parabolic.ts      the service: reads (RPC + subgraph + API) and unsigned tx builders
+  curve.ts          ported curve math
+  tx.ts             viem encodeFunctionData builders (buy, sell, approve, launchToken, memo buy)
+  agents.ts         ERC-8004 identity registry: balanceOf / ownerOf / tokenURI reads, register builder
+  chain.ts          viem RPC wrapper (batched HTTP) behind a small Rpc interface
+  chains.ts         the chain registry and chain-qualified references (`rhc:0x…`)
+  deployed.ts       the shipped deployment records (abi/deployments.json): addresses, start blocks, routers
+  subgraph.ts       GraphQL client and Coin/Protocol shapes
+  restapi.ts        Parabolic's public read API client (listings when no subgraph is set)
+  coins.ts          coin summaries, sorting
+  quote-unit.ts     the money a coin is counted in, so no figure reads as dollars when it is not
+  format.ts         JSON with bigints as decimal strings, short addresses
+  ticker.ts         check_ticker's rule: the site's normalisation, its verdict shape, the sentence
+  referrals.ts      referral_status, read from the site's /api/v1/referrals route
+  venues.ts         the other launchpads: factories, hooks, proofs, venue subgraph variables
+  routed.ts         list_venue_coins and the four routed tools through ParabolicAggregatorRouter
+  venue-history.ts  venue_history, read from the site's /api/v1/coins views
+  config.ts         PARABOLIC_* environment
+  abi.ts            loads abi/*.json
+  docs.ts           parameters + Arc facts text
+test/               vitest (curve parity, calldata decode, tools over an in-memory MCP transport)
+scripts/            sync-abis.mjs, smoke.mjs
 ```
 
 Scripts: `npm run build`, `npm test`, `npm start` (stdio), `npm run smoke`, `npm run sync-abis`, `npm run typecheck`.
@@ -340,7 +377,7 @@ The source lives in a private repository; the published package ships `src/` alo
 code is readable from `node_modules`. If you have the repository checked out:
 
 ```sh
-npm install          # reads .npmrc (legacy-peer-deps) to skip a vitest peer-resolution bug on Node 23
+npm install
 npm run build        # -> dist/
 npm test             # vitest: curve math, tx builders, tools against a mocked subgraph and RPC
 npm run smoke        # starts dist/index.js over stdio, initialize + tools/list
@@ -349,6 +386,6 @@ npm run sync-abis    # re-copy abi/*.json from ../contracts/out after a forge bu
 
 ## Links
 
-- Parabolic — <https://www.parabolic.family>
-- Protocol parameters, deployed addresses and the public read API — <https://www.parabolic.family/docs>
-- Questions and bug reports — contact@parabolic.family
+- Parabolic: <https://www.parabolic.family>
+- Protocol parameters, deployed addresses and the public read API: <https://www.parabolic.family/docs>
+- Questions and bug reports: contact@parabolic.family