@candledottv/mcp 0.10.10 → 0.10.12

package/README.md

@@ -1,7 +1,7 @@
 # @candledottv/mcp
 
 An MCP (Model Context Protocol) server for the Candle agent rail. It exposes Candle's REST API as
-twenty-nine tools over stdio, so an MCP-capable agent can launch tokens (optionally seeded with a dev
+thirty-one 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.
@@ -31,7 +31,7 @@ Environment below -- or skip env editing entirely: install the Candle CLI
 environment.
 
 `CANDLE_MCP_TOOLS` (optional) is a comma-separated allowlist of tool names; only those register.
-Unset means all twenty-nine. An unknown name fails startup with the valid names in the message, rather
+Unset means all thirty-one. 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.
 
@@ -79,6 +79,10 @@ tools, getting a key, funding the embedded wallet, and idempotent retries, see
 - `CANDLE_KEY_SIGNER_PEM_FILE` -- the perps write tools only: the path to the key signer's PEM
   (`candle tee signer new --out <pem>` writes one). The relay's authorization is signed with it;
   without it those tools refuse before anything is built.
+- `CANDLE_IMAGE_DIR` -- the launch tools only: an absolute path to a directory of images you mean
+  to publish. Set, `candle_launch_token` and `candle_launch_and_seed` accept `imagePath` for a
+  file inside it; unset, they take `imageUrl` only and the server reads no image file. See
+  [Launching with an image file](#launching-with-an-image-file).
 - `CANDLE_HYPERLIQUID_BUILDER` / `CANDLE_HYPERLIQUID_NETWORK` -- the perps tools: pin Candle's
   Hyperliquid builder address for the pre-sign check, and set `testnet` to trade testnet.
 - `CANDLE_API_KEY` -- alias for `CANDLE_AGENT_API_KEY`, the same variable name the Candle CLI uses
@@ -88,7 +92,7 @@ tools, getting a key, funding the embedded wallet, and idempotent retries, see
 
 | 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_launch_token` | Launch a token on Candle | `POST /api/v1/launch/headless` (or `/dry-run` when `dryRun: true`); with `imagePath`, `POST /api/v1/uploads/agent-image` first | `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_token_forensics` | Deployer history, deploy-window buyers, sourced token safety flags | `GET /api/v1/markets/:chain/:mint/forensics` | none |
@@ -96,7 +100,7 @@ tools, getting a key, funding the embedded wallet, and idempotent retries, see
 | `candle_get_agent_profile` | Get an agent profile | `GET /api/v1/users/:idOrWallet/agent` | none |
 | `candle_get_plans` | Plans: prices, fees, limits and what each can do, as JSON and a Markdown table | `GET /api/v1/agent/plans` | 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_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`; with `imagePath`, `POST /api/v1/uploads/agent-image` first | `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`, Withdraw (`transfer:write`) |
 | `candle_sweep` | Sweep a wallet to one destination | One `POST /api/v1/agent/transfer` per asset, `amountRaw: "max"` | `CANDLE_AGENT_API_KEY`, Withdraw (`transfer:write`) |
@@ -109,6 +113,8 @@ tools, getting a key, funding the embedded wallet, and idempotent retries, see
 | `candle_get_portfolio` | What the account's embedded and TEE wallets hold on Solana and Hood (Hood in `hood`), with prices; unpriced holdings say why, never zero | `GET /api/v1/agent/portfolio` | `CANDLE_AGENT_API_KEY` (`account:read`) |
 | `candle_execution_status` | One call before trading: wallets to spend from, tier, and whether trading is possible | Composes the wallet and tier reads | `CANDLE_AGENT_API_KEY` |
 | `candle_get_operation` | Look up a trade or launch by the id its write used, and whether it landed | `GET /api/v1/trade/agent/jobs/:clientId` or `/api/v1/launch/headless/jobs/:clientId` | `CANDLE_AGENT_API_KEY` |
+| `candle_get_fees` | The creator fees the account's launched tokens can pay: raw amounts from chain reads, and the reason a token cannot be claimed | `GET /api/v1/agent/fees` | `CANDLE_AGENT_API_KEY` (`account:read`) |
+| `candle_claim_fees` | Collect one token's creator fees to the wallet fixed at launch (no destination argument); `dryRun` sends nothing. Answers `LAUNCH_DISABLED` until the server enables agent claims | `POST /api/v1/agent/fees/:mint/claim` | `CANDLE_AGENT_API_KEY` (`launch:write`) |
 | `candle_perps_setup` | Approve Candle's Hyperliquid builder fee once; report the account's mode and balance | `POST /api/v1/agent/perps/setup`, then relay sign and Hyperliquid submit | `CANDLE_AGENT_API_KEY` (`perps:write`), `CANDLE_KEY_SIGNER_PEM_FILE` |
 | `candle_perps_open` | Open or add to a perps position, with optional take-profit and stop-loss | `POST /api/v1/agent/perps/open`, checked here, relay-signed, submitted to Hyperliquid | `CANDLE_AGENT_API_KEY` (`perps:write`), `CANDLE_KEY_SIGNER_PEM_FILE` |
 | `candle_perps_close` | Close all or part of a perps position, reduce-only | `POST /api/v1/agent/perps/close`, the same | `CANDLE_AGENT_API_KEY` (`perps:write`), `CANDLE_KEY_SIGNER_PEM_FILE` |
@@ -118,6 +124,35 @@ tools, getting a key, funding the embedded wallet, and idempotent retries, see
 | `candle_perps_orders` | Open Hyperliquid orders and every action Candle built | `GET /api/v1/agent/perps/orders` | `CANDLE_AGENT_API_KEY` |
 | `candle_perps_positions` | Perps positions and account value, read live | `GET /api/v1/agent/perps/positions` | `CANDLE_AGENT_API_KEY` |
 
+### Launching with an image file
+
+A launch takes its image as `imageUrl`, an `https://` URL. With `CANDLE_IMAGE_DIR` set to an
+absolute directory path, `candle_launch_token` and `candle_launch_and_seed` also accept
+`imagePath`: an absolute path to a PNG, JPEG, GIF or WebP file of at most 10MB inside that
+directory. The server uploads it through `POST /api/v1/uploads/agent-image` and launches with the
+URL that comes back; the launch routes never see a path. Pass exactly one of `imageUrl` and
+`imagePath`.
+
+- **The directory is the operator's grant.** A file is read only when its real path is inside the
+  real path of `CANDLE_IMAGE_DIR`; a link that leads outside is refused, and every path outside
+  gets the same sentence (`IMAGE_OUTSIDE_DIR`) whether or not anything is there. Keep only images
+  you mean to publish in it.
+- **An upload is public and permanent, on a dry run too.** `dryRun: true` uploads as well, because
+  the dry run fetches the image it validates. The URL cannot be withdrawn, and a square image
+  keeps its original bytes, metadata such as EXIF and GPS data included.
+- **Checked before any request.** The type comes from the file's first bytes
+  (`IMAGE_TYPE_UNSUPPORTED`), over 10MB is `IMAGE_TOO_LARGE`, a missing or non-regular file is
+  `IMAGE_UNREADABLE`, and a `CANDLE_IMAGE_DIR` that is not an existing directory (or is the
+  filesystem root) refuses every `imagePath` with `IMAGE_DIR_INVALID`.
+- **The result carries the `imageUrl` used.** Pass that on a retry, or after a dry run, instead of
+  uploading the file again.
+- The upload needs `launch:write`, spends no funds and does not count against the daily launch
+  cap; the plan's uploads-per-minute limit applies. `bannerUrl` is always a URL.
+
+The hosted server at `mcp.candle.tv` has no `imagePath`: it cannot read your disk. There, run
+`candle image upload <path>` (Candle CLI 0.11.24 or later, with a `launch:write` key) and pass the
+URL it prints as `imageUrl`.
+
 ### Transfers and sweeps
 
 `candle_transfer` moves one asset from the account's embedded wallet: to any of the account's
@@ -133,7 +168,7 @@ explicitly. Assets with nothing spendable report `empty`; a failed asset never s
 ## Errors
 
 This package never reinterprets an error body, and that body is not one uniform shape across all
-twenty-nine tools:
+thirty-one 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`.

package/dist/index.js

@@ -105,11 +105,13 @@ function percentOfBalance(balanceRaw, percent) {
   return result.toString();
 }
 
-// src/orchestrate.ts
-import { randomUUID } from "node:crypto";
+// src/image.ts
+import { constants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, sep } from "node:path";
 
 // src/version.ts
-var SERVER_VERSION = "0.10.10";
+var SERVER_VERSION = "0.10.12";
 
 // src/update-notice.ts
 var PLAIN_VERSION = /^\d+\.\d+\.\d+$/;
@@ -143,7 +145,212 @@ function updateAvailable() {
   };
 }
 
+// src/image.ts
+var MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+var OUTSIDE_IMAGE_DIR = "Image files must be inside the configured CANDLE_IMAGE_DIR.";
+var NOTHING_UPLOADED = "Nothing was uploaded.";
+var READ_CHUNK_BYTES = 256 * 1024;
+
+class ImageRefusal extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+function configuredImageDir(env) {
+  return env.CANDLE_IMAGE_DIR?.trim() || undefined;
+}
+var nodeFs = { realpath, lstat, open };
+function sniffImageType(bytes) {
+  const at = (offset, signature) => signature.every((byte, i) => bytes[offset + i] === byte);
+  if (at(0, [137, 80, 78, 71, 13, 10, 26, 10]))
+    return "image/png";
+  if (at(0, [255, 216, 255]))
+    return "image/jpeg";
+  if (at(0, [71, 73, 70, 56]) && (bytes[4] === 55 || bytes[4] === 57) && bytes[5] === 97)
+    return "image/gif";
+  if (at(0, [82, 73, 70, 70]) && at(8, [87, 69, 66, 80]))
+    return "image/webp";
+  return;
+}
+function isInside(dir, path) {
+  const rel = relative(dir, path);
+  return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+function errno(error) {
+  return error?.code;
+}
+async function realImageDir(imageDir, fs) {
+  const invalid = () => new ImageRefusal("IMAGE_DIR_INVALID", `CANDLE_IMAGE_DIR must be an absolute path to an existing directory, and not the filesystem root. ${NOTHING_UPLOADED}`);
+  if (!isAbsolute(imageDir))
+    throw invalid();
+  try {
+    const real = await fs.realpath(imageDir);
+    if (dirname(real) === real || !(await fs.lstat(real, { bigint: true })).isDirectory())
+      throw invalid();
+    return real;
+  } catch {
+    throw invalid();
+  }
+}
+async function missingInside(dirReal, path, fs) {
+  const absent = (error) => errno(error) === "ENOENT" || errno(error) === "ENOTDIR";
+  for (let current = path;; ) {
+    try {
+      await fs.lstat(current, { bigint: true });
+      return false;
+    } catch (error) {
+      if (!absent(error))
+        return false;
+    }
+    const parent = dirname(current);
+    if (parent === current)
+      return false;
+    try {
+      const real = await fs.realpath(parent);
+      return real === dirReal || isInside(dirReal, real);
+    } catch (error) {
+      if (!absent(error))
+        return false;
+      current = parent;
+    }
+  }
+}
+async function readImageInDir(imageDir, imagePath, fs = nodeFs) {
+  if (!isAbsolute(imagePath))
+    throw new ImageRefusal("MCP_VALIDATION", `imagePath must be an absolute path inside CANDLE_IMAGE_DIR; this server's working directory is not something a caller can know. ${NOTHING_UPLOADED}`);
+  const dirReal = await realImageDir(imageDir, fs);
+  const outside = () => new ImageRefusal("IMAGE_OUTSIDE_DIR", OUTSIDE_IMAGE_DIR);
+  const unreadable = (why) => new ImageRefusal("IMAGE_UNREADABLE", `Could not read the image at imagePath: ${why}. ${NOTHING_UPLOADED}`);
+  const tooLarge = () => new ImageRefusal("IMAGE_TOO_LARGE", `The file at imagePath is over 10MB, the largest image Candle hosts. ${NOTHING_UPLOADED}`);
+  let fileReal;
+  try {
+    fileReal = await fs.realpath(imagePath);
+  } catch {
+    throw await missingInside(dirReal, imagePath, fs) ? unreadable("there is no file at that path") : outside();
+  }
+  if (!isInside(dirReal, fileReal))
+    throw outside();
+  let handle;
+  try {
+    handle = await fs.open(fileReal, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+  } catch (error) {
+    throw errno(error) === "ELOOP" ? outside() : unreadable("it could not be opened");
+  }
+  let bytes;
+  try {
+    const opened = await handle.stat({ bigint: true });
+    let named;
+    try {
+      if (await fs.realpath(fileReal) !== fileReal || !isInside(await realImageDir(imageDir, fs), fileReal))
+        throw outside();
+      named = await fs.lstat(fileReal, { bigint: true });
+    } catch {
+      throw outside();
+    }
+    if (named.dev !== opened.dev || named.ino !== opened.ino)
+      throw outside();
+    if (!opened.isFile())
+      throw unreadable("it is not a regular file");
+    const chunks = [];
+    let total = 0;
+    try {
+      while (total <= MAX_IMAGE_BYTES) {
+        const want = Math.min(READ_CHUNK_BYTES, MAX_IMAGE_BYTES + 1 - total);
+        const chunk = new Uint8Array(want);
+        const { bytesRead } = await handle.read(chunk, 0, want, null);
+        if (bytesRead === 0)
+          break;
+        chunks.push(chunk.subarray(0, bytesRead));
+        total += bytesRead;
+      }
+    } catch {
+      throw unreadable("the read failed");
+    }
+    if (total > MAX_IMAGE_BYTES)
+      throw tooLarge();
+    bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.length;
+    }
+  } finally {
+    await handle.close().catch(() => {});
+  }
+  const contentType = sniffImageType(bytes);
+  if (!contentType)
+    throw new ImageRefusal("IMAGE_TYPE_UNSUPPORTED", `The file at imagePath is not a PNG, JPEG, GIF or WebP image. The type is read from the file's first bytes, not its name. ${NOTHING_UPLOADED}`);
+  return { bytes, contentType };
+}
+async function resolveLaunchImage(args, imageDir, cfg, doFetch, fs = nodeFs) {
+  const { imagePath, ...rest } = args;
+  const hasPath = typeof imagePath === "string" && imagePath.length > 0;
+  const hasUrl = typeof rest.imageUrl === "string" && rest.imageUrl.length > 0;
+  const invalid = (message) => ({ refused: { code: "MCP_VALIDATION", message } });
+  if (imageDir === undefined) {
+    if (imagePath !== undefined)
+      return invalid(`imagePath is not available on this server: no CANDLE_IMAGE_DIR is configured. Pass imageUrl, an https URL. ${NOTHING_UPLOADED}`);
+    return { args: rest };
+  }
+  if (hasPath && hasUrl)
+    return invalid(`Pass exactly one of imageUrl or imagePath, not both. ${NOTHING_UPLOADED}`);
+  if (!hasPath && !hasUrl)
+    return invalid("Pass imageUrl (an https URL) or imagePath (an absolute path to an image file inside CANDLE_IMAGE_DIR).");
+  if (!hasPath)
+    return { args: rest };
+  if (!cfg.apiKey)
+    return invalid(`CANDLE_AGENT_API_KEY is required to upload an image; the key needs the launch:write scope. ${NOTHING_UPLOADED}`);
+  let image;
+  try {
+    image = await readImageInDir(imageDir, imagePath, fs);
+  } catch (error) {
+    if (error instanceof ImageRefusal)
+      return { refused: { code: error.code, message: error.message } };
+    throw error;
+  }
+  let res;
+  try {
+    res = await doFetch(`${cfg.apiUrl.replace(/\/$/, "")}/api/v1/uploads/agent-image`, {
+      method: "POST",
+      headers: { "Content-Type": image.contentType, "x-api-key": cfg.apiKey },
+      body: image.bytes
+    });
+  } catch (error) {
+    return {
+      refused: {
+        code: "MCP_TRANSPORT",
+        message: `The image upload failed in transit (${error instanceof Error ? error.message : String(error)}). ` + "No launch was attempted. The upload may or may not have reached Candle; if it did, the file is public."
+      }
+    };
+  }
+  noteVersionHeaders(res);
+  const text = await res.text();
+  if (!res.ok)
+    return { uploadFailed: text };
+  let uploaded;
+  try {
+    uploaded = JSON.parse(text)?.imageUrl;
+  } catch {
+    uploaded = undefined;
+  }
+  if (typeof uploaded !== "string" || !uploaded.startsWith("https://"))
+    return {
+      refused: {
+        code: "MCP_TRANSPORT",
+        message: "Candle did not return an https URL for the uploaded image. No launch was attempted."
+      }
+    };
+  return { args: { ...rest, imageUrl: uploaded }, uploaded };
+}
+function imageRefusalBody(refused, extra) {
+  return JSON.stringify({ ...extra, success: false, error: { code: refused.code, message: refused.message } });
+}
+var UPLOADED_IMAGE_NOTE = "imagePath was uploaded to imageUrl, which is public and permanent. To retry, or to launch after a dry run, pass this imageUrl instead of imagePath, so the file is not uploaded again.";
+
 // src/orchestrate.ts
+import { randomUUID } from "node:crypto";
 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.");
@@ -391,10 +598,10 @@ async function executeTrade(args, cfg, doFetch) {
   const wrapped = JSON.stringify({ clientTradeId, resolved, api: posted.body });
   return posted.ok ? { text: wrapped } : { text: wrapped, isError: true };
 }
-async function executeLaunchAndSeed(args, cfg, doFetch) {
+async function executeLaunchAndSeed(args, cfg, doFetch, imageDir, imageFs) {
   const apiKey = requireApiKey(cfg);
   const clientLaunchId = args.clientLaunchId ?? randomUUID();
-  const { devBuy, dryRun, buyAmount: _rawBuyAmount, ...launchFields } = args;
+  const { devBuy, dryRun, buyAmount: _rawBuyAmount, ...imageFields } = args;
   let buyAmount;
   if (devBuy !== undefined) {
     const q = quoteIdDecimals(args.quoteAsset, args.chain, { clientLaunchId });
@@ -405,19 +612,34 @@ async function executeLaunchAndSeed(args, cfg, doFetch) {
       return converted.err;
     buyAmount = converted.raw;
   }
+  const image = await resolveLaunchImage(imageFields, imageDir, cfg, doFetch, imageFs);
+  if ("refused" in image)
+    return { text: imageRefusalBody(image.refused, { clientLaunchId }), isError: true };
+  if ("uploadFailed" in image) {
+    let api;
+    try {
+      api = JSON.parse(image.uploadFailed);
+    } catch {
+      api = image.uploadFailed;
+    }
+    return { text: JSON.stringify({ clientLaunchId, api }), isError: true };
+  }
+  const uploaded = image.uploaded === undefined ? {} : { imageUrl: image.uploaded, imageNote: UPLOADED_IMAGE_NOTE };
   const path = dryRun ? "/api/v1/launch/headless/dry-run" : "/api/v1/launch/headless";
   const posted = await postJson(`${base(cfg)}${path}`, apiKey, {
-    ...launchFields,
+    ...image.args,
     clientLaunchId,
     ...buyAmount !== undefined ? { buyAmount } : {}
   }, doFetch);
-  if ("thrown" in posted)
-    return transportError("clientLaunchId", clientLaunchId, posted.thrown);
+  if ("thrown" in posted) {
+    const failed = transportError("clientLaunchId", clientLaunchId, posted.thrown);
+    return image.uploaded === undefined ? failed : { ...failed, text: JSON.stringify({ ...JSON.parse(failed.text), ...uploaded }) };
+  }
   if (!posted.ok) {
-    return { text: JSON.stringify({ clientLaunchId, api: posted.body }), isError: true };
+    return { text: JSON.stringify({ clientLaunchId, ...uploaded, api: posted.body }), isError: true };
   }
   if (dryRun) {
-    return { text: JSON.stringify({ clientLaunchId, dryRun: true, api: posted.body }) };
+    return { text: JSON.stringify({ clientLaunchId, dryRun: true, ...uploaded, api: posted.body }) };
   }
   const launch = posted.body;
   let market = null;
@@ -438,7 +660,7 @@ async function executeLaunchAndSeed(args, cfg, doFetch) {
     note = "launch confirmed; the follow-up market read failed, read it via candle_get_market";
   }
   return {
-    text: JSON.stringify({ clientLaunchId, launch, market, ...note ? { note } : {} })
+    text: JSON.stringify({ clientLaunchId, ...uploaded, launch, market, ...note ? { note } : {} })
   };
 }
 var SWEEP_BASE_ASSETS = {
@@ -1450,6 +1672,8 @@ var TOOL_NAMES = [
   "candle_resolve_token",
   "candle_execution_status",
   "candle_get_operation",
+  "candle_get_fees",
+  "candle_claim_fees",
   "candle_perps_setup",
   "candle_perps_open",
   "candle_perps_close",
@@ -1572,6 +1796,27 @@ function buildRequest(name, args, cfg) {
       const path = kind === "launch" ? `/api/v1/launch/headless/jobs/${encodeURIComponent(clientId)}` : `/api/v1/trade/agent/jobs/${encodeURIComponent(clientId)}`;
       return { url: `${base2}${path}`, init: { method: "GET", headers: jsonHeaders(apiKey) } };
     }
+    case "candle_get_fees": {
+      const apiKey = requireApiKey2(cfg);
+      const { cursor, limit } = args;
+      const params = new URLSearchParams;
+      if (cursor !== undefined)
+        params.set("cursor", cursor);
+      if (limit !== undefined)
+        params.set("limit", String(limit));
+      return {
+        url: `${base2}/api/v1/agent/fees${params.size ? `?${params}` : ""}`,
+        init: { method: "GET", headers: jsonHeaders(apiKey) }
+      };
+    }
+    case "candle_claim_fees": {
+      const apiKey = requireApiKey2(cfg);
+      const { mint, dryRun } = args;
+      return {
+        url: `${base2}/api/v1/agent/fees/${encodeURIComponent(mint)}/claim`,
+        init: { method: "POST", headers: jsonHeaders(apiKey), body: JSON.stringify({ dryRun: dryRun === true }) }
+      };
+    }
     case "candle_get_wallets": {
       const apiKey = requireApiKey2(cfg);
       return {
@@ -1707,6 +1952,14 @@ var getOperationShape = {
   clientId: z2.string().describe("The clientTradeId or clientLaunchId the write used, or that the tool echoed back to you"),
   kind: z2.enum(["trade", "launch"]).describe("Which rail the id belongs to. Required: ids are caller-chosen strings with no shape to dispatch on")
 };
+var getFeesShape = {
+  cursor: z2.string().optional().describe("The previous page's continueCursor, verbatim"),
+  limit: z2.number().optional().describe("Tokens per page, 1 to 50 (default 20). Each one costs chain reads")
+};
+var claimFeesShape = {
+  mint: z2.string().describe("The launched token: a Solana mint or a Hood token address, as candle_get_fees lists it"),
+  dryRun: z2.boolean().optional().describe("Check and read only. Sends nothing and writes nothing. Use it first to see what would be claimed")
+};
 var resolveTokenShape = {
   mint: z2.string().describe("Token mint (Solana, base58) or contract address (Hood, 0x-prefixed)")
 };
@@ -1743,11 +1996,18 @@ var tradeShape = {
   paper: z2.preprocess((value) => value === "true" || value === 1 || value === "1" ? true : value === "false" || value === 0 || value === "0" ? false : value, z2.boolean().optional().describe("Rehearse instead of trading. The request passes every admission rule a live trade passes " + "-- the same planner, spend gate, key cap and loss limits -- and records the quote, but " + "nothing is ever broadcast and no funds move. Use it to check that a strategy is admitted " + "before risking anything on it. A paper fill is optimistic by construction: it books the " + "quoted price, so the gap between a paper arm and a live one IS the execution cost. " + "A sell of a mint this key already paper-bought also closes that paper book when the " + "live wallet is empty, even if this flag is omitted."))
 };
 var { buyAmount: _rawBuyAmount, ...seedableLaunchShape } = launchTokenShape;
-var launchAndSeedShape = {
-  ...seedableLaunchShape,
+var seedShape = {
   clientLaunchId: z2.string().optional().describe("Idempotency key. Auto-generated when omitted and echoed in the result."),
   devBuy: z2.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 on solana and sent as a follow-up " + "transaction on hood. Paid from the account's embedded wallet. 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 launchAndSeedShape = { ...seedableLaunchShape, ...seedShape };
+var localImageShape = {
+  imageUrl: launchTokenShape.imageUrl.optional().describe(`${launchTokenShape.imageUrl.description}. Pass this or imagePath, never both`),
+  imagePath: z2.string().optional().describe("An absolute image path inside CANDLE_IMAGE_DIR. The file is uploaded and becomes public and permanent, " + "including on a dry run. PNG, JPEG, GIF or WebP, at most 10MB, read from the file's first bytes. " + "Uploading spends no funds and does not count against the launch cap; only the upload limit applies. " + "Pass this or imageUrl, never both. The result carries the imageUrl used: pass that on a retry, or " + "after a dry run, instead of uploading the file again. bannerUrl takes no file")
+};
+var localLaunchTokenShape = { ...launchTokenShape, ...localImageShape };
+var localLaunchAndSeedShape = { ...seedableLaunchShape, ...localImageShape, ...seedShape };
+var IMAGE_PATH_DISCLOSURE = " With imagePath, the image file is uploaded first and becomes public and permanent, on a dry run too; " + "nothing about a dry run keeps that file private.";
 var transferShape = {
   chain: z2.enum(["solana", "hood"]).describe("Which chain the transfer executes on"),
   asset: z2.enum(["SOL", "USDC", "CNDL", "ETH", "USDG"]).optional().describe("A base asset key. Pass exactly one of asset or mint."),
@@ -1779,11 +2039,24 @@ function registerToolSubset(server, options) {
       return;
     server.registerTool(name, { ...definition, ...options.metadata?.[name] }, handler);
   };
+  const imageDir = configuredImageDir(env);
   register("candle_launch_token", {
     title: "Launch a token on Candle",
-    description: "Launch a new token via the Candle headless launch API, from the account's embedded wallet. Works on every plan, Free included. Set dryRun: true to validate without spending anything.",
-    inputSchema: launchTokenShape
-  }, async (args) => callAndRelay("candle_launch_token", args, getConfig(), doFetch));
+    description: "Launch a new token via the Candle headless launch API, from the account's embedded wallet. Works on every plan, Free included. Set dryRun: true to validate without spending anything." + (imageDir ? IMAGE_PATH_DISCLOSURE : ""),
+    inputSchema: imageDir ? localLaunchTokenShape : launchTokenShape
+  }, async (args) => {
+    const image = await resolveLaunchImage(args, imageDir, getConfig(), doFetch);
+    if ("refused" in image) {
+      return { content: [{ type: "text", text: imageRefusalBody(image.refused) }], isError: true };
+    }
+    if ("uploadFailed" in image)
+      return { content: [{ type: "text", text: image.uploadFailed }], isError: true };
+    const relayed = await callAndRelay("candle_launch_token", image.args, getConfig(), doFetch);
+    if (image.uploaded === undefined)
+      return relayed;
+    const uploaded = JSON.stringify({ imageUrl: image.uploaded, note: UPLOADED_IMAGE_NOTE });
+    return { ...relayed, content: [...relayed.content, { type: "text", text: uploaded }] };
+  });
   register("candle_get_market", {
     title: "Get market state",
     description: "Read Candle and indexed external markets, including indexed-but-not-routable tokens. No key needed. " + EXTERNAL_MARKET_DISCLOSURE + " " + "Read candleLaunched, launchpad, venue and trade.routable; jupiterOk and discovery flags are distinct. " + "Routability is stored eligibility, not a quote or permission. General quotes use POST /api/v1/trade/agent/quote. " + "Curve quotes and lifecycle describe Candle launches. MARKET_NOT_FOUND is a legacy code: read " + "error.routing.reason, error.discovery and sibling error.retryable. A curve-only 404 does not mean untradeable.",
@@ -1846,6 +2119,16 @@ MARKET_NOT_FOUND means Candle has no market for that token and this could not ru
 ` + "Amounts come back RAW, deliberately: the answer you need after a timeout is the outcome, " + "and you already know what you asked for.",
     inputSchema: getOperationShape
   }, async (args) => callAndRelay("candle_get_operation", args, getConfig(), doFetch));
+  register("candle_get_fees", {
+    title: "Read the creator fees this account's tokens can pay",
+    description: "The tokens launched by the account's own wallets, with what each could pay now in creator fees " + "(raw units from direct chain reads) and `claimable: true` or the `reason` it is not. Reads only; " + "moves nothing. It returns no earned or paid-out totals. An unreadable token is marked, never " + "shown as zero. Paged: pass `continueCursor` back as `cursor`.",
+    inputSchema: getFeesShape
+  }, async (args) => callAndRelay("candle_get_fees", args, getConfig(), doFetch));
+  register("candle_claim_fees", {
+    title: "Claim a token's creator fees",
+    description: "Collect one token's creator fees and pay them to the wallet fixed at launch. There is no destination " + "argument and the tool cannot send funds anywhere else. Candle signs with the embedded wallet, which " + "pays the network fee. Needs launch:write, and the server keeps it off until it is enabled (LAUNCH_DISABLED). " + "Call it with dryRun: true first; a real claim moves real funds into the recipient wallet, which may be " + "the wallet this agent trades from. Not idempotent by id: if the result is lost, read candle_get_fees " + "before claiming again.",
+    inputSchema: claimFeesShape
+  }, async (args) => callAndRelay("candle_claim_fees", args, getConfig(), doFetch));
   register("candle_get_wallets", {
     title: "List the wallets Candle executes with",
     description: "The account's EMBEDDED wallets, one per chain, with their delegation state. These are " + "the wallets candle_trade, candle_swap and candle_transfer spend from, so this is how an " + "agent finds its own funding addresses. Reads only; moves nothing. Not the same as the " + "account's LINKED wallets, which are the owner's own wallets and are not spent from here. " + "Balances are not included: read a specific one with the market and balance endpoints.",
@@ -1947,10 +2230,10 @@ MARKET_NOT_FOUND means Candle has no market for that token and this could not ru
   });
   register("candle_launch_and_seed", {
     title: "Launch a token and seed it",
-    description: "Launch a new token from the account's embedded wallet, with an optional dev-buy seed (in the " + "launch transaction on solana, a best-effort follow-up on hood). Works on every plan, Free included (this is not the atomic launch). 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
+    description: "Launch a new token from the account's embedded wallet, with an optional dev-buy seed (in the " + "launch transaction on solana, a best-effort follow-up on hood). Works on every plan, Free included (this is not the atomic launch). 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." + (imageDir ? IMAGE_PATH_DISCLOSURE : ""),
+    inputSchema: imageDir ? localLaunchAndSeedShape : launchAndSeedShape
   }, async (args) => {
-    const result = await executeLaunchAndSeed(args, getConfig(), doFetch);
+    const result = await executeLaunchAndSeed(args, getConfig(), doFetch, imageDir);
     return { content: [{ type: "text", text: result.text }], ...result.isError ? { isError: true } : {} };
   });
   const perpsTool = (tool) => async (args) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@candledottv/mcp",
-  "version": "0.10.10",
+  "version": "0.10.12",
   "description": "MCP server for the Candle agent rail: launch tokens, read markets, report activity",
   "type": "module",
   "license": "MIT",