@zenalexa/unicli 0.210.0 → 0.211.2

package/dist/mcp/server.js

@@ -3,20 +3,19 @@
  * MCP (Model Context Protocol) server for Uni-CLI.
  *
  * Two registration modes:
- *   1. **Expanded (default)** — one tool per adapter command
+ *   1. **Smart default** — 3 tools: `unicli_run`, `unicli_list`,
+ *      `unicli_discover`. Keeps the MCP handshake under 200 tokens.
+ *   2. **Expanded (`--expanded`)** — 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.
+ *      `columns`. MCP clients see the full Uni-CLI surface area.
  *
- * Two transports:
+ * Three 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.
+ *     single JSON-RPC envelope and returns a single JSON response.
+ *   - **sse (`--transport sse [--port 19826]`)** — Streamable HTTP with
+ *     Server-Sent Events. GET /mcp/sse opens the event stream, POST
+ *     /mcp/message?sessionId=xxx delivers JSON-RPC requests.
  *
  * Auth pass-through is automatic: every adapter the CLI loads (including
  * cookie-based ones) is exposed by name; the runtime resolves cookies on
@@ -28,174 +27,143 @@ 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";
-// ── Lazy-mode core tools (preserved for `--lazy` flag) ──────────────────────
-function buildLazyTools() {
+// sse-transport.ts is deprecated (spec 2025-03-26). Kept for backwards compatibility.
+// import { startSseServer } from "./sse-transport.js";
+import { startStreamableHttp } from "./streamable-http.js";
+import { handleOAuthRoute, createOAuthMiddleware } from "./oauth.js";
+import { buildInputSchema, buildOutputSchema, buildToolName, truncateDescription, } from "./schema.js";
+// ── Smart default tools (4 meta-tools — the default mode) ─────────────────
+const MAX_RESULT_SIZE_CHARS = 10_000;
+function buildDefaultTools() {
     return [
         {
-            name: "list_adapters",
-            description: "List all available Uni-CLI adapters and their commands. " +
-                "Use this to discover what sites and commands are available before calling run_command.",
+            name: "unicli_run",
+            description: "Execute any Uni-CLI command. Returns JSON results.",
             inputSchema: {
                 type: "object",
                 properties: {
                     site: {
                         type: "string",
-                        description: "Filter by site name (optional, partial match)",
+                        description: "Site name (e.g. hackernews, github, bilibili)",
                     },
-                    type: {
+                    command: {
                         type: "string",
-                        description: "Filter by adapter type: web-api, desktop, browser, bridge, service",
-                        enum: ["web-api", "desktop", "browser", "bridge", "service"],
+                        description: "Command to run (e.g. top, search, hot)",
+                    },
+                    args: {
+                        type: "object",
+                        description: 'Key-value arguments (e.g. {"query": "ai", "limit": 10})',
+                        additionalProperties: true,
                     },
                 },
+                required: ["site", "command"],
+            },
+            _meta: {
+                "anthropic/searchHint": "Execute CLI commands on 200+ websites and desktop apps. Run adapters by site and command name.",
+            },
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: true,
             },
         },
         {
-            name: "run_command",
-            description: "Execute a Uni-CLI adapter command. Equivalent to running `unicli <site> <command>` on the CLI. " +
-                "Returns JSON results. Use list_adapters first to discover available commands.",
+            name: "unicli_list",
+            description: "List available commands. Filter by site or adapter type.",
             inputSchema: {
                 type: "object",
                 properties: {
                     site: {
                         type: "string",
-                        description: "The adapter site name (e.g. hackernews, github, bilibili)",
+                        description: "Filter by site name (partial match)",
                     },
-                    command: {
+                    type: {
                         type: "string",
-                        description: "The command to run (e.g. top, search, hot)",
-                    },
-                    args: {
-                        type: "object",
-                        description: 'Command arguments as key-value pairs (e.g. {"query": "ai", "limit": 10})',
-                        additionalProperties: true,
+                        description: "Filter by adapter type",
+                        enum: ["web-api", "desktop", "browser", "bridge", "service"],
                     },
                 },
-                required: ["site", "command"],
+            },
+            _meta: {
+                "anthropic/searchHint": "Browse available Uni-CLI sites and commands. Filter by site name or adapter type.",
+                "anthropic/alwaysLoad": true,
+            },
+            annotations: {
+                readOnlyHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
             },
         },
-    ];
-}
-// ── 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,
+        {
+            name: "unicli_search",
+            description: "Search 200+ sites and 956 commands by intent. Bilingual (EN/ZH). Returns top matches with usage examples.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "Natural language intent (e.g. 'download video', '推特热门', 'stock price')",
+                    },
+                    limit: {
+                        type: "integer",
+                        description: "Max results (default 5)",
+                        default: 5,
+                    },
+                },
+                required: ["query"],
+            },
+            _meta: {
+                "anthropic/searchHint": "Find CLI commands by intent. Semantic search across websites, desktop apps, macOS. Bilingual Chinese/English.",
+                "anthropic/alwaysLoad": true,
+            },
+            annotations: {
+                readOnlyHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
         },
