@aisa-one/cli 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-08-18
+
+### Fixed
+
+- **`aisa mcp setup` wrote a dead URL.** It hardcoded
+  `https://docs.aisa.one/mcp`, a hostname with no DNS record, and wrote it
+  into every client's config. Setup now reads the live discovery manifest at
+  `aisa.one/.well-known/mcp.json` and writes one entry per live server
+  (default set of five; `--all` for everything), so new servers work without
+  a CLI release. If the manifest cannot be fetched, nothing is written.
+- **`{url}` entries were written for clients that cannot execute them.**
+  Claude Desktop and Windsurf spawn stdio processes and silently ignore url
+  entries; they now get an `npx mcp-remote` bridge, verified end to end
+  against production.
+- **A config file that failed to parse was replaced with `{}`.** A
+  hand-edited `mcp.json` with comments or a trailing comma was wiped by
+  setup. It is now left untouched, with an error.
+
+### Added
+
+- Entries carry the configured API key as a Bearer header; without a key
+  they are written credential-less and the server's OAuth challenge drives
+  the browser flow on first use.
+- `aisa mcp status` now pings every configured endpoint with a real
+  initialize request instead of checking that a JSON key exists — a 401 is
+  reported as healthy (the auth challenge), an unresolvable hostname as the
+  failure it is.
+- The stale dead entry earlier releases wrote is removed on the next setup.
+
 ## [0.2.4] — 2026-08-07
 
 Text-only follow-up to 0.2.3: no behavioural change, but the URL it printed

package/README.md

@@ -250,15 +250,20 @@ To publish a skill, open a pull request against
 ## MCP Server
 
 ```bash
-aisa mcp setup                          # configure detected agents
-aisa mcp status                         # check configuration
+aisa mcp setup                          # configure the default servers for every detected client
+aisa mcp setup --all                    # every live server, not just the defaults
+aisa mcp setup --agent cursor           # one client only
+aisa mcp status                         # list entries and ping each configured endpoint
 ```
 
-> **Not currently usable.** These commands write
-> `https://docs.aisa.one/mcp`, which has no DNS record, and `mcp setup`
-> overwrites an agent config file it cannot parse — a `mcp.json` with comments
-> or a trailing comma will be emptied. Avoid `aisa mcp setup` until this is
-> fixed.
+`setup` reads the platform's discovery manifest (`aisa.one/.well-known/mcp.json`)
+at run time and writes one entry per live server, in the shape each client
+executes: a `url` entry for Cursor, an `npx mcp-remote` stdio bridge for
+Claude Desktop and Windsurf. With an API key configured the entries carry it
+as a Bearer header; without one they carry no credentials and the server's
+OAuth flow opens in your browser on first use. A config file that exists but
+does not parse is never overwritten. The docs-search MCP is always included
+as `aisa-docs`.
 
 ## Shell Completion
 

package/dist/commands/mcp.d.ts

@@ -1,4 +1,22 @@
+/** One config entry in the shape the client actually executes. */
+export declare function buildEntry(shape: "url" | "stdio", endpoint: string, key: string | undefined): Record<string, unknown>;
 export declare function mcpSetupAction(options: {
     agent?: string;
-}): void;
-export declare function mcpStatusAction(): void;
+    all?: boolean;
+}): Promise<void>;
+/**
+ * `aisa mcp status` — what is configured, and does it actually answer.
+ *
+ * The old status only checked that a config file contained an "aisa" key,
+ * which is exactly how a dead URL looked healthy. Reachability means a real
+ * HTTP exchange with each configured endpoint.
+ */
+export declare function mcpStatusAction(): Promise<void>;
+/**
+ * One initialize POST, no credentials. What each answer means:
+ *   200 -> alive and open (the docs MCP)
+ *   401 -> alive, auth required — the expected answer from mcp.aisa.one
+ *   anything else -> alive but odd; say so
+ *   network error -> the dead-hostname class this command exists to catch
+ */
+export declare function pingEndpoint(endpoint: string): Promise<string>;

package/dist/commands/mcp.js

@@ -2,19 +2,78 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import chalk from "chalk";
 import { success, error, info, hint } from "../utils/display.js";
 import { expandHome, ensureDir } from "../utils/file.js";
