riskmodels 2.0.0

package/dist/commands/health.js

@@ -0,0 +1,60 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { loadConfig } from "../lib/config.js";
+import { apiRootFromUserBase } from "../lib/api-url.js";
+import { ApiHttpError, apiFetchOptionalAuth } from "../lib/api-client.js";
+import { printResults } from "../lib/display.js";
+/** Production health can exceed 15s when Supabase is cold; Vercel rollouts may return 502–504. */
+const HEALTH_TIMEOUT_MS = 120_000;
+const HEALTH_MAX_ATTEMPTS = 6;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isTransientHealthFailure(err) {
+    if (err instanceof ApiHttpError) {
+        return [502, 503, 504].includes(err.status);
+    }
+    if (err instanceof Error) {
+        if (err.name === "AbortError" || err.name === "TimeoutError")
+            return true;
+        const m = err.message.toLowerCase();
+        if (m.includes("fetch failed"))
+            return true;
+        if (m.includes("econnreset") || m.includes("etimedout"))
+            return true;
+    }
+    return false;
+}
+export function healthCommand() {
+    return new Command("health")
+        .description("Service health check (GET /api/health, no auth). Retries transient 5xx and network errors.")
+        .action(async (_opts, cmd) => {
+        const json = cmd.optsWithGlobals().json ?? false;
+        const cfg = await loadConfig();
+        const apiRoot = apiRootFromUserBase(cfg?.apiBaseUrl);
+        for (let attempt = 1; attempt <= HEALTH_MAX_ATTEMPTS; attempt += 1) {
+            try {
+                const { body } = await apiFetchOptionalAuth(apiRoot, "GET", "/health", {
+                    signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS),
+                });
+                printResults(body, json);
+                return;
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                const retry = isTransientHealthFailure(e) && attempt < HEALTH_MAX_ATTEMPTS;
+                if (retry) {
+                    const waitSec = 15 * attempt;
+                    if (!json) {
+                        console.error(chalk.yellow(`Health check attempt ${attempt}/${HEALTH_MAX_ATTEMPTS} failed (${msg}); retrying in ${waitSec}s…`));
+                    }
+                    await sleep(waitSec * 1000);
+                    continue;
+                }
+                console.error(chalk.red(msg));
+                process.exitCode = 1;
+                return;
+            }
+        }
+    });
+}

package/dist/commands/install.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function installCommand(): Command;

package/dist/commands/install.js

