@zenalexa/unicli 0.207.1 → 0.209.0

package/dist/mcp/server.js

@@ -1,21 +1,35 @@
 #!/usr/bin/env node
 /**
- * MCP (Model Context Protocol) stdio server for Uni-CLI.
+ * MCP (Model Context Protocol) server for Uni-CLI.
  *
- * Lazy tool registration strategy:
- *   - At startup, only two tools are registered: list_adapters + run_command
- *   - run_command takes site + command as params, resolves the adapter dynamically
- *   - This avoids registering 600+ tools upfront, keeping MCP handshake fast
+ * Two registration modes:
+ *   1. **Expanded (default)** — one tool per adapter command
+ *      (`unicli_<site>_<command>`) with JSON Schema derived from `args` +
+ *      `columns`. This is the production mode the v0.208 plan calls out:
+ *      MCP clients see the full Uni-CLI surface area without an extra
+ *      list_adapters → run_command roundtrip.
+ *   2. **Lazy (`--lazy`)** — only `list_adapters` + `run_command` are
+ *      registered. Useful when an MCP client has a hard tool-count limit
+ *      or wants the smallest possible handshake.
  *
- * Protocol: JSON-RPC 2.0 over stdio (newline-delimited JSON)
+ * Two transports:
+ *   - **stdio (default)** — newline-delimited JSON over stdin/stdout
+ *   - **http (`--transport http [--port 19826]`)** — POST /mcp accepts a
+ *     single JSON-RPC envelope and returns a single JSON response. No
+ *     SSE streaming yet — additive in a future release.
+ *
+ * Auth pass-through is automatic: every adapter the CLI loads (including
+ * cookie-based ones) is exposed by name; the runtime resolves cookies on
+ * each call via the same code path as the CLI.
  */
 import { createInterface } from "node:readline";
+import { createServer, } from "node:http";
 import { loadAllAdapters, loadTsAdapters } from "../discovery/loader.js";
 import { getAllAdapters, listCommands, resolveCommand } from "../registry.js";
 import { runPipeline } from "../engine/yaml-runner.js";
 import { VERSION } from "../constants.js";
