yoinkai-mcp 0.1.0 → 0.2.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 — and let it 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
 
@@ -24,6 +24,7 @@ Cursor, Claude Desktop, or any MCP client:
 - **scan_launch** / **xray_token** — safety X-ray 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.
+- **launch_token** — build the unsigned transaction that launches a new token through the audited YoinkLaunch factory: fixed 1B supply, pool seeded in the same tx, liquidity locked forever, flat 0.0005 ETH fee, optional creator first buy. 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.
 

package/SKILL.md

@@ -1,11 +1,11 @@
 ---
 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, X-ray, and launch tokens on Robinhood Chain via the YOINK launch graph. Use when the user asks about new tokens, launches, token safety, 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
 
@@ -13,10 +13,19 @@ You have the `yoink` MCP server (package `yoinkai-mcp`). It is read-only: it rea
 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.
 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. **Launch a token** — `launch_token` with a name and ticker builds the exact unsigned transaction for the audited YoinkLaunch factory: fixed 1B supply, pool created and seeded in the same tx, liquidity locked forever, flat 0.0005 ETH fee, optional creator first buy (`initialBuyEth`). 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 + ticker (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, ticker, total ETH (fee + first buy), and that supply and liquidity 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.
 
 ## 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. 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).
 - 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.

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, 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'];
@@ -77,6 +78,111 @@ async function xray(addr) {
   };
 }
 
+// ---- launch verb: builds the tx, NEVER signs or sends (no keys in this process) ----
+// Audited YoinkLaunch factory (docs/AUDIT_YOINKLAUNCH.md): fixed 1B supply, token is
+// always token1, LP minted to an escape-proof locker, flat 0.0005 ETH fee. Encoder is
+// a byte-exact port of the proven web path (landing/terminal.html encYoinkLaunch).
+const FACTORY = '0xbcc67639cd2c3e9498714be53018949e3b17ea5e';
+const LAUNCH_FEE = 500000000000000n; // 0.0005 ETH, compile-time constant in the factory
+const SEL_LAUNCH = '0xe1f7d84a';     // launch((string,string,string,string,string[3],uint256))
+const SEL_FEE = '0x09197a81';        // LAUNCH_FEE()
+const CHAIN_ID = 4663;               // 0x1237 Robinhood Chain
+
+const w256 = (n) => BigInt(n).toString(16).padStart(64, '0');
+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 pool (deterministic:
+// single-sided position [-887200,204200], price starts at the upper tick).
+// exact V3 math: L=amount1*Q96/(sqrtU-sqrtL); token0 in: sqrtP1=L*Q96*sqrtP0/(L*Q96+dx*sqrtP0)
+function ylExpectedOut(buyWei) {
+  const Q96 = 79228162514264337593543950336n, sU = 2151813121295408910812139624586144n, sL = 4306310044n;
+  const L = (1000000000000000000000000000n * Q96) / (sU - sL);
+  const dx = buyWei * 9900n / 10000n; // 1% pool fee off the input
+  const sP1 = (L * Q96 * sU) / ((L * Q96) + (dx * sU));
+  return (L * (sU - sP1)) / Q96;
+}
+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 : ''); };
+
+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 ticker 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
+  }
+  const minOut = buyWei > 0n ? ylExpectedOut(buyWei) * 9800n / 10000n : 0n; // 2% slippage, matches web
+  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 audited 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 audited 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), predictedPool: '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) + ')');
+    }
+  }
+
+  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)',
+      initialBuy: buyWei > 0n ? fmtEth(buyWei) + ' ETH spent as a first buy to the creator, min tokens out ' + minOut.toString() + ' (fresh-pool quote, 2% slippage)' : 'none',
+      factory: FACTORY, feeVerifiedOnChain: feeVerified, simulation,
+    },
+    launchDesign: 'Audited YoinkLaunch factory: token deploys, pool is created and seeded with the full supply in the same tx, and the LP position is locked in a contract with no withdraw path — liquidity can never be pulled.',
+    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 address is in the receipt (or scan_launch it once the graph picks it up).',
+  };
+}
+
 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' } } } },
@@ -88,6 +194,18 @@ const TOOLS = [
     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: 'launch_token', description: 'Build the UNSIGNED transaction that launches a new token on Robinhood Chain via the audited YoinkLaunch factory (fixed 1B supply, liquidity locked forever, 0.0005 ETH flat fee, 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, 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) {
@@ -109,9 +227,14 @@ async function call(name, args) {
       launches: launches.map((t) => ({ name: t.name, symbol: t.symbol, address: t.address, block: t.block })) };
   }
   if (name === 'graph_stats') return j('/v0/stats');
+  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, ylExpectedOut, buildLaunch, call, TOOLS, FACTORY, LAUNCH_FEE };
+if (require.main !== module) return;
+
 // ---- MCP stdio transport ----
 const send = (m) => process.stdout.write(JSON.stringify(m) + '\n');
 let buf = '';
@@ -125,7 +248,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.2.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,7 +1,7 @@
 {
   "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.2.0",
+  "description": "MCP server over the YOINK launch graph on Robinhood Chain: scan launches, X-ray tokens for safety, read deployer history, and build unsigned token-launch transactions you sign in your own wallet. No keys, no custody.",
   "type": "commonjs",
   "bin": { "yoinkai-mcp": "index.js" },
   "files": ["index.js", "README.md", "SKILL.md"],