@@ -0,0 +1,136 @@
+import { Command } from "commander";
+import inquirer from "inquirer";
+import chalk from "chalk";
+import { configPath, DEFAULT_API_BASE, loadConfig } from "../lib/config.js";
+import { detectClients, selectedClients } from "../lib/mcp-config-paths.js";
+import { buildInstallPlans, firstPrompt } from "../lib/mcp-install-plan.js";
+import { printResults } from "../lib/display.js";
+import { redactSecret } from "../lib/redact.js";
+import { installMcpConfig, writeSharedApiKey } from "../lib/mcp-config-writer.js";
+import { apiRootFromUserBase } from "../lib/api-url.js";
+import { apiFetchOptionalAuth } from "../lib/api-client.js";
+function envApiKey() {
+    return process.env.RISKMODELS_API_KEY?.trim() || undefined;
+}
+async function connectionTest(apiBaseUrl) {
+    const apiRoot = apiRootFromUserBase(apiBaseUrl);
+    const endpoint = `${apiRoot.replace(/\/$/, "")}/health`;
+    try {
+        await apiFetchOptionalAuth(apiRoot, "GET", "/health", {
+            signal: AbortSignal.timeout(15_000),
+        });
+        return { ok: true, endpoint, message: "RiskModels API health check passed." };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            endpoint,
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function resolveApiKey(opts) {
+    if (opts.apiKey?.trim())
+        return { apiKey: opts.apiKey.trim(), source: "--api-key" };
+    const envKey = envApiKey();
+    if (envKey)
+        return { apiKey: envKey, source: "RISKMODELS_API_KEY" };
+    const cfg = await loadConfig();
+    if (cfg?.apiKey?.trim())
+        return { apiKey: cfg.apiKey.trim(), source: configPath() };
+    if (opts.yes)
+        return { source: "missing" };
+    console.error(chalk.yellow("No RiskModels API key found."));
+    console.error(chalk.dim("Get a key: https://riskmodels.app/get-api-key"));
+    const answer = await inquirer.prompt([
+        {
+            type: "password",
+            name: "apiKey",
+            message: "RiskModels API key",
+            mask: "*",
+            validate: (value) => (value.trim() ? true : "API key is required"),
+        },
+    ]);
+    return { apiKey: answer.apiKey.trim(), source: "prompt" };
+}
+export function installCommand() {
+    return new Command("install")
+        .description("Detect AI clients and install/register the RiskModels MCP server")
+        .option("--client <name>", "claude | cursor | codex | vscode")
+        .option("--all", "Target all detected clients")
+        .option("--api-key <key>", "RiskModels API key for one-shot setup")
+        .option("--dry-run", "Show planned config changes without writing")
+        .option("--yes", "Non-interactive mode")
+        .option("--embed-key", "Explicitly embed the API key in MCP config env (not recommended)")
+        .option("--json", "JSON output")
+        .action(async (opts, cmd) => {
+        const json = opts.json || cmd.optsWithGlobals().json || false;
+        let clients;
+        try {
+            clients = selectedClients({ client: opts.client, all: opts.all });
+        }
+        catch (error) {
+            console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+            process.exitCode = 1;
+            return;
+        }
+        const dryRun = opts.dryRun ?? false;
+        const { apiKey, source } = await resolveApiKey(opts);
+        const detections = await detectClients(clients);
+        const plans = buildInstallPlans(detections, { apiKey, embedKey: opts.embedKey });
+        const existingConfig = await loadConfig();
+        const output = {
+            dryRun,
+            apiKey: {
+                found: !!apiKey,
+                source,
+                value: redactSecret(apiKey),
+                storage: configPath(),
+                willStoreInSharedConfig: !!apiKey && source !== configPath() && !dryRun,
+                embeddedInMcpConfig: !!opts.embedKey,
+            },
+            clients: plans,
+            firstPrompt: firstPrompt(),
+            nextStep: dryRun
+                ? "Review this plan, then rerun without --dry-run to write configs with backups."
+                : "Install complete. Restart your MCP client, then try the first prompt.",
+        };
+        if (dryRun) {
+            printResults(output, json);
+            if (!json) {
+                console.error(chalk.green(`First prompt to try: "${firstPrompt()}"`));
+            }
+            return;
+        }
+        if (!apiKey) {
+            printResults({
+                ...output,
+                error: "No RiskModels API key found. Get one at https://riskmodels.app/get-api-key or pass --api-key.",
+            }, json);
+            process.exitCode = 1;
+            return;
+        }
+        const sharedConfigWrite = await writeSharedApiKey(apiKey, existingConfig?.apiBaseUrl ?? DEFAULT_API_BASE);
+        const writes = await Promise.all(detections.map((detection) => installMcpConfig(detection, {
+            apiKey,
+            embedKey: opts.embedKey,
+            apiBaseUrl: existingConfig?.apiBaseUrl,
+        })));
+        const test = await connectionTest(existingConfig?.apiBaseUrl);
+        const result = {
+            ...output,
+            sharedConfigWrite,
+            writes,
+            connectionTest: test,
+        };
+        printResults(result, json);
+        if (writes.some((write) => write.action === "error") || !test.ok) {
+            process.exitCode = 1;
+            return;
+        }
+        if (!json) {
+            console.error(chalk.green("RiskModels MCP install completed with backups."));
+            console.error(chalk.green(`First prompt to try: "${firstPrompt()}"`));
+        }
+    });
+}

package/dist/commands/l3.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function l3Command(): Command;

package/dist/commands/l3.js

@@ -0,0 +1,33 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { loadConfig } from "../lib/config.js";
+import { requireResolvedAuth } from "../lib/credentials.js";
+import { apiFetchJson } from "../lib/api-client.js";
+import { printResults } from "../lib/display.js";
+export function l3Command() {
+    return new Command("l3")
+        .description("L3 factor decomposition time series (GET /l3-decomposition)")
+        .argument("<ticker>", "Symbol")
+        .option("--market-factor-etf <sym>", "Market factor ETF (default SPY)", "SPY")
+        .action(async (ticker, opts, cmd) => {
+        const json = cmd.optsWithGlobals().json ?? false;
+        const cfg = await loadConfig();
+        const auth = requireResolvedAuth(cfg, chalk.yellow);
+        if (!auth)
+            return;
+        const query = {
+            ticker: ticker.trim(),
+            market_factor_etf: opts.marketFactorEtf ?? "SPY",
+        };
+        try {
+            const { body, costUsd } = await apiFetchJson(auth, "GET", "/l3-decomposition", { query });
+            printResults(body, json);
+            if (!json && costUsd)
+                console.log(chalk.dim(`Cost: $${costUsd}`));
+        }
+        catch (e) {
+            console.error(chalk.red(e instanceof Error ? e.message : String(e)));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/macro-factors.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function macroFactorsCommand(): Command;

package/dist/commands/macro-factors.js

@@ -0,0 +1,39 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { loadConfig } from "../lib/config.js";
+import { requireResolvedAuth } from "../lib/credentials.js";
+import { apiFetchJson } from "../lib/api-client.js";
+import { printResults } from "../lib/display.js";
+export function macroFactorsCommand() {
+    return new Command("macro-factors")
+        .description("Daily macro factor returns from macro_factors (GET /macro-factors, no ticker)")
+        .option("--factors <list>", "Comma-separated factor keys (default: all six)")
+        .option("--start <date>", "Inclusive YYYY-MM-DD")
+        .option("--end <date>", "Inclusive YYYY-MM-DD")
+        .action(async (opts, cmd) => {
+        const json = cmd.optsWithGlobals().json ?? false;
+        const cfg = await loadConfig();
+        const auth = requireResolvedAuth(cfg, chalk.yellow);
+        if (!auth)
+            return;
+        const query = {};
+        if (opts.factors?.trim())
+            query.factors = opts.factors.trim();
+        if (opts.start?.trim())
+            query.start = opts.start.trim();
+        if (opts.end?.trim())
+            query.end = opts.end.trim();
+        try {
+            const { body, costUsd } = await apiFetchJson(auth, "GET", "/macro-factors", {
+                query,
+            });
+            printResults(body, json);
+            if (!json && costUsd)
+                console.log(chalk.dim(`Cost: $${costUsd}`));
+        }
+        catch (e) {
+            console.error(chalk.red(e instanceof Error ? e.message : String(e)));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/manifest.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function manifestCommand(): Command;

package/dist/commands/manifest.js

@@ -0,0 +1,270 @@
+import { Command } from "commander";
+import chalk from "chalk";
+/** Aligned with OpenAPI paths under /api (see OPENAPI_SPEC.yaml). */
+const TOOLS = [
+    {
+        name: "riskmodels_cli_query",
+        description: "Execute read-only SQL SELECT against RiskModels data (billed). POST /api/cli/query with Bearer token.",
+        method: "POST",
+        path: "/api/cli/query",
+        properties: {
+            sql: { type: "string", description: "SELECT query (single statement, no semicolons)" },
+            limit: { type: "integer", description: "Max rows if SQL omits LIMIT (1–10000)" },
+        },
+        required: ["sql"],
+    },
+    {
+        name: "riskmodels_get_metrics",
+        description: "Latest V3 hedge ratios, explained risk, volatility. GET /api/metrics/{ticker}",
+        method: "GET",
+        path: "/api/metrics/{ticker}",
+        properties: {
+            ticker: { type: "string", description: "Stock symbol, e.g. AAPL" },
+        },
+        required: ["ticker"],
+    },
+    {
+        name: "riskmodels_batch_analyze",
+        description: "Multi-ticker batch: returns, hedge_ratios, full_metrics, l3_decomposition. POST /api/batch/analyze",
+        method: "POST",
+        path: "/api/batch/analyze",
+        properties: {
+            tickers: {
+                type: "array",
+                description: "Up to 100 ticker strings",
+            },
+            metrics: {
+                type: "array",
+                description: "Whitelist: returns, l3_decomposition, hedge_ratios, full_metrics",
+            },
+            years: { type: "integer", description: "1–15 for returns / l3_decomposition" },
+            format: { type: "string", description: "json | parquet | csv", enum: ["json", "parquet", "csv"] },
+        },
+        required: ["tickers", "metrics"],
+    },
+    {
+        name: "riskmodels_portfolio_risk_index",
+        description: "Holdings-weighted L3 portfolio decomposition. POST /api/portfolio/risk-index",
+        method: "POST",
+        path: "/api/portfolio/risk-index",
+        properties: {
+            positions: {
+                type: "array",
+                description: "{ ticker, weight }[] — weights normalized server-side",
+            },
+            timeSeries: { type: "boolean", description: "Include daily portfolio ER time series" },
+            years: { type: "integer", description: "History when timeSeries is true" },
+        },
+        required: ["positions"],
+    },
+    {
+        name: "riskmodels_ticker_returns",
+        description: "Daily returns for a stock or ETF. Stocks include L1/L2/L3 hedge ratio + explained-risk columns; ETFs return date/returns_gross/price_close (L* columns are null). GET /api/ticker-returns",
+        method: "GET",
+        path: "/api/ticker-returns",
+        properties: {
+            ticker: { type: "string", description: "Stock or ETF symbol (e.g. NVDA, SPY)" },
+            years: { type: "integer", description: "Years of history (1–15)" },
+            format: { type: "string", description: "json | parquet | csv", enum: ["json", "parquet", "csv"] },
+        },
+        required: ["ticker"],
+    },
+    {
+        name: "riskmodels_l3_decomposition",
+        description: "L3 HR/ER time series. GET /api/l3-decomposition",
+        method: "GET",
+        path: "/api/l3-decomposition",
+        properties: {
+            ticker: { type: "string", description: "Stock symbol" },
+            market_factor_etf: { type: "string", description: "Default SPY" },
+        },
+        required: ["ticker"],
+    },
+    {
+        name: "riskmodels_factor_correlation",
+        description: "Macro factor correlation (batch or single). POST /api/correlation",
+        method: "POST",
+        path: "/api/correlation",
+        properties: {
+            ticker: { type: "string", description: "One ticker or use array in wire JSON for batch" },
+            factors: { type: "array", description: "Macro factor keys" },
+            return_type: {
+                type: "string",
+                description: "gross | l1 | l2 | l3_residual",
+                enum: ["gross", "l1", "l2", "l3_residual"],
+            },
+            window_days: { type: "integer", description: "20–2000" },
+            method: { type: "string", description: "pearson | spearman", enum: ["pearson", "spearman"] },
+        },
+        required: ["ticker"],
+    },
+    {
+        name: "riskmodels_factor_correlation_by_ticker",
+        description: "GET convenience for macro correlations. GET /api/metrics/{ticker}/correlation",
+        method: "GET",
+        path: "/api/metrics/{ticker}/correlation",
+        properties: {
+            ticker: { type: "string", description: "Stock symbol" },
+            factors: { type: "string", description: "Comma-separated factor keys" },
+        },
+        required: ["ticker"],
+    },
+    {
+        name: "riskmodels_macro_factor_series",
+        description: "Raw macro factor daily returns. GET /api/macro-factors",
+        method: "GET",
+        path: "/api/macro-factors",
+        properties: {
+            factors: { type: "string", description: "Comma-separated factor keys" },
+            start: { type: "string", description: "YYYY-MM-DD" },
+            end: { type: "string", description: "YYYY-MM-DD" },
+        },
+        required: [],
+    },
+    {
+        name: "riskmodels_rankings_snapshot",
+        description: "Cross-sectional ranks for one ticker. GET /api/rankings/{ticker}",
+        method: "GET",
+        path: "/api/rankings/{ticker}",
+        properties: {
+            ticker: { type: "string", description: "Stock symbol" },
+            metric: { type: "string", description: "Optional filter" },
+            cohort: { type: "string", description: "universe | sector | subsector" },
+            window: { type: "string", description: "1d | 21d | 63d | 252d" },
+        },
+        required: ["ticker"],
+    },
+    {
+        name: "riskmodels_rankings_top",
+        description: "Leaderboard. GET /api/rankings/top",
+        method: "GET",
+        path: "/api/rankings/top",
+        properties: {
+            metric: { type: "string", description: "Required" },
+            cohort: { type: "string", description: "universe | sector | subsector" },
+            window: { type: "string", description: "1d | 21d | 63d | 252d" },
+            limit: { type: "integer", description: "1–100" },
+        },
+        required: ["metric", "cohort", "window"],
+    },
+    {
+        name: "riskmodels_search_tickers",
+        description: "Universe search (no auth). GET /api/tickers",
+        method: "GET",
+        path: "/api/tickers",
+        properties: {
+            search: { type: "string", description: "Symbol or name" },
+            mag7: { type: "boolean", description: "MAG7 only" },
+            include_metadata: { type: "boolean", description: "Sector / ETF metadata" },
+        },
+        required: [],
+    },
+    {
+        name: "riskmodels_health",
+        description: "Service health (no auth). GET /api/health",
+        method: "GET",
+        path: "/api/health",
+        properties: {},
+        required: [],
+    },
+    {
+        name: "riskmodels_estimate",
+        description: "Pre-flight cost estimate. POST /api/estimate",
+        method: "POST",
+        path: "/api/estimate",
+        properties: {
+            endpoint: { type: "string", description: "Endpoint slug, e.g. ticker-returns" },
+            params: { type: "string", description: "JSON object string with same params as the target endpoint" },
+        },
+        required: ["endpoint"],
+    },
+];
+function inputSchema(tool) {
+    const properties = {};
+    for (const [key, spec] of Object.entries(tool.properties)) {
+        const base = {
+            description: spec.description,
+            ...(spec.enum ? { enum: spec.enum } : {}),
+        };
+        if (spec.type === "integer") {
+            base.type = "integer";
+        }
+        else if (spec.type === "array") {
+            base.type = "array";
+            base.items = { type: "string" };
+        }
+        else {
+            base.type = spec.type;
+        }
+        properties[key] = base;
+    }
+    const schema = {
+        type: "object",
+        properties,
+    };
+    if (tool.required.length) {
+        schema.required = tool.required;
+    }
+    return schema;
+}
+function anthropicManifest() {
+    return {
+        manifest_version: "1.0",
+        tools: TOOLS.map((t) => ({
+            name: t.name,
+            description: `${t.description} Base URL: https://riskmodels.app`,
+            input_schema: inputSchema(t),
+        })),
+    };
+}
+function openaiManifest() {
+    return {
+        tools: TOOLS.map((t) => ({
+            type: "function",
+            function: {
+                name: t.name,
+                description: `${t.description} Base URL: https://riskmodels.app`,
+                parameters: inputSchema(t),
+            },
+        })),
+    };
+}
+/** Zed-oriented bundle: tool list + JSON Schema parameters (no auth embedded). */
+function zedManifest() {
+    return {
+        schema_version: 1,
+        name: "riskmodels",
+        description: "RiskModels API tools (use Authorization: Bearer rm_agent_* or OAuth against https://riskmodels.app/api)",
+        tools: TOOLS.map((t) => ({
+            name: t.name,
+            description: t.description,
+            method: t.method,
+            path: t.path,
+            parameters: inputSchema(t),
+        })),
+    };
+}
+export function manifestCommand() {
+    return new Command("manifest")
+        .description("Print static agent tool manifest (no API credentials required)")
+        .option("-f, --format <name>", "openai | anthropic | zed", "anthropic")
+        .action((opts) => {
+        const fmt = (opts.format ?? "anthropic").toLowerCase();
+        let out;
+        if (fmt === "openai") {
+            out = openaiManifest();
+        }
+        else if (fmt === "anthropic") {
+            out = anthropicManifest();
+        }
+        else if (fmt === "zed") {
+            out = zedManifest();
+        }
+        else {
+            console.error(chalk.red(`Unknown format: ${fmt}. Use openai, anthropic, or zed.`));
+            process.exitCode = 1;
+            return;
+        }
+        console.log(JSON.stringify(out, null, 2));
+    });
+}

package/dist/commands/mcp-config.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function mcpConfigCommand(): Command;

package/dist/commands/mcp-config.js

@@ -0,0 +1,95 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { loadConfig, configPath } from "../lib/config.js";
+/**
+ * Default absolute path users are most likely to paste into MCP configs.
+ * We don't try to introspect where the user cloned RiskModels_API — we print
+ * a placeholder they can edit. Override with --mcp-server-path for precision.
+ */
+const DEFAULT_MCP_SERVER_PLACEHOLDER = "/ABSOLUTE/PATH/TO/RiskModels_API/mcp/dist/index.js";
+function claudeDesktopConfig(serverPath, apiKey) {
+    const env = {};
+    if (apiKey)
+        env.RISKMODELS_API_KEY = apiKey;
+    return {
+        mcpServers: {
+            riskmodels: {
+                command: "node",
+                args: [serverPath],
+                ...(Object.keys(env).length ? { env } : {}),
+            },
+        },
+    };
+}
+function cursorConfig(serverPath, apiKey) {
+    // Same schema shape as Claude Desktop; Cursor reads .cursor/mcp.json
+    // either at workspace root or ~/.cursor/mcp.json globally.
+    return claudeDesktopConfig(serverPath, apiKey);
+}
+function zedConfig(serverPath, apiKey) {
+    const env = {};
+    if (apiKey)
+        env.RISKMODELS_API_KEY = apiKey;
+    return {
+        context_servers: {
+            riskmodels: {
+                command: {
+                    path: "node",
+                    args: [serverPath],
+                    ...(Object.keys(env).length ? { env } : {}),
+                },
+            },
+        },
+    };
+}
+function humanPath(client) {
+    if (client === "claude-desktop") {
+        return "~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\\Claude\\claude_desktop_config.json (Windows)";
+    }
+    if (client === "cursor") {
+        return ".cursor/mcp.json (workspace) or ~/.cursor/mcp.json (global)";
+    }
+    return "~/.config/zed/settings.json";
+}
+export function mcpConfigCommand() {
+    return new Command("mcp-config")
+        .description("Print a ready-to-paste MCP client config for Claude Desktop, Cursor, or Zed")
+        .option("-c, --client <name>", "claude-desktop | cursor | zed (default: claude-desktop)", "claude-desktop")
+        .option("-p, --mcp-server-path <path>", "Absolute path to RiskModels_API/mcp/dist/index.js", DEFAULT_MCP_SERVER_PLACEHOLDER)
+        .option("--embed-key", "Embed the API key from ~/.config/riskmodels/config.json in the env block. Default is to rely on the MCP server's fallback read of the CLI config file.")
+        .action(async (opts) => {
+        const client = (opts.client || "claude-desktop").toLowerCase();
+        if (!["claude-desktop", "cursor", "zed"].includes(client)) {
+            console.error(chalk.red(`Unknown client: ${client}. Use claude-desktop, cursor, or zed.`));
+            process.exitCode = 1;
+            return;
+        }
+        let apiKey;
+        if (opts.embedKey) {
+            const cfg = await loadConfig();
+            apiKey = cfg?.apiKey?.trim();
+            if (!apiKey) {
+                console.error(chalk.yellow("warning: --embed-key requested but no apiKey in " +
+                    configPath() +
+                    ". Run `riskmodels config init` first."));
+            }
+        }
+        const serverPath = opts.mcpServerPath || DEFAULT_MCP_SERVER_PLACEHOLDER;
+        let config;
+        if (client === "claude-desktop")
+            config = claudeDesktopConfig(serverPath, apiKey);
+        else if (client === "cursor")
+            config = cursorConfig(serverPath, apiKey);
+        else
+            config = zedConfig(serverPath, apiKey);
+        // Helpful human-readable guidance ONLY to stderr so stdout stays pipe-clean.
+        console.error(chalk.dim(`# Paste this into ${humanPath(client)}`));
+        if (!opts.embedKey) {
+            console.error(chalk.dim(`# The MCP server reads ~/.config/riskmodels/config.json automatically — no key needed in the env block.`));
+        }
+        if (serverPath === DEFAULT_MCP_SERVER_PLACEHOLDER) {
+            console.error(chalk.dim(`# Replace the placeholder path with the absolute path to your RiskModels_API/mcp/dist/index.js.`));
+        }
+        console.log(JSON.stringify(config, null, 2));
+    });
+}

package/dist/commands/mcp.d.ts

@@ -0,0 +1,12 @@
+import { Command } from "commander";
+/**
+ * Resolve path to the built MCP server entry (mcp/dist/index.js).
+ *
+ * Order:
+ * 1. RISKMODELS_MCP_SERVER_PATH
+ * 2. --mcp-server-path CLI option
+ * 3. ./mcp/dist/index.js relative to cwd (repo root when running from RiskModels_API)
+ * 4. ../../mcp/dist/index.js relative to cli/dist (monorepo dev: npm link / npm run from repo)
+ */
+export declare function resolveMcpServerPath(explicit?: string): string | null;
+export declare function mcpServeCommand(): Command;