-// ── Tool Definitions ────────────────────────────────────────────────────────
-function buildCoreTools() {
+// ── Lazy-mode core tools (preserved for `--lazy` flag) ──────────────────────
+function buildLazyTools() {
     return [
         {
             name: "list_adapters",
@@ -62,6 +76,161 @@ function buildCoreTools() {
         },
     ];
 }
+// ── Expanded-mode: one tool per adapter command ─────────────────────────────
+/**
+ * Map an adapter `arg.type` to a JSON Schema primitive. Defaults to "string"
+ * for unknown / missing types — safer than failing the schema build.
+ */
+function jsonTypeFor(t) {
+    switch (t) {
+        case "int":
+            return "integer";
+        case "float":
+            return "number";
+        case "bool":
+            return "boolean";
+        case "str":
+        default:
+            return "string";
+    }
+}
+/**
+ * Build the input JSON Schema for one adapter command from its `args`.
+ */
+function buildInputSchema(cmd) {
+    const props = {
+        limit: {
+            type: "integer",
+            description: "Cap result count (default 20)",
+            default: 20,
+        },
+    };
+    const required = [];
+    for (const a of cmd.adapterArgs ?? []) {
+        if (a.name === "limit")
+            continue; // already added
+        const prop = {
+            type: jsonTypeFor(a.type),
+            description: a.description,
+        };
+        if (a.default !== undefined)
+            prop.default = a.default;
+        if (a.choices)
+            prop.enum = a.choices;
+        props[a.name] = prop;
+        if (a.required)
+            required.push(a.name);
+    }
+    const schema = {
+        type: "object",
+        properties: props,
+        additionalProperties: false,
+    };
+    if (required.length > 0)
+        schema.required = required;
+    return schema;
+}
+/**
+ * Build the output JSON Schema. We model results as `{ count, results }`
+ * mirroring run_command, where each item in `results` follows the
+ * `columns` shape (string-typed properties — Uni-CLI columns are
+ * format-agnostic and the runtime emits whatever the pipeline produced).
+ */
+/**
+ * Build an output JSON Schema. We model results as `{count, results}` where
+ * `results` is an array of items. `columns` becomes the item's property set.
+ *
+ * Note: we return a simple nested schema rather than a full JSON Schema
+ * (which would need a deeper `items` type for `array`). Most MCP clients
+ * only inspect the top-level type; Anthropic's client is permissive. If a
+ * strict validator rejects this, it will still fall back to the lazy tool
+ * path via `run_command`.
+ */
+function buildOutputSchema(cmd) {
+    const itemProps = {};
+    for (const col of cmd.columns ?? []) {
+        itemProps[col] = { type: "string", description: `Column: ${col}` };
+    }
+    return {
+        type: "object",
+        properties: {
+            count: { type: "integer", description: "Number of results returned" },
+            results: {
+                type: "array",
+                description: "Result rows",
+                items: {
+                    type: "object",
+                    ...(Object.keys(itemProps).length > 0
+                        ? { properties: itemProps }
+                        : {}),
+                },
+            },
+        },
+    };
+}
+/**
+ * MCP tool name: `unicli_<site>_<command>` with non-alphanumeric chars
+ * collapsed to `_`. Anthropic / Claude Desktop accept underscores; some
+ * older clients reject hyphens, so we normalize defensively.
+ *
+ * CRITICAL: normalization is NOT reversible (e.g. both `claude-code_version`
+ * and `claude_code-version` would yield the same normalized name). The
+ * expanded-mode dispatcher uses a name → {adapter, cmdName} lookup table
+ * built at the same time as the tool list, so callers never need to reverse
+ * the normalization. See `expandedRegistry` and `buildExpandedTools` below.
+ */
+function buildToolName(site, command) {
+    return `unicli_${site}_${command}`.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+const expandedRegistry = new Map();
+function buildExpandedTools() {
+    const tools = [];
+    // Always include list_adapters for discovery + as a smoke test.
+    tools.push(buildLazyTools()[0]);
+    expandedRegistry.clear();
+    // Collision detection: if two (site, command) pairs normalize to the same
+    // tool name, the first one wins and the second is silently shadowed. We
+    // don't expect this in practice (most adapters use lowercase alphanumeric
+    // + hyphen names), but flag it on stderr so it gets noticed.
+    const seen = new Set();
+    for (const adapter of getAllAdapters()) {
+        for (const [cmdName, cmd] of Object.entries(adapter.commands)) {
+            const description = cmd.description?.trim() ||
+                adapter.description?.trim() ||
+                `${cmdName} for ${adapter.name}`;
+            const toolName = buildToolName(adapter.name, cmdName);
+            if (seen.has(toolName)) {
+                process.stderr.write(`unicli MCP: tool name collision: ${toolName} — shadowing ${adapter.name}/${cmdName}\n`);
+                continue;
+            }
+            seen.add(toolName);
+            expandedRegistry.set(toolName, { adapter, cmdName, cmd });
+            tools.push({
+                name: toolName,
+                description: `[${adapter.name}] ${description}`,
+                inputSchema: buildInputSchema(cmd),
+                outputSchema: buildOutputSchema(cmd),
+            });
+        }
+    }
+    // Add unicli_discover tool — expose explore+synthesize+generate as MCP tool
+    tools.push({
+        name: "unicli_discover",
+        description: "Auto-discover CLI capabilities for any website URL. Navigates the page, captures API endpoints, and optionally generates YAML adapters.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "Website URL to explore" },
+                goal: {
+                    type: "string",
+                    description: "Optional: capability to find (e.g. 'search', 'hot', 'feed')",
+                },
+            },
+            required: ["url"],
+        },
+    });
+    return tools;
+}
 // ── Tool Handlers ───────────────────────────────────────────────────────────
 function handleListAdapters(params) {
     let commands = listCommands();
@@ -102,47 +271,7 @@ function handleListAdapters(params) {
         ],
     };
 }