-    };
-    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 }
-                        : {}),
+        {
+            name: "unicli_explore",
+            description: "Auto-discover API endpoints for any URL. Navigates the page, captures network requests, generates YAML adapters.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    url: { type: "string", description: "Website URL to explore" },
+                    goal: {
+                        type: "string",
+                        description: "Capability to find (e.g. 'search', 'hot', 'feed')",
+                    },
                 },
+                required: ["url"],
+            },
+            _meta: {
+                "anthropic/searchHint": "Auto-discover API endpoints for any website URL. Generate YAML adapters for new sites.",
+            },
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: true,
             },
         },
-    };
+    ];
 }
+const expandedRegistry = new Map();
 /**
- * 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.
+ * Build the expanded tool set: 4 default meta-tools + one full tool per
+ * adapter command. Clients see the complete Uni-CLI surface area.
  *
- * 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.
+ * Token cost: ~160K for 956 commands. Use only when the client can handle it.
  */
-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]);
+    tools.push(...buildDefaultTools());
     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();
+    const seen = new Set(DEFAULT_TOOL_NAMES);
     for (const adapter of getAllAdapters()) {
         for (const [cmdName, cmd] of Object.entries(adapter.commands)) {
-            const description = cmd.description?.trim() ||
+            const rawDesc = cmd.description?.trim() ||
                 adapter.description?.trim() ||
                 `${cmdName} for ${adapter.name}`;
             const toolName = buildToolName(adapter.name, cmdName);
@@ -207,30 +175,82 @@ function buildExpandedTools() {
             expandedRegistry.set(toolName, { adapter, cmdName, cmd });
             tools.push({
                 name: toolName,
-                description: `[${adapter.name}] ${description}`,
+                description: truncateDescription(`[${adapter.name}] ${rawDesc}`),
                 inputSchema: buildInputSchema(cmd),
                 outputSchema: buildOutputSchema(cmd),
+                _meta: {
+                    "anthropic/searchHint": `${adapter.name}: ${rawDesc}`,
+                },
+                annotations: {
+                    readOnlyHint: true,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
             });
         }
     }
-    // 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')",
+    return tools;
+}
+/**
+ * Build deferred tool set: 4 default meta-tools with full schemas, plus
+ * lightweight stubs for all adapter commands (name + searchHint only,
+ * minimal inputSchema). Clients like Claude Code's ToolSearch can discover
+ * tools by searchHint and then call them — the handler resolves the full
+ * command at call time via the expandedRegistry.
+ *
+ * Token cost: ~8K (vs ~160K for expanded). 95% reduction.
+ */
+function buildDeferredTools() {
+    const tools = [];
+    tools.push(...buildDefaultTools());
+    expandedRegistry.clear();
+    const seen = new Set(DEFAULT_TOOL_NAMES);
+    for (const adapter of getAllAdapters()) {
+        for (const [cmdName, cmd] of Object.entries(adapter.commands)) {
+            const rawDesc = cmd.description?.trim() ||
+                adapter.description?.trim() ||
+                `${cmdName} for ${adapter.name}`;
+            const toolName = buildToolName(adapter.name, cmdName);
+            if (seen.has(toolName))
+                continue;
+            seen.add(toolName);
+            // Register in the lookup table for runtime dispatch
+            expandedRegistry.set(toolName, { adapter, cmdName, cmd });
+            // Lightweight stub: name + searchHint + minimal schema.
+            // Full inputSchema is resolved at call time via expandedRegistry.
+            tools.push({
+                name: toolName,
+                description: truncateDescription(`[${adapter.name}] ${rawDesc}`),
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        _args: {
+                            type: "object",
+                            description: "Command arguments (pass key-value pairs)",
+                            additionalProperties: true,
+                        },
+                    },
                 },
-            },
-            required: ["url"],
-        },
-    });
+                _meta: {
+                    "anthropic/searchHint": `${adapter.name}: ${rawDesc}`,
+                },
+                annotations: {
+                    readOnlyHint: true,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
+            });
+        }
+    }
     return tools;
 }
