@candledottv/mcp 0.3.0 → 0.5.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
-ten tools over stdio, so an MCP-capable agent can launch tokens (optionally seeded with a dev
+eleven 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.
@@ -9,7 +9,8 @@ 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
+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:
 
 ```json
@@ -24,8 +25,10 @@ server with no `env` block at all and those three work immediately:
 ```
 
 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.
+Environment below -- or skip env editing entirely: install the Candle CLI
+(`curl -fsSL https://candle.tv/install.sh | bash` or `brew install candledottv/tap/candle`), run
+`candle auth login`, and `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
@@ -58,7 +61,12 @@ tools, getting a key, funding the embedded wallet, and idempotent retries, see
 ## 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.
+  `http://localhost:3001` when developing against a local API. A cleartext `http://` URL pointing
+  at a NON-loopback host is refused at startup, since every write tool sends `x-api-key`; loopback
+  (`localhost`, `127.0.0.0/8`, `::1`) needs no opt-in.
+- `CANDLE_ALLOW_INSECURE_HTTP` -- set to any non-empty value to allow an `http://` API URL to a
+  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
@@ -77,6 +85,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`) | `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, holder concentration, risk tier | `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 |
 | `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`) |
@@ -100,7 +109,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
-ten tools:
+eleven 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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-// src/index.ts
+// src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
@@ -9,9 +9,36 @@ 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();
+function isLoopbackHost(hostname) {
+  const host = hostname.toLowerCase();
+  if (host === "localhost" || host.endsWith(".localhost"))
+    return true;
+  if (host === "::1" || host === "[::1]")
+    return true;
+  return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+}
+function assertTransportSecurity(apiUrl, env) {
+  let parsed;
+  try {
+    parsed = new URL(apiUrl);
+  } catch {
+    throw new Error(`CANDLE_API_URL is not a valid URL: ${JSON.stringify(apiUrl)}`);
+  }
+  if (parsed.protocol === "https:")
+    return;
+  if (parsed.protocol !== "http:") {
+    throw new Error(`CANDLE_API_URL must be http or https, got ${parsed.protocol.replace(":", "")}`);
+  }
+  if (isLoopbackHost(parsed.hostname))
+    return;
+  if (env.CANDLE_ALLOW_INSECURE_HTTP?.trim())
+    return;
+  throw new Error(`Refusing to send credentials in the clear to ${parsed.origin}. Set CANDLE_API_URL to an https:// ` + "URL, or set CANDLE_ALLOW_INSECURE_HTTP=1 if this really is a trusted local endpoint.");
+}
+function resolveConfig(env = process.env) {
+  const apiUrl = env.CANDLE_API_URL?.trim() || DEFAULT_API_URL;
+  assertTransportSecurity(apiUrl, env);
+  const apiKey = env.CANDLE_AGENT_API_KEY?.trim() || env.CANDLE_API_KEY?.trim();
   return apiKey ? { apiUrl, apiKey } : { apiUrl };
 }
 