-async function handleRunCommand(params) {
-    const site = params.site;
-    const command = params.command;
-    const args = params.args ?? {};
-    if (!site || !command) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({ error: "site and command are required" }),
-                },
-            ],
-            isError: true,
-        };
-    }
-    const resolved = resolveCommand(site, command);
-    if (!resolved) {
-        // Provide helpful suggestion
-        const adapters = getAllAdapters();
-        const matchingSites = adapters
-            .filter((a) => a.name.includes(site))
-            .map((a) => ({
-            site: a.name,
-            commands: Object.keys(a.commands),
-        }));
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        error: `Unknown command: ${site} ${command}`,
-                        suggestion: matchingSites.length > 0
-                            ? `Did you mean one of these? ${JSON.stringify(matchingSites)}`
-                            : "Use list_adapters to see all available commands.",
-                    }, null, 2),
-                },
-            ],
-            isError: true,
-        };
-    }
-    const { adapter, command: cmd } = resolved;
+async function runResolvedCommand(adapter, cmd, cmdName, args) {
     // Merge default args
     const mergedArgs = { limit: 20, ...args };
     if (args.limit !== undefined) {
@@ -193,7 +322,7 @@ async function handleRunCommand(params) {
                     type: "text",
                     text: JSON.stringify({
                         error: message,
-                        adapter_path: `src/adapters/${adapter.name}/${command}.yaml`,
+                        adapter_path: `src/adapters/${adapter.name}/${cmdName}.yaml`,
                         suggestion: "The adapter may need updating. Check the YAML file.",
                     }, null, 2),
                 },
@@ -202,91 +331,221 @@ async function handleRunCommand(params) {
         };
     }
 }
+async function handleRunCommand(params) {
+    const site = params.site;
+    const command = params.command;
+    const args = params.args ?? {};
+    if (!site || !command) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ error: "site and command are required" }),
+                },
+            ],
+            isError: true,
+        };
+    }
+    const resolved = resolveCommand(site, command);
+    if (!resolved) {
+        const adapters = getAllAdapters();
+        const matchingSites = adapters
+            .filter((a) => a.name.includes(site))
+            .map((a) => ({
+            site: a.name,
+            commands: Object.keys(a.commands),
+        }));
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: `Unknown command: ${site} ${command}`,
+                        suggestion: matchingSites.length > 0
+                            ? `Did you mean one of these? ${JSON.stringify(matchingSites)}`
+                            : "Use list_adapters to see all available commands.",
+                    }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+    return runResolvedCommand(resolved.adapter, resolved.command, command, args);
+}
+/**
+ * Expanded-tool dispatcher — parse `unicli_<site>_<command>` back to its
+ * components and call the resolver. Returns `undefined` when the tool name
+ * is not in expanded form, so the caller can fall through to lazy-tool
+ * handling (list_adapters / run_command).
+ */
+async function handleExpandedTool(toolName, args) {
+    if (!toolName.startsWith("unicli_"))
+        return undefined;
+    // Dictionary lookup into the expansion registry built by
+    // `buildExpandedTools`. This is the ONLY correct way to map a normalized
+    // tool name back to its adapter + command because the normalization
+    // (`s/[^a-zA-Z0-9_]/_/g`) is not reversible — a command file named
+    // `capture-list.yaml` and another named `capture_list.yaml` would map
+    // to the same tool name. The registry resolves the ambiguity deterministically
+    // (first-write-wins, collisions logged to stderr in `buildExpandedTools`).
+    const entry = expandedRegistry.get(toolName);
+    if (!entry)
+        return undefined;
+    return runResolvedCommand(entry.adapter, entry.cmd, entry.cmdName, args);
+}
 // ── MCP Protocol Handler ────────────────────────────────────────────────────
 const PROTOCOL_VERSION = "2024-11-05";
