@candledottv/mcp 0.5.0 → 0.6.1

package/README.md

@@ -1,17 +1,17 @@
 # @candledottv/mcp
 
 An MCP (Model Context Protocol) server for the Candle agent rail. It exposes Candle's REST API as
-eleven tools over stdio, so an MCP-capable agent can launch tokens (optionally seeded with a dev
+fifteen 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`, `candle_token_forensics`, and
-`candle_get_agent_profile`. Install the
-server with no `env` block at all and those three work immediately:
+Five tools are read-only and need nothing but `CANDLE_API_URL` (which already defaults to
+production): `candle_get_market`, `candle_get_feed`, `candle_token_forensics`,
+`candle_get_agent_profile`, and `candle_resolve_token`. Install the
+server with no `env` block at all and those five work immediately:
 
 ```json
 {
@@ -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 eight. An unknown name fails startup with the valid names in the message, rather
+Unset means all fifteen. 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.
 
@@ -68,9 +68,9 @@ tools, getting a key, funding the embedded wallet, and idempotent retries, see
   non-loopback host. For a trusted local endpoint that is not loopback, such as a devcontainer
   reaching its host; not for anything that leaves the machine.
 - `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
+  Candle account's agent settings page. Required by every tool except the five read-only ones
+  listed above, which includes the account-scoped reads (`candle_get_wallets`,
+  `candle_execution_status`, `candle_get_operation`) as well as the writes; those five
   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
@@ -93,6 +93,10 @@ tools, getting a key, funding the embedded wallet, and idempotent retries, see
 | `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`) |
+| `candle_resolve_token` | Turn a bare mint or contract address into Candle's market for it | `GET /api/v1/markets/:chain/:mint` | none |
+| `candle_get_wallets` | The account's embedded wallets, one per chain, with delegation state | `GET /api/v1/agent/wallets/embedded` | `CANDLE_AGENT_API_KEY` |
+| `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` |
 
 ### Transfers and sweeps
 
@@ -109,7 +113,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
-eleven tools:
+fifteen 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

@@ -42,9 +42,6 @@ function resolveConfig(env = process.env) {
   return apiKey ? { apiUrl, apiKey } : { apiUrl };
 }
 
-// src/orchestrate.ts
-import { randomUUID } from "node:crypto";
-
 // src/convert.ts
 var QUOTE_DECIMALS = {
   sol: 9,
@@ -88,6 +85,7 @@ function percentOfBalance(balanceRaw, percent) {
 }
 
 // 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.");
@@ -385,6 +383,48 @@ async function executeSweep(args, cfg, doFetch) {
     ...transferred === 0 && failed > 0 ? { isError: true } : {}
   };
 }
+async function resolveToken(args, cfg, doFetch) {
+  const chain = chainForMint(args.mint);
+  const read = await readMarket(args.mint, cfg, doFetch, { mint: args.mint, chain });
+  if ("err" in read)
+    return read.err;
+  return { text: JSON.stringify({ success: true, chain, mint: args.mint, market: read.market }, null, 2) };
+}
+async function executionStatus(cfg, doFetch) {
+  const apiKey = requireApiKey(cfg);
+  const get = async (path) => {
+    const res = await doFetch(`${base(cfg)}${path}`, { method: "GET", headers: headers(apiKey) });
+    const text = await res.text();
+    let body;
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = text;
+    }
+    return { ok: res.ok, status: res.status, body };
+  };
+  const [wallets, tier, limits] = await Promise.all([
+    get("/api/v1/agent/wallets/embedded"),
+    get("/api/v1/agent/tier"),
+    get("/api/v1/agent/keys/self/limits")
+  ]);
+  const unreadable = [
+    ["wallets", wallets],
+    ["tier", tier],
+    ["limits", limits]
+  ].filter(([, r]) => !r.ok);
+  return {
+    text: JSON.stringify({
+      success: true,
+      ready: unreadable.length === 0 ? true : undefined,
+      unreadable: unreadable.length > 0 ? unreadable.map(([name]) => name) : undefined,
+      wallets: wallets.body,
+      tier: tier.body,
+      limits: limits.body
+    }, null, 2),
+    ...unreadable.length > 0 ? { isError: true } : {}
+  };
+}
 
 // src/tools.ts
 var TOOL_NAMES = [
@@ -398,7 +438,11 @@ var TOOL_NAMES = [
   "candle_launch_and_seed",
   "candle_swap",
   "candle_transfer",
-  "candle_sweep"
+  "candle_sweep",
+  "candle_get_wallets",
+  "candle_resolve_token",
+  "candle_execution_status",
+  "candle_get_operation"
 ];
 function resolveToolAllowlist(env) {
   const raw = env.CANDLE_MCP_TOOLS?.trim();
@@ -423,6 +467,25 @@ function jsonHeaders(apiKey) {
     headers2["x-api-key"] = apiKey;
   return headers2;
 }
+function swapBody(args) {
+  const { amount, amountRaw, ...rest } = args;
+  const hasAmount = typeof amount === "string" && amount.length > 0;
+  const hasRaw = typeof amountRaw === "string" && amountRaw.length > 0;
+  if (hasAmount && hasRaw) {
+    throw new Error("Pass exactly one of amount or amountRaw, not both.");
+  }
+  if (!hasAmount && !hasRaw) {
+    throw new Error('Pass an amount, e.g. amount: "0.5".');
+  }
+  if (hasRaw)
+    return { ...rest, amountRaw };
+  const from = String(rest.from ?? "").toLowerCase();
+  const decimals = QUOTE_DECIMALS[from];
+  if (decimals === undefined) {
+    throw new Error(`Unknown decimals for base asset "${from}". Pass amountRaw instead.`);
+  }
+  return { ...rest, amountRaw: decimalToRaw(amount, decimals) };
+}
 function buildRequest(name, args, cfg) {
   const base2 = cfg.apiUrl.replace(/\/$/, "");
   switch (name) {
@@ -475,7 +538,20 @@ function buildRequest(name, args, cfg) {
       const apiKey = requireApiKey2(cfg);
       return {
         url: `${base2}/api/v1/agent/swap`,
-        init: { method: "POST", headers: jsonHeaders(apiKey), body: JSON.stringify(args) }
+        init: { method: "POST", headers: jsonHeaders(apiKey), body: JSON.stringify(swapBody(args)) }
+      };
+    }
+    case "candle_get_operation": {
+      const apiKey = requireApiKey2(cfg);
+      const { clientId, kind } = args;
+      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_wallets": {
+      const apiKey = requireApiKey2(cfg);
+      return {
+        url: `${base2}/api/v1/agent/wallets/embedded`,
+        init: { method: "GET", headers: jsonHeaders(apiKey) }
       };
     }
     case "candle_transfer": {
@@ -532,10 +608,18 @@ var reportActivityShape = {
 var getAgentProfileShape = {
   idOrWallet: z.string().describe("Candle username or wallet address")
 };
+var getOperationShape = {
+  clientId: z.string().describe("The clientTradeId or clientLaunchId the write used, or that the tool echoed back to you"),
+  kind: z.enum(["trade", "launch"]).describe("Which rail the id belongs to. Required: ids are caller-chosen strings with no shape to dispatch on")
+};
+var resolveTokenShape = {
+  mint: z.string().describe("Token mint (Solana, base58) or contract address (Hood, 0x-prefixed)")
+};
 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"),
+  amount: z.string().optional().describe('Decimal amount of `from` to spend, e.g. "0.5". Preferred. Pass exactly one of amount or amountRaw.'),
+  amountRaw: z.string().optional().describe("Raw base units of `from`, as a positive integer string. Kept for callers that already " + "compute raw units; new callers should use `amount`."),
   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")
 };
@@ -605,9 +689,52 @@ function registerTools(server, env = process.env) {
     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_get_operation", {
+    title: "What happened to a write",
+    description: "Look up a trade or launch by the id its write used, and find out whether it landed. " + `Reads only; moves nothing.
+
+` + "Call this after a timeout, after a restart, or any time you hold an id and do not know " + `the outcome. Do NOT re-send the write to find out.
+
+` + `Four answers, four different next moves:
+` + "- `confirmed`/`failed`: it is over. `signature` proves the first, `errorCode` explains " + `the second.
+` + "- `built`/`submitted`: still in flight. Wait and ask again.\n" + "- 404 (`JOB_NOT_FOUND`): Candle never saw this id, so the write never reached the rail " + "and nothing moved. The original request is safe to send again exactly as it was. This " + `is a definite answer, not a failure to retry.
+
+` + "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, cfg));
+  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.",
+    inputSchema: {}
+  }, async () => callAndRelay("candle_get_wallets", {}, cfg));
+  register("candle_resolve_token", {
+    title: "Resolve a contract address to a token",
+    description: "Turn a bare contract address or mint into Candle's market for it: chain, symbol, " + "decimals, quote asset, and whether Candle can trade it. Start here when a human gives " + "you an address and nothing else. The chain is read off the address's own shape and is " + "not guessed, so it does not need to be supplied. Reads only; moves nothing. A 404 means " + "Candle has no market for that address, which is an answer, not a failure to retry.",
+    inputSchema: resolveTokenShape
+  }, async (args) => {
+    const result = await resolveToken(args, cfg, fetch);
+    return { content: [{ type: "text", text: result.text }], ...result.isError ? { isError: true } : {} };
+  });
+  register("candle_execution_status", {
+    title: "Can this key execute right now",
+    description: "One call before trading: the embedded wallets to spend from, the tier that decides what " + "may be traded, and this key's own spend limits. Reads only; moves nothing. Call it when " + "a run starts, or after an authorization error, rather than inferring readiness from a " + "failed trade. If a read could not be completed the tool says which one and does NOT " + "claim the account is unready: an unreachable endpoint and a missing tier are different " + "problems with different fixes.",
+    inputSchema: {}
+  }, async () => {
+    const result = await executionStatus(cfg, fetch);
+    return { content: [{ type: "text", text: result.text }], ...result.isError ? { isError: true } : {} };
+  });
   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.",
+    description: "Convert one base asset into another through the account's own embedded wallets. MOVES " + `REAL FUNDS.
+
+` + "SOL, USDC and CNDL are on Solana. ETH and USDG are on Hood. A pair drawn from ONE of " + "those groups settles on that chain in a single transaction. A pair spanning both is a " + `BRIDGE, and this is how a Hood wallet gets funded before launching or trading there.
+
+` + `A bridge behaves differently and the difference matters:
+` + `- It is several transactions, not one, and it takes time rather than settling on the call.
+` + "- A confirmed source transaction is NOT proof the destination was credited. Read the " + "returned status before treating the funds as arrived; the response carries the venue's " + `own status URLs for the cross-chain fill.
+` + "- Do NOT re-send after a timeout. `clientSwapId` only coalesces a duplicate that arrives " + "while the first call is still in flight; once the first has settled, a second call with " + `the same id bridges AGAIN. If a bridge times out, check its status rather than retrying.
+
+` + 'Amounts are decimal (`amount`, e.g. "0.5"); `amountRaw` still accepts raw base units for ' + "callers that already compute them. Test-environment keys are refused: every leg settles " + "on a live venue.",
     inputSchema: swapShape
   }, async (args) => callAndRelay("candle_swap", args, cfg));
   register("candle_transfer", {
@@ -642,7 +769,7 @@ function registerTools(server, env = process.env) {
 }
 
 // src/version.ts
-var SERVER_VERSION = "0.5.0";
+var SERVER_VERSION = "0.6.1";
 
 // src/server.ts
 function createCandleMcpServer(env = process.env) {

package/package.json

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