hookit-mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# hookit-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lets an AI agent launch a coin on [hookit.fun](https://hookit.fun) (Ink) by itself, with its own Uniswap v4 hook modules, and collect its creator fees.
+
+## Setup
+
+```json
+{
+  "mcpServers": {
+    "hookit": {
+      "command": "npx",
+      "args": ["-y", "hookit-mcp"],
+      "env": { "HOOKIT_PRIVATE_KEY": "0x…" }
+    }
+  }
+}
+```
+
+The key signs on this machine and is never sent anywhere. Give it a wallet funded for launches and nothing else.
+
+Optional env: `HOOKIT_API_URL` (default `https://hookit.fun`), `HOOKIT_RPC_URL` (default Ink public RPC).
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `list_presets` | Strategies by goal: clean, community, deflationary, floor, builder, dynamic. |
+| `list_modules` | Every hook module, its settings and the rules a combination must follow. |
+| `list_pairs` | What a coin can be priced in. |
+| `wallet_status` | Whether the wallet holds enough ETH to launch. |
+| `launch_token` | Launches in one call, with an optional `devBuyPct`. `dryRun: true` checks and simulates without signing. |
+| `claim_fees` | Collects the creator fees the wallet earned on coins it launched. |
+| `send_eth` | Sends ETH from the wallet, for example back to a Kraken deposit address on Ink. `dryRun: true` checks only. |
+
+## With Kraken
+
+Ink is Kraken's chain: Kraken moves ETH to and from Ink directly. Run the [Kraken CLI](https://github.com/krakenfx/kraken-cli) MCP next to this one and an agent can fund its wallet from Kraken, launch, collect its fees with `claim_fees`, and send them back to its Kraken deposit address on Ink with `send_eth`. Use only the address Kraken returns for the "ETH - Ink" deposit method, and send at least 0.001 ETH: Kraken marks smaller deposits as failed and the funds are lost.
+
+```json
+{
+  "mcpServers": {
+    "kraken": {
+      "command": "kraken",
+      "args": ["mcp", "-s", "market,account,funding"],
+      "env": { "KRAKEN_API_KEY": "…", "KRAKEN_API_SECRET": "…" }
+    },
+    "hookit": {
+      "command": "npx",
+      "args": ["-y", "hookit-mcp"],
+      "env": { "HOOKIT_PRIVATE_KEY": "0x…" }
+    }
+  }
+}
+```
+
+Kraken withdraws only to saved addresses: save the agent's wallet in Kraken on the Ink network first.
+
+Without MCP: `GET /api/agents/catalog` and `POST /api/agents/prepare-launch` on hookit.fun (see `/llms.txt`).

