@candledottv/mcp 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Candle
+
+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,193 @@
+# @candledottv/mcp
+
+An MCP (Model Context Protocol) server for the Candle agent rail. It exposes Candle's REST API as
+ten tools over stdio, so an MCP-capable agent can launch tokens (optionally seeded with a dev
+buy in the same call), trade, convert between base assets (including across chains), read market
+and feed data, report on-chain activity, and check an agent profile without hand-rolling HTTP
+calls.
+
+## Try it without a key
+
+Three tools are read-only and need nothing but `CANDLE_API_URL` (which already defaults to
+production): `candle_get_market`, `candle_get_feed`, and `candle_get_agent_profile`. Install the
+server with no `env` block at all and those three work immediately:
+
+```json
+{
+  "mcpServers": {
+    "candle": {
+      "command": "npx",
+      "args": ["-y", "@candledottv/mcp"]
+    }
+  }
+}
+```
+
+Add `CANDLE_AGENT_API_KEY` only once you're ready to launch, trade, or report activity, see
+Environment below -- or skip env editing entirely: after `npx @candledottv/cli auth login`,
+`candle mcp` launches this server with the stored key and API URL in its environment.
+
+`CANDLE_MCP_TOOLS` (optional) is a comma-separated allowlist of tool names; only those register.
+Unset means all eight. An unknown name fails startup with the valid names in the message, rather
+than silently registering the wrong surface. `candle mcp --read-only` / `--tools` set this for
+you.
+
+Most tools are a thin wrapper: a one-request mapping onto `apps/api`
+(`POST /api/v1/launch/headless`, `GET /api/v1/markets/:chain/:mint`, `GET /api/v1/markets/feed`,
+`POST /api/v1/activity/report`, `GET /api/v1/users/:idOrWallet/agent`) that hands the response body
+straight back to the caller, unchanged, error responses included. `candle_trade` and
+`candle_launch_and_seed` are the two exceptions: each is a small orchestration (a decimal-to-raw
+conversion, an idempotency key, a follow-up read) on top of the same REST surface, see Errors
+below.
+
+Both take decimal amounts, never raw base units, and resolve the scale themselves:
+
+- A `candle_trade` **buy** is denominated in the token's OWN quote asset, whatever it was launched
+  against (SOL for a SOL-launched token, USDC or CNDL for those quote pairs). The tool reads the
+  market first and converts against its `quoteDecimals`; the `quoteAsset` field applies only to a
+  mint Candle never launched, the arbitrary-token path a Pro or Max key trades through Jupiter. A
+  **sell** is denominated in tokens and converts against the market's own `decimals`.
+- A `candle_launch_and_seed` `devBuy` is denominated in the quote asset that launch selects, since
+  there the caller genuinely picks the new token's quote pair: `quoteAsset` if given, otherwise
+  SOL on Solana and ETH on Hood.
+
+For a full walkthrough of `candle_launch_and_seed` and `candle_trade`, including the keyless read
+tools, getting a key, funding the embedded wallet, and idempotent retries, see
+`docs/mcp-launch-and-seed.md` in the `candle-monorepo` repo.
+
+## Environment
+
+- `CANDLE_API_URL` -- base URL of the Candle API. Defaults to `https://api.alpha.candle.tv` (the alpha deployment; production does not serve the agent API yet). Set it to
+  `http://localhost:3001` when developing against a local API.
+- `CANDLE_AGENT_API_KEY` -- an agent API key (`cndl_live_...` / `cndl_test_...`), issued from a
+  Candle account's agent settings page. Only required by `candle_launch_token`,
+  `candle_report_activity`, `candle_trade`, `candle_launch_and_seed`, and `candle_swap`; the three
+  read-only tools
+  work without it, so the server is useful the moment it is installed and only asks for a key when
+  you try to write. `candle_trade` additionally needs the key's `swap:write` scope server-side,
+  which is opt-in only and never granted by omission, see `docs/mcp-launch-and-seed.md` in the
+  `candle-monorepo` repo.
+- `CANDLE_API_KEY` -- alias for `CANDLE_AGENT_API_KEY`, the same variable name the Candle CLI uses
+  for this credential. Set either one; if both are set, `CANDLE_AGENT_API_KEY` takes precedence.
+
+## Tools
+
+| Tool | Description | REST call | Auth |
+| --- | --- | --- | --- |
+| `candle_launch_token` | Launch a token on Candle | `POST /api/v1/launch/headless` (or `/dry-run` when `dryRun: true`) | `CANDLE_AGENT_API_KEY` |
+| `candle_get_market` | Get market state | `GET /api/v1/markets/:chain/:mint` | none |
+| `candle_get_feed` | Get a token feed | `GET /api/v1/markets/feed?bucket=...` | none |
+| `candle_report_activity` | Report on-chain activity | `POST /api/v1/activity/report` | `CANDLE_AGENT_API_KEY` |
+| `candle_get_agent_profile` | Get an agent profile | `GET /api/v1/users/:idOrWallet/agent` | none |
+| `candle_trade` | Buy or sell a token | Reads the market for its decimals (or wallet balance, for a percent sell) then `POST /api/v1/trade/agent/build` | `CANDLE_AGENT_API_KEY` (`swap:write`) |
+| `candle_launch_and_seed` | Launch a token and seed it | `POST /api/v1/launch/headless` (or `/dry-run`), then a follow-up `GET /api/v1/markets/:chain/:mint` | `CANDLE_AGENT_API_KEY` |
+| `candle_swap` | Swap between base assets | `POST /api/v1/agent/swap` | `CANDLE_AGENT_API_KEY` (`swap:write`) |
+| `candle_transfer` | Transfer an asset | `POST /api/v1/agent/transfer` | `CANDLE_AGENT_API_KEY` (`transfer:write`) |
+| `candle_sweep` | Sweep a wallet to one destination | One `POST /api/v1/agent/transfer` per asset, `amountRaw: "max"` | `CANDLE_AGENT_API_KEY` (`transfer:write`) |
+
+### Transfers and sweeps
+
+`candle_transfer` moves one asset from the account's embedded wallet: to any of the account's
+OWN wallets freely (any asset, `amountRaw` in RAW base units or `"max"` for the spendable
+balance), or to an address the OWNER pre-approved as a withdrawal address in the Candle console
+(base assets only, bounded by the account's spend caps and the key's transaction limit).
+Anything else is refused before signing -- an agent key can never approve its own destination.
+
+`candle_sweep` is the whole-wallet loop: one `"max"` transfer per asset on the chosen chain,
+tokens before the native asset (the native asset pays the fees), plus any `mints` named
+explicitly. Assets with nothing spendable report `empty`; a failed asset never stops the rest.
+
+## Errors
+
+This package never reinterprets an error body, and that body is not one uniform shape across all
+ten tools:
+
+- `candle_launch_token`, `candle_get_market`, and `candle_get_feed` hit endpoints that use the
+  structured envelope `{ success: false, error: { code, message, ... } }`. Branch on `error.code`.
+- `candle_report_activity` relays `apps/api/src/routes/activity.ts`'s own plain error shape
+  verbatim: `{ error: true, payload: string }`.
+- `candle_get_agent_profile` relays `apps/api/src/routes/users.ts`'s own plain error shape
+  verbatim: `{ error: string }`.
+- `candle_trade` and `candle_launch_and_seed` wrap the underlying REST body instead of relaying it
+  bare, in one of two shapes depending on how far the call got:
+  - A failure caught before any REST request goes out (e.g. passing both `amount` and `percent`,
+    an unrecognized `quoteAsset`, or a devBuy conversion
+    error) returns
+    `{ clientTradeId | clientLaunchId, success: false, error: { code: "MCP_VALIDATION", message } }`.
+  - A pre-request READ that comes back non-ok (an expired key on the wallet read, a 500 on the
+    market read) is relayed verbatim instead: `{ clientTradeId | clientLaunchId, success: false,
+    api }`, where `api` is that read's own body. The tool never reinterprets it as "you have no
+    embedded wallet" or "this token has no decimals".
+  - A request that dies in transit, a rejected connection or a body that is not JSON, returns
+    `{ clientTradeId | clientLaunchId, success: false, error: { code: "MCP_TRANSPORT", message,
+    retryable: true } }`. It means undetermined, not failed: the call may or may not have reached
+    Candle. Retry it with the SAME id and the same body, which either replays the original result
+    or runs it for the first time. A new id would be a second trade or launch.
+  - Once the underlying request is actually sent, the shape is
+    `{ clientTradeId | clientLaunchId, resolved?, api | launch, market?, note? }`. `candle_trade`
+    always returns `{ clientTradeId, resolved, api }`: `resolved` is the decimal-to-raw (or
+    percent-to-raw) conversion this tool computed before calling the trade endpoint, and `api` is
+    that endpoint's own response body verbatim, success or error. `candle_launch_and_seed` returns
+    `{ clientLaunchId, api }` for a dry run or a failed launch, and
+    `{ clientLaunchId, launch, market, note? }` for a confirmed launch: `launch` is the launch
+    endpoint's own response body, `market` is a best-effort follow-up market read (`null` when
+    that read failed), and `note` is present only alongside a failed follow-up read, pointing at
+    `candle_get_market` to fetch it separately.
+  - Either way, both tools echo their idempotency id (`clientTradeId` / `clientLaunchId`) at the
+    top level, so a caller can always find it to retry safely: retrying with the SAME id is a safe
+    replay, a new id is a second trade or launch. See `docs/mcp-launch-and-seed.md` in the
+    `candle-monorepo` repo for the full idempotent-retry rule.
+
+## MCP client config
+
+Add this to your MCP client (Claude Desktop, Claude Code, Cursor, or anything else that speaks
+stdio MCP). No checkout and no build required:
+
+```json
+{
+  "mcpServers": {
+    "candle": {
+      "command": "npx",
+      "args": ["-y", "@candledottv/mcp"],
+      "env": {
+        "CANDLE_AGENT_API_KEY": "cndl_live_..."
+      }
+    }
+  }
+}
+```
+
+`CANDLE_API_URL` is omitted on purpose: it already defaults to production. Drop the `env` block
+entirely if you only want the read-only tools.
+
+## Running it directly
+
+```bash
+npx -y @candledottv/mcp
+```
+
+The server speaks JSON-RPC over stdio, so running it in a terminal is only useful for smoke
+testing. It is meant to be spawned by an MCP client.
+
+## Development
+
+From a monorepo checkout:
+
+```bash
+bun run src/index.ts   # run from source against CANDLE_API_URL
+bun test               # request-building, version parity, and config-default guards
+bun run typecheck      # tsc --noEmit
+bun run build          # bundle to dist/index.js for publishing
+```
+
+`bun run build` targets node and leaves `@modelcontextprotocol/sdk` and `zod` as external
+dependencies, so npm installs and dedupes them normally. The published `bin` is the built
+`dist/index.js` with a `#!/usr/bin/env node` shebang, not the TypeScript source: MCP clients spawn
+this on machines that have node and may not have bun.
+
+`@modelcontextprotocol/sdk` is pinned to `1.22.0` rather than the newest 1.x release: starting at
+`1.23.0`, the SDK's zod v3/v4 compatibility types (`server/zod-compat.ts`) trip a TypeScript
+`TS2589` ("Type instantiation is excessively deep") once more than a couple of `registerTool`
+calls with multi-field zod input shapes coexist in one file, which this package's tools
+always will. `1.22.0` predates that rewrite and type-checks cleanly with the exact same tool
+code. Re-check this pin when bumping the SDK.