+const DEFAULT_TOOL_NAMES = new Set([
+    "unicli_run",
+    "unicli_list",
+    "unicli_search",
+    "unicli_explore",
+    "unicli_discover",
+]);
 // ── Tool Handlers ───────────────────────────────────────────────────────────
 function handleListAdapters(params) {
     let commands = listCommands();
@@ -331,6 +351,21 @@ async function runResolvedCommand(adapter, cmd, cmdName, args) {
         };
     }
 }
+/**
+ * Annotate a tool result with `_meta.anthropic/maxResultSizeChars` when the
+ * serialized payload exceeds MAX_RESULT_SIZE_CHARS (10 KB). This tells
+ * Claude Code to accept large payloads without truncation.
+ */
+export function annotateIfLarge(result) {
+    const totalChars = result.content.reduce((sum, c) => sum + c.text.length, 0);
+    if (totalChars > MAX_RESULT_SIZE_CHARS) {
+        return {
+            ...result,
+            _meta: { "anthropic/maxResultSizeChars": 100_000 },
+        };
+    }
+    return result;
+}
 async function handleRunCommand(params) {
     const site = params.site;
     const command = params.command;
@@ -375,7 +410,7 @@ async function handleRunCommand(params) {
 /**
  * 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
+ * is not in expanded form, so the caller can fall through to default-tool
  * handling (list_adapters / run_command).
  */
 async function handleExpandedTool(toolName, args) {
@@ -394,21 +429,29 @@ async function handleExpandedTool(toolName, args) {
     return runResolvedCommand(entry.adapter, entry.cmd, entry.cmdName, args);
 }
 // ── MCP Protocol Handler ────────────────────────────────────────────────────
-const PROTOCOL_VERSION = "2024-11-05";
+const PROTOCOL_VERSION = "2025-03-26";
 function parseArgs(argv) {
     const opts = {
-        lazy: false,
+        expanded: false,
         transport: "stdio",
         port: 19826,
+        auth: false,
     };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
-        if (a === "--lazy")
-            opts.lazy = true;
+        if (a === "--expanded")
+            opts.expanded = true;
+        else if (a === "--auth")
+            opts.auth = true;
         else if (a === "--transport") {
             const v = argv[++i];
-            if (v === "stdio" || v === "http")
+            if (v === "stdio" || v === "http" || v === "streamable") {
                 opts.transport = v;
+            }
+            else if (v === "sse") {
+                // Deprecated alias — SSE replaced by Streamable HTTP in spec 2025-03-26
+                opts.transport = "streamable";
+            }
         }
         else if (a === "--port") {
             const v = parseInt(argv[++i], 10);
@@ -429,7 +472,7 @@ function buildHandler(tools) {
                     result: {
                         protocolVersion: PROTOCOL_VERSION,
                         capabilities: {
-                            tools: {},
+                            tools: { listChanged: false },
                         },
                         serverInfo: {
                             name: "unicli",
@@ -438,6 +481,8 @@ function buildHandler(tools) {
                     },
                 };
             case "notifications/initialized":
+                // JSON-RPC notifications must not receive responses.
+                // Returning a sentinel that transports check before serializing.
                 return null;
             case "tools/list":
                 return {
@@ -456,17 +501,65 @@ function buildHandler(tools) {
                 }
                 const toolArgs = params.arguments ?? {};
                 switch (params.name) {
+                    // Support both old names (list_adapters, run_command) and new
+                    // names (unicli_list, unicli_run) for backwards compatibility.
+                    case "unicli_list":
                     case "list_adapters": {
                         const result = handleListAdapters(toolArgs);
-                        return { jsonrpc: "2.0", id, result };
+                        return { jsonrpc: "2.0", id, result: annotateIfLarge(result) };
                     }
+                    case "unicli_run":
                     case "run_command":
                         return handleRunCommand(toolArgs).then((result) => ({
                             jsonrpc: "2.0",
                             id,
-                            result,
+                            result: annotateIfLarge(result),
                         }));
+                    case "unicli_search": {
+                        const searchQuery = toolArgs.query;
+                        const searchLimit = toolArgs.limit || 5;
+                        if (!searchQuery) {
+                            return {
+                                jsonrpc: "2.0",
+                                id,
+                                error: {
+                                    code: -32602,
+                                    message: "Missing required parameter: query",
+                                },
+                            };
+                        }
+                        return import("../discovery/search.js").then(({ search: searchFn }) => {
+                            const results = searchFn(searchQuery, searchLimit);
+                            return {
+                                jsonrpc: "2.0",
+                                id,
+                                result: annotateIfLarge({
+                                    content: [
+                                        {
+                                            type: "text",
+                                            text: JSON.stringify({
+                                                query: searchQuery,
+                                                count: results.length,
+                                                results: results.map((r) => ({
+                                                    command: `unicli ${r.site} ${r.command}`,
+                                                    site: r.site,
+                                                    name: r.command,
+                                                    description: r.description,
+                                                    score: r.score,
+                                                    category: r.category,
+                                                    usage: r.usage,
+                                                })),
+                                            }, null, 2),
+                                        },
+                                    ],
+                                }),
+                            };
+                        });
+                    }
+                    case "unicli_explore":
                     case "unicli_discover": {
+                        // unicli_explore is the canonical name (v0.211.1+).
+                        // unicli_discover kept as alias for backwards compatibility.
                         const discoverUrl = toolArgs.url;
                         const discoverGoal = toolArgs.goal;
                         if (!discoverUrl) {
@@ -479,6 +572,17 @@ function buildHandler(tools) {
                                 },
                             };
                         }
+                        if (!discoverUrl.startsWith("http://") &&
+                            !discoverUrl.startsWith("https://")) {
+                            return {
+                                jsonrpc: "2.0",
+                                id,
+                                error: {
+                                    code: -32602,
+                                    message: "URL must start with http:// or https://",
+                                },
+                            };
+                        }
                         return import("node:child_process").then(({ execFile: ef }) => import("node:util").then(({ promisify: prom }) => {
                             const execFileP = prom(ef);
                             const discoverArgs = ["generate", discoverUrl, "--json"];
@@ -490,11 +594,13 @@ function buildHandler(tools) {
                             }).then(({ stdout }) => ({
                                 jsonrpc: "2.0",
                                 id,
-                                result: { content: [{ type: "text", text: stdout }] },
+                                result: annotateIfLarge({
+                                    content: [{ type: "text", text: stdout }],
+                                }),
                             }), (err) => ({
                                 jsonrpc: "2.0",
                                 id,
-                                result: {
+                                result: annotateIfLarge({
                                     content: [
                                         {
                                             type: "text",
@@ -504,20 +610,20 @@ function buildHandler(tools) {
                                         },
                                     ],
                                     isError: true,
-                                },
+                                }),
                             }));
                         }));
                     }
                     default:
                         return handleExpandedTool(params.name, toolArgs).then((result) => {
                             if (result)
-                                return { jsonrpc: "2.0", id, result };
+                                return { jsonrpc: "2.0", id, result: annotateIfLarge(result) };
                             return {
                                 jsonrpc: "2.0",
                                 id,
                                 error: {
-                                    code: -32601,
-                                    message: `Unknown tool: ${params.name}. Use list_adapters to see all available commands.`,
+                                    code: -32602,
+                                    message: `Unknown tool: ${params.name}. Use unicli_list to see available commands.`,
                                 },
                             };
                         });
@@ -596,15 +702,29 @@ async function startStdio(handler) {
  * 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) {
+async function startHttp(handler, port, authEnabled = false) {
+    const oauthMiddleware = authEnabled ? createOAuthMiddleware() : null;
     const server = createServer((req, res) => {
-        if (req.method === "GET" && (req.url === "/" || req.url === "/mcp")) {
+        // OAuth routes (authorize + token) — always public
+        if (authEnabled && handleOAuthRoute(req, res))
+            return;
+        // Health endpoint — always public
+        if (req.method === "GET" &&
+            (req.url === "/" || req.url === "/mcp" || req.url === "/health")) {
             res.writeHead(200, { "Content-Type": "application/json" });
+            const adapterCount = getAllAdapters().length;
+            const commandCount = listCommands().length;
+            // Compute actual expanded tool count: 3 default tools + all adapter commands.
+            let expandedCount = 3; // default tools
+            for (const adapter of getAllAdapters()) {
+                expandedCount += Object.keys(adapter.commands).length;
+            }
             res.end(JSON.stringify({
-                server: "unicli",
+                status: "ok",
+                adapters: adapterCount,
+                commands: commandCount,
+                tools: { default: 3, expanded: expandedCount },
                 version: VERSION,
-                tools: toolCount,
-                protocol: PROTOCOL_VERSION,
             }));
             return;
         }
@@ -613,9 +733,31 @@ async function startHttp(handler, port, toolCount) {
             res.end(JSON.stringify({ error: "POST /mcp" }));
             return;
         }
+        // OAuth middleware — block unauthenticated requests when --auth is set
+        if (oauthMiddleware?.(req, res))
+            return;
+        const MAX_BODY = 1_048_576; // 1 MB
         const chunks = [];
-        req.on("data", (chunk) => chunks.push(chunk));
+        let bodySize = 0;
+        let aborted = false;
+        req.on("data", (chunk) => {
+            bodySize += chunk.length;
+            if (bodySize > MAX_BODY) {
+                aborted = true;
+                res.writeHead(413, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: null,
+                    error: { code: -32600, message: "Request too large" },
+                }));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
         req.on("end", async () => {
+            if (aborted)
+                return;
             const body = Buffer.concat(chunks).toString("utf-8");
             let parsed;
             try {
@@ -632,8 +774,14 @@ async function startHttp(handler, port, toolCount) {
             }
             try {
                 const response = await handler(parsed);
+                if (!response) {
+                    // JSON-RPC notification — no response expected
+                    res.writeHead(204);
+                    res.end();
+                    return;
+                }
                 res.writeHead(200, { "Content-Type": "application/json" });
-                res.end(JSON.stringify(response ?? null));
+                res.end(JSON.stringify(response));
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -661,18 +809,38 @@ async function main() {
     // Load adapters (same as CLI)
     loadAllAdapters();
     await loadTsAdapters();
-    const tools = opts.lazy ? buildLazyTools() : buildExpandedTools();
+    // Three modes:
+    //   default  → 4 meta-tools (~200 tokens)
+    //   expanded → 4 meta-tools + 956 full tool schemas (~160K tokens)
+    //   deferred → 4 meta-tools + 956 lightweight stubs (~8K tokens)
+    const mode = opts.expanded ? "expanded" : "default";
+    const tools = opts.expanded ? buildExpandedTools() : buildDefaultTools();
+    // Deferred mode is auto-activated for Streamable HTTP transport (remote
+    // clients benefit most from searchHint-based discovery).
+    // For explicit control, the expanded flag takes precedence.
+    if (opts.transport === "streamable" && !opts.expanded) {
+        const deferredTools = buildDeferredTools();
+        tools.length = 0;
+        tools.push(...deferredTools);
+    }
     const handler = buildHandler(tools);
     const adapterCount = getAllAdapters().length;
     const commandCount = listCommands().length;
     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`);
+        await startHttp(handler, opts.port, opts.auth);
+        const authLabel = opts.auth ? ", OAuth enabled" : "";
+        process.stderr.write(`unicli MCP server v${VERSION} — ${adapterCount} sites, ${commandCount} commands (${tools.length} tools registered, mode=${mode}${authLabel})\n`);
+        return;
+    }
+    if (opts.transport === "streamable") {
+        await startStreamableHttp(opts.port, handler, { auth: opts.auth });
+        const authLabel = opts.auth ? ", OAuth enabled" : "";
+        process.stderr.write(`unicli MCP server v${VERSION} — ${adapterCount} sites, ${commandCount} commands (${tools.length} tools, mode=${mode}, transport=streamable${authLabel})\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`);
+    process.stderr.write(`unicli MCP server v${VERSION} — ${adapterCount} sites, ${commandCount} commands (${tools.length} tools registered, mode=${mode})\n`);
 }
 main().catch((err) => {
     process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);