@candledottv/mcp 0.10.14 → 0.10.16

package/README.md

@@ -1,7 +1,7 @@
 # @candledottv/mcp
 
 An MCP (Model Context Protocol) server for the Candle agent rail. The current source exposes Candle's REST API as
-forty-one tools over stdio, so an MCP-capable agent can launch tokens (optionally seeded with a dev
+forty-two 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 forty-one. An unknown name fails startup with the valid names in the message, rather
+Unset means all forty-two. 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.
 
@@ -55,6 +55,12 @@ Both take decimal amounts, never raw base units, and resolve the scale themselve
   there the caller genuinely picks the new token's quote pair: `quoteAsset` if given, otherwise
   SOL on Solana and ETH on Hood.
 
+Both launch tools also take `mode: "exp-custom"` with `curve: { virtualQuote, threshold }`: a
+Solana curve with your own V and G, in whole SOL or CNDL as decimal strings, inside limits the
+API enforces and each tool's description states. Dry-run first: the dry run returns the curve's
+terms. It works only where the deployment has switched it on. See
+[Custom curves](https://docs.candle.tv/developers/headless-launch#custom-curves-choose-v-and-g-switched-off).
+
 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
 [Candle MCP server](https://docs.candle.tv/developers/mcp-server).
@@ -95,6 +101,7 @@ tools, getting a key, funding the embedded wallet, and idempotent retries, see
 | `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_vamp_candidates` | Tickers being copied near graduation: Solana tokens near graduation or graduated in the last 6 hours, most-copied in the last 24 hours first, each with a launch draft (name, ticker, image URL) and `draftNotes` for the fields you must supply. Counts exclude the candidate itself. Answers 404 where the deployment has not switched it on | `GET /api/v1/markets/vamp-candidates?limit=...&minCopies24h=...&stage=...` | `CANDLE_AGENT_API_KEY` (`account:read`) |
 | `candle_token_forensics` | Deployer history, deploy-window buyers, sourced token safety flags | `GET /api/v1/markets/:chain/:mint/forensics` | 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 |
@@ -178,7 +185,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
-forty-one tools:
+forty-two 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

@@ -112,7 +112,7 @@ import { lstat, open, realpath } from "node:fs/promises";
 import { dirname, isAbsolute, relative, sep } from "node:path";
 
 // src/version.ts
-var SERVER_VERSION = "0.10.14";
+var SERVER_VERSION = "0.10.16";
 
 // src/update-notice.ts
 var PLAIN_VERSION = /^\d+\.\d+\.\d+$/;
@@ -1652,6 +1652,8 @@ function planTableMarkdown(table) {
 }
 
 // src/tools.ts
+var VAMP_CANDIDATES_DESCRIPTION = "Lists Solana tokens that are close to graduating or graduated in the last 6 hours whose ticker other tokens " + "are copying, most-copied in the last 24 hours first. Each entry carries a launch draft (name, ticker, image URL) " + "for `candle_launch_token` or `candle_launch_and_seed`; draft notes identify fields you must supply or adjust. " + "Upload your own image through the agent image upload when the image is unavailable. Use `dryRun: true` first. " + "Counts exclude the candidate itself and cover both Solana and Hood launches at the venues returned in " + "`coverage`, not Candle's own. `coverage.since` is the returned Solana coverage date; Hood history may differ.";
+var CUSTOM_CURVE_RULE = 'mode "exp-custom" with curve { virtualQuote, threshold } launches a Solana curve with your own V (the virtual ' + "quote it starts with) and G (the quote it raises before graduating), in whole SOL or CNDL as decimal strings, " + "accepted when V is 1 to 100 SOL and G 1 to 250 SOL (66,000 to 6,600,000 and 66,000 to 16,500,000 CNDL), when " + "every price up to 20 x G stays under the ceiling (V + 20G)^2 < V x X at this stakerAllocationBps, when neither " + "is finer than the quote's decimals, and when the dev buy is at most 10% of G; a curve past a limit is " + "CURVE_OUT_OF_RANGE, and at the ceiling it carries maxThresholdRaw, the largest G that fits. " + "Dry-run it first (dryRun: true): the dry run spends nothing and returns curveTerms, the market cap at start and " + "at graduation and the supply sold by graduation. Only where the API has EXP_CURVES and EXP_CUSTOM_CURVES on; " + "elsewhere exp-custom is refused as an unknown mode.";
 var localProfileTools = new WeakMap;
 var STAKING_DISCLOSURE = "No instant unstake. Read pool.withdrawalTimelockSeconds for the wait. Solana rewards accrue to the holding wallet. Outside the account's main wallet, sCNDL earns no Hood staking rewards; Pro eligibility follows the deployment's tier mode (main-wallet mode excludes it). CNDL in a pending withdrawal counts toward nothing for Pro.";
 var stakingWriteShape = {
@@ -1664,6 +1666,7 @@ var TOOL_NAMES = [
   "candle_launch_token",
   "candle_get_market",
   "candle_get_feed",
+  "candle_vamp_candidates",
   "candle_token_forensics",
   "candle_report_activity",
   "candle_get_agent_profile",
@@ -1792,6 +1795,21 @@ function buildRequest(name, args, cfg) {
         init: { method: "GET", headers: jsonHeaders() }
       };
     }
+    case "candle_vamp_candidates": {
+      const apiKey = requireApiKey2(cfg);
+      const { limit, minCopies24h, stage } = args;
+      const params = new URLSearchParams;
+      if (limit !== undefined)
+        params.set("limit", String(limit));
+      if (minCopies24h !== undefined)
+        params.set("minCopies24h", String(minCopies24h));
+      if (stage !== undefined)
+        params.set("stage", stage);
+      return {
+        url: `${base2}/api/v1/markets/vamp-candidates${params.size ? `?${params}` : ""}`,
+        init: { method: "GET", headers: jsonHeaders(apiKey) }
+      };
+    }
     case "candle_report_activity": {
       const apiKey = requireApiKey2(cfg);
       return {
@@ -2055,7 +2073,11 @@ var launchTokenShape = {
   bannerUrl: z2.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: z2.string().optional().describe('"solana" or "hood"; defaults to solana'),
   quoteAsset: z2.string().optional().describe("Quote asset symbol; defaults per chain"),
-  mode: z2.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"),
+  mode: z2.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. " + '"exp-custom" launches a Solana curve with your own V and G, given in curve, where the API has it ' + "switched on"),
+  curve: z2.object({
+    virtualQuote: z2.string().describe('V: the virtual quote the curve starts with, in whole quote units, e.g. "12" SOL'),
+    threshold: z2.string().describe('G: the quote the curve raises before it graduates, in whole quote units, e.g. "40" SOL')
+  }).strict().optional().describe('mode "exp-custom" only, and required there. Decimal strings in whole units of the quote asset (sol or ' + "cndl), never raw units. Dry-run first: the API checks the limits and returns the curve's terms"),
   stakerAllocationBps: z2.number().optional().describe("Staker allocation in basis points"),
   dexVersion: z2.string().nullable().optional().describe('"v3" or "v4"; required for hood launches'),
   buyAmount: z2.union([z2.string(), z2.number()]).optional().describe("Initial buy, in quote base units (string or number)"),
@@ -2122,6 +2144,11 @@ 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 vampCandidatesShape = {
+  limit: z2.number().optional().describe("Entries to return, 1 to 50 (default 20)"),
+  minCopies24h: z2.number().optional().describe("Only tokens whose ticker was copied at least this many times in the last 24 hours (default 1)"),
+  stage: z2.enum(["final_stretch", "graduated", "all"]).optional().describe("final_stretch: still on the bonding curve; graduated: graduated in the last 6 hours; all (default)")
+};
 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")
@@ -2221,7 +2248,7 @@ function registerToolSubset(server, options) {
   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." + (imageDir ? IMAGE_PATH_DISCLOSURE : ""),
+    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. " + CUSTOM_CURVE_RULE + (imageDir ? IMAGE_PATH_DISCLOSURE : ""),
     inputSchema: imageDir ? localLaunchTokenShape : launchTokenShape
   }, async (args) => {
     const image = await resolveLaunchImage(args, imageDir, getConfig(), doFetch);
@@ -2257,6 +2284,11 @@ MARKET_NOT_FOUND means Candle has no market for that token and this could not ru
 ` + "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, getConfig(), doFetch));
+  register("candle_vamp_candidates", {
+    title: "Tickers being copied near graduation",
+    description: VAMP_CANDIDATES_DESCRIPTION,
+    inputSchema: vampCandidatesShape
+  }, async (args) => callAndRelay("candle_vamp_candidates", args, getConfig(), doFetch));
   register("candle_report_activity", {
     title: "Report on-chain activity",
     description: "Report a client-executed transaction (transfer, swap, stake) so Candle records and verifies it.",
@@ -2467,7 +2499,7 @@ 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." + (imageDir ? IMAGE_PATH_DISCLOSURE : ""),
+    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. " + CUSTOM_CURVE_RULE + (imageDir ? IMAGE_PATH_DISCLOSURE : ""),
     inputSchema: imageDir ? localLaunchAndSeedShape : launchAndSeedShape
   }, async (args) => {
     const result = await executeLaunchAndSeed(args, getConfig(), doFetch, imageDir);
@@ -2592,6 +2624,8 @@ Never let a MARKET_NOT_FOUND stand in for a clean bill of health. The same rule
 coverage note on every forensics measurement: "unavailable" is NOT "clean" — say so rather than
 reporting a token as safe.
 
+LAUNCHING A COPY: candle_vamp_candidates (a key with account:read) lists Solana tickers being copied near graduation, each with a launch draft for candle_launch_token or candle_launch_and_seed. Supply any draft field that is null (draftNotes says why), and launch with dryRun: true first. Where the deployment has not switched it on it answers 404.
+
 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.

package/package.json

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