yoinkai-mcp 0.1.0 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
 # yoinkai-mcp
 
-Read-only MCP server over the [YOINK](https://yoinkai.fun) launch graph on Robinhood Chain. Give any agent eyes on token launches as they land.
+MCP server over the [YOINK](https://yoinkai.fun) launch graph on Robinhood Chain. Give any agent eyes on token launches as they land — quote live prices, and prep a launch of your own in one command.
 
-No keys. No custody. No trades through this server — buys, sells, and launches happen in your own wallet on [yoinkai.fun](https://yoinkai.fun).
+No keys. No custody. This server never signs or sends anything: `launch_token` builds the exact unsigned transaction and hands it to you; you review and sign in your own wallet. Buys and sells happen in your own wallet on [yoinkai.fun](https://yoinkai.fun).
 
 ## Install
 
@@ -20,12 +20,14 @@ Cursor, Claude Desktop, or any MCP client:
 
 ## Tools
 
-- **top_launches** — the newest token launches on Robinhood Chain: name, ticker, address, deployer, source.
-- **scan_launch** / **xray_token** — safety X-ray of any token address: sellable, 0% tax, no owner control, LP locked, template-verified.
+- **top_launches** — the newest token launches on Robinhood Chain: name, symbol, address, deployer, source.
+- **scan_launch** / **xray_token** — safety Trust Score of any token address: sellable, 0% tax, no owner control, LP locked, template-verified.
 - **deployer_history** — every launch from a wallet, with a serial-deployer flag.
 - **graph_stats** — totals for the launch graph: tokens indexed, unique deployers, top serial deployers.
+- **quote_token** — current price and expected receive amount for any token, routed to its live venue: a token still bonding quotes from its bonding curve contract (1% fee included); a graduated or pool token quotes the Uniswap V3 pool via QuoterV2 exact-in simulation plus the terminal fee. USD figures use a sanity-checked ETH/USD rate and are omitted when price sources disagree. Read-only.
+- **launch_token** — build the unsigned transaction that launches a new token through the YOINK bonding-curve factory: fixed 1B supply, no upfront liquidity needed, flat 0.0005 ETH fee (verified on-chain before every build), optional creator first buy. Trading starts on the curve immediately; at 4.2 ETH raised the token graduates — a Uniswap V3 pool is created and the LP position is locked forever. Returns `to`/`value`/`data` plus a plain-language review block; pass your wallet address as `from` and it dry-runs the exact tx against the chain before anyone signs. You sign in your own wallet — the server can't.
 
-The graph indexes launches as they land — launchpad launches, factory deploys, and raw contract deploys.
+The graph indexes launches as they land — bonding-curve launches, launchpad launches, factory deploys, and raw contract deploys. Launches built through this MCP are labeled as agent launches on yoinkai.fun.
 
 ## Notes
 

package/SKILL.md

@@ -1,23 +1,35 @@
 ---
 name: yoink
-description: Watch and X-ray token launches on Robinhood Chain via the YOINK launch graph. Use when the user asks about new tokens, launches, token safety, or deployer reputation on Robinhood Chain.
+description: Watch, score, quote, and launch tokens on Robinhood Chain via the YOINK launch graph. Use when the user asks about new tokens, launches, token safety, token prices, deployer reputation, or wants to launch a token on Robinhood Chain.
 ---
 
 # YOINK — launches on Robinhood Chain
 
-You have the `yoink` MCP server (package `yoinkai-mcp`). It is read-only: it reads the YOINK launch graph and the chain but cannot touch funds. All trading happens in the user's own wallet at https://yoinkai.fun.
+You have the `yoink` MCP server (package `yoinkai-mcp`). It reads the YOINK launch graph and the chain, and it can BUILD an unsigned launch transaction — but it holds no keys and can never sign or send. All signing happens in the user's own wallet; trading happens at https://yoinkai.fun.
 
 ## What you can do
 
-1. **Find new launches** — `top_launches` returns the newest tokens (name, ticker, address, deployer, source). Use it when the user asks "what just launched" or wants to watch the chain.
-2. **X-ray a token** — `scan_launch` (alias `xray_token`) with a 0x address answers: is it sellable, is there tax, does an owner control it, is the LP locked, does the bytecode match the verified standard template. ALWAYS X-ray a token before saying anything positive about it.
+1. **Find new launches** — `top_launches` returns the newest tokens (name, symbol, address, deployer, source). Use it when the user asks "what just launched" or wants to watch the chain.
+2. **Check a token's Trust Score** — `scan_launch` (alias `xray_token`) with a 0x address answers: is it sellable, is there tax, does an owner control it, is the LP locked, does the bytecode match the verified standard template. ALWAYS check a token's Trust Score before saying anything positive about it.
 3. **Check the deployer** — `deployer_history` with a wallet address shows every launch from that wallet and flags serial deployers. A deployer with many short-lived launches is a risk signal.
 4. **Graph totals** — `graph_stats` for indexed-token counts, unique deployers, and the top serial deployers.
+5. **Quote a price** — `quote_token` with a token address returns the current price and, given an amount, the expected receive amount. It routes to the live venue automatically: a token still bonding quotes from its bonding curve contract (1% fee included); a graduated or pool token quotes the Uniswap V3 pool (exact-in simulation plus the terminal fee). Size a buy with `amountUsd` or `amountEth`; size a sell with `amountTokens` (or a USD/ETH target). USD figures come from a sanity-checked ETH/USD rate and are omitted when price sources disagree — never fill that gap with a guess.
+6. **Launch a token** — `launch_token` with a name and symbol builds the exact unsigned transaction for the YOINK bonding-curve factory: fixed 1B supply, no upfront liquidity needed, flat 0.0005 ETH fee (verified on-chain before every build), optional creator first buy (`initialBuyEth`). Trading starts on the curve immediately; at 4.2 ETH raised the token graduates — a Uniswap V3 pool is created and the LP position is locked in a contract with no withdraw path. If you know the user's wallet address, pass it as `from` so the tool dry-runs the exact tx on-chain before anyone signs.
+
+## Launch flow (follow exactly)
+
+1. Collect name + symbol (description, logo URI, links, first buy optional). Logo must already be an `ipfs://` or `https://` URI — image uploads happen on yoinkai.fun, not here.
+2. Call `launch_token`. If it errors, relay the reason plainly; nothing was built.
+3. SHOW THE USER THE REVIEW BLOCK before anything is signed: name, symbol, total ETH (fee + first buy), and that supply, curve, and graduation terms are fixed by the factory. Never skip this.
+4. The user signs the returned `to`/`value`/`data` on chain 4663 from their own wallet or signer. If they have no signer wired up, send them to https://yoinkai.fun to launch there instead.
+5. Only claim the token is live after the transaction confirms — the token address is in the receipt, or `scan_launch` it once the graph indexes it. Never claim a launch happened because the tx was built.
+
+Launches built through this skill are labeled as agent launches on yoinkai.fun.
 
 ## Rules
 
-- Read-only: never claim you can buy, sell, or launch for the user. When they want to trade, send them to the token's page on https://yoinkai.fun (append the 0x address to a token page link only if you have verified it via X-ray).
+- Non-custodial: never claim you can sign, send, buy, or sell for the user. `launch_token` only PREPARES a transaction and `quote_token` only READS prices. When they want to trade, send them to the token's page on https://yoinkai.fun (append the 0x address to a token page link only if you have verified it via the Trust Score).
 - Never invent metrics. Everything you state about a token must come from a tool result.
-- An X-ray that does NOT match the template is a warning, not a verdict — say the contract needs manual verification before trading.
-- Copycats exist: identical names or tickers on different contracts. The address is the identity; the name is not. When two tokens share a name, the older contract is usually the original.
+- A Trust Score that does NOT match the template is a warning, not a verdict — say the contract needs manual verification before trading.
+- Copycats exist: identical names or symbols on different contracts. The address is the identity; the name is not. When two tokens share a name, the older contract is usually the original.
 - Not financial advice; say so when giving a safety read.

package/index.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-// yoinkai-mcp: read-only MCP server over the YOINK launch graph on Robinhood Chain.
-// Any agent (Claude, Cursor, Codex) can scan launches, X-ray tokens, and read deployer
-// history. Read-only by design: no keys, no trades, no launches. Money paths stay in
-// the user's wallet on yoinkai.fun. Zero deps, Node >= 18 (global fetch), speaks MCP
-// stdio JSON-RPC 2.0.
+// yoinkai-mcp: MCP server over the YOINK launch graph on Robinhood Chain.
+// Any agent (Claude, Cursor, Codex) can scan launches, X-ray tokens, quote prices,
+// read deployer history, and BUILD an unsigned token-launch transaction. Non-custodial
+// by design: no keys, nothing is ever signed or sent by this server — the user reviews
+// and signs every transaction in their own wallet. Zero deps, Node >= 18 (global fetch),
+// speaks MCP stdio JSON-RPC 2.0.
 
 const API = process.env.YOINK_API || 'https://yoink-graph.fly.dev';
 const RPCS = [API + '/rpc', 'https://robinhoodchain.blockscout.com/api/eth-rpc', 'https://rpc.mainnet.chain.robinhood.com'];
@@ -73,21 +74,380 @@ async function xray(addr) {
     verdict: tpl === true ? 'passes the standard template: sellable, 0% tax, no owner, LP locked'
       : tpl === false ? 'does NOT match the standard template, verify the contract before trading'
       : 'could not read the contract code',
-    note: 'read-only X-ray from the YOINK launch graph. Not financial advice. Trades happen in your own wallet on yoinkai.fun.',
+    note: 'Read-only Trust Score from the YOINK launch graph. Not financial advice. Trades happen in your own wallet on yoinkai.fun.',
+  };
+}
+
+// ---- launch verb: builds the tx, NEVER signs or sends (no keys in this process) ----
+// YoinkCurveFactory (docs/CHAIN.md, docs/SPEC_BONDING_CURVE_V2.md): launches deploy the
+// audited YoinkToken template (fixed 1B supply) plus a per-token YoinkBondingCurve
+// holding the full supply — no upfront liquidity needed. Trading starts on the curve;
+// at 4.2 ETH net raised the token graduates: a Uniswap V3 pool is created and the LP
+// position is locked in a contract with no withdraw path. launch(LaunchParams) has the
+// SAME selector and struct as the old V1 factory (byte-exact port of the proven web
+// path, landing/terminal.html encYoinkLaunch) and returns (token, curve).
+const CURVE_FACTORY = '0xbb49b39141cbaf28bb89c5f16d0613d3beab04b8'; // LIVE mainnet 2026-07-07, flip-verified
+const FACTORY_V1 = '0xbcc67639cd2c3e9498714be53018949e3b17ea5e';    // old born-graduated factory, reference only
+const FACTORY = CURVE_FACTORY;       // launch target
+const LAUNCH_FEE = 500000000000000n; // 0.0005 ETH — LAUNCH_FEE() in the curve factory, re-verified on-chain per build
+const SEL_LAUNCH = '0xe1f7d84a';     // launch((string,string,string,string,string[3],uint256)) -> (token, curve)
+const SEL_FEE = '0x09197a81';        // LAUNCH_FEE()
+const CHAIN_ID = 4663;               // 0x1237 Robinhood Chain
+const GRAD_WEI = 4200000000000000000n; // graduation threshold: 4.2 ETH net raised on the curve
+
+const w256 = (n) => BigInt(n).toString(16).padStart(64, '0');
+const padA = (a) => '000000000000000000000000' + a.toLowerCase().slice(2);
+const padStr = (s) => { const b = Array.from(new TextEncoder().encode(s)); const hx = b.map((x) => x.toString(16).padStart(2, '0')).join(''); return w256(b.length) + (b.length ? hx.padEnd(Math.ceil(hx.length / 64) * 64, '0') : ''); };
+const tupDyn = (parts) => { let head = '', tail = '', off = parts.length * 32; for (const p of parts) { head += w256(off); tail += p; off += p.length / 2; } return head + tail; };
+// launch(LaunchParams{name,symbol,logo,description,socials[3],minTokensOut})
+function encYoinkLaunch(o, minOut) {
+  const soc = tupDyn([padStr(o.socials[0] || ''), padStr(o.socials[1] || ''), padStr(o.socials[2] || '')]);
+  const dyn = [padStr(o.name), padStr(o.symbol), padStr(o.logo || ''), padStr(o.desc || ''), soc];
+  let head = '', tail = '', off = 6 * 32;
+  for (const d of dyn) { head += w256(off); tail += d; off += d.length / 2; }
+  head += w256(minOut);
+  return SEL_LAUNCH + w256(0x20) + head + tail;
+}
+// expected tokens out for the creator initial buy on a FRESH curve (deterministic: the
+// curve deploys inside this same launch tx, nothing can trade it first). Byte-exact
+// BigInt mirror of YoinkBondingCurve._quoteBuy at e0=0, sold0=0 (same function the live
+// web path uses): fee = value/100 (floor), net capped at GRAD_WEI (a big first buy
+// graduates the curve, the excess refunds to the creator in the same tx), tokens out
+// rounds DOWN via ceilDiv on the kept virtual reserve. Verified against the deployed
+// contract: exact minOut simulates clean, minOut+1 reverts "minOut".
+function ycExpectedOut(buyWei) {
+  const VE = 1050000000000000000n, VT = 1000000000000000000000000000n, K = VE * VT;
+  let net = buyWei - buyWei / 100n; // 1% fee off the gross first
+  if (net >= GRAD_WEI) net = GRAD_WEI; // graduation cap, contract refunds the unused gross
+  const kept = (K + (VE + net) - 1n) / (VE + net); // ceilDiv(K, VE+net)
+  return VT > kept ? VT - kept : 0n;
+}
+const fmtEth = (wei) => { const s = wei.toString().padStart(19, '0'); const i = s.slice(0, -18), f = s.slice(-18).replace(/0+$/, ''); return (i || '0') + (f ? '.' + f : ''); };
+
+// telemetry, NOT money path: label agent-built launches so yoinkai.fun can show an
+// "Agent" chip on them. Fire-and-forget with a short timeout — any failure (including
+// a 404 while the indexer endpoint is not deployed yet) is swallowed and can never
+// block, delay, or fail the launch build. Sends only what the caller already gave us.
+function agentIntent(o) {
+  try {
+    const ac = new AbortController(); const tm = setTimeout(() => ac.abort(), 2000);
+    fetch(API + '/v0/agent-intent', { method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(o), signal: ac.signal }).catch(() => {}).finally(() => clearTimeout(tm));
+  } catch { /* telemetry must never throw */ }
+}
+
+async function buildLaunch(args) {
+  const name = String(args.name || '').trim();
+  if (!name) throw new Error('Need a token name');
+  if (name.length > 32) throw new Error('Name too long (max 32 characters)');
+  const symbol = String(args.symbol || '').toUpperCase().replace(/[^A-Z0-9]/g, '');
+  if (!symbol) throw new Error('Need a symbol (letters and digits)');
+  if (symbol.length > 10) throw new Error('Symbol too long (max 10 characters)');
+  const desc = String(args.description || '');
+  if (desc.length > 180) throw new Error('Description too long (max 180 characters)');
+  const logo = String(args.logo || '');
+  if (logo && !/^(ipfs:\/\/|https:\/\/)/.test(logo)) throw new Error('Logo must be an ipfs:// or https:// URI (upload the image on yoinkai.fun to get one)');
+  if (logo.length > 256) throw new Error('Logo URI too long (max 256 characters)');
+  const socials = {};
+  for (const k of ['x', 'telegram', 'website']) {
+    const v = String(args[k] || '');
+    if (v && !/^https:\/\//.test(v)) throw new Error(k + ' link must start with https://');
+    if (v.length > 256) throw new Error(k + ' link too long (max 256 characters)');
+    socials[k] = v;
+  }
+  let buyWei = 0n;
+  if (args.initialBuyEth != null && args.initialBuyEth !== '') {
+    const n = parseFloat(args.initialBuyEth);
+    if (!isFinite(n) || n < 0) throw new Error('initialBuyEth must be a non-negative number of ETH');
+    if (n > 1) throw new Error('initialBuyEth over 1 ETH — set it lower, or launch on yoinkai.fun if you really mean it');
+    if (n > 0) buyWei = BigInt(Math.round(n * 1e18)); // same conversion as the web path
+  }
+  // exact minOut: a fresh curve cannot be front-run (it deploys in this same tx), and the
+  // pre-sign simulation fails closed if this mirror ever drifts from the contract math.
+  const minOut = buyWei > 0n ? ycExpectedOut(buyWei) : 0n;
+  const data = encYoinkLaunch({ name, symbol, logo, desc, socials: [socials.x, socials.telegram, socials.website] }, minOut);
+  const value = LAUNCH_FEE + buyWei;
+  const valueHex = '0x' + value.toString(16);
+
+  // tripwire: the deployed factory must still charge exactly the expected fee.
+  // A malformed/empty return (e.g. '0x') counts as unverified, not as a mismatch.
+  let feeVerified = false;
+  const feeHex = await rpc('eth_call', [{ to: FACTORY, data: SEL_FEE }, 'latest']).catch(() => null);
+  if (typeof feeHex === 'string' && /^0x[0-9a-fA-F]{64}$/.test(feeHex)) {
+    if (BigInt(feeHex) !== LAUNCH_FEE) throw new Error('on-chain LAUNCH_FEE does not match the expected constant — refusing to build. Report this.');
+    feeVerified = true;
+  }
+
+  // optional dry run from the user's wallet (needs their address, not their keys)
+  let simulation = { ran: false, note: 'pass your wallet address as "from" to dry-run the exact tx before signing' };
+  if (args.from != null && args.from !== '') {
+    if (!isAddr(args.from)) throw new Error('"from" must be a 0x wallet address');
+    const from = args.from.toLowerCase();
+    try {
+      const pre = await rpc('eth_call', [{ from, to: FACTORY, value: valueHex, data }, 'latest']);
+      if (pre && pre.length >= 130) simulation = { ran: true, ok: true, predictedToken: '0x' + pre.slice(26, 66), predictedCurve: '0x' + pre.slice(90, 130) };
+      else throw new Error('empty result');
+    } catch (e) {
+      throw new Error('simulation reverted — this launch would fail on-chain, nothing to sign. Check the wallet holds fee + buy + gas (~0.002 ETH headroom) on Robinhood Chain and retry. (' + String(e.message || e) + ')');
+    }
+  }
+
+  // agent-launch label (fire-and-forget telemetry; see agentIntent above)
+  agentIntent({ deployer: isAddr(args.from) ? args.from.toLowerCase() : null, name, symbol, ts: Date.now() });
+
+  return {
+    action: 'REVIEW_THEN_SIGN',
+    network: { chainId: CHAIN_ID, chainIdHex: '0x1237', name: 'Robinhood Chain', explorer: 'https://robinhoodchain.blockscout.com', rpc: 'https://rpc.mainnet.chain.robinhood.com' },
+    tx: { to: FACTORY, value: valueHex, data },
+    cost: { launchFeeEth: fmtEth(LAUNCH_FEE), initialBuyEth: fmtEth(buyWei), totalValueEth: fmtEth(value), gasNote: 'keep ~0.002 ETH extra for gas' },
+    review: {
+      name, symbol, description: desc || null, logo: logo || null,
+      x: socials.x || null, telegram: socials.telegram || null, website: socials.website || null,
+      supply: '1,000,000,000 (fixed by the factory, 18 decimals)',
+      trading: 'starts immediately on a bonding curve — no upfront liquidity. At ' + fmtEth(GRAD_WEI) + ' ETH raised the token graduates: a Uniswap V3 pool is created and the LP position is locked in a contract with no withdraw path.',
+      initialBuy: buyWei > 0n ? fmtEth(buyWei) + ' ETH spent as the creator first buy on the fresh curve (includes the 1% curve fee), exact tokens out ' + minOut.toString() + ' — deterministic, nothing can trade the curve before this tx' : 'none',
+      factory: FACTORY, feeVerifiedOnChain: feeVerified, simulation,
+      agentLabel: 'this launch will be labeled as an agent launch on yoinkai.fun',
+    },
+    launchDesign: 'YoinkCurveFactory: the token deploys with its full 1B supply on a per-token bonding curve in one tx. Buys and sells trade against the curve (1% fee) until it raises ' + fmtEth(GRAD_WEI) + ' ETH; graduation then creates the Uniswap V3 pool and locks the LP position in a contract with no withdraw path.',
+    sign: 'This server holds no keys and CANNOT send this transaction. Show the review to the user, then have them sign exactly this tx (to/value/data on chain 4663) from their own wallet or agent signer — or launch by hand at https://yoinkai.fun. The new token and curve addresses are in the receipt (or scan_launch it once the graph picks it up).',
+  };
+}
+
+// ---- quote verb: current price + expected receive on the token's live venue ----
+// Tokens still bonding quote from their own YoinkBondingCurve previewBuy/previewSell —
+// the contract is the single source of quote truth (1% fee included), no curve math is
+// duplicated here. Graduated and non-curve tokens quote the Uniswap V3 pool through
+// QuoterV2 (exact-in simulation) with the terminal fee applied the same way the
+// yoinkai.fun trade path charges it. Selectors mirror landing/curve.js and
+// landing/swap.js (flip-verified there before wiring).
+const QUOTER = '0x33e885ed0ec9bf04ecfb19341582aadcb4c8a9e7';   // QuoterV2.quoteExactInputSingle 0xc6a5026a
+const V4_ROUTER = '0x4146465c858f34ee210cae1547bec03a70b37f6c'; // per-token terminal fee oracle (feeBps 0xe868ce52)
+const LAUNCHED_TOPIC = '0xec774f0683e9ac48e8d835f412f9f877a8a5dee9af3170d78cf3ef33149d15e7'; // Launched(address,address,address,uint256,uint256)
+const CURVE_START = 4046164; // curve factory deploy block
+const CSEL = { pBuy: '0x48153279', pSell: '0xfb3dd95f', grad: '0xe7c2b772', realEth: '0x7a2a2a2b' };
+
+// token -> curve resolution: the graph is primary (ONLY its own miss body is an
+// authoritative "no curve"); fallback = the factory's Launched events (token = topic1).
+async function resolveCurve(token) {
+  try {
+    const r = await fetch(API + '/v0/curve/' + token);
+    if (r.status === 404) {
+      const o = await r.json().catch(() => null);
+      if (o && o.error === 'no curve for this token') return null; // authoritative miss
+    } else if (r.ok) {
+      const o = await r.json();
+      if (o && /^0x[0-9a-f]{40}$/i.test(o.curve || '')) return o.curve.toLowerCase();
+    }
+  } catch { /* fall through to logs */ }
+  const logs = await rpc('eth_getLogs', [{ address: CURVE_FACTORY, fromBlock: '0x' + CURVE_START.toString(16), toBlock: 'latest',
+    topics: [LAUNCHED_TOPIC, '0x' + padA(token)] }]).catch(() => null);
+  if (!Array.isArray(logs)) throw new Error('could not resolve the trading venue (graph and RPC both unavailable) — try again');
+  return logs[0] ? ('0x' + logs[0].topics[2].slice(26)).toLowerCase() : null;
+}
+
+// $ conversion MONEY GUARD (ported from landing/swap.js): a rate is accepted only when
+// two independent sources agree within 20%, or a lone source agrees within 20% with the
+// last in-process good value (<24h). Anything else -> null -> USD fields are OMITTED
+// from the answer, never guessed.
+let _usdGood = null; // { v, t }
+async function ethUsdNow() {
+  if (_usdGood && Date.now() - _usdGood.t < 120000) return _usdGood.v;
+  const srcs = [
+    ['https://api.coinbase.com/v2/prices/ETH-USD/spot', (o) => parseFloat(o && o.data && o.data.amount)],
+    ['https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd', (o) => o && o.ethereum && o.ethereum.usd],
+  ];
+  const vals = [];
+  await Promise.all(srcs.map(async ([url, pick]) => {
+    try {
+      const ac = new AbortController(); const tm = setTimeout(() => ac.abort(), 6000);
+      const v = pick(await fetch(url, { signal: ac.signal }).finally(() => clearTimeout(tm)).then((r) => r.json()));
+      if (v && isFinite(v) && v > 0) vals.push(v);
+    } catch {}
+  }));
+  const agree = (a, b) => Math.abs(a - b) <= Math.max(a, b) * 0.2;
+  let v = null;
+  if (vals.length >= 2) v = agree(vals[0], vals[1]) ? (vals[0] + vals[1]) / 2 : null;
+  else if (vals.length === 1) v = (!_usdGood || Date.now() - _usdGood.t >= 86400000 || agree(vals[0], _usdGood.v)) ? vals[0] : null;
+  if (v) _usdGood = { v, t: Date.now() };
+  return v;
+}
+
+// terminal fee for the pool path, decided on-chain by the router (launchpad 1%,
+// external 0.15%). Unknown -> assume the HIGHER tier: never understate a fee.
+async function feeBpsFor(token) {
+  try {
+    const hx = await rpc('eth_call', [{ to: V4_ROUTER, data: '0xe868ce52' + padA(token) }, 'latest']);
+    const v = Number(BigInt(hx)); if (v > 0 && v < 10000) return v;
+  } catch {}
+  return 100;
+}
+const qTier = async (tin, tout, amtIn, tier) => {
+  const hx = await rpc('eth_call', [{ to: QUOTER, data: '0xc6a5026a' + padA(tin) + padA(tout) + w256(amtIn) + w256(tier) + w256(0) }, 'latest']).catch(() => null);
+  return (hx && hx.length >= 66) ? BigInt('0x' + hx.slice(2, 66)) : 0n;
+};
+async function bestPoolOut(tin, tout, amtIn) {
+  const tiers = [10000, 3000, 500];
+  const outs = await Promise.all(tiers.map((t) => qTier(tin, tout, amtIn, t)));
+  let best = null;
+  for (let i = 0; i < tiers.length; i++) if (outs[i] > 0n && (!best || outs[i] > best.out)) best = { tier: tiers[i], out: outs[i] };
+  return best;
+}
+const fmtUnits = (x, dec) => { if (!dec) return x.toString(); const s = x.toString().padStart(dec + 1, '0'); const i = s.slice(0, -dec), f = s.slice(-dec).replace(/0+$/, ''); return (i || '0') + (f ? '.' + f : ''); };
+
+async function quoteToken(args) {
+  if (!isAddr(args.address)) throw new Error('Need a 0x token contract address');
+  const token = args.address.toLowerCase();
+  const side = String(args.side || 'buy').toLowerCase();
+  if (side !== 'buy' && side !== 'sell') throw new Error('side must be "buy" or "sell"');
+  const num = (v, what) => { if (v == null || v === '') return null; const n = parseFloat(v); if (!isFinite(n) || n <= 0) throw new Error(what + ' must be a positive number'); return n; };
+  const amountEth = num(args.amountEth, 'amountEth'), amountUsd = num(args.amountUsd, 'amountUsd'), amountTokens = num(args.amountTokens, 'amountTokens');
+  if (amountTokens != null && amountTokens > 1e15) throw new Error('amountTokens too large');
+
+  const notes = [];
+  const [name, symbol] = await Promise.all([viewStr(token, '0x06fdde03'), viewStr(token, '0x95d89b41')]);
+  let dec = null;
+  try { const hx = await rpc('eth_call', [{ to: token, data: '0x313ce567' }, 'latest']); const v = Number(BigInt(hx)); if (v >= 0 && v <= 36) dec = v; } catch {}
+  if (dec == null) { dec = 18; notes.push('could not read decimals() from the token — amounts assume 18 decimals'); }
+  const unit = 10n ** BigInt(dec);
+  const toUnits = (n) => { const s = n.toFixed(dec); const [i, f = ''] = s.split('.'); return BigInt(i) * unit + BigInt(f || '0'); };
+  const toWei = (n) => BigInt(Math.round(n * 1e18));
+
+  const ethUsd = await ethUsdNow();
+  if (!ethUsd) notes.push('USD figures omitted: live ETH/USD sources were unavailable or disagreed by more than 20% — this tool never guesses a rate');
+  if (amountUsd != null && !ethUsd) throw new Error('cannot size a $ amount right now: ETH/USD price sources disagree or are unavailable. Pass amountEth instead.');
+
+  // venue: a live (un-graduated) bonding curve wins; graduated or no-curve -> V3 pool
+  const curveAddr = await resolveCurve(token);
+  let venue = 'pool', curveInfo = null;
+  if (curveAddr) {
+    const [g, e] = await Promise.all([CSEL.grad, CSEL.realEth].map((d) => rpc('eth_call', [{ to: curveAddr, data: d }, 'latest']).catch(() => null)));
+    if (!g) throw new Error('could not read the curve state — try again');
+    if (BigInt(g) === 0n) {
+      venue = 'curve';
+      const raised = BigInt(e || '0x0');
+      curveInfo = { curve: curveAddr, raisedEth: fmtEth(raised), graduatesAtEth: fmtEth(GRAD_WEI),
+        progressPct: Math.min(100, Math.round(Number(raised) / Number(GRAD_WEI) * 100)) };
+    }
+  }
+
+  const curveBuy = async (wei) => {
+    const hx = await rpc('eth_call', [{ to: curveAddr, data: CSEL.pBuy + w256(wei) }, 'latest']);
+    if (!hx || hx.length < 130) throw new Error('curve quote failed — try again');
+    return { out: BigInt('0x' + hx.slice(2, 66)), refund: BigInt('0x' + hx.slice(66, 130)) };
+  };
+  const curveSell = async (amt) => {
+    const hx = await rpc('eth_call', [{ to: curveAddr, data: CSEL.pSell + w256(amt) }, 'latest']);
+    if (!hx || hx.length < 66) throw new Error('curve quote failed — try again');
+    return BigInt('0x' + hx.slice(2, 66));
+  };
+  const bps = venue === 'pool' ? await feeBpsFor(token) : 100; // curve fee is fixed 1% inside preview*
+  const noPool = 'no Uniswap V3 pool with liquidity found for this token — it may not be tradable on yoinkai.fun';
+  const poolBuy = async (wei) => { // terminal fee comes off the ETH in, then the pool swap
+    const b = await bestPoolOut(WETH, token, wei - (wei * BigInt(bps)) / 10000n);
+    if (!b || b.out <= 0n) throw new Error(noPool);
+    return b;
+  };
+  const poolSell = async (amt) => { // pool swap, then the terminal fee off the ETH out
+    const b = await bestPoolOut(token, WETH, amt);
+    if (!b || b.out <= 0n) throw new Error(noPool);
+    return { tier: b.tier, out: b.out - (b.out * BigInt(bps)) / 10000n };
+  };
+
+  // reference price from a small (0.001 ETH) buy on the live venue, fees included
+  const probeWei = 1000000000000000n;
+  const probeOut = venue === 'curve' ? (await curveBuy(probeWei)).out : (await poolBuy(probeWei)).out;
+  if (probeOut <= 0n) throw new Error('could not price this token — the venue returned a zero quote');
+  const priceEth = (Number(probeWei) / 1e18) / (Number(probeOut) / Number(unit));
+  const price = {
+    ethPerToken: Number(priceEth.toPrecision(6)),
+    usdPerToken: ethUsd ? Number((priceEth * ethUsd).toPrecision(6)) : null,
+    basis: 'effective price of a 0.001 ETH buy on the live venue, fees included — larger trades move the price',
+  };
+
+  let quote = null;
+  if (side === 'buy' && (amountEth != null || amountUsd != null)) {
+    const spendWei = amountEth != null ? toWei(amountEth) : toWei(amountUsd / ethUsd);
+    if (venue === 'curve') {
+      const q = await curveBuy(spendWei);
+      quote = { spendEth: fmtEth(spendWei), tokensOut: fmtUnits(q.out, dec) };
+      if (q.refund > 0n) {
+        quote.refundEth = fmtEth(q.refund);
+        notes.push('this buy fills the curve to graduation — the unused ' + fmtEth(q.refund) + ' ETH refunds to your wallet in the same transaction');
+      }
+    } else {
+      const q = await poolBuy(spendWei);
+      quote = { spendEth: fmtEth(spendWei), tokensOut: fmtUnits(q.out, dec), poolFeeTier: (q.tier / 10000) + '%' };
+    }
+    if (ethUsd) quote.spendUsd = Number((Number(spendWei) / 1e18 * ethUsd).toFixed(2));
+  } else if (side === 'sell' && (amountTokens != null || amountEth != null || amountUsd != null)) {
+    let tokAmt;
+    if (amountTokens != null) tokAmt = toUnits(amountTokens);
+    else { // size the sell from the probe price to hit a $/ETH target — approximate by design
+      const targetEth = amountEth != null ? amountEth : amountUsd / ethUsd;
+      tokAmt = toUnits(targetEth / priceEth);
+      notes.push('token amount sized from the reference price to receive about ' + targetEth.toFixed(6) + ' ETH — approximate; the receive amount below is the real quote for that token amount');
+    }
+    if (tokAmt <= 0n) throw new Error('sell amount rounds to zero tokens');
+    if (venue === 'curve') {
+      const net = await curveSell(tokAmt);
+      quote = { tokensIn: fmtUnits(tokAmt, dec), receiveEth: fmtEth(net) };
+      if (ethUsd) quote.receiveUsd = Number((Number(net) / 1e18 * ethUsd).toFixed(2));
+    } else {
+      const q = await poolSell(tokAmt);
+      quote = { tokensIn: fmtUnits(tokAmt, dec), receiveEth: fmtEth(q.out), poolFeeTier: (q.tier / 10000) + '%' };
+      if (ethUsd) quote.receiveUsd = Number((Number(q.out) / 1e18 * ethUsd).toFixed(2));
+    }
+  } else if (side === 'sell') {
+    notes.push('pass amountTokens (or a USD/ETH target) to size a sell — showing price only');
+  }
+
+  return {
+    token, name: name || null, symbol: symbol || null, decimals: dec,
+    venue: venue === 'curve' ? 'bonding curve' : 'uniswap v3 pool',
+    venueDetail: venue === 'curve'
+      ? 'still bonding — quotes come from the curve contract itself (previewBuy/previewSell) and INCLUDE the 1% terminal fee, excluding your slippage setting.'
+      : 'Uniswap V3 pool via QuoterV2 exact-in simulation — includes the pool fee and the ' + (bps / 100) + '% yoinkai.fun terminal fee, excludes your slippage setting.',
+    curve: curveInfo,
+    side, price,
+    ethUsd: ethUsd ? Number(ethUsd.toFixed(2)) : null,
+    quote,
+    notes,
+    note: 'Read-only quote from live on-chain calls. Not financial advice. Trades happen in your own wallet on yoinkai.fun.',
   };
 }
 
 const TOOLS = [
   { name: 'top_launches', description: 'Most active recent token launches on Robinhood Chain by newest block. Returns name, symbol, address, deployer, source.',
     inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'how many, default 20, max 100' } } } },
-  { name: 'scan_launch', description: 'X-ray one token by contract address: is it sellable, taxed, owner-controlled, LP locked, and who deployed it.',
+  { name: 'scan_launch', description: 'Trust Score scan of one token by contract address: is it sellable, taxed, owner-controlled, LP locked, and who deployed it.',
     inputSchema: { type: 'object', properties: { address: { type: 'string', description: '0x contract address' } }, required: ['address'] } },
-  { name: 'xray_token', description: 'Alias of scan_launch. Full safety X-ray of a token by address.',
+  { name: 'xray_token', description: 'Alias of scan_launch, the same Trust Score scan.',
     inputSchema: { type: 'object', properties: { address: { type: 'string' } }, required: ['address'] } },
   { name: 'deployer_history', description: 'Every launch from a wallet in the graph, with a serial-deployer flag. Reputation signal for a launch.',
     inputSchema: { type: 'object', properties: { address: { type: 'string', description: '0x deployer wallet' } }, required: ['address'] } },
   { name: 'graph_stats', description: 'Totals for the YOINK launch graph: tokens indexed, unique deployers, top serial deployers.',
     inputSchema: { type: 'object', properties: {} } },
+  { name: 'quote_token', description: 'Current price and expected receive amount for a token on Robinhood Chain. Routes to the live venue automatically: tokens still bonding quote from their bonding curve contract (1% fee included); graduated or pool tokens quote the Uniswap V3 pool via QuoterV2 exact-in simulation plus the terminal fee. Give amountUsd or amountEth to size a buy; amountTokens (or a USD/ETH target) to size a sell; omit amounts for price only. USD figures use a sanity-checked ETH/USD rate and are omitted when price sources disagree. Read-only: never signs, sends, or executes anything.',
+    inputSchema: { type: 'object', properties: {
+      address: { type: 'string', description: '0x token contract address' },
+      side: { type: 'string', enum: ['buy', 'sell'], description: 'buy (default) or sell' },
+      amountUsd: { type: 'number', description: 'trade size in US dollars' },
+      amountEth: { type: 'number', description: 'trade size in ETH' },
+      amountTokens: { type: 'number', description: 'token amount, for the sell side' },
+    }, required: ['address'] } },
+  { name: 'launch_token', description: 'Build the UNSIGNED transaction that launches a new token on Robinhood Chain via the YOINK bonding-curve factory: fixed 1B supply, no upfront liquidity needed, flat 0.0005 ETH fee (verified on-chain before every build), trading starts on the curve immediately, and at 4.2 ETH raised the token graduates to a Uniswap V3 pool with the LP position locked. Optional creator first buy. Returns to/value/data for the user to review and sign in their OWN wallet — this server never holds keys and cannot send anything. ALWAYS show the review block to the user before they sign.',
+    inputSchema: { type: 'object', properties: {
+      name: { type: 'string', description: 'token name, max 32 chars' },
+      symbol: { type: 'string', description: 'ticker symbol, letters/digits, max 10 chars' },
+      description: { type: 'string', description: 'optional, max 180 chars, stored on-chain in the launch event' },
+      logo: { type: 'string', description: 'optional ipfs:// or https:// image URI' },
+      x: { type: 'string', description: 'optional https:// X/Twitter link' },
+      telegram: { type: 'string', description: 'optional https:// Telegram link' },
+      website: { type: 'string', description: 'optional https:// website link' },
+      initialBuyEth: { type: 'number', description: 'optional creator first buy in ETH, same tx (max 1)' },
+      from: { type: 'string', description: 'optional 0x wallet address that will sign — enables an exact dry run against the chain before anyone signs' },
+    }, required: ['name', 'symbol'] } },
 ];
 
 async function call(name, args) {
@@ -98,20 +458,26 @@ async function call(name, args) {
     return (r.tokens || []).map((t) => ({ name: t.name, symbol: t.symbol, address: t.address, deployer: t.deployer, source: t.source, block: t.block }));
   }
   if (name === 'scan_launch' || name === 'xray_token') {
-    if (!isAddr(args.address)) throw new Error('need a 0x contract address');
+    if (!isAddr(args.address)) throw new Error('Need a 0x contract address');
     return xray(args.address.toLowerCase());
   }
   if (name === 'deployer_history') {
-    if (!isAddr(args.address)) throw new Error('need a 0x wallet address');
+    if (!isAddr(args.address)) throw new Error('Need a 0x wallet address');
     const r = await j('/v0/deployer/' + args.address.toLowerCase());
     const launches = r.launches || [];
     return { deployer: args.address.toLowerCase(), count: launches.length, serialDeployer: launches.length >= 3,
       launches: launches.map((t) => ({ name: t.name, symbol: t.symbol, address: t.address, block: t.block })) };
   }
   if (name === 'graph_stats') return j('/v0/stats');
-  throw new Error('unknown tool ' + name);
+  if (name === 'quote_token') return quoteToken(args);
+  if (name === 'launch_token') return buildLaunch(args);
+  throw new Error('Unknown tool ' + name);
 }
 
+// exported for the audit/parity harness; running as a bin starts the stdio server below
+module.exports = { encYoinkLaunch, ycExpectedOut, buildLaunch, quoteToken, call, TOOLS, FACTORY, CURVE_FACTORY, FACTORY_V1, LAUNCH_FEE };
+if (require.main !== module) return;
+
 // ---- MCP stdio transport ----
 const send = (m) => process.stdout.write(JSON.stringify(m) + '\n');
 let buf = '';
@@ -125,7 +491,7 @@ process.stdin.on('data', async (d) => {
     const reply = (result) => send({ jsonrpc: '2.0', id: msg.id, result });
     const fail = (message) => send({ jsonrpc: '2.0', id: msg.id, error: { code: -32000, message } });
     try {
-      if (msg.method === 'initialize') reply({ protocolVersion: '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: 'yoinkai-mcp', version: '0.1.0' } });
+      if (msg.method === 'initialize') reply({ protocolVersion: '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: 'yoinkai-mcp', version: '0.3.0' } });
       else if (msg.method === 'tools/list') reply({ tools: TOOLS });
       else if (msg.method === 'tools/call') {
         const out = await call(msg.params.name, msg.params.arguments);

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "yoinkai-mcp",
-  "version": "0.1.0",
-  "description": "Read-only MCP server over the YOINK launch graph on Robinhood Chain: scan launches, X-ray tokens for safety, read deployer history. No keys, no custody.",
+  "version": "0.3.0",
+  "description": "MCP server over the YOINK launch graph on Robinhood Chain: scan launches, X-ray tokens for safety, quote live prices, read deployer history, and build unsigned bonding-curve token launches you sign in your own wallet. No keys, no custody.",
   "type": "commonjs",
   "bin": { "yoinkai-mcp": "index.js" },
+  "scripts": { "test": "node test/smoke.js" },
   "files": ["index.js", "README.md", "SKILL.md"],
   "engines": { "node": ">=18" },
   "keywords": ["mcp", "model-context-protocol", "robinhood-chain", "yoink", "token-launch", "agent", "crypto"],