superacli 1.1.4 → 1.1.6

package/cli/skills-mcp.js

@@ -0,0 +1,102 @@
+function buildMcpServersUsageSkillMarkdown(options = {}) {
+  const {
+    showDag = false,
+    renderYamlObject,
+    skillId = "mcp.servers.usage",
+  } = options;
+  const frontmatter = {
+    skill_name: "mcp_servers_usage",
+    description:
+      "Teaches agents how to manage and use MCP servers through SuperCLI, including browser-use style SSE bridges.",
+    command: `skills get ${skillId}`,
+    arguments: [
+      { name: "format", type: "string", required: false, description: "Output format, default skill.md" },
+      { name: "show-dag", type: "boolean", required: false, description: "Include internal DAG for agent reasoning" },
+    ],
+    output_schema: { instruction: "string", examples: "array" },
+    metadata: { side_effects: false, risk_level: "safe", dag_supported: true },
+  };
+
+  if (showDag) {
+    frontmatter.dag = [
+      { id: 1, type: "list_or_register_mcp_server" },
+      { id: 2, type: "discover_tools", depends_on: [1] },
+      { id: 3, type: "call_or_bind_tool", depends_on: [2] },
+      { id: 4, type: "execute_bound_command", depends_on: [3] },
+    ];
+  }
+
+  const body = [
+    "# Instruction",
+    "",
+    "Use this workflow to manage and use MCP servers safely in non-interactive agent flows:",
+    "",
+    "1. List registered MCP servers and inspect current state:",
+    "",
+    "```bash",
+    "supercli mcp list --json",
+    "```",
+    "",
+    "2. Register or update an MCP server:",
+    "",
+    "```bash",
+    "# HTTP MCP",
+    "supercli mcp add summarize-local --url http://127.0.0.1:8787 --json",
+    "",
+    "# browser-use style stdio bridge over remote SSE via mcp-remote",
+    "# Provide key at runtime; do not hardcode secrets in repository files",
+    "supercli mcp add browser-use --command npx \\",
+    "  --args-json '[\"mcp-remote\",\"https://api.browser-use.com/mcp\",\"--header\",\"X-Browser-Use-API-Key: ${BROWSER_USE_API_KEY}\"]' \\",
+    "  --env-json '{\"BROWSER_USE_API_KEY\":\"${BROWSER_USE_API_KEY}\"}' \\",
+    "  --json",
+    "```",
+    "",
+    "3. Discover available tools from the configured MCP server:",
+    "",
+    "```bash",
+    "supercli mcp tools --mcp-server browser-use --json",
+    "```",
+    "",
+    "4. Call a discovered tool directly without creating a command first:",
+    "",
+    "```bash",
+    "supercli mcp call --mcp-server browser-use --tool <tool_name> --input-json '{}' --timeout-ms 180000 --json",
+    "```",
+    "",
+    "Reference example (browser-use task creation):",
+    "",
+    "```bash",
+    "supercli mcp call --mcp-server browser-use --tool browser_task --input-json '{\"task\":\"Search Google for the latest iPhone reviews and summarize the top 3 results\"}' --timeout-ms 180000 --json",
+    "```",
+    "",
+    "5. Optionally bind a tool as a stable SuperCLI command alias:",
+    "",
+    "```bash",
+    "supercli mcp bind --mcp-server browser-use --tool <tool_name> --as ai.browser.probe --description \"Probe browser-use MCP\"",
+    "supercli ai browser probe --json",
+    "```",
+    "",
+    "6. Run diagnostics when tools cannot be discovered:",
+    "",
+    "```bash",
+    "supercli mcp doctor --mcp-server browser-use --json",
+    "```",
+    "",
+    "7. Remove stale MCP entries when no longer needed:",
+    "",
+    "```bash",
+    "supercli mcp remove browser-use --json",
+    "```",
+    "",
+    "# Notes",
+    "",
+    "- Prefer passing secrets via runtime environment variables and CLI args, not committed files.",
+    "- If your MCP args/env contain ${ENV_VAR} placeholders, export them before running mcp tools/call/doctor.",
+    "- For named MCP servers, command-level adapter settings override server-level defaults on conflicts.",
+    "- Use `supercli skills teach --format skill.md` for general skills discovery guidance.",
+  ];
+
+  return `---\n${renderYamlObject(frontmatter)}\n---\n\n${body.join("\n")}`;
+}
+
+module.exports = { buildMcpServersUsageSkillMarkdown };

