@candledottv/mcp 0.6.4 → 0.8.0

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
-fifteen tools over stdio, so an MCP-capable agent can launch tokens (optionally seeded with a dev
+nineteen 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 fifteen. An unknown name fails startup with the valid names in the message, rather
+Unset means all nineteen. 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.
 
@@ -95,6 +95,10 @@ tools, getting a key, funding the embedded wallet, and idempotent retries, see
 | `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_get_profile_wallets` | Which wallets an agent profile may spend from, and whether it is scoped | `GET /api/v1/agent/keys/:prefix/wallets` | `CANDLE_AGENT_API_KEY` |
+| `candle_set_profile_wallets` | Replace the wallets an agent profile may spend from | `PUT /api/v1/agent/keys/:prefix/wallets` | `CANDLE_AGENT_API_KEY` |
+| `candle_get_profile_pnl` | An agent profile's realized P&L, fees, and open positions at cost basis | `GET /api/v1/agent/keys/:prefix/pnl` | `CANDLE_AGENT_API_KEY` |
+| `candle_get_profile_trades` | An agent profile's orders, fills, fees and transaction hashes | `GET /api/v1/agent/keys/:prefix/trades` | `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` |
 
@@ -113,7 +117,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
-fifteen tools:
+nineteen 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

@@ -106,7 +106,7 @@ function percentOfBalance(balanceRaw, percent) {
 import { randomUUID } from "node:crypto";
 
 // src/version.ts
-var SERVER_VERSION = "0.6.4";
+var SERVER_VERSION = "0.8.0";
 
 // src/update-notice.ts
 var PLAIN_VERSION = /^\d+\.\d+\.\d+$/;
@@ -499,6 +499,10 @@ var TOOL_NAMES = [
   "candle_transfer",
   "candle_sweep",
   "candle_get_wallets",
+  "candle_get_profile_wallets",
+  "candle_set_profile_wallets",
+  "candle_get_profile_pnl",
+  "candle_get_profile_trades",
   "candle_resolve_token",
   "candle_execution_status",
   "candle_get_operation"
@@ -572,8 +576,15 @@ function buildRequest(name, args, cfg) {
       };
     }
     case "candle_get_feed": {
-      const { bucket, chain } = args;
-      const query = new URLSearchParams({ bucket, ...chain ? { chain } : {} });
+      const { bucket, chain, where, sort, fields, limit } = args;
+      const query = new URLSearchParams({
+        bucket,
+        ...chain ? { chain } : {},
+        ...where ? { where } : {},
+        ...sort ? { sort } : {},
+        ...fields ? { fields } : {},
+        ...limit ? { limit } : {}
+      });
       return {
         url: `${base2}/api/v1/markets/feed?${query.toString()}`,
         init: { method: "GET", headers: jsonHeaders() }
@@ -613,6 +624,39 @@ function buildRequest(name, args, cfg) {
         init: { method: "GET", headers: jsonHeaders(apiKey) }
       };
     }
+    case "candle_get_profile_wallets": {
+      const apiKey = requireApiKey2(cfg);
+      const { keyPrefix } = args;
+      return {
+        url: `${base2}/api/v1/agent/keys/${encodeURIComponent(keyPrefix)}/wallets`,
+        init: { method: "GET", headers: jsonHeaders(apiKey) }
+      };
+    }
+    case "candle_set_profile_wallets": {
+      const apiKey = requireApiKey2(cfg);
+      const { keyPrefix, walletIds } = args;
+      return {
+        url: `${base2}/api/v1/agent/keys/${encodeURIComponent(keyPrefix)}/wallets`,
+        init: { method: "PUT", headers: jsonHeaders(apiKey), body: JSON.stringify({ walletIds }) }
+      };
+    }
+    case "candle_get_profile_pnl": {
+      const apiKey = requireApiKey2(cfg);
+      const { keyPrefix } = args;
+      return {
+        url: `${base2}/api/v1/agent/keys/${encodeURIComponent(keyPrefix)}/pnl`,
+        init: { method: "GET", headers: jsonHeaders(apiKey) }
+      };
+    }
+    case "candle_get_profile_trades": {
+      const apiKey = requireApiKey2(cfg);
+      const { keyPrefix, limit } = args;
+      const query = limit === undefined ? "" : `?limit=${encodeURIComponent(String(limit))}`;
+      return {
+        url: `${base2}/api/v1/agent/keys/${encodeURIComponent(keyPrefix)}/trades${query}`,
+        init: { method: "GET", headers: jsonHeaders(apiKey) }
+      };
+    }
     case "candle_transfer": {
       const apiKey = requireApiKey2(cfg);
       return {
@@ -659,7 +703,11 @@ var tokenForensicsShape = {
 };
 var getFeedShape = {
   bucket: z.enum(["new", "graduated", "onfire", "bluechip"]),
-  chain: z.string().optional().describe("Optional chain filter")
+  chain: z.string().optional().describe("Optional chain filter"),
+  where: z.string().optional().describe('JSON filter, e.g. {"marketCap":{"lt":150000},"liquidityUsd":{"gte":25000},"mintAuthorityDisabled":{"eq":true}}. ' + "Comparators: eq, ne, lt, lte, gt, gte, present. An ABSENT field satisfies none of them except " + "present:false, so a filter for mintAuthorityDisabled eq true returns only tokens that actually say " + "true, never ones where the flag is simply missing. Use present:false to find the tokens with no data."),
+  sort: z.string().optional().describe('Sort as "field" or "field:asc" / "field:desc". A bare field means desc.'),
+  fields: z.string().optional().describe("Comma-separated fields to return, e.g. symbol,marketCap,liquidityUsd. chain, address and symbol always " + "ride along. Cuts a 135KB response to a couple of KB."),
+  limit: z.string().optional().describe("Max rows to return, 1-200.")
 };
 var reportActivityShape = {
   chain: z.string().describe('"solana" or "hood"'),
@@ -675,6 +723,20 @@ var getOperationShape = {
 var resolveTokenShape = {
   mint: z.string().describe("Token mint (Solana, base58) or contract address (Hood, 0x-prefixed)")
 };
+var profileWalletsShape = {
+  keyPrefix: z.string().describe("The profile's API key prefix, as listed by candle keys list or in the dashboard")
+};
+var profilePnlShape = {
+  keyPrefix: z.string().describe("The profile's API key prefix")
+};
+var profileTradesShape = {
+  keyPrefix: z.string().describe("The profile's API key prefix"),
+  limit: z.number().optional().describe("How many of the most recent trades to return. Default 200, max 1000.")
+};
+var setProfileWalletsShape = {
+  keyPrefix: z.string().describe("The profile's API key prefix"),
+  walletIds: z.array(z.string()).describe("The linked-wallet ids the profile may spend from -- ids, not addresses. This REPLACES the " + "whole set: any wallet omitted loses access. An empty array assigns none.")
+};
 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`"),
@@ -688,7 +750,7 @@ var tradeShape = {
   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."),
+  quoteAsset: z.string().optional().describe('What the wallet spends on a buy or receives on a sell: "sol", "usdc" or "cndl" on Solana, ' + '"eth" or "usdg" on Hood. Safe to pass through from candle_quote. On Solana it applies only ' + "to an arbitrary mint Candle never launched (Pro/Max) and is ignored for a Candle token, " + "whose quote comes from the token itself. On Hood it is the settlement asset of a DEX " + "trade; a USDG buy adds an approval transaction an ETH buy does not. It is not the route: " + "the cheapest path to the asset is chosen separately. Defaults to sol / ETH settlement."),
   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.")
 };
@@ -726,17 +788,25 @@ function registerTools(server, env = process.env) {
   }, 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.",
+    description: "Read the current market state for a token: lifecycle, pool address, whether buys are " + `open. Reads only; moves nothing. No key needed.
+
+` + "COVERAGE: this answers for tokens that have a CANDLE market. candle_get_feed indexes " + "the wider market too (pump.fun, pons.family), so a mint that feed just returned can " + "still come back MARKET_NOT_FOUND here. That is a coverage boundary, not a fault and " + "not a reason to retry or re-authenticate -- say Candle has no market for it and move on.",
     inputSchema: getMarketShape
   }, async (args) => callAndRelay("candle_get_market", args, cfg));
   register("candle_token_forensics", {
     title: "Token forensics",
-    description: "Gate a buy before making it: deployer history, who bought in the deploy window (the creator's own wallets are marked disclosed; strangers in the same slot are the bundle signal), holder concentration, and a risk tier (LOW/MODERATE/HIGH/CRITICAL) with per-factor reasons. Every measurement carries a coverage note -- 'unavailable' is not 'clean'. No key needed.",
+    description: `Gate a buy before making it: deployer history, who bought in the deploy window (the creator's own wallets are marked disclosed; strangers in the same slot are the bundle signal), holder concentration, and a risk tier (LOW/MODERATE/HIGH/CRITICAL) with per-factor reasons. Every measurement carries a coverage note -- 'unavailable' is not 'clean'. No key needed.
+
+MARKET_NOT_FOUND means Candle has no market for that token and this could not run. That is also not 'clean': report that you could not check it, rather than reporting the token as safe. That refusal now carries error.coverage -- covered:false, a reason ('external_launchpad' when the token launched somewhere else, 'unknown_mint' when nobody has indexed it), the launchpad when known, and every check that consequently did not run. Read it instead of guessing. Most of the feed answers this way.`,
     inputSchema: tokenForensicsShape
   }, async (args) => callAndRelay("candle_token_forensics", 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.",
+    description: "Read one of the trade page's public feeds: new, graduated, onfire, or bluechip. Reads " + `only; moves nothing. No key needed. Start here when nobody has named a token.
+
+` + "This indexes the WIDER market, not just Candle's own launches, so rows carry a " + "`launchpad` (pump.fun, pons.family, ...). A row appearing here does NOT mean Candle " + "has a market for it: candle_get_market and candle_token_forensics can legitimately " + `answer MARKET_NOT_FOUND for a mint this returned.
+
+` + "Filter, sort and pick fields SERVER-SIDE rather than reading the whole feed: an " + "unfiltered response is around 135KB and will not fit in a tool result. See `where`, " + "`sort` and `fields`.\n\n" + "One rule to know before screening on safety: a missing field is NOT a false one. " + "mintAuthorityDisabled and freezeAuthorityDisabled are absent on a real share of rows, " + "and absent means nobody checked, not that the authority is disabled. `where` never lets " + 'an absent field satisfy a comparison, so {"mintAuthorityDisabled":{"eq":true}} returns ' + "only tokens that actually say so.",
     inputSchema: getFeedShape
   }, async (args) => callAndRelay("candle_get_feed", args, cfg));
   register("candle_report_activity", {
@@ -767,6 +837,26 @@ function registerTools(server, env = process.env) {
     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_get_profile_wallets", {
+    title: "Read which wallets an agent profile can spend from",
+    description: "An agent profile (API key) either spends from EVERY wallet on its account or only from " + "the ones assigned to it. Read walletScope before drawing any conclusion from the list: " + "an empty list means 'every wallet' under scope 'all' and 'none at all' under 'selected'. " + "Reads only; moves nothing.",
+    inputSchema: profileWalletsShape
+  }, async (args) => callAndRelay("candle_get_profile_wallets", args, cfg));
+  register("candle_set_profile_wallets", {
+    title: "Set which wallets an agent profile can spend from",
+    description: "REPLACES the profile's whole wallet set with the ids given, so a wallet left out of the " + "list loses access; pass an empty list to leave the profile with no wallets. NARROWING " + "ONLY: an API key can remove wallets from its OWN profile, but naming one it does not " + "already hold is a grant and needs a human in the dashboard, as does editing any other " + "profile. Takes effect only while the profile's scope is 'selected'. Wallet ids are the " + "linked-wallet ids, not addresses.",
+    inputSchema: setProfileWalletsShape
+  }, async (args) => callAndRelay("candle_set_profile_wallets", args, cfg));
+  register("candle_get_profile_pnl", {
+    title: "Read an agent profile's realized P&L",
+    description: "Realized profit for this profile's own fills, the Candle fees charged against it, and the " + "positions it still holds with their COST BASIS -- not their current value, which is not marked " + "here. Deposits, withdrawals and transfers are excluded: funding a wallet is not profit. Check " + "`unvalued` and `truncated` before quoting the number; they mean the total is partial. Reads only.",
+    inputSchema: profilePnlShape
+  }, async (args) => callAndRelay("candle_get_profile_pnl", args, cfg));
+  register("candle_get_profile_trades", {
+    title: "Read an agent profile's trade history",
+    description: "Orders, actual fills, fees, timestamps and transaction hashes for this profile. Includes FAILED " + "trades, with an errorCode saying why each did not go through, so this answers 'what happened to " + "my order' as well as 'what did I trade'. Reads only; moves nothing.",
+    inputSchema: profileTradesShape
+  }, async (args) => callAndRelay("candle_get_profile_trades", args, 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.",
@@ -812,7 +902,18 @@ function registerTools(server, env = process.env) {
   });
   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.",
+    description: "Buy or sell a token. MOVES REAL FUNDS: the payer is the account's embedded (main) " + `wallet, executed server-side via delegation.
+
+` + `Before the first trade of a run, once:
+` + "1. candle_execution_status  -- confirms the wallets, the tier and this key's spend " + "limits. Call it at the start, or after an auth error; do not infer readiness from a " + `failed trade.
+` + "2. candle_resolve_token  -- if a human handed you a bare address. It returns the chain, " + `so you never have to guess it.
+` + "3. candle_token_forensics  -- before you quote or buy anything. It returns a risk tier " + "and per-factor reasons. MARKET_NOT_FOUND there means Candle has no market for the " + `token, NOT that the token is clean.
+
+` + "Arguments: `mint` and `side` are required. Amounts are DECIMAL, never raw base units " + '(amount: "0.5", not lamports). Omitting the amount on a sell sells the whole ' + `position.
+
+` + `After the call:
+` + "- A timeout is not a failure. Retry with the SAME clientTradeId from the result -- it " + `coalesces the duplicate. A NEW id is a SECOND trade, and that is how you double-spend.
+` + "- If you no longer hold the result, do not re-send to find out what happened. Ask " + "candle_get_operation with the clientTradeId; a 404 there means the trade never reached " + "the rail and nothing moved.",
     inputSchema: tradeShape
   }, async (args) => {
     const result = await executeTrade(args, cfg, fetch);
@@ -829,8 +930,36 @@ function registerTools(server, env = process.env) {
 }
 
 // src/server.ts
+var INSTRUCTIONS = `Candle is a trading and token-launch rail for agents. You hold a scoped API key, never a private key; signing and funding stay with the key owner's wallet.
+
+START HERE — five tools need NO credential. Call these first to confirm the server is wired before asking anyone for anything:
+  candle_get_market       price, market cap, volume, curve state for one token
+  candle_get_feed         the roster: hot streak, new pairs, graduated, blue chip
+  candle_resolve_token    a ticker or partial name -> mint address + chain
+  candle_token_forensics  call this before quoting or buying, whenever the token has a Candle market. Returns deployer history, who bought in the deploy window (strangers in the same slot are the bundle signal), holder concentration, and a risk tier LOW/MODERATE/HIGH/CRITICAL with per-factor reasons
+  candle_get_agent_profile  your own tier, caps and verified activity
+
+COVERAGE — read this before you treat an error as a broken server.
+candle_get_feed indexes the wider market (pump.fun, pons.family and other external launchpads).
+candle_get_market and candle_token_forensics answer for tokens that have a CANDLE market. So a
+mint that candle_get_feed just returned can still come back MARKET_NOT_FOUND from those two, and
+that is a coverage boundary, not a fault and not a reason to retry, re-auth, or tell the human the
+integration is down. Report it as "Candle has no market for this token, so I could not run
+forensics on it" and let the human decide.
+
+Never let a MARKET_NOT_FOUND stand in for a clean bill of health. The same rule governs the
+coverage note on every forensics measurement: "unavailable" is NOT "clean" — say so rather than
+reporting a token as safe.
+
+WRITING (trade, launch, transfer, sweep, swap) needs a key. If a call returns an auth error, the fix is on the human's side: they run \`candle auth login\`, which authorizes a device in the browser and stores the credentials. Do not ask them to paste a key into a config file, and do not retry the call until they confirm.
+
+Two chains: solana and hood. Most tools take an explicit chain — resolve it with candle_resolve_token rather than guessing.
+
+Writes are idempotent by client token and may be asynchronous: poll candle_execution_status or candle_get_operation rather than re-issuing a call. Re-issuing is how you double-spend.
+
+Full reference, error catalogue and end-to-end recipes: https://docs.candle.tv — and AGENTS.md in github.com/candledottv/agentic.`;
 function createCandleMcpServer(env = process.env) {
-  const server = new McpServer({ name: "candle-mcp", version: SERVER_VERSION });
+  const server = new McpServer({ name: "candle-mcp", version: SERVER_VERSION }, { instructions: INSTRUCTIONS });
   registerTools(server, env);
   return server;
 }

package/package.json

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