package/dist/index.js

@@ -0,0 +1,599 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/tools.ts
+import { z } from "zod";
+
+// src/client.ts
+var DEFAULT_API_URL = "https://api.alpha.candle.tv";
+function resolveConfig() {
+  const apiUrl = process.env.CANDLE_API_URL?.trim() || DEFAULT_API_URL;
+  const apiKey = process.env.CANDLE_AGENT_API_KEY?.trim() || process.env.CANDLE_API_KEY?.trim();
+  return apiKey ? { apiUrl, apiKey } : { apiUrl };
+}
+
+// src/orchestrate.ts
+import { randomUUID } from "node:crypto";
+
+// src/convert.ts
+var QUOTE_DECIMALS = {
+  sol: 9,
+  usdc: 6,
+  cndl: 6,
+  eth: 18,
+  usdg: 6
+};
+function defaultQuoteId(chain) {
+  return chain === "hood" ? "eth" : "sol";
+}
+var DECIMAL_RE = /^\d+(\.\d+)?$/;
+function decimalToRaw(amount, decimals) {
+  if (!Number.isInteger(decimals) || decimals < 0) {
+    throw new Error(`decimals must be a non-negative integer, got ${decimals}`);
+  }
+  if (!DECIMAL_RE.test(amount)) {
+    throw new Error(`amount must be a plain positive decimal string, got "${amount}"`);
+  }
+  const [whole, fraction = ""] = amount.split(".");
+  if (fraction.length > decimals) {
+    throw new Error(`amount "${amount}" has more fraction digits than the asset's ${decimals} decimals`);
+  }
+  const raw = BigInt(whole + fraction.padEnd(decimals, "0"));
+  if (raw === 0n)
+    throw new Error("amount must be greater than zero");
+  return raw.toString();
+}
+function percentOfBalance(balanceRaw, percent) {
+  if (!Number.isInteger(percent) || percent < 1 || percent > 100) {
+    throw new Error(`percent must be an integer between 1 and 100, got ${percent}`);
+  }
+  if (!/^\d+$/.test(balanceRaw)) {
+    throw new Error(`balanceRaw must be a raw integer string, got "${balanceRaw}"`);
+  }
+  const result = BigInt(balanceRaw) * BigInt(percent) / 100n;
+  if (result === 0n) {
+    throw new Error(`${percent}% of the balance ${balanceRaw} floors to zero raw units; nothing to sell`);
+  }
+  return result.toString();
+}
+
+// src/orchestrate.ts
+function requireApiKey(cfg) {
+  if (!cfg.apiKey) {
+    throw new Error("CANDLE_AGENT_API_KEY is required for this tool. Set it in the environment or MCP client config.");
+  }
+  return cfg.apiKey;
+}
+function headers(apiKey) {
+  const h = { "Content-Type": "application/json" };
+  if (apiKey)
+    h["x-api-key"] = apiKey;
+  return h;
+}
+function base(cfg) {
+  return cfg.apiUrl.replace(/\/$/, "");
+}
+function errText(message, extra) {
+  return {
+    text: JSON.stringify({ ...extra, success: false, error: { code: "MCP_VALIDATION", message } }),
+    isError: true
+  };
+}
+function relayRead(body, extra) {
+  let api;
+  try {
+    api = JSON.parse(body);
+  } catch {
+    api = body;
+  }
+  return { text: JSON.stringify({ ...extra, success: false, api }), isError: true };
+}
+function transportError(idKey, id, thrown) {
+  const detail = thrown instanceof Error ? thrown.message : String(thrown);
+  return {
+    text: JSON.stringify({
+      [idKey]: id,
+      success: false,
+      error: {
+        code: "MCP_TRANSPORT",
+        message: `The request failed in transit (${detail}). It may or may not have reached Candle. ` + `Retry with THIS SAME ${idKey} ("${id}") and the same body: the same id replays the ` + "original result instead of executing a second time, while a NEW id is a second, independent " + "trade or launch.",
+        retryable: true
+      }
+    }),
+    isError: true
+  };
+}
+function chainForMint(mint) {
+  return mint.startsWith("0x") ? "hood" : "solana";
+}
+function quoteIdDecimals(quoteAsset, chain, extra) {
+  const quote = quoteAsset ?? defaultQuoteId(chain);
+  const decimals = QUOTE_DECIMALS[quote];
+  if (decimals === undefined) {
+    return {
+      err: errText(`unknown quoteAsset "${quote}"; expected one of ${Object.keys(QUOTE_DECIMALS).join(", ")}`, extra)
+    };
+  }
+  return { decimals };
+}
+function rawOrError(amount, decimals, extra) {
+  try {
+    return { raw: decimalToRaw(amount, decimals) };
+  } catch (err) {
+    return { err: errText(err instanceof Error ? err.message : String(err), extra) };
+  }
+}
+async function postJson(url, apiKey, payload, doFetch) {
+  try {
+    const res = await doFetch(url, { method: "POST", headers: headers(apiKey), body: JSON.stringify(payload) });
+    return { ok: res.ok, body: JSON.parse(await res.text()) };
+  } catch (thrown) {
+    return { thrown };
+  }
+}
+async function readMarket(mint, cfg, doFetch, extra) {
+  const res = await doFetch(`${base(cfg)}/api/v1/markets/${chainForMint(mint)}/${mint}`, {
+    method: "GET",
+    headers: headers()
+  });
+  const text = await res.text();
+  if (!res.ok)
+    return { status: res.status, err: relayRead(text, extra) };
+  return { market: JSON.parse(text).market ?? {} };
+}
+async function executeTrade(args, cfg, doFetch) {
+  const apiKey = requireApiKey(cfg);
+  const clientTradeId = args.clientTradeId ?? randomUUID();
+  if (args.amount !== undefined && args.percent !== undefined) {
+    return errText("pass exactly one of amount or percent, not both", { clientTradeId });
+  }
+  if (args.amount === undefined && args.percent === undefined) {
+    return errText("pass exactly one of amount or percent", { clientTradeId });
+  }
+  if (args.percent !== undefined && args.side !== "sell") {
+    return errText("percent is only valid on sells; buys take a quote-asset amount", { clientTradeId });
+  }
+  let amountRaw;
+  let resolved;
+  try {
+    if (args.side === "buy") {
+      const amount = args.amount;
+      const read = await readMarket(args.mint, cfg, doFetch, { clientTradeId });
+      let decimals;
+      if ("market" in read) {
+        const quoteDecimals = read.market.quoteDecimals;
+        if (typeof quoteDecimals !== "number") {
+          return errText(`could not resolve the quote decimals for mint ${args.mint}; a buy is denominated in that token's own quote asset and this market does not report its scale. Read the market with candle_get_market, then trade a raw amount via the SDK instead`, { clientTradeId });
+        }
+        decimals = quoteDecimals;
+      } else if (read.status === 404) {
+        const q = quoteIdDecimals(args.quoteAsset, chainForMint(args.mint), { clientTradeId });
+        if ("err" in q)
+          return q.err;
+        decimals = q.decimals;
+      } else {
+        return read.err;
+      }
+      const converted = rawOrError(amount, decimals, { clientTradeId });
+      if ("err" in converted)
+        return converted.err;
+      amountRaw = converted.raw;
+      resolved = { amountDecimal: amount, decimals, amountRaw };
+    } else if (args.amount !== undefined) {
+      const read = await readMarket(args.mint, cfg, doFetch, { clientTradeId });
+      if (!("market" in read))
+        return read.err;
+      const decimals = read.market.decimals;
+      if (typeof decimals !== "number") {
+        return errText(`could not resolve decimals for mint ${args.mint}; pass a raw-ready amount via the SDK instead`, { clientTradeId });
+      }
+      const converted = rawOrError(args.amount, decimals, { clientTradeId });
+      if ("err" in converted)
+        return converted.err;
+      amountRaw = converted.raw;
+      resolved = { amountDecimal: args.amount, decimals, amountRaw };
+    } else {
+      const percent = args.percent;
+      const walletsRes = await doFetch(`${base(cfg)}/api/v1/agent/wallets/embedded`, {
+        method: "GET",
+        headers: headers(apiKey)
+      });
+      const walletsText = await walletsRes.text();
+      if (!walletsRes.ok)
+        return relayRead(walletsText, { clientTradeId });
+      const walletsBody = JSON.parse(walletsText);
+      const chain = chainForMint(args.mint);
+      const address = chain === "hood" ? walletsBody.wallets?.evm?.address : walletsBody.wallets?.solana?.address;
+      if (!address) {
+        return errText(`percent sells need an embedded ${chain === "hood" ? "EVM" : "Solana"} wallet, and this account has none`, { clientTradeId });
+      }
+      const balRes = await doFetch(`${base(cfg)}/api/v1/tokens/${args.mint}/balance/${address}`, {
+        method: "GET",
+        headers: headers()
+      });
+      const balText = await balRes.text();
+      if (!balRes.ok)
+        return relayRead(balText, { clientTradeId });
+      const balBody = JSON.parse(balText);
+      const balance = balBody.payload?.balance;
+      if (!balance) {
+        return errText(`the embedded wallet ${address} holds no ${args.mint}; nothing to sell`, { clientTradeId });
+      }
+      amountRaw = percentOfBalance(balance, percent);
+      resolved = { percent, balanceRaw: balance, amountRaw };
+    }
+  } catch (err) {
+    return errText(err instanceof Error ? err.message : String(err), { clientTradeId });
+  }
+  const posted = await postJson(`${base(cfg)}/api/v1/trade/agent/build`, apiKey, {
+    clientTradeId,
+    mint: args.mint,
+    side: args.side,
+    amountRaw,
+    payer: { type: "main" },
+    ...args.quoteAsset !== undefined ? { quoteAsset: args.quoteAsset } : {},
+    ...args.maxSlippageBps !== undefined ? { maxSlippageBps: args.maxSlippageBps } : {}
+  }, doFetch);
+  if ("thrown" in posted)
+    return transportError("clientTradeId", clientTradeId, posted.thrown);
+  const wrapped = JSON.stringify({ clientTradeId, resolved, api: posted.body });
+  return posted.ok ? { text: wrapped } : { text: wrapped, isError: true };
+}
+async function executeLaunchAndSeed(args, cfg, doFetch) {
+  const apiKey = requireApiKey(cfg);
+  const clientLaunchId = args.clientLaunchId ?? randomUUID();
+  const { devBuy, dryRun, buyAmount: _rawBuyAmount, ...launchFields } = args;
+  let buyAmount;
+  if (devBuy !== undefined) {
+    const q = quoteIdDecimals(args.quoteAsset, args.chain, { clientLaunchId });
+    if ("err" in q)
+      return q.err;
+    const converted = rawOrError(devBuy, q.decimals, { clientLaunchId });
+    if ("err" in converted)
+      return converted.err;
+    buyAmount = converted.raw;
+  }
+  const path = dryRun ? "/api/v1/launch/headless/dry-run" : "/api/v1/launch/headless";
+  const posted = await postJson(`${base(cfg)}${path}`, apiKey, {
+    ...launchFields,
+    clientLaunchId,
+    ...buyAmount !== undefined ? { buyAmount } : {}
+  }, doFetch);
+  if ("thrown" in posted)
+    return transportError("clientLaunchId", clientLaunchId, posted.thrown);
+  if (!posted.ok) {
+    return { text: JSON.stringify({ clientLaunchId, api: posted.body }), isError: true };
+  }
+  if (dryRun) {
+    return { text: JSON.stringify({ clientLaunchId, dryRun: true, api: posted.body }) };
+  }
+  const launch = posted.body;
+  let market = null;
+  let note;
+  try {
+    const marketRes = await doFetch(`${base(cfg)}/api/v1/markets/${launch.chain ?? "solana"}/${launch.mint}`, {
+      method: "GET",
+      headers: headers()
+    });
+    if (marketRes.ok) {
+      market = JSON.parse(await marketRes.text()).market ?? null;
+    } else {
+      note = "launch confirmed; the follow-up market read failed, read it via candle_get_market";
+    }
+  } catch {
+    note = "launch confirmed; the follow-up market read failed, read it via candle_get_market";
+  }
+  return {
+    text: JSON.stringify({ clientLaunchId, launch, market, ...note ? { note } : {} })
+  };
+}
+var SWEEP_BASE_ASSETS = {
+  solana: ["USDC", "CNDL", "SOL"],
+  hood: ["USDG", "ETH"]
+};
+async function executeSweep(args, cfg, doFetch) {
+  const apiKey = cfg.apiKey;
+  if (!apiKey) {
+    throw new Error("CANDLE_AGENT_API_KEY is required for this tool. Set it in the environment or MCP client config.");
+  }
+  const base2 = cfg.apiUrl.replace(/\/$/, "");
+  const baseAssets = SWEEP_BASE_ASSETS[args.chain];
+  const targets = [
+    ...baseAssets.slice(0, -1).map((value) => ({ field: "asset", value })),
+    ...(args.mints ?? []).map((value) => ({ field: "mint", value })),
+    { field: "asset", value: baseAssets[baseAssets.length - 1] }
+  ];
+  const results = [];
+  for (const target of targets) {
+    let body;
+    let ok = false;
+    try {
+      const res = await doFetch(`${base2}/api/v1/agent/transfer`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "x-api-key": apiKey },
+        body: JSON.stringify({
+          chain: args.chain,
+          [target.field]: target.value,
+          amountRaw: "max",
+          to: args.to
+        })
+      });
+      ok = res.ok;
+      const text = await res.text();
+      try {
+        body = JSON.parse(text);
+      } catch {
+        body = text;
+      }
+    } catch (err) {
+      results.push({ asset: target.value, status: "error", error: String(err) });
+      continue;
+    }
+    if (ok) {
+      const payload = body;
+      results.push({
+        asset: target.value,
+        status: "transferred",
+        amountRaw: payload.amountRaw,
+        signature: payload.signature
+      });
+      continue;
+    }
+    const code = body?.error?.code ?? "";
+    if (code === "TRANSFER_AMOUNT_UNAVAILABLE") {
+      results.push({ asset: target.value, status: "empty" });
+    } else {
+      results.push({ asset: target.value, status: "error", error: body });
+    }
+  }
+  const transferred = results.filter((r) => r.status === "transferred").length;
+  const failed = results.filter((r) => r.status === "error").length;
+  return {
+    text: JSON.stringify({ chain: args.chain, to: args.to, transferred, failed, results }),
+    ...transferred === 0 && failed > 0 ? { isError: true } : {}
+  };
+}
+
+// src/tools.ts
+var TOOL_NAMES = [
+  "candle_launch_token",
+  "candle_get_market",
+  "candle_get_feed",
+  "candle_report_activity",
+  "candle_get_agent_profile",
+  "candle_trade",
+  "candle_launch_and_seed",
+  "candle_swap",
+  "candle_transfer",
+  "candle_sweep"
+];
+function resolveToolAllowlist(env) {
+  const raw = env.CANDLE_MCP_TOOLS?.trim();
+  if (!raw)
+    return new Set(TOOL_NAMES);
+  const requested = raw.split(",").map((name) => name.trim()).filter((name) => name.length > 0);
+  const unknown = requested.filter((name) => !TOOL_NAMES.includes(name));
+  if (requested.length === 0 || unknown.length > 0) {
+    throw new Error(`CANDLE_MCP_TOOLS contains unknown tool name(s): ${unknown.join(", ") || "(none given)"}. Valid names: ${TOOL_NAMES.join(", ")}`);
+  }
+  return new Set(requested);
+}
+function requireApiKey2(cfg) {
+  if (!cfg.apiKey) {
+    throw new Error("CANDLE_AGENT_API_KEY is required for this tool. Set it in the environment or MCP client config.");
+  }
+  return cfg.apiKey;
+}
+function jsonHeaders(apiKey) {
+  const headers2 = { "Content-Type": "application/json" };
+  if (apiKey)
+    headers2["x-api-key"] = apiKey;
+  return headers2;
+}
+function buildRequest(name, args, cfg) {
+  const base2 = cfg.apiUrl.replace(/\/$/, "");
+  switch (name) {
+    case "candle_launch_token": {
+      const apiKey = requireApiKey2(cfg);
+      const { dryRun, ...body } = args;
+      const path = dryRun ? "/api/v1/launch/headless/dry-run" : "/api/v1/launch/headless";
+      return {
+        url: `${base2}${path}`,
+        init: { method: "POST", headers: jsonHeaders(apiKey), body: JSON.stringify(body) }
+      };
+    }
+    case "candle_get_market": {
+      const { chain, mint } = args;
+      return { url: `${base2}/api/v1/markets/${chain}/${mint}`, init: { method: "GET", headers: jsonHeaders() } };
+    }
+    case "candle_get_feed": {
+      const { bucket, chain } = args;
+      const query = new URLSearchParams({ bucket, ...chain ? { chain } : {} });
+      return {
+        url: `${base2}/api/v1/markets/feed?${query.toString()}`,
+        init: { method: "GET", headers: jsonHeaders() }
+      };
+    }
+    case "candle_report_activity": {
+      const apiKey = requireApiKey2(cfg);
+      return {
+        url: `${base2}/api/v1/activity/report`,
+        init: { method: "POST", headers: jsonHeaders(apiKey), body: JSON.stringify(args) }
+      };
+    }
+    case "candle_get_agent_profile": {
+      const { idOrWallet } = args;
+      return { url: `${base2}/api/v1/users/${idOrWallet}/agent`, init: { method: "GET", headers: jsonHeaders() } };
+    }
+    case "candle_swap": {
+      const apiKey = requireApiKey2(cfg);
+      return {
+        url: `${base2}/api/v1/agent/swap`,
+        init: { method: "POST", headers: jsonHeaders(apiKey), body: JSON.stringify(args) }
+      };
+    }
+    case "candle_transfer": {
+      const apiKey = requireApiKey2(cfg);
+      return {
+        url: `${base2}/api/v1/agent/transfer`,
+        init: { method: "POST", headers: jsonHeaders(apiKey), body: JSON.stringify(args) }
+      };
+    }
+  }
+}
+async function callAndRelay(name, args, cfg) {
+  const { url, init } = buildRequest(name, args, cfg);
+  const res = await fetch(url, init);
+  const text = await res.text();
+  return {
+    content: [{ type: "text", text }],
+    ...res.ok ? {} : { isError: true }
+  };
+}
+var launchTokenShape = {
+  clientLaunchId: z.string().describe("Caller-chosen idempotency key, unique per account"),
+  name: z.string().describe("Token name"),
+  symbol: z.string().describe("Token symbol"),
+  imageUrl: z.string().describe("https URL to the token image. Must be roughly SQUARE (aspect ratio at most 1.5:1): it " + "renders as a small circle/square avatar everywhere. Share cards, OG images and banners " + "are rejected with IMAGE_WRONG_SHAPE -- pass those as bannerUrl instead"),
+  bannerUrl: z.string().optional().describe("Optional https URL to WIDE artwork for the token page's banner strip (wider than 1.5:1, " + "e.g. 1200x630). This is where a share card or OG image belongs. A square image here is " + "rejected with BANNER_WRONG_SHAPE. Omit it and the strip falls back to imageUrl"),
+  chain: z.string().optional().describe('"solana" or "hood"; defaults to solana'),
+  quoteAsset: z.string().optional().describe("Quote asset symbol; defaults per chain"),
+  mode: z.string().optional().describe('"open" or "exclusive"; defaults to open. "test-open" / "test-exclusive" launch the ' + "low-threshold test curves (~1/80 economics) where the API has ENABLE_TEST_CURVES on"),
+  stakerAllocationBps: z.number().optional().describe("Staker allocation in basis points"),
+  dexVersion: z.string().nullable().optional().describe('"v3" or "v4"; required for hood launches'),
+  buyAmount: z.union([z.string(), z.number()]).optional().describe("Initial buy, in quote base units (string or number)"),
+  description: z.string().optional(),
+  socials: z.record(z.string()).optional().describe("Social links keyed by platform"),
+  visibility: z.string().optional().describe('"production", "test", "local", or "hidden"'),
+  dryRun: z.boolean().optional().describe("Validate without executing the launch")
+};
+var getMarketShape = {
+  chain: z.string().describe('"solana" or "hood"'),
+  mint: z.string().describe("Token mint (solana) or contract address (hood)")
+};
+var getFeedShape = {
+  bucket: z.enum(["new", "graduated", "onfire", "bluechip"]),
+  chain: z.string().optional().describe("Optional chain filter")
+};
+var reportActivityShape = {
+  chain: z.string().describe('"solana" or "hood"'),
+  signature: z.string().describe("Transaction signature/hash to verify and record")
+};
+var getAgentProfileShape = {
+  idOrWallet: z.string().describe("Candle username or wallet address")
+};
+var swapShape = {
+  from: z.enum(["SOL", "USDC", "CNDL", "ETH", "USDG"]).describe("Base asset to spend"),
+  to: z.enum(["SOL", "USDC", "CNDL", "ETH", "USDG"]).describe("Base asset to receive; must differ from `from`"),
+  amountRaw: z.string().describe("Raw base units of `from` to spend, as a positive integer string"),
+  maxSlippageBps: z.number().optional().describe("Slippage bound in bps, 0-10000. Server defaults to 100 (1%)"),
+  clientSwapId: z.string().optional().describe("Optional dedup key. Only coalesces a duplicate that arrives while the first call is still " + "in flight; one arriving after it settled will swap again")
+};
+var tradeShape = {
+  mint: z.string().describe("Token mint (solana) or contract address (hood)"),
+  side: z.enum(["buy", "sell"]),
+  amount: z.string().optional().describe("Decimal amount. Buys: how much of THIS TOKEN'S OWN quote asset to spend (SOL for a " + 'SOL-launched token, USDC for a USDC-quoted one, and so on: e.g. "0.5"). Sells: how many ' + "TOKENS to sell. Pass exactly one of amount or percent."),
+  percent: z.number().optional().describe("Sells only: sell this percent (integer 1-100) of the wallet's holding, on either chain."),
+  quoteAsset: z.string().optional().describe('Quote asset ("sol", "usdc", "cndl") for an arbitrary Solana mint Candle never launched ' + "(Pro/Max only); defaults to sol. Ignored for a Candle-launched token, whose quote comes " + "from the token itself, so it never changes how a buy amount is interpreted there."),
+  maxSlippageBps: z.number().optional().describe("Max slippage in basis points; API default applies when omitted"),
+  clientTradeId: z.string().optional().describe("Idempotency key. Auto-generated when omitted and echoed in the result. Retrying with the " + "SAME id is safe (idempotent replay); a new id is a SECOND trade.")
+};
+var { buyAmount: _rawBuyAmount, ...seedableLaunchShape } = launchTokenShape;
+var launchAndSeedShape = {
+  ...seedableLaunchShape,
+  clientLaunchId: z.string().optional().describe("Idempotency key. Auto-generated when omitted and echoed in the result."),
+  devBuy: z.string().optional().describe('Seed buy in DECIMAL units of the quote asset this launch selects (e.g. "0.25" SOL, or ' + "ETH on hood), bundled into the launch transaction itself. Follows quoteAsset, which " + "defaults to sol on solana and eth on hood. Capped by the platform dev-buy ceiling; for " + "a larger seed, launch then follow with candle_trade.")
+};
+var transferShape = {
+  chain: z.enum(["solana", "hood"]).describe("Which chain the transfer executes on"),
+  asset: z.enum(["SOL", "USDC", "CNDL", "ETH", "USDG"]).optional().describe("A base asset key. Pass exactly one of asset or mint."),
+  mint: z.string().optional().describe("An arbitrary token: SPL mint (Solana) or ERC-20 contract (Hood). Own-wallet destinations only; withdrawals to approved addresses are base-assets-only."),
+  amountRaw: z.string().describe('RAW base units as a decimal string (lamports, wei, token raw units), or "max" to sweep the spendable balance. NOT a human decimal: 1 SOL is "1000000000".'),
+  to: z.string().describe("Destination address. Must be one of the account's own wallets, or an address the OWNER pre-approved as a withdrawal address in the Candle console -- anything else is refused before signing."),
+  clientTransferId: z.string().optional().describe("Caller-chosen idempotency key for safe retries")
+};
+var sweepShape = {
+  chain: z.enum(["solana", "hood"]).describe("Which chain to sweep"),
+  to: z.string().describe("Destination address, same rules as candle_transfer's `to`"),
+  mints: z.array(z.string()).optional().describe("Extra token mints/contracts to sweep besides the chain's base assets (own-wallet destinations only).")
+};
+function registerTools(server, env = process.env) {
+  const cfg = resolveConfig();
+  const allowed = resolveToolAllowlist(env);
+  const register = (name, ...rest) => {
+    if (!allowed.has(name))
+      return;
+    return server.registerTool(name, ...rest);
+  };
+  register("candle_launch_token", {
+    title: "Launch a token on Candle",
+    description: "Launch a new token via the Candle headless launch API. Set dryRun: true to validate without spending anything.",
+    inputSchema: launchTokenShape
+  }, async (args) => callAndRelay("candle_launch_token", args, cfg));
+  register("candle_get_market", {
+    title: "Get market state",
+    description: "Read the current market state for a token: lifecycle, pool address, whether buys are open.",
+    inputSchema: getMarketShape
+  }, async (args) => callAndRelay("candle_get_market", args, cfg));
+  register("candle_get_feed", {
+    title: "Get a token feed",
+    description: "Read one of the trade page's public feeds: new, graduated, onfire, or bluechip.",
+    inputSchema: getFeedShape
+  }, async (args) => callAndRelay("candle_get_feed", args, cfg));
+  register("candle_report_activity", {
+    title: "Report on-chain activity",
+    description: "Report a client-executed transaction (transfer, swap, stake) so Candle records and verifies it.",
+    inputSchema: reportActivityShape
+  }, async (args) => callAndRelay("candle_report_activity", args, cfg));
+  register("candle_get_agent_profile", {
+    title: "Get an agent profile",
+    description: "Read a Candle user's public agent profile: whether agent features are enabled and launch counts.",
+    inputSchema: getAgentProfileShape
+  }, async (args) => callAndRelay("candle_get_agent_profile", args, cfg));
+  register("candle_swap", {
+    title: "Convert between base assets",
+    description: "Convert one base asset into another through the account's own embedded wallets. MOVES " + "REAL FUNDS. A pair spanning the Solana side (SOL/USDC/CNDL) and the Hood side (ETH/USDG) " + "routes through the bridge, so this is how a Hood wallet gets funded before launching or " + "trading on hood. Amounts are RAW base units, not decimal. Test-environment keys are " + "refused: every leg settles on a live venue.",
+    inputSchema: swapShape
+  }, async (args) => callAndRelay("candle_swap", args, cfg));
+  register("candle_transfer", {
+    title: "Transfer an asset",
+    description: "Move an asset from the account's embedded wallet to one of the account's own wallets, or to an owner-approved withdrawal address. amountRaw 'max' sweeps the spendable balance of that asset.",
+    inputSchema: transferShape
+  }, async (args) => callAndRelay("candle_transfer", args, cfg));
+  register("candle_sweep", {
+    title: "Sweep a wallet",
+    description: "Sweep the embedded wallet on one chain to a destination: every base asset (plus any explicitly named mints), one transfer per asset with amountRaw 'max'. Assets with nothing spendable are reported as empty, not errors.",
+    inputSchema: sweepShape
+  }, async (args) => {
+    const result = await executeSweep(args, cfg, fetch);
+    return { content: [{ type: "text", text: result.text }], ...result.isError ? { isError: true } : {} };
+  });
+  register("candle_trade", {
+    title: "Buy or sell a token",
+    description: "Execute a buy or sell through the Candle trade rail. MOVES REAL FUNDS: the payer is the " + "account's embedded (main) wallet, executed server-side via delegation. Amounts are " + "decimal (never raw base units). Retry a timeout with the SAME clientTradeId from the " + "result; a new id is a second trade.",
+    inputSchema: tradeShape
+  }, async (args) => {
+    const result = await executeTrade(args, cfg, fetch);
+    return { content: [{ type: "text", text: result.text }], ...result.isError ? { isError: true } : {} };
+  });
+  register("candle_launch_and_seed", {
+    title: "Launch a token and seed it",
+    description: "Launch a new token with an optional dev-buy seed bundled into the launch itself, then " + "return the fresh market state and token links in one result. MOVES REAL FUNDS unless " + "dryRun. Seeds above the platform dev-buy ceiling are rejected (DEV_BUY_TOO_HIGH); " + "launch, then top up with candle_trade.",
+    inputSchema: launchAndSeedShape
+  }, async (args) => {
+    const result = await executeLaunchAndSeed(args, cfg, fetch);
+    return { content: [{ type: "text", text: result.text }], ...result.isError ? { isError: true } : {} };
+  });
+}
+
+// src/version.ts
+var SERVER_VERSION = "0.3.0";
+
+// src/index.ts
+var server = new McpServer({ name: "candle-mcp", version: SERVER_VERSION });
+registerTools(server);
+var transport = new StdioServerTransport;
+await server.connect(transport);

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@candledottv/mcp",
+  "version": "0.3.0",
+  "description": "MCP server for the Candle agent rail: launch tokens, read markets, report activity",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://docs.candle.tv/developers/mcp-server",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/candledottv/agentic.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/candledottv/agentic/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "candle",
+    "solana",
+    "token-launch",
+    "ai-agent",
+    "agent"
+  ],
+  "bin": {
+    "candle-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --target=node --format=esm --packages=external --outfile=dist/index.js",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.22.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.1.14",
+    "typescript": "^5.7.2"
+  }
+}