@parabolicfamily/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Parabolic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+# Parabolic MCP server
+
+A small [Model Context Protocol](https://modelcontextprotocol.io) server for **Parabolic**, the dollar-native token launchpad on Arc. It lets AI agents (Claude Code, Cursor, custom ERC-8004 agents) discover coins, quote curve trades with the contract's exact math, and build **unsigned** transactions, without a browser.
+
+**What it never does:** hold keys, sign, send or broadcast transactions, custody funds, or accept private keys, seed phrases or session tokens as input. Every `build_*` tool returns `{ to, data, value, chainId }` for the caller's own wallet to sign. Quotes are read from chain at call time and can move before a transaction lands.
+
+## Install
+
+Requires Node 22+. Nothing to build: point your MCP client at it with `npx`.
+
+```sh
+npx -y @parabolicfamily/mcp        # starts the server on stdio
+```
+
+The ABIs ship with the package, so it works offline against any Arc RPC you point it at.
+
+## Configure
+
+Nothing is required. Out of the box the server talks to **Arc Testnet** with the deployed Parabolic
+addresses already built in, so `npx -y @parabolicfamily/mcp` is a working install.
+
+Set `PARABOLIC_CHAIN_ID` and the RPC and contract addresses for that chain follow it. Arc mainnet
+(5042) opens on **16 September 2026**; its addresses ship in the release right after the deployment.
+
+| Variable | Meaning | Default |
+|---|---|---|
+| `PARABOLIC_CHAIN_ID` | 5042002 Arc Testnet, 5042 Arc mainnet | `5042002` |
+| `PARABOLIC_RPC_URL` | Arc JSON-RPC endpoint | the public endpoint for the chain id |
+| `PARABOLIC_FACTORY` | `ParabolicLaunchFactory`: coin lookups, launch transactions, log-scan listing | the deployment for the chain id |
+| `PARABOLIC_MEMO_ROUTER` | `ParabolicMemoRouter`: the atomic launch-and-buy and the referral-carrying buy | 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 (falls back to a log scan) |
+| `PARABOLIC_HOOK` | `ParabolicHook` address | read from `factory.memeHook()` |
+| `PARABOLIC_ARC_MEMO` | Arc `Memo` system contract | `0x5294E9927c3306DcBaDb03fe70b92e01cCede505` |
+| `PARABOLIC_LAUNCH_CONFIG_ID` | Factory launch-config index (0 = the $5K open / $12,500 graduation curve) | `0` |
+| `PARABOLIC_FACTORY_START_BLOCK` | First block of the `TokenLaunched` scan used when there is no subgraph | `0` |
+
+Every deployed address is published at <https://www.parabolic.family/docs#contracts> and verified on
+Arcscan, so you can check the built-in defaults against the site before you sign anything.
+
+### Claude Code
+
+```sh
+claude mcp add parabolic -- npx -y @parabolicfamily/mcp
+```
+
+That is enough to browse coins and quote trades on Arc Testnet. For mainnet, or to use a subgraph for
+richer listings, add the environment:
+
+```sh
+claude mcp add parabolic \
+  -e PARABOLIC_CHAIN_ID=5042 \
+  -e PARABOLIC_SUBGRAPH_URL=https://your-subgraph/gn \
+  -- npx -y @parabolicfamily/mcp
+```
+
+### Generic JSON (Cursor, Claude Desktop, other MCP clients)
+
+```json
+{
+  "mcpServers": {
+    "parabolic": {
+      "command": "npx",
+      "args": ["-y", "@parabolicfamily/mcp"],
+      "env": {
+        "PARABOLIC_CHAIN_ID": "5042002"
+      }
+    }
+  }
+}
+```
+
+### Hosting over HTTP later
+
+`createServer()` (the package's main export) builds the `McpServer` without a transport, so the same tools can be served over Streamable HTTP:
+
+```ts
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createServer } from "@parabolicfamily/mcp";
+
+const server = createServer();                      // reads PARABOLIC_* from process.env
+const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+await server.connect(transport);
+// then hand transport.handleRequest(req, res, body) to your HTTP framework
+```
+
+`createServer({ config, env, rpc, fetch })` also accepts overrides, which is how the tests inject an in-memory RPC and a fake subgraph.
+
+## Tools
+
+Amounts go in as whole units (`"25"` or `25` = 25 USDC; tokens likewise) and come back as `{ amount, raw }` pairs (whole units and raw 18-decimal, or 6-decimal for EURC, integers). Addresses are checksummed. Every tool returns JSON text plus `structuredContent`; errors come back as `isError` results with a plain message.
+
+| Tool | Purpose |
+|---|---|
+| `parabolic.list_coins` | `{ status?: "climbing" \| "graduated", sort?: "trending" \| "new" \| "near_graduation" \| "market_cap", limit? }`. Subgraph when configured (adds holders, 24h volume/change), otherwise a `TokenLaunched` log scan of the factory (newest 50). |
+| `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.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.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.docs` | The adopted parameters, curve mechanics, verified Arc facts and this server's configuration, as text. |
+
+Resources: `parabolic://docs/parameters` (same text as `parabolic.docs`) and `parabolic://coins/{address}` (same JSON as `parabolic.get_coin`).
+
+### Examples
+
+Quote a $50 buy on a freshly opened curve (result abbreviated; the numbers are what the ported math returns for the adopted parameters):
+
+```json
+{ "name": "parabolic.quote_buy", "arguments": { "address": "0x1000…0001", "quoteIn": "50" } }
+```
+```json
+{
+  "side": "buy", "pair": "USDC",
+  "quoteIn": { "amount": "50", "raw": "50000000000000000000" },
+  "tokensOut": { "amount": "9802950.787206654124170709", "raw": "9802950787206654124170709" },
+  "minTokensOut": { "amount": "9704921.279334587582929001", "raw": "9704921279334587582929001", "slippageBps": 100 },
+  "fees": { "totalBps": 100, "fee": { "bps": 100, "amount": "0.5" }, "creatorTax": { "bps": 0, "amount": "0" }, "snipeTax": { "bps": 0, "amount": "0", "windowOpen": false, "buyerExempt": false } },
+  "spotPrice": 0.000005, "effectivePrice": 0.0000051005, "priceImpactPct": 2.0101, "graduatesCoin": false
+}
+```
+
+Build the same buy for a wallet to sign:
+
+```json
+{ "name": "parabolic.build_buy_tx", "arguments": { "address": "0x1000…0001", "quoteIn": "50", "recipient": "0xYourWallet" } }
+```
+```json
+{
+  "kind": "buy",
+  "tx": { "to": "0x2000…0002", "data": "0x…", "value": "0x2b5e3af16b1880000", "valueWei": "50000000000000000000", "chainId": 5042002 },
+  "quote": { "expectedTokensOut": { "…": "…" }, "minTokensOut": { "…": "…" }, "graduatesCoin": false },
+  "gas": { "note": "estimate then multiply by 1.25 …" }
+}
+```
+
+Launch a coin with a $200 dev buy:
+
+```json
+{ "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.
+
+## Notes on the mechanics
+
+- Curve math is a port of `ParabolicBondingCurve` / `ParabolicBondingCurveMath` (and of `web/lib/curve.ts`): fee legs are taken off the buy input separately, the constant product is priced on `getReserves()`, and a buy that would take more than `sellableTokens()` is clamped to the last sellable tokens, charged the grossed-up price and refunded the rest; that buy graduates the coin, so give it extra gas. Sells take the fee off the gross quote output and close once the curve is ready to graduate.
+- `minTokensOut` on the curve is a price bound (`spent × minTokensOut ≤ received × tokensOut`), so a clamped fill still honours the caller's terms.
+- The snipe tax decays per second along `remaining² / window²`; a quote in the launch window overstates the tax a later block charges. Pass `buyer` to have the exemption checked.
+- At graduation the curve still holds the reserved 28.57% of supply: ≈ 20.4% seeds the Uniswap v4 full-range position with the $12,500 raised at the same terminal price, and ≈ 8.2% is permanently locked. Fully diluted graduation market cap: $61,250.
+- Fair launch: `ParabolicMemoRouter.launchAndBuy` / `launchAndBuyWithToken` put the creator's opening buy inside the launch transaction (snipe-tax exempt, before anyone else can trade). Called directly they work from any wallet; the router forwards no exemption list and rejects a `creatorFeeRecipient` other than zero or the signer.
+- A memo-routed buy (`memo: { referral }`) wraps `ParabolicMemoRouter.buy` inside Arc's `Memo.memo(...)` so the referral code is attributed on-chain. It is **EOA-only** (the Memo contract's caller must be `tx.origin`) and forwards no value, so the router pulls whole 6-decimal USDC units through the ERC-20 view (`0x3600…0000`) and needs a one-time approval; smart-account wallets should use the direct buy. Memo-wrapped launches (referral on a launch) are not built here.
+- The factory has no enumeration function (only `getLaunchedToken(address)`), so listing needs the subgraph; without it the server scans `TokenLaunched` logs from `PARABOLIC_FACTORY_START_BLOCK` and reads the newest 50 launches.
+
+## Development
+
+```
+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)
+  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
+  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`.
+
+## Working on the server itself
+
+The source lives in a private repository; the published package ships `src/` alongside `dist/` so the
+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 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
+npm run sync-abis    # re-copy abi/*.json from ../contracts/out after a forge build
+```
+
+## 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