-import { MCP_CONFIGS, MCP_URL } from "../constants.js";
+import { MCP_CONFIGS, MCP_MANIFEST_URL, DOCS_MCP_URL, MCP_DEFAULT_SLUGS } from "../constants.js";
+import { getApiKey } from "../config.js";
 import { join } from "node:path";
-export function mcpSetupAction(options) {
-    const targets = options.agent && options.agent !== "all"
-        ? [options.agent]
-        : Object.keys(MCP_CONFIGS);
-    let configured = 0;
+const stripped = (name) => name.replace(/^AIsa\s+/i, "");
+async function fetchLiveServers() {
+    const res = await fetch(MCP_MANIFEST_URL, { signal: AbortSignal.timeout(15_000) });
+    if (!res.ok)
+        throw new Error(`manifest answered HTTP ${res.status}`);
+    const manifest = (await res.json());
+    const live = (manifest.servers ?? [])
+        .filter((s) => s.status === "live" && s.slug && s.transport?.endpoint)
+        .map((s) => ({
+        slug: s.slug,
+        name: s.name ?? s.slug,
+        endpoint: s.transport.endpoint,
+        toolCount: s.tools?.length ?? 0,
+    }));
+    if (live.length === 0)
+        throw new Error("manifest lists no live servers");
+    return live;
+}
+/** One config entry in the shape the client actually executes. */
+export function buildEntry(shape, endpoint, key) {
+    if (shape === "url") {
+        return key ? { url: endpoint, headers: { Authorization: `Bearer ${key}` } } : { url: endpoint };
+    }
+    // The exact invocation verified against production on 2026-08-18. The
+    // header value splits on the first colon, so no space after "Authorization:".
+    // Without a key, mcp-remote answers the server's 401 challenge by running
+    // the OAuth flow itself and caching tokens under ~/.mcp-auth.
+    const args = ["-y", "mcp-remote", endpoint];
+    if (key)
+        args.push("--header", `Authorization:Bearer ${key}`);
+    args.push("--transport", "http-only");
+    return { command: "npx", args };
+}
+/** The dead entry every pre-v0.3 setup wrote. Remove it on sight. */
+const DEAD_URL = "https://docs.aisa.one/mcp";
+export async function mcpSetupAction(options) {
+    const targets = options.agent && options.agent !== "all" ? [options.agent] : Object.keys(MCP_CONFIGS);
     for (const agent of targets) {
-        const config = MCP_CONFIGS[agent];
-        if (!config) {
+        if (!MCP_CONFIGS[agent]) {
             error(`Unknown agent: ${agent}. Valid: ${Object.keys(MCP_CONFIGS).join(", ")}, all`);
             return;
         }
+    }
+    // Fetch before touching any file: a setup that cannot see the manifest has
+    // nothing true to write.
+    let servers;
+    try {
+        servers = await fetchLiveServers();
+    }
+    catch (e) {
+        error(`Could not read the MCP manifest at ${MCP_MANIFEST_URL}: ${e.message}`);
+        hint("Nothing was written. Check your network and try again.");
+        process.exitCode = 1;
+        return;
+    }
+    const chosen = options.all
+        ? servers
+        : servers.filter((s) => MCP_DEFAULT_SLUGS.includes(s.slug));
+    const skipped = servers.length - chosen.length;
+    const key = getApiKey();
+    if (key) {
+        info("Using your configured API key (Bearer). It will be written into each client's config file.");
+    }
+    else {
+        info("No API key configured — entries are written without credentials, and the");
+        info("server's OAuth flow will open in your browser on first use.");
+    }
+    for (const agent of targets) {
+        const config = MCP_CONFIGS[agent];
         const filePath = expandHome(config.path);
         let existing = {};
         if (existsSync(filePath)) {
@@ -22,46 +81,123 @@ export function mcpSetupAction(options) {
                 existing = JSON.parse(readFileSync(filePath, "utf-8"));
             }
             catch {
-                existing = {};
+                // A file we cannot parse is a file we do not own. The old command
+                // replaced it with {} — a user's hand-edited config (comments,
+                // trailing commas) was wiped by a "setup". Refuse instead.
+                error(`${agent}: ${config.path} exists but is not valid JSON — refusing to overwrite it.`);
+                hint("Fix or remove the file, then re-run setup.");
+                continue;
             }
         }
         else {
             ensureDir(join(filePath, ".."));
         }
-        const servers = existing[config.key] || {};
-        servers["aisa"] = { url: MCP_URL };
-        existing[config.key] = servers;
+        const entries = existing[config.key] || {};
+        // Clean up the dead entry earlier releases wrote, and only that one:
+        // an "aisa" entry the user pointed somewhere else on purpose stays.
+        const stale = entries["aisa"];
+        if (stale?.url === DEAD_URL)
+            delete entries["aisa"];
+        for (const s of chosen) {
+            entries[`aisa-${s.slug}`] = buildEntry(config.shape, s.endpoint, key);
+        }
+        // The docs-search MCP is tiny, unauthenticated, and answers "how do I call
+        // this" questions — always included.
+        entries["aisa-docs"] = buildEntry(config.shape, DOCS_MCP_URL, undefined);
+        existing[config.key] = entries;
         writeFileSync(filePath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
-        console.log(`  ${chalk.green("✓")} ${agent}: ${config.path}`);
-        configured++;
+        console.log(`  ${chalk.green("✓")} ${agent}: ${chosen.length + 1} servers (${config.shape}) → ${config.path}`);
     }
-    if (configured > 0) {
-        success(`MCP server configured for ${configured} agent(s)`);
-        hint("Restart your agent/editor to activate");
+    success(`Configured ${chosen.length} live servers plus docs search for ${targets.length} client(s)`);
+    for (const s of chosen) {
+        console.log(`    ${chalk.cyan(`aisa-${s.slug}`)}  ${stripped(s.name)} (${s.toolCount} tools)`);
     }
+    if (skipped > 0)
+        hint(`${skipped} more live servers available — run with --all to configure every one`);
+    hint("Restart your agent/editor to activate");
 }
-export function mcpStatusAction() {
-    info(`MCP Server: ${MCP_URL}`);
+/**
+ * `aisa mcp status` — what is configured, and does it actually answer.
+ *
+ * The old status only checked that a config file contained an "aisa" key,
+ * which is exactly how a dead URL looked healthy. Reachability means a real
+ * HTTP exchange with each configured endpoint.
+ */
+export async function mcpStatusAction() {
+    const endpoints = new Map(); // endpoint -> [client/entry]
     for (const [agent, config] of Object.entries(MCP_CONFIGS)) {
         const filePath = expandHome(config.path);
-        if (existsSync(filePath)) {
-            try {
-                const data = JSON.parse(readFileSync(filePath, "utf-8"));
-                const servers = data[config.key];
-                if (servers?.["aisa"]) {
-                    console.log(`  ${chalk.green("✓")} ${agent}: configured`);
-                }
-                else {
-                    console.log(`  ${chalk.gray("○")} ${agent}: not configured`);
-                }
-            }
-            catch {
-                console.log(`  ${chalk.gray("○")} ${agent}: config unreadable`);
-            }
-        }
-        else {
+        if (!existsSync(filePath)) {
             console.log(`  ${chalk.gray("○")} ${agent}: not installed`);
+            continue;
+        }
+        let entries = {};
+        try {
+            const data = JSON.parse(readFileSync(filePath, "utf-8"));
+            entries = data[config.key] || {};
+        }
+        catch {
+            console.log(`  ${chalk.gray("○")} ${agent}: config unreadable`);
+            continue;
+        }
+        const ours = Object.entries(entries).filter(([name]) => name.startsWith("aisa"));
+        if (ours.length === 0) {
+            console.log(`  ${chalk.gray("○")} ${agent}: not configured`);
+            continue;
         }
+        console.log(`  ${chalk.green("✓")} ${agent}: ${ours.length} entries`);
+        for (const [name, entry] of ours) {
+            const e = entry;
+            const endpoint = e.url ?? e.args?.find((a) => a.startsWith("http"));
+            if (endpoint) {
+                const users = endpoints.get(endpoint) ?? [];
+                users.push(`${agent}/${name}`);
+                endpoints.set(endpoint, users);
+            }
+        }
+    }
+    if (endpoints.size === 0) {
+        hint("Run 'aisa mcp setup' to configure");
+        return;
+    }
+    console.log("");
+    info("Checking each configured endpoint:");
+    for (const [endpoint, users] of endpoints) {
+        console.log(`  ${endpoint}  ${chalk.gray(`(${users.length} entr${users.length > 1 ? "ies" : "y"})`)}`);
+        console.log(`    ${await pingEndpoint(endpoint)}`);
+    }
+}
+/**
+ * One initialize POST, no credentials. What each answer means:
+ *   200 -> alive and open (the docs MCP)
+ *   401 -> alive, auth required — the expected answer from mcp.aisa.one
+ *   anything else -> alive but odd; say so
+ *   network error -> the dead-hostname class this command exists to catch
+ */
+export async function pingEndpoint(endpoint) {
+    try {
+        const res = await fetch(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "initialize",
+                params: {
+                    protocolVersion: "2025-06-18",
+                    capabilities: {},
+                    clientInfo: { name: "aisa-cli", version: "status" },
+                },
+            }),
+            signal: AbortSignal.timeout(8_000),
+        });
+        if (res.status === 200)
+            return `${chalk.green("✓")} reachable (open)`;
+        if (res.status === 401)
+            return `${chalk.green("✓")} reachable (auth required — normal)`;
+        return `${chalk.yellow("⚠")} reachable but answered HTTP ${res.status}`;
+    }
+    catch (e) {
+        return `${chalk.red("✗")} unreachable: ${e.message}`;
     }
-    hint("Run 'aisa mcp setup' to configure");
 }

package/dist/constants.d.ts

@@ -1,8 +1,27 @@
-export declare const VERSION = "0.2.4";
+export declare const VERSION = "0.3.0";
 /** Root of the platform. Per-surface bases are derived in api.ts#resolveBases. */
 export declare const BASE_URL = "https://api.aisa.one";
 export declare const ENV_VAR_NAME = "AISA_API_KEY";
-export declare const MCP_URL = "https://docs.aisa.one/mcp";
+/**
+ * The MCP discovery manifest — the single source of truth for which servers
+ * exist and where they live. The CLI deliberately knows no server list of its
+ * own: servers ship and retire on the platform side, and reading the manifest
+ * at setup time means a new server works without a CLI release (the same
+ * philosophy as LLM_ROUTE_PREFIXES below, applied to the fast-moving side).
+ *
+ * History: until v0.2.4 this file hardcoded MCP_URL = "https://docs.aisa.one/mcp",
+ * a host that does not resolve — every `aisa mcp setup` wrote a dead entry into
+ * users' configs, and nothing noticed because the command had no tests.
+ */
+export declare const MCP_MANIFEST_URL = "https://aisa.one/.well-known/mcp.json";
+/** Mintlify's docs-search MCP (3 tools: search/read/feedback). Unauthenticated. */
+export declare const DOCS_MCP_URL = "https://aisa.one/docs/mcp";
+/**
+ * Servers configured by default. Eleven entries per client is a lot of config;
+ * these five cover the broadest agent needs, and `--all` configures everything
+ * the manifest lists as live.
+ */
+export declare const MCP_DEFAULT_SLUGS: readonly string[];
 /**
  * First path segment of every route the LLM gateway serves under /v1 (plus
  * /v1beta for Gemini). Everything else is an integration API under /apis/v1.
@@ -15,9 +34,17 @@ export declare const MCP_URL = "https://docs.aisa.one/mcp";
  */
 export declare const LLM_ROUTE_PREFIXES: readonly string[];
 export declare const AGENT_DIRS: Record<string, string>;
+/**
+ * Per-client config shape. This is the part v0.2.4 got wrong even apart from
+ * the dead URL: it wrote `{url}` everywhere, but Claude Desktop's mcpServers
+ * only executes command/args (stdio) entries and silently ignores url ones.
+ * Stdio clients get an `npx mcp-remote` bridge instead — verified end to end
+ * against mcp.aisa.one (initialize -> tools/list -> tools/call) on 2026-08-18.
+ */
 export declare const MCP_CONFIGS: Record<string, {
     path: string;
     key: string;
+    shape: "url" | "stdio";
 }>;
 /**
  * Ticker symbol → CoinGecko coin id.

package/dist/constants.js

@@ -1,8 +1,33 @@
-export const VERSION = "0.2.4";
+export const VERSION = "0.3.0";
 /** Root of the platform. Per-surface bases are derived in api.ts#resolveBases. */
 export const BASE_URL = "https://api.aisa.one";
 export const ENV_VAR_NAME = "AISA_API_KEY";
-export const MCP_URL = "https://docs.aisa.one/mcp";
+/**
+ * The MCP discovery manifest — the single source of truth for which servers
+ * exist and where they live. The CLI deliberately knows no server list of its
+ * own: servers ship and retire on the platform side, and reading the manifest
+ * at setup time means a new server works without a CLI release (the same
+ * philosophy as LLM_ROUTE_PREFIXES below, applied to the fast-moving side).
+ *
+ * History: until v0.2.4 this file hardcoded MCP_URL = "https://docs.aisa.one/mcp",
+ * a host that does not resolve — every `aisa mcp setup` wrote a dead entry into
+ * users' configs, and nothing noticed because the command had no tests.
+ */
+export const MCP_MANIFEST_URL = "https://aisa.one/.well-known/mcp.json";
+/** Mintlify's docs-search MCP (3 tools: search/read/feedback). Unauthenticated. */
+export const DOCS_MCP_URL = "https://aisa.one/docs/mcp";
+/**
+ * Servers configured by default. Eleven entries per client is a lot of config;
+ * these five cover the broadest agent needs, and `--all` configures everything
+ * the manifest lists as live.
+ */
+export const MCP_DEFAULT_SLUGS = [
+    "web-search",
+    "twitter-api",
+    "crypto-market-data",
+    "marketpulse",
+    "stock-pulse",
+];
 /**
  * First path segment of every route the LLM gateway serves under /v1 (plus
  * /v1beta for Gemini). Everything else is an integration API under /apis/v1.
@@ -35,15 +60,24 @@ export const AGENT_DIRS = {
     gemini: "~/.gemini/skills/",
     openclaw: "~/.openclaw/skills/",
 };
+/**
+ * Per-client config shape. This is the part v0.2.4 got wrong even apart from
+ * the dead URL: it wrote `{url}` everywhere, but Claude Desktop's mcpServers
+ * only executes command/args (stdio) entries and silently ignores url ones.
+ * Stdio clients get an `npx mcp-remote` bridge instead — verified end to end
+ * against mcp.aisa.one (initialize -> tools/list -> tools/call) on 2026-08-18.
+ */
 export const MCP_CONFIGS = {
-    cursor: { path: "~/.cursor/mcp.json", key: "mcpServers" },
+    cursor: { path: "~/.cursor/mcp.json", key: "mcpServers", shape: "url" },
     "claude-desktop": {
         path: "~/Library/Application Support/Claude/claude_desktop_config.json",
         key: "mcpServers",
+        shape: "stdio",
     },
     windsurf: {
         path: "~/.codeium/windsurf/mcp_config.json",
         key: "mcpServers",
+        shape: "stdio",
     },
 };
 /**

package/dist/index.js

@@ -472,12 +472,13 @@ skills
 const mcp = program.command("mcp").description("MCP server integration");
 mcp
     .command("setup")
-    .description("Configure AIsa MCP server for AI agents")
+    .description("Configure AIsa MCP servers (from the live manifest) for AI agents")
     .option("--agent <agent>", "Target agent: cursor, claude-desktop, windsurf, all")
+    .option("--all", "Configure every live server, not just the default set")
     .action(mcpSetupAction);
 mcp
     .command("status")
-    .description("Check MCP server configuration status")
+    .description("Check MCP configuration and ping each configured endpoint")
     .action(mcpStatusAction);
 // ── Config ──
 const configCmd = program.command("config").description("Manage CLI configuration");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aisa-one/cli",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "CLI for the AIsa unified AI infrastructure platform - one API key for 80+ LLMs and 900+ endpoints across finance, search, social, and video APIs",
   "type": "module",
   "main": "dist/index.js",