@@ -135,7 +162,7 @@ async function postJson(url, apiKey, payload, doFetch) {
   }
 }
 async function readMarket(mint, cfg, doFetch, extra) {
-  const res = await doFetch(`${base(cfg)}/api/v1/markets/${chainForMint(mint)}/${mint}`, {
+  const res = await doFetch(`${base(cfg)}/api/v1/markets/${chainForMint(mint)}/${encodeURIComponent(mint)}`, {
     method: "GET",
     headers: headers()
   });
@@ -210,7 +237,7 @@ async function executeTrade(args, cfg, doFetch) {
       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}`, {
+      const balRes = await doFetch(`${base(cfg)}/api/v1/tokens/${encodeURIComponent(args.mint)}/balance/${encodeURIComponent(address)}`, {
         method: "GET",
         headers: headers()
       });
@@ -274,7 +301,9 @@ async function executeLaunchAndSeed(args, cfg, doFetch) {
   let market = null;
   let note;
   try {
-    const marketRes = await doFetch(`${base(cfg)}/api/v1/markets/${launch.chain ?? "solana"}/${launch.mint}`, {
+    if (launch.mint === undefined)
+      throw new Error("the launch response carried no mint");
+    const marketRes = await doFetch(`${base(cfg)}/api/v1/markets/${encodeURIComponent(launch.chain ?? "solana")}/${encodeURIComponent(launch.mint)}`, {
       method: "GET",
       headers: headers()
     });
@@ -362,6 +391,7 @@ var TOOL_NAMES = [
   "candle_launch_token",
   "candle_get_market",
   "candle_get_feed",
+  "candle_token_forensics",
   "candle_report_activity",
   "candle_get_agent_profile",
   "candle_trade",
@@ -407,7 +437,17 @@ function buildRequest(name, args, cfg) {
     }
     case "candle_get_market": {
       const { chain, mint } = args;
-      return { url: `${base2}/api/v1/markets/${chain}/${mint}`, init: { method: "GET", headers: jsonHeaders() } };
+      return {
+        url: `${base2}/api/v1/markets/${encodeURIComponent(chain)}/${encodeURIComponent(mint)}`,
+        init: { method: "GET", headers: jsonHeaders() }
+      };
+    }
+    case "candle_token_forensics": {
+      const { chain, mint } = args;
+      return {
+        url: `${base2}/api/v1/markets/${encodeURIComponent(chain)}/${encodeURIComponent(mint)}/forensics`,
+        init: { method: "GET", headers: jsonHeaders() }
+      };
     }
     case "candle_get_feed": {
       const { bucket, chain } = args;
@@ -426,7 +466,10 @@ function buildRequest(name, args, cfg) {
     }
     case "candle_get_agent_profile": {
       const { idOrWallet } = args;
-      return { url: `${base2}/api/v1/users/${idOrWallet}/agent`, init: { method: "GET", headers: jsonHeaders() } };
+      return {
+        url: `${base2}/api/v1/users/${encodeURIComponent(idOrWallet)}/agent`,
+        init: { method: "GET", headers: jsonHeaders() }
+      };
     }
     case "candle_swap": {
       const apiKey = requireApiKey2(cfg);
@@ -474,6 +517,10 @@ var getMarketShape = {
   chain: z.string().describe('"solana" or "hood"'),
   mint: z.string().describe("Token mint (solana) or contract address (hood)")
 };
+var tokenForensicsShape = {
+  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")
@@ -521,7 +568,7 @@ var sweepShape = {
   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 cfg = resolveConfig(env);
   const allowed = resolveToolAllowlist(env);
   const register = (name, ...rest) => {
     if (!allowed.has(name))
@@ -538,6 +585,11 @@ function registerTools(server, env = process.env) {
     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_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.",
+    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.",
@@ -590,10 +642,25 @@ function registerTools(server, env = process.env) {
 }
 
 // src/version.ts
-var SERVER_VERSION = "0.3.0";
+var SERVER_VERSION = "0.5.0";
+
+// src/server.ts
+function createCandleMcpServer(env = process.env) {
+  const server = new McpServer({ name: "candle-mcp", version: SERVER_VERSION });
+  registerTools(server, env);
+  return server;
+}
+async function runStdioServer(env = process.env, transport = new StdioServerTransport) {
+  const server = createCandleMcpServer(env);
+  await server.connect(transport);
+  await new Promise((resolve) => {
+    const sdkOnClose = transport.onclose;
+    transport.onclose = () => {
+      sdkOnClose?.();
+      resolve();
+    };
+  });
+}
 
 // src/index.ts
-var server = new McpServer({ name: "candle-mcp", version: SERVER_VERSION });
-registerTools(server);
-var transport = new StdioServerTransport;
-await server.connect(transport);
+await runStdioServer();

package/package.json

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