package/index.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+// hookit-mcp: lets an AI agent launch a coin on hookit.fun (Ink) with its own hook modules.
+// The key in HOOKIT_PRIVATE_KEY signs on this machine and is never sent anywhere.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createPublicClient, createWalletClient, decodeEventLog, defineChain, formatEther, http, isAddress, parseAbi, parseEther, zeroAddress } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { z } from "zod";
+
+const API = (process.env.HOOKIT_API_URL || "https://hookit.fun").replace(/\/$/, "");
+const RPC = process.env.HOOKIT_RPC_URL || "https://rpc-gel.inkonchain.com";
+const KEY = process.env.HOOKIT_PRIVATE_KEY?.trim();
+
+const ink = defineChain({
+  id: 57073,
+  name: "Ink",
+  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+  rpcUrls: { default: { http: [RPC] } },
+  blockExplorers: { default: { name: "Blockscout", url: "https://explorer.inkonchain.com" } },
+});
+
+const account = KEY ? privateKeyToAccount(KEY.startsWith("0x") ? KEY : `0x${KEY}`) : null;
+const publicClient = createPublicClient({ chain: ink, transport: http(RPC) });
+const walletClient = account ? createWalletClient({ account, chain: ink, transport: http(RPC) }) : null;
+
+const factoryAbi = parseAbi([
+  "event TokenLaunched(uint256 indexed launchId, address indexed token, address indexed creator, bytes32 poolId, address hooks, bool customHook, int24 tickLower, int24 tickUpper, uint128 liquidity)",
+  "function masterHook() view returns (address)",
+  "function launchFee() view returns (uint256)",
+]);
+const hookAbi = parseAbi(["function feeEscrow() view returns (address)"]);
+const routerAbi = parseAbi([
+  "event PayoutLaunch(address indexed token, address indexed agent, address indexed controller, uint8 provider, uint256 accountId, address wallet)",
+]);
+const escrowAbi = parseAbi([
+  "function balanceOf(address account, address currency) view returns (uint256)",
+  "function claimAll(address[] currencies)",
+]);
+const erc20Abi = parseAbi(["function symbol() view returns (string)", "function decimals() view returns (uint8)"]);
+
+let catalogCache = null;
+async function catalog() {
+  if (catalogCache) return catalogCache;
+  const res = await fetch(`${API}/api/agents/catalog`);
+  if (!res.ok) throw new Error(`hookit catalog unavailable (${res.status})`);
+  catalogCache = await res.json();
+  return catalogCache;
+}
+
+function reply(value) {
+  return { content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }] };
+}
+function fail(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+function needKey() {
+  return fail("No wallet. Set HOOKIT_PRIVATE_KEY in this server's env to a wallet funded for launches and nothing else.");
+}
+
+const launchShape = {
+  name: z.string().describe("Coin name, up to 32 characters."),
+  symbol: z.string().describe("Ticker, 1 to 12 letters or digits."),
+  description: z.string().optional(),
+  image: z.string().optional().describe("Logo as an https:// or ipfs:// URL."),
+  twitter: z.string().optional(),
+  telegram: z.string().optional(),
+  website: z.string().optional(),
+  pair: z.string().optional().describe("What the coin is priced in. Default eth. See list_pairs."),
+  pairs: z.array(z.string()).optional().describe("Several pairs for a multi-pair launch (USDG and stocks only)."),
+  preset: z.string().optional().describe("A strategy from list_presets: clean, community, deflationary, floor, builder, dynamic."),
+  hookTaxPct: z.number().optional().describe("Extra swap fee feeding the hook modules, 0 to 9."),
+  modules: z.record(z.union([z.boolean(), z.number()])).optional().describe("Module settings from list_modules, e.g. {\"autoBurn\": true, \"autoBurnPct\": 100}. Without a preset they start from a clean slate."),
+  devBuyPct: z.number().optional().describe("Creator's own first buy in the launch tx, % of supply (up to 2.5, less with Max Tx). No sniper tax on it."),
+  payout: z
+    .object({
+      kind: z.enum(["wallet", "x", "github", "tiktok"]),
+      address: z.string().optional(),
+      handle: z.string().optional(),
+      accountId: z.string().optional(),
+    })
+    .optional()
+    .describe("Who receives the creator fees. Default: the launching wallet."),
+};
+
+async function prepare(args) {
+  const res = await fetch(`${API}/api/agents/prepare-launch`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ ...args, from: account?.address }),
+  });
+  const body = await res.json().catch(() => ({ ok: false, error: `hookit answered ${res.status}` }));
+  if (!res.ok && !body.error) body.error = `hookit answered ${res.status}`;
+  return body;
+}
+
+const server = new McpServer({ name: "hookit", version: "0.1.0" });
+
+server.registerTool(
+  "list_presets",
+  {
+    description: "Launch strategies by goal (clean, community, deflationary, floor, builder, dynamic) with the exact hook modules each one turns on. Needs no key.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+  },
+  async () => {
+    const c = await catalog();
+    return reply(c.presets.map(({ id, label, goal, settings, singlePairOnly }) => ({ id, label, goal, settings, singlePairOnly })));
+  },
+);
+
+server.registerTool(
+  "list_modules",
+  {
+    description: "Every hook module an agent can combine, what it does, its settings and the rules a combination must follow. Needs no key.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+  },
+  async () => {
+    const c = await catalog();
+    return reply({ modules: c.modules, rules: c.rules });
+  },
+);
+
+server.registerTool(
+  "list_pairs",
+  {
+    description: "What a coin can be priced in (ETH, USDG, kHYPE, kBTC, HKT, tokenized stocks), and which can be combined in a multi-pair launch. Needs no key.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+  },
+  async () => reply((await catalog()).pairs),
+);
+
+server.registerTool(
+  "wallet_status",
+  {
+    description: "Says in words whether the wallet can launch: its address, ETH balance and the launch fee.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+  },
+  async () => {
+    if (!account) return needKey();
+    const c = await catalog();
+    const [balance, fee] = await Promise.all([
+      publicClient.getBalance({ address: account.address }),
+      c.factory ? publicClient.readContract({ address: c.factory, abi: factoryAbi, functionName: "launchFee" }).catch(() => null) : null,
+    ]);
+    const gasPrice = await publicClient.getGasPrice();
+    const needed = (fee ?? 0n) + gasPrice * 4_000_000n;
+    return reply({
+      address: account.address,
+      chain: "Ink (57073)",
+      balanceEth: formatEther(balance),
+      launchFeeEth: fee === null ? "unknown" : formatEther(fee),
+      roughCostEth: formatEther(needed),
+      ready: balance >= needed,
+      verdict:
+        balance >= needed
+          ? "Ready to launch."
+          : `Not enough ETH on Ink. Send about ${formatEther(needed - balance)} ETH more to ${account.address}.`,
+      ...(balance >= needed
+        ? {}
+        : {
+            howToFund:
+              "Withdraw ETH from Kraken straight to Ink (choose the Ink network), or bridge from another chain. With the Kraken CLI MCP loaded, an agent can do the withdrawal itself; the user must first whitelist this address in Kraken.",
+          }),
+    });
+  },
+);
+
+server.registerTool(
+  "launch_token",
+  {
+    description:
+      "Launches a coin on hookit.fun with the chosen preset or hook modules, in one call. With dryRun it only checks the launch and returns the unsigned transaction: use it first and show the user the settings.",
+    inputSchema: { ...launchShape, dryRun: z.boolean().optional().describe("Check and simulate only. Signs nothing.") },
+  },
+  async ({ dryRun, ...args }) => {
+    if (!dryRun && !account) return needKey();
+    let prepared = await prepare(args);
+    if (prepared.error) return fail(prepared.error);
+    if (!dryRun && prepared.approve) {
+      // ERC-20 dev buy: approve the pair token, then prepare again so the launch is simulated.
+      const approveHash = await walletClient.sendTransaction({
+        to: prepared.approve.tx.to,
+        data: prepared.approve.tx.data,
+      });
+      await publicClient.waitForTransactionReceipt({ hash: approveHash });
+      prepared = await prepare(args);
+      if (prepared.error) return fail(prepared.error);
+    }
+    if (dryRun) {
+      return reply({
+        dryRun: true,
+        verdict: prepared.simulation?.needsApproval
+          ? "Valid. A real launch will first approve the dev buy token, then launch."
+          : prepared.simulation?.ok === false
+            ? `The launch would fail: ${prepared.simulation.error}`
+            : "The launch is valid.",
+        plan: prepared.plan,
+        approveFirst: prepared.approve ?? null,
+        tx: prepared.tx,
+        warnings: prepared.warnings,
+      });
+    }
+    if (prepared.simulation && !prepared.simulation.ok) {
+      return fail(`The launch would fail: ${prepared.simulation.error}\nSettings: ${prepared.plan.settings.join("; ")}`);
+    }
+
+    const hash = await walletClient.sendTransaction({
+      to: prepared.tx.to,
+      data: prepared.tx.data,
+      value: BigInt(prepared.tx.value),
+      gas: BigInt(prepared.tx.gas),
+    });
+    const receipt = await publicClient.waitForTransactionReceipt({ hash });
+    if (receipt.status !== "success") return fail(`Launch transaction reverted: ${hash}`);
+    let token = null;
+    let agent = null;
+    for (const log of receipt.logs) {
+      for (const abi of [factoryAbi, routerAbi]) {
+        try {
+          const ev = decodeEventLog({ abi, data: log.data, topics: log.topics });
+          if (ev.eventName === "TokenLaunched") token = ev.args.token;
+          if (ev.eventName === "PayoutLaunch") agent = ev.args.agent;
+        } catch {}
+      }
+    }
+    return reply({
+      launched: true,
+      token,
+      page: token ? `${API}/token/${token}` : null,
+      tx: `https://explorer.inkonchain.com/tx/${hash}`,
+      settings: prepared.plan.settings,
+      payout: prepared.plan.payout,
+      payoutAgent: agent,
+      note: agent
+        ? "Creator fees go to the payout target through this launch's CreatorPayoutAgent. This wallet is its controller."
+        : "Creator fees build up in FeeEscrow for this wallet. Call claim_fees to collect them.",
+    });
+  },
+);
+
+server.registerTool(
+  "claim_fees",
+  {
+    description: "Collects the creator fees this wallet has earned on coins it launched itself (paid in ETH and the pair tokens).",
+    inputSchema: {
+      currencies: z.array(z.string()).optional().describe("Token addresses to collect. Default: ETH plus every pair token."),
+    },
+  },
+  async ({ currencies }) => {
+    if (!account) return needKey();
+    const c = await catalog();
+    if (!c.factory) return fail("Launches are not configured on this hookit.");
+    const hook = await publicClient.readContract({ address: c.factory, abi: factoryAbi, functionName: "masterHook" });
+    const escrow = await publicClient.readContract({ address: hook, abi: hookAbi, functionName: "feeEscrow" });
+    const candidates = currencies?.length ? currencies : [zeroAddress, ...(c.pairAddresses ?? [])];
+    const owed = [];
+    for (const currency of candidates) {
+      const amount = await publicClient.readContract({ address: escrow, abi: escrowAbi, functionName: "balanceOf", args: [account.address, currency] });
+      if (amount > 0n) owed.push({ currency, amount });
+    }
+    if (owed.length === 0) return reply("Nothing to collect yet.");
+    const hash = await walletClient.writeContract({ address: escrow, abi: escrowAbi, functionName: "claimAll", args: [owed.map((o) => o.currency)] });
+    await publicClient.waitForTransactionReceipt({ hash });
+    const lines = [];
+    for (const { currency, amount } of owed) {
+      if (currency === zeroAddress) {
+        lines.push(`${formatEther(amount)} ETH`);
+        continue;
+      }
+      const [symbol, decimals] = await Promise.all([
+        publicClient.readContract({ address: currency, abi: erc20Abi, functionName: "symbol" }).catch(() => currency),
+        publicClient.readContract({ address: currency, abi: erc20Abi, functionName: "decimals" }).catch(() => 18),
+      ]);
+      lines.push(`${Number(amount) / 10 ** Number(decimals)} ${symbol}`);
+    }
+    return reply({ collected: lines, tx: `https://explorer.inkonchain.com/tx/${hash}` });
+  },
+);
+
+server.registerTool(
+  "send_eth",
+  {
+    description:
+      "Sends ETH from this wallet on Ink, for example to cash out to the user's Kraken ETH deposit address on the Ink network (get it with the Kraken MCP deposit addresses tool for the \"ETH - Ink\" method only). Kraken's minimum ETH deposit on Ink is 0.001 ETH; smaller deposits fail and the funds are lost, so never send less. Run it with dryRun first and repeat the address and amount to the user before sending.",
+    inputSchema: {
+      to: z.string().describe("Destination address on Ink."),
+      amountEth: z.string().describe('Amount in ETH, or "max" to send everything except gas.'),
+      dryRun: z.boolean().optional().describe("Check only. Signs nothing."),
+    },
+  },
+  async ({ to, amountEth, dryRun }) => {
+    if (!account) return needKey();
+    if (!isAddress(to)) return fail(`Not an address: ${to}`);
+    const [balance, gasPrice] = await Promise.all([publicClient.getBalance({ address: account.address }), publicClient.getGasPrice()]);
+    // A plain transfer is 21k gas; keep extra for the L1 data fee.
+    const gasReserve = gasPrice * 60_000n + 20_000_000_000_000n;
+    let value;
+    if (amountEth.trim().toLowerCase() === "max") {
+      value = balance > gasReserve ? balance - gasReserve : 0n;
+    } else {
+      try {
+        value = parseEther(amountEth.trim());
+      } catch {
+        return fail(`Not an amount: ${amountEth}`);
+      }
+    }
+    if (value <= 0n) return fail(`Nothing to send: the wallet holds ${formatEther(balance)} ETH.`);
+    if (value + gasReserve > balance) {
+      return fail(`Not enough ETH: the wallet holds ${formatEther(balance)} ETH and needs some left for gas.`);
+    }
+    if (dryRun) return reply({ dryRun: true, from: account.address, to, amountEth: formatEther(value), verdict: "Ready to send." });
+    const hash = await walletClient.sendTransaction({ to, value });
+    await publicClient.waitForTransactionReceipt({ hash });
+    return reply({ sentEth: formatEther(value), to, tx: `https://explorer.inkonchain.com/tx/${hash}` });
+  },
+);
+
+await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "hookit-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Let an AI agent launch a coin on hookit.fun (Ink) with its own hook modules, and collect its creator fees.",
+  "type": "module",
+  "bin": { "hookit-mcp": "index.js" },
+  "files": ["index.js", "README.md"],
+  "engines": { "node": ">=20" },
+  "license": "MIT",
+  "keywords": ["mcp", "model-context-protocol", "ink", "uniswap-v4", "hooks", "launchpad", "agents"],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.31.0",
+    "viem": "^2.55.0",
+    "zod": "^3.25.0"
+  }
+}