package/cli/skills.js

@@ -1,4 +1,5 @@
 const { createPlan } = require("./planner")
+const { buildMcpServersUsageSkillMarkdown: buildMcpUsage } = require("./skills-mcp")
 
 const PLUGINS_USAGE_SKILL_ID = "plugins.registry.usage"
 const MCP_SERVERS_USAGE_SKILL_ID = "mcp.servers.usage"
@@ -223,46 +224,11 @@ function buildPluginsUsageSkillMarkdown(options = {}) {
 }
 
 function buildMcpServersUsageSkillMarkdown(options = {}) {
-  const includeDag = !!options.showDag
-  const frontmatter = {
-    skill_name: "mcp_servers_usage",
-    description: "Teaches agents how to manage and use MCP servers through SuperCLI, including browser-use style SSE bridges.",
-    command: `skills get ${MCP_SERVERS_USAGE_SKILL_ID}`,
-    arguments: [
-      {
-        name: "format",
-        type: "string",
-        required: false,
-        description: "Output format, default skill.md"
-      },
-      {
-        name: "show-dag",
-        type: "boolean",
-        required: false,
-        description: "Include internal DAG for agent reasoning"
-      }
-    ],
-    output_schema: {
-      instruction: "string",
-      examples: "array"
-    },
-    metadata: {
-      side_effects: false,
-      risk_level: "safe",
-      dag_supported: true
-    }
-  }
-
-  if (includeDag) {
-    frontmatter.dag = [
-      { id: 1, type: "list_mcp_servers" },
-      { id: 2, type: "register_or_update_mcp_server", depends_on: [1] },
-      { id: 3, type: "verify_mcp_server_configuration", depends_on: [2] },
-      { id: 4, type: "execute_mcp_backed_command", depends_on: [3] }
-    ]
-  }
-
-  return `---\n${renderYamlObject(frontmatter)}\n---\n\n# Instruction\n\nUse this workflow to manage and use MCP servers safely in non-interactive agent flows:\n\n1. List registered MCP servers and inspect current state:\n\n\`\`\`bash\nsupercli mcp list --json\n\`\`\`\n\n2. Register or update a server by URL (HTTP MCP):\n\n\`\`\`bash\nsupercli mcp add summarize-local --url http://127.0.0.1:8787 --json\n\`\`\`\n\n3. Register a stdio bridge server (browser-use style over remote SSE using mcp-remote):\n\n\`\`\`bash\n# Provide key at runtime; do not hardcode secrets in repository files\nsupercli mcp add browser-use --command npx \\\n  --args-json '["mcp-remote","https://api.browser-use.com/mcp","--header","X-Browser-Use-API-Key: \${BROWSER_USE_API_KEY}"]' \\\n  --env-json '{"BROWSER_USE_API_KEY":"\${BROWSER_USE_API_KEY}"}' \\\n  --json\n\`\`\`\n\n4. Verify the MCP server registration:\n\n\`\`\`bash\nsupercli mcp list --json\n\`\`\`\n\n5. Execute MCP-backed commands normally once configured:\n\n\`\`\`bash\n# Example command that uses adapter: mcp under the hood\nsupercli ai browser probe --json\n\`\`\`\n\n6. Remove stale MCP entries when no longer needed:\n\n\`\`\`bash\nsupercli mcp remove browser-use --json\n\`\`\`\n\n# Notes\n\n- Prefer passing secrets via runtime environment variables and CLI args, not committed files.\n- For named MCP servers, command-level adapter settings override server-level defaults on conflicts.\n- Use \`supercli skills teach --format skill.md\` for general skills discovery guidance.`
+  return buildMcpUsage({
+    showDag: !!options.showDag,
+    renderYamlObject,
+    skillId: MCP_SERVERS_USAGE_SKILL_ID,
+  })
 }
 
 function listSkillsMetadata(config) {

package/cli/supercli.js

@@ -8,6 +8,7 @@ const {
   setMcpServer,
   removeMcpServer,
   listMcpServers,
+  upsertCommand,
 } = require("./config");
 const { execute } = require("./executor");
 const { buildCapabilities } = require("./help-json");
@@ -209,10 +210,10 @@ function renderTopLevelHelp(config) {
     console.log("\n  Usage: supercli <namespace> <resource> <action> [--args]");
     if (hasServer) console.log("  Sync: supercli sync");
     console.log(
-      "  Plugins: supercli plugins explore | supercli plugins install <name|path> | supercli plugins install --git <repo>",
+      "  Plugins: supercli plugins explore | supercli plugins learn <name> | supercli plugins install <name|path> | supercli plugins install --git <repo>",
     );
     console.log(
-      "  MCP: supercli mcp list | supercli mcp add <name> --url <url> | supercli mcp add <name> --command <cmd> --args-json '[]' | supercli mcp remove <name>",
+      "  MCP: supercli mcp list | supercli mcp add <name> --url <url> | supercli mcp tools --mcp-server <name> | supercli mcp call --mcp-server <name> --tool <tool> | supercli mcp bind --mcp-server <name> --tool <tool> --as <ns.res.act> | supercli mcp doctor --mcp-server <name> | supercli mcp remove <name>",
     );
     console.log(
       "  Skills: supercli skills list | supercli skills get <id> | supercli skills search --query <q> | supercli skills sync",
@@ -370,6 +371,10 @@ async function main() {
         setMcpServer,
         removeMcpServer,
         listMcpServers,
+        loadConfig,
+        executeCommand: execute,
+        upsertCommand,
+        serverUrl: SERVER || "",
       });
       return;
     }

package/docs/initial/mcp-local-mode.md

@@ -17,9 +17,44 @@ For `adapter: mcp`, SUPERCLI resolves the tool endpoint in this order:
 supercli mcp list
 supercli mcp add summarize-local --url http://127.0.0.1:8787
 supercli mcp add browser-use --command npx --args-json '["mcp-remote","https://api.browser-use.com/mcp","--header","X-Browser-Use-API-Key: your-api-key"]'
+supercli mcp tools --mcp-server browser-use --json
+supercli mcp call --mcp-server browser-use --tool <tool_name> --input-json '{}' --timeout-ms 180000
+supercli mcp bind --mcp-server browser-use --tool <tool_name> --as ai.browser.probe
+supercli ai browser probe --json
+supercli mcp doctor --mcp-server browser-use --json
 supercli mcp remove summarize-local
 ```
 
+## Reference Example: browser-use `browser_task`
+
+```bash
+supercli mcp call --mcp-server browser-use --tool browser_task --input-json '{"task":"Search Google for the latest iPhone reviews and summarize the top 3 results"}' --timeout-ms 180000 --json
+```
+
+Typical response shape:
+
+```json
+{
+  "ok": true,
+  "server": "browser-use",
+  "tool": "browser_task",
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "{\"task_id\":\"...\",\"status\":\"Task created and started successfully...\",\"message\":\"TASK CREATED: Run monitor_task with task_id=...\"}"
+      }
+    ]
+  }
+}
+```
+
+When `browser_task` returns a `task_id`, continue with:
+
+```bash
+supercli mcp call --mcp-server browser-use --tool monitor_task --input-json '{"task_id":"<task_id>"}' --timeout-ms 180000 --json
+```
+
 These commands only update local cache (`~/.supercli/config.json`).
 
 Local config also accepts a Claude-style `mcpServers` object and normalizes it to `mcp_servers` internally.

package/docs/mcp-cheatsheet.md

@@ -0,0 +1,324 @@
+# MCP Server Cheatsheet: SSE/HTTP Implementation in Node.js (Pure, No SDKs - Spec v2025-06-18)
+
+<div style="border: 1px solid #ccc; padding: 20px; margin: 10px 0; background-color: #f9f9f9; border-radius: 8px;">
+  <strong>Artifact Note:</strong> This is a pure Node.js implementation cheatsheet for an SSE/HTTP-capable MCP server. It uses only built-in modules (e.g., `http`, `https`, `url`, `querystring`) for bidirectional streaming via JSON-RPC 2.0. No external SDKs or npm packages—ideal for lightweight setups. Expand sections for details.
+</div>
+
+## Overview
+- **MCP Purpose**: Open protocol for AI apps (e.g., LLMs) to access external tools/resources via JSON-RPC 2.0.
+- **Focus**: Pure Node.js server for bidirectional streaming (client-to-server via POST, server-to-client via SSE GET).
+- **Transports**: SSE + HTTP (streamable; single endpoint preferred) or stdio (local-only). SSE enables real-time server pushes like tool calls/notifications.
+- **Key Benefits**: Resumable streams, session management, secure (Origin validation, auth).
+- **Node.js Notes**: Uses `http.Server` for endpoints; manual JSON-RPC parsing; EventEmitter for internal messaging.
+
+<details>
+<summary><strong>Prerequisites (Click to Expand)</strong></summary>
+
+- **Runtime**: Node.js 20+ (LTS recommended for stability).
+- **Modules**: Built-ins only: `http`, `https`, `url`, `querystring`, `crypto` (for sessions), `events` (for pub/sub).
+- **Tools**: Familiarity with JSON-RPC, HTTP/SSE; editor like VS Code.
+- **Security**: Use `https` in prod; validate origins to prevent rebinding. Run with `node server.js`.
+
+</details>
+
+## Transport Types: SSE/HTTP
+| Type | Description | Pros | Cons |
+|------|-------------|------|------|
+| **Streamable HTTP + SSE** | Single endpoint (`/mcp`) for POST (client → server) & GET (SSE stream server → client). | Bidirectional, resumable, efficient for remote. | Manual SSE flushing; manage sessions. |
+| **HTTP Only** | POST for all; no streaming. | Simple. | No real-time pushes. |
+| **Stdio** | Local stdin/stdout (not HTTP). | Fast for desktop. | Non-remote. |
+
+- **Protocol Version**: Client sends `MCP-Protocol-Version: 2025-06-18` header; server rejects invalid (400 Bad Request).
+
+<details>
+<summary><strong>Server Setup Steps (Click to Expand)</strong></summary>
+
+1. **Init Project**:  
+   Create `server.js` and `package.json` (for scripts, no deps):  
+   ```json
+   // package.json
+   {"name": "mcp-server", "scripts": {"start": "node server.js"}}
+   ```
+
+2. **Create HTTP Server Instance**:  
+   ```javascript
+   const http = require('http');
+   const url = require('url');
+   const { EventEmitter } = require('events');
+   const crypto = require('crypto');
+
+   const server = http.createServer(handleRequest);
+   const emitter = new EventEmitter();  // For internal pub/sub (e.g., server pushes)
+
+   function handleRequest(req, res) {
+     const parsedUrl = url.parse(req.url, true);
+     const method = req.method;
+     const pathname = parsedUrl.pathname;
+
+     // Validate protocol version
+     if (!req.headers['mcp-protocol-version'] || req.headers['mcp-protocol-version'] !== '2025-06-18') {
+       res.writeHead(400, { 'Content-Type': 'application/json' });
+       res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32600, message: 'Invalid Protocol Version' } }));
+       return;
+     }
+
+     if (pathname === '/mcp' || pathname === '/messages/') {
+       if (method === 'POST') {
+         handlePost(req, res, emitter);
+       } else if (method === 'GET') {
+         handleSSE(req, res, emitter);
+       } else if (method === 'DELETE') {
+         handleDelete(req, res);
+       } else {
+         res.writeHead(405);
+         res.end();
+       }
+     } else {
+       res.writeHead(404);
+       res.end();
+     }
+   }
+   ```
+
+3. **Define Tools/Resources** (Manual Dispatch):  
+   Use a map for methods (tools/resources).  
+   ```javascript
+   const tools = {
+     example_tool: async (params) => `Processed: ${params.param}`,
+     // Add async funcs for I/O
+   };
+
+   const resources = {
+     'example://{id}': (id) => `Resource data for ${id}`,
+   };
+
+   // In handlePost: Parse method, dispatch
+   async function dispatchMethod(method, params, id, sessionId) {
+     if (tools[method]) {
+       try {
+         const result = await tools[method](params);
+         return { jsonrpc: '2.0', result, id };
+       } catch (e) {
+         return { jsonrpc: '2.0', error: { code: -32000, message: e.message }, id };
+       }
+     } else if (method.startsWith('resources/')) {
+       // Handle resources similarly
+     }
+     return { jsonrpc: '2.0', error: { code: -32601, message: 'Method Not Found' }, id };
+   }
+   ```
+
+4. **Setup SSE Transport**:  
+   Manual SSE handling with keep-alives.  
+   ```javascript
+   function handleSSE(req, res, emitter) {
+     const sessionId = req.headers['mcp-session-id'];
+     if (!sessionId) {
+       res.writeHead(401);
+       res.end('Missing Session ID');
+       return;
+     }
+
+     res.writeHead(200, {
+       'Content-Type': 'text/event-stream',
+       'Cache-Control': 'no-cache',
+       'Connection': 'keep-alive',
+       'Access-Control-Allow-Origin': req.headers.origin || '*',  // Validate in prod
+     });
+
+     let lastEventId = req.headers['last-event-id'] || '0';
+     // Resume logic: Replay events > lastEventId (store in session map)
+
+     const heartbeat = setInterval(() => {
+       res.write(`: heartbeat\n\n`);  // Keep-alive
+     }, 15000);
+
+     // Listen for server pushes
+     const listener = (msg) => {
+       if (msg.sessionId === sessionId && msg.eventId > parseInt(lastEventId)) {
+         res.write(`id: ${msg.eventId}\ndata: ${JSON.stringify(msg.data)}\n\n`);
+         lastEventId = msg.eventId.toString();
+       }
+     };
+     emitter.on('push', listener);
+
+     req.on('close', () => {
+       clearInterval(heartbeat);
+       emitter.off('push', listener);
+       res.end();
+     });
+   }
+   ```
+
+5. **Handle POST (Client Messages)**:  
+   Parse JSON-RPC, dispatch, respond or push via SSE.  
+   ```javascript
+   function handlePost(req, res, emitter) {
+     let body = '';
+     req.on('data', chunk => body += chunk);
+     req.on('end', async () => {
+       try {
+         const msg = JSON.parse(body);
+         if (!msg.jsonrpc || msg.jsonrpc !== '2.0') throw new Error('Invalid JSON-RPC');
+
+         const sessionId = req.headers['mcp-session-id'] || generateSessionId();
+         res.setHeader('Mcp-Session-Id', sessionId);
+
+         if (msg.id !== undefined) {  // Request
+           const response = await dispatchMethod(msg.method, msg.params || {}, msg.id, sessionId);
+           res.writeHead(202, { 'Content-Type': 'application/json' });
+           res.end(JSON.stringify(response));
+         } else {  // Notification
+           await dispatchMethod(msg.method, msg.params || {}, null, sessionId);  // Fire-and-forget
+           res.writeHead(202);
+           res.end();
+         }
+
+         // For server-initiated pushes (e.g., notifications)
+         emitter.emit('push', { sessionId, eventId: Date.now(), data: { /* response */ } });
+       } catch (e) {
+         res.writeHead(400, { 'Content-Type': 'application/json' });
+         res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32700, message: 'Parse Error' } }));
+       }
+     });
+   }
+
+   function generateSessionId() {
+     return crypto.randomUUID();
+   }
+   ```
+
+6. **Run Server**:  
+   ```javascript
+   server.listen(8000, '127.0.0.1', () => {
+     console.log('MCP Server running on http://127.0.0.1:8000');
+   });
+   ```
+   - For HTTPS: Replace `http` with `https`, provide key/cert.
+
+</details>
+
+## Endpoints
+| Method | Path | Purpose | Headers/Body |
+|--------|------|---------|--------------|
+| **POST** | `/mcp` (or `/messages/`) | Client sends JSON-RPC (requests/notifications). | `Accept: application/json, text/event-stream`<br>Body: JSON-RPC msg |
+| **GET** | `/mcp` (or `/sse/`) | Open SSE stream for server pushes (requests/notifications). | `Accept: text/event-stream`<br>`Last-Event-ID` (for resume) |
+| **DELETE** | `/mcp` | Terminate session. | `Mcp-Session-Id` header |
+
+- **Responses**:  
+  - POST: 202 Accepted (no body) or JSON.  
+  - Errors: 400/404/500 with JSON-RPC error body (no `id` for non-requests).  
+- **Keep-Alives**: SSE heartbeats every 15s; close after response.
+
+<details>
+<summary><strong>Message Formats (JSON-RPC 2.0) (Click to Expand)</strong></summary>
+
+- **Request** (Client → Server):  
+  ```json
+  {"jsonrpc": "2.0", "method": "tool_name", "params": {"key": "value"}, "id": 1}
+  ```
+- **Notification** (No response expected): Omit `id`.  
+- **Response** (Server → Client):  
+  ```json
+  {"jsonrpc": "2.0", "result": "value", "id": 1}
+  ```
+- **Error**:  
+  ```json
+  {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": 1}
+  ```
+- **SSE Events**: `data: <JSON>\n\n` (UTF-8); unique `id` for resumability.  
+- **Session**: Server assigns `Mcp-Session-Id` in response header; client echoes in headers.
+
+</details>
+
+## Security & Authentication
+- **Basics**: Use `https.createServer` in prod; validate `Origin` header (reject mismatches).  
+  ```javascript
+  // In handleRequest
+  if (req.headers.origin !== 'https://trusted-client.com') {
+    res.writeHead(403);
+    res.end();
+    return;
+  }
+  ```
+- **Auth**:  
+  - API keys in headers (e.g., `Authorization: Bearer <token>`—verify manually).  
+  - Sessions: Store in Map (e.g., `sessions.set(sessionId, { expires: Date.now() + 3600000 })`); expire after 1h inactivity (404).  
+- **Best Practices**: User approval for tools; no embedded newlines in msgs; log to console.error.
+
+<details>
+<summary><strong>Error Handling (Click to Expand)</strong></summary>
+
+- **Common Codes**: -32600 (Invalid Req), -32601 (Method Not Found), -32700 (Parse Error).  
+- **Implementation**:  
+  ```javascript
+  try {
+    // Tool logic (e.g., fetch)
+    const response = await fetch(url, { timeout: 30000 });
+    if (!response.ok) throw new Error('HTTP Error');
+    return await response.json();
+  } catch (e) {
+    return { jsonrpc: '2.0', error: { code: -32000, message: e.message }, id };
+  }
+  ```
+- **Disconnections**: Don't cancel on close; require explicit `CancelledNotification`. Resume via `Last-Event-ID` (store events per session in a Map).
+
+</details>
+
+<details>
+<summary><strong>Example: Full Pure Node.js SSE MCP Server (Click to Expand)</strong></summary>
+
+```javascript
+// server.js
+const http = require('http');
+const url = require('url');
+const { EventEmitter } = require('events');
+const crypto = require('crypto');
+
+const emitter = new EventEmitter();
+const sessions = new Map();  // Simple session store
+
+const server = http.createServer(handleRequest);
+server.listen(8000, '127.0.0.1', () => console.log('MCP Server on http://127.0.0.1:8000'));
+
+const tools = {
+  echo: async (params) => `Echo: ${params.message}`,
+};
+
+async function dispatchMethod(method, params, id, sessionId) {
+  if (tools[method]) {
+    try {
+      const result = await tools[method](params);
+      emitter.emit('push', { sessionId, eventId: Date.now(), data: { jsonrpc: '2.0', result, id } });
+      return { jsonrpc: '2.0', result, id };
+    } catch (e) {
+      return { jsonrpc: '2.0', error: { code: -32000, message: e.message }, id };
+    }
+  }
+  return { jsonrpc: '2.0', error: { code: -32601, message: 'Method Not Found' }, id };
+}
+
+function handleRequest(req, res) {
+  // ... (as in steps above)
+  // Integrate dispatchMethod, handlePost, handleSSE
+}
+
+function handlePost(req, res, emitter) {
+  // ... (as in steps above)
+}
+
+function handleSSE(req, res, emitter) {
+  // ... (as in steps above)
+}
+
+function generateSessionId() {
+  return crypto.randomUUID();
+}
+```
+- **Test**: POST to `/mcp` with JSON-RPC (e.g., via curl: `curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"echo","params":{"message":"hi"},"id":1}' http://localhost:8000/mcp`); GET `/mcp` for SSE. Config client: `{"url": "http://localhost:8000/mcp"}`.
+
+For HTTPS or advanced deployment (e.g., PM2), extend with `https` module.
+
+</details>
+
+---