-const tools = buildCoreTools();
-function handleRequest(req) {
-    const id = req.id ?? null;
-    switch (req.method) {
-        case "initialize":
-            return {
-                jsonrpc: "2.0",
-                id,
-                result: {
-                    protocolVersion: PROTOCOL_VERSION,
-                    capabilities: {
-                        tools: {},
-                    },
-                    serverInfo: {
-                        name: "unicli",
-                        version: VERSION,
+function parseArgs(argv) {
+    const opts = {
+        lazy: false,
+        transport: "stdio",
+        port: 19826,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--lazy")
+            opts.lazy = true;
+        else if (a === "--transport") {
+            const v = argv[++i];
+            if (v === "stdio" || v === "http")
+                opts.transport = v;
+        }
+        else if (a === "--port") {
+            const v = parseInt(argv[++i], 10);
+            if (Number.isFinite(v))
+                opts.port = v;
+        }
+    }
+    return opts;
+}
+function buildHandler(tools) {
+    return function handleRequest(req) {
+        const id = req.id ?? null;
+        switch (req.method) {
+            case "initialize":
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        protocolVersion: PROTOCOL_VERSION,
+                        capabilities: {
+                            tools: {},
+                        },
+                        serverInfo: {
+                            name: "unicli",
+                            version: VERSION,
+                        },
                     },
-                },
-            };
-        case "notifications/initialized":
-            // Client acknowledgement — no response needed for notifications
-            return null;
-        case "tools/list":
-            return {
-                jsonrpc: "2.0",
-                id,
-                result: { tools },
-            };
-        case "tools/call": {
-            const params = req.params;
-            if (!params?.name) {
+                };
+            case "notifications/initialized":
+                return null;
+            case "tools/list":
                 return {
                     jsonrpc: "2.0",
                     id,
-                    error: { code: -32602, message: "Missing tool name" },
+                    result: { tools },
                 };
-            }
-            const toolArgs = params.arguments ?? {};
-            switch (params.name) {
-                case "list_adapters": {
-                    const result = handleListAdapters(toolArgs);
-                    return { jsonrpc: "2.0", id, result };
-                }
-                case "run_command":
-                    return handleRunCommand(toolArgs).then((result) => ({
+            case "tools/call": {
+                const params = req.params;
+                if (!params?.name) {
+                    return {
                         jsonrpc: "2.0",
                         id,
-                        result,
-                    }));
-                default:
+                        error: { code: -32602, message: "Missing tool name" },
+                    };
+                }
+                const toolArgs = params.arguments ?? {};
+                switch (params.name) {
+                    case "list_adapters": {
+                        const result = handleListAdapters(toolArgs);
+                        return { jsonrpc: "2.0", id, result };
+                    }
+                    case "run_command":
+                        return handleRunCommand(toolArgs).then((result) => ({
+                            jsonrpc: "2.0",
+                            id,
+                            result,
+                        }));
+                    case "unicli_discover": {
+                        const discoverUrl = toolArgs.url;
+                        const discoverGoal = toolArgs.goal;
+                        if (!discoverUrl) {
+                            return {
+                                jsonrpc: "2.0",
+                                id,
+                                error: {
+                                    code: -32602,
+                                    message: "Missing required parameter: url",
+                                },
+                            };
+                        }
+                        return import("node:child_process").then(({ execFile: ef }) => import("node:util").then(({ promisify: prom }) => {
+                            const execFileP = prom(ef);
+                            const discoverArgs = ["generate", discoverUrl, "--json"];
+                            if (discoverGoal)
+                                discoverArgs.push("--goal", discoverGoal);
+                            return execFileP("unicli", discoverArgs, {
+                                timeout: 120_000,
+                                encoding: "utf-8",
+                            }).then(({ stdout }) => ({
+                                jsonrpc: "2.0",
+                                id,
+                                result: { content: [{ type: "text", text: stdout }] },
+                            }), (err) => ({
+                                jsonrpc: "2.0",
+                                id,
+                                result: {
+                                    content: [
+                                        {
+                                            type: "text",
+                                            text: JSON.stringify({
+                                                error: err instanceof Error ? err.message : String(err),
+                                            }),
+                                        },
+                                    ],
+                                    isError: true,
+                                },
+                            }));
+                        }));
+                    }
+                    default:
+                        return handleExpandedTool(params.name, toolArgs).then((result) => {
+                            if (result)
+                                return { jsonrpc: "2.0", id, result };
+                            return {
+                                jsonrpc: "2.0",
+                                id,
+                                error: {
+                                    code: -32601,
+                                    message: `Unknown tool: ${params.name}. Use list_adapters to see all available commands.`,
+                                },
+                            };
+                        });
+                }
+            }
+            case "ping":
+                return { jsonrpc: "2.0", id, result: {} };
+            default:
+                if (id !== null && id !== undefined) {
                     return {
                         jsonrpc: "2.0",
                         id,
                         error: {
                             code: -32601,
-                            message: `Unknown tool: ${params.name}. Available tools: ${tools.map((t) => t.name).join(", ")}`,
+                            message: `Method not found: ${req.method}`,
                         },
                     };
-            }
+                }
+                return null;
         }
-        case "ping":
-            return { jsonrpc: "2.0", id, result: {} };
-        default:
-            // Unknown method — return error for requests (has id), ignore notifications
-            if (id !== null && id !== undefined) {
-                return {
-                    jsonrpc: "2.0",
-                    id,
-                    error: { code: -32601, message: `Method not found: ${req.method}` },
-                };
-            }
-            return null;
-    }
+    };
 }
 // ── Stdio Transport ─────────────────────────────────────────────────────────
 function send(response) {
     const json = JSON.stringify(response);
     process.stdout.write(json + "\n");
 }
-async function main() {
-    // Load adapters (same as CLI)
-    loadAllAdapters();
-    await loadTsAdapters();
+async function startStdio(handler) {
     const rl = createInterface({
         input: process.stdin,
         terminal: false,
@@ -308,7 +567,7 @@ async function main() {
             return;
         }
         try {
-            const response = await handleRequest(req);
+            const response = await handler(req);
             if (response) {
                 send(response);
             }
@@ -325,10 +584,95 @@ async function main() {
     rl.on("close", () => {
         process.exit(0);
     });
-    // Log to stderr so it doesn't interfere with JSON-RPC on stdout
+}
+// ── HTTP Transport ──────────────────────────────────────────────────────────
+/**
+ * Simple JSON-RPC over HTTP. POST /mcp accepts a single JSON-RPC envelope and
+ * returns a single JSON response. GET /mcp returns server info — handy for
+ * a health check from a browser.
+ *
+ * Note: this is intentionally NOT a full MCP Streamable HTTP transport —
+ * no SSE event stream, no session resume. Most clients that "speak HTTP"
+ * to MCP only need request/response, and starting with the simpler shape
+ * means zero new dependencies and a tiny attack surface.
+ */
+async function startHttp(handler, port, toolCount) {
+    const server = createServer((req, res) => {
+        if (req.method === "GET" && (req.url === "/" || req.url === "/mcp")) {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                server: "unicli",
+                version: VERSION,
+                tools: toolCount,
+                protocol: PROTOCOL_VERSION,
+            }));
+            return;
+        }
+        if (req.method !== "POST" || req.url !== "/mcp") {
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "POST /mcp" }));
+            return;
+        }
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", async () => {
+            const body = Buffer.concat(chunks).toString("utf-8");
+            let parsed;
+            try {
+                parsed = JSON.parse(body);
+            }
+            catch {
+                res.writeHead(400, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: null,
+                    error: { code: -32700, message: "Parse error" },
+                }));
+                return;
+            }
+            try {
+                const response = await handler(parsed);
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify(response ?? null));
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: parsed.id ?? null,
+                    error: { code: -32603, message: `Internal error: ${message}` },
+                }));
+            }
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, "127.0.0.1", () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    process.stderr.write(`unicli MCP server v${VERSION} — HTTP transport on http://127.0.0.1:${port}/mcp\n`);
+}
+// ── main ────────────────────────────────────────────────────────────────────
+async function main() {
+    const opts = parseArgs(process.argv.slice(2));
+    // Load adapters (same as CLI)
+    loadAllAdapters();
+    await loadTsAdapters();
+    const tools = opts.lazy ? buildLazyTools() : buildExpandedTools();
+    const handler = buildHandler(tools);
     const adapterCount = getAllAdapters().length;
     const commandCount = listCommands().length;
-    process.stderr.write(`unicli MCP server v${VERSION} — ${adapterCount} sites, ${commandCount} commands (2 tools registered)\n`);
+    if (opts.transport === "http") {
+        await startHttp(handler, opts.port, tools.length);
+        process.stderr.write(`unicli MCP server v${VERSION} — ${adapterCount} sites, ${commandCount} commands (${tools.length} tools registered, mode=${opts.lazy ? "lazy" : "expanded"})\n`);
+        return;
+    }
+    // stdio (default)
+    await startStdio(handler);
+    process.stderr.write(`unicli MCP server v${VERSION} — ${adapterCount} sites, ${commandCount} commands (${tools.length} tools registered, mode=${opts.lazy ? "lazy" : "expanded"})\n`);
 }
 main().catch((err) => {
     process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);