package/docs/plugins.md

@@ -16,6 +16,8 @@ dcli plugins list
 dcli plugins explore
 dcli plugins explore --name commiat
 dcli plugins explore --tags git,ai
+dcli plugins explore --has-learn true --installed false --source bundled --limit 10 --json
+dcli plugins learn <plugin-name>
 dcli plugins install <plugin-name>
 dcli plugins install --git https://github.com/org/repo.git --manifest-path plugins/supercli/plugin.json --ref main
 dcli plugins show <plugin-name>
@@ -38,7 +40,12 @@ Default is `fail`.
 
 - `plugins list` shows installed plugins.
 - `plugins explore` shows discoverable plugins from `plugins/plugins.json`.
+- `plugins explore` supports filters: `--name`, `--tags`, `--has-learn true|false`, `--installed true|false`, `--source bundled|git`, `--limit <n>`.
+- `plugins explore --json` includes `has_learn`, `installed`, and `filters` metadata so agents can prioritize plugins with learning content.
+- `plugins learn <name>` prints plugin-provided learning content before or after install.
 - `plugins install` supports local path, registry name, and direct remote git manifest installs.
+- Plugin manifests can define `learn` content via `learn.text` or `learn.file` (path inside plugin folder).
 - Plugin manifests can define `post_install` hooks (`script`, optional `runtime`, optional `timeout_ms`) that execute from the plugin folder after install.
 - `agency-agents` is a bundled zero-command plugin. Installing it adds a remote skills provider named `agency-agents` and refreshes the local skills catalog.
 - `visual-explainer` is a bundled zero-command plugin. Installing it adds a remote skills provider named `visual-explainer` sourced from normalized markdown skills in `javimosch/visual-explainer` and refreshes the local skills catalog.
+- `browser-use` is a bundled hybrid plugin. Installing it auto-registers a `browser-use` MCP server, discovers and binds Browser Use MCP tools into direct `browseruse.tool.*` commands, and installs local Browser Use skills from the plugin folder.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superacli",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "Config-driven, AI-friendly dynamic CLI",
   "license": "MIT",
   "main": "server/app.js",

package/plugins/browser-use/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "browser-use",
+  "version": "0.1.0",
+  "description": "Hybrid browser-use plugin: auto-register MCP server, bind MCP tools as commands, and install local usage skills",
+  "source": "https://api.browser-use.com/mcp",
+  "checks": [
+    { "type": "binary", "name": "npx" }
+  ],
+  "learn": {
+    "file": "skills/quickstart/SKILL.md"
+  },
+  "post_install": {
+    "script": "scripts/post-install.js",
+    "runtime": "node",
+    "timeout_ms": 15000
+  },
+  "post_uninstall": {
+    "script": "scripts/post-uninstall.js",
+    "runtime": "node",
+    "timeout_ms": 15000
+  },
+  "commands": []
+}