superacli 1.1.22 → 1.1.26

package/cli/plugins-manager.js

@@ -1,10 +1,10 @@
 const fs = require("fs")
 const path = require("path")
-const os = require("os")
 const { spawnSync } = require("child_process")
 const { SUPPORTED_ADAPTERS } = require("./adapter-schema")
 const { getRegistryPlugin } = require("./plugins-registry")
 const { getPluginInstallGuidance } = require("./plugin-install-guidance")
+const { syncClientPluginResources } = require("./config")
 const {
   readPluginsLock,
   writePluginsLock,
@@ -78,6 +78,36 @@ function parseManifestFile(manifestPath) {
       recoverable: false
     })
   }
+  
+  // Validate server_resources if present
+  if (raw.server_resources) {
+    if (typeof raw.server_resources !== "object" || Array.isArray(raw.server_resources)) {
+      throw Object.assign(new Error("Invalid plugin manifest: server_resources must be an object"), {
+        code: 85,
+        type: "invalid_argument",
+        recoverable: false
+      })
+    }
+    
+    // Validate mcp resources
+    if (raw.server_resources.mcp && !Array.isArray(raw.server_resources.mcp)) {
+      throw Object.assign(new Error("Invalid plugin manifest: server_resources.mcp must be an array"), {
+        code: 85,
+        type: "invalid_argument",
+        recoverable: false
+      })
+    }
+    
+    // Validate spec resources
+    if (raw.server_resources.specs && !Array.isArray(raw.server_resources.specs)) {
+      throw Object.assign(new Error("Invalid plugin manifest: server_resources.specs must be an array"), {
+        code: 85,
+        type: "invalid_argument",
+        recoverable: false
+      })
+    }
+  }
+  
   return raw
 }
 
@@ -504,6 +534,7 @@ function installPlugin(ref, options = {}) {
       installed_at: new Date().toISOString(),
       commands: installedCommands,
       checks: manifest.checks || [],
+      server_resources: manifest.server_resources || {},
       lifecycle_hooks: {
         post_uninstall: serializeHook(loaded.manifestPath, manifest.post_uninstall, "post_uninstall")
       }
@@ -511,6 +542,15 @@ function installPlugin(ref, options = {}) {
 
     const postInstall = runPostInstall(manifest, loaded.manifestPath)
     writePluginsLock(lock)
+    
+    // Sync client plugin resources to server if SUPERCLI_SERVER is set (fire and forget)
+    const server = process.env.SUPERCLI_SERVER
+    if (server && manifest.server_resources) {
+      syncClientPluginResources(server).catch(err => {
+        console.warn(`[Plugin ${manifest.name}] Failed to sync resources to server:`, err.message)
+      })
+    }
+    
     return {
       plugin: manifest.name,
       version: manifest.version || "0.0.0",

package/cli/server-command.js

@@ -2,6 +2,7 @@ const fs = require("fs")
 const path = require("path")
 
 const SERVER = process.env.SUPERCLI_SERVER
+const API_KEY = process.env.SUPERCLI_API_KEY
 
 function getServerUrl() {
   return SERVER ? SERVER.replace(/\/$/, "") : null
@@ -13,12 +14,17 @@ async function serverFetch(endpoint, options = {}) {
     throw new Error("SUPERCLI_SERVER not set. Set it to your server URL.")
   }
   const url = `${base}${endpoint}`
+  const headers = {
+    "Content-Type": "application/json",
+    "Accept": "application/json",
+    ...options.headers,
+  }
+  if (API_KEY) {
+    headers["X-API-Key"] = API_KEY
+  }
   const res = await fetch(url, {
     ...options,
-    headers: {
-      "Content-Type": "application/json",
-      ...options.headers,
-    },
+    headers,
   })
   if (!res.ok) {
     const text = await res.text()
@@ -76,6 +82,8 @@ async function handleServerCommand(options) {
         return await handleOpenapi({ action, arg, flags, humanMode, output })
       case "jobs":
         return await handleJobs({ action, flags, humanMode, output, outputHumanTable })
+      case "adapters":
+        return await handleAdapters({ action, arg, flags, humanMode, output, outputHumanTable, positional })
       default:
         outputError({ code: 85, type: "invalid_argument", message: `Unknown server resource: ${resource}`, recoverable: false })
         return true
@@ -392,4 +400,166 @@ async function handleJobs({ action, flags, humanMode, output, outputHumanTable }
   throw new Error(`Unknown jobs action: ${action}. Use: list, prune`)
 }
 
+async function handleAdapters({ action, arg, flags, humanMode, output, outputHumanTable, positional }) {
+  if (action === "list") {
+    const data = await serverFetch("/api/adapters?format=json")
+    if (humanMode) {
+      console.log("\n  ⚡ Adapters\n")
+      outputHumanTable(data.adapters, [
+        { key: "name", label: "Name" },
+        { key: "execution_context", label: "Context" },
+        { key: "timeout_ms", label: "Timeout" },
+        { key: "allow_network", label: "Network" },
+      ])
+      console.log("")
+    } else {
+      output(data)
+    }
+    return true
+  }
+
+  if (action === "add") {
+    let payload
+    const jsonPath = flags["from-file"]
+    const sourcePath = flags["source-file"]
+    const jsonData = positional[3]
+
+    if (jsonPath) {
+      payload = readJsonFile(jsonPath)
+      if (sourcePath) {
+        payload.source = fs.readFileSync(path.resolve(sourcePath), "utf-8")
+      }
+    } else if (sourcePath) {
+      if (!jsonData) {
+        throw new Error("Usage: supercli server adapters add '{metadata}' --source-file <path>")
+      }
+      payload = JSON.parse(jsonData)
+      payload.source = fs.readFileSync(path.resolve(sourcePath), "utf-8")
+    } else if (flags["from-stdin"]) {
+      let stdinData = ""
+      for await (const chunk of process.stdin) {
+        stdinData += chunk
+      }
+      payload = JSON.parse(stdinData)
+    } else if (jsonData) {
+      payload = JSON.parse(jsonData)
+    } else {
+      throw new Error("Usage: supercli server adapters add '{json}' or --from-file <path> or --source-file <path>")
+    }
+
+    if (!payload.name || !payload.source) {
+      throw new Error("Adapter requires 'name' and 'source' fields")
+    }
+
+    const result = await serverFetch("/api/adapters", {
+      method: "POST",
+      body: JSON.stringify(payload),
+    })
+    output(result)
+    return true
+  }
+
+  if (action === "remove") {
+    const adapterName = positional[3]
+    if (!adapterName) {
+      throw new Error("Usage: supercli server adapters remove <name>")
+    }
+    const result = await serverFetch(`/api/adapters/${encodeURIComponent(adapterName)}`, {
+      method: "DELETE",
+    })
+    output(result)
+    return true
+  }
+
+  if (action === "update") {
+    const adapterName = positional[3]
+    const updateData = positional[4]
+    if (!adapterName) {
+      throw new Error("Usage: supercli server adapters update <name> '{json}' or --from-file <path>")
+    }
+    let payload
+    const jsonPath = flags["from-file"]
+    const sourcePath = flags["source-file"]
+
+    if (jsonPath) {
+      payload = readJsonFile(jsonPath)
+      if (sourcePath) {
+        payload.source = fs.readFileSync(path.resolve(sourcePath), "utf-8")
+      }
+    } else if (sourcePath) {
+      payload = JSON.parse(updateData || "{}")
+      payload.source = fs.readFileSync(path.resolve(sourcePath), "utf-8")
+    } else if (flags["from-stdin"]) {
+      let stdinData = ""
+      for await (const chunk of process.stdin) {
+        stdinData += chunk
+      }
+      payload = JSON.parse(stdinData)
+    } else {
+      payload = JSON.parse(updateData || "{}")
+    }
+
+    const result = await serverFetch(`/api/adapters/${encodeURIComponent(adapterName)}`, {
+      method: "PUT",
+      body: JSON.stringify(payload),
+    })
+    output(result)
+    return true
+  }
+
+  if (action === "packages") {
+    const packageAction = arg
+    const targetAdapterName = positional[4]
+
+    if (!targetAdapterName) {
+      throw new Error("Usage: supercli server adapters packages <list|add|remove> <name>")
+    }
+
+    if (packageAction === "list") {
+      const data = await serverFetch(`/api/adapters/${encodeURIComponent(targetAdapterName)}/packages?format=json`)
+      if (humanMode) {
+        console.log(`\n  ⚡ Packages for ${targetAdapterName}\n`)
+        outputHumanTable(data.packages || [], [
+          { key: "package", label: "Package" },
+          { key: "version", label: "Version" },
+        ])
+        console.log("")
+      } else {
+        output(data)
+      }
+      return true
+    }
+
+    if (packageAction === "add") {
+      const packageName = flags.package
+      const version = flags.version
+      if (!packageName) {
+        throw new Error("Usage: supercli server adapters packages add <name> --package <pkg> --version <ver>")
+      }
+      const result = await serverFetch(`/api/adapters/${encodeURIComponent(targetAdapterName)}/packages`, {
+        method: "POST",
+        body: JSON.stringify({ package: packageName, version }),
+      })
+      output(result)
+      return true
+    }
+
+    if (packageAction === "remove") {
+      const packageName = flags.package
+      if (!packageName) {
+        throw new Error("Usage: supercli server adapters packages remove <name> --package <pkg>")
+      }
+      const result = await serverFetch(`/api/adapters/${encodeURIComponent(targetAdapterName)}/packages/${encodeURIComponent(packageName)}`, {
+        method: "DELETE",
+      })
+      output(result)
+      return true
+    }
+
+    throw new Error(`Unknown packages action: ${packageAction}. Use: list, add, remove`)
+  }
+
+  throw new Error(`Unknown adapters action: ${action}. Use: list, add, remove, update, packages`)
+}
+
 module.exports = { handleServerCommand }

package/cli/supercli.js

@@ -9,6 +9,7 @@ const {
   removeMcpServer,
   listMcpServers,
   upsertCommand,
+  getClientId,
 } = require("./config");
 const { execute } = require("./executor");
 const { buildCapabilities } = require("./help-json");
@@ -25,6 +26,7 @@ const { handleAskCommand } = require("./ask");
 const { handleSkillsCommand } = require("./skills");
 const { findNamespacePassthrough } = require("./namespace-passthrough");
 const { discoverPluginsByIntent } = require("./discover");
+const { startDaemon, stopDaemon, getDaemonStatus, writeLog } = require("./daemon");
 
 const SERVER = process.env.SUPERCLI_SERVER;
 const hasServer = !!SERVER;
@@ -236,7 +238,7 @@ function renderTopLevelHelp(config) {
       console.log('  AI: supercli ask "<your natural language query>"   # LLM-powered suggestions (no execution)');
     }
     console.log("  Server: supercli --server");
-    console.log("  Server CLI: supercli server status | supercli server plugins <list|add|remove> | supercli server mcp <list|add|remove> | supercli server commands <list|add|remove> | supercli server jobs <list|prune>");
+    console.log("  Server CLI: supercli server status | supercli server plugins <list|add|remove> | supercli server mcp <list|add|remove> | supercli server commands <list|add|remove> | supercli server jobs <list|prune> | supercli server adapters <list|add|remove|update> | supercli server adapters packages <list|add|remove> <name>");
     console.log(
       "  Flags: --help | --json | --human | --compact | --schema | --help-json | --server\n",
     );
@@ -570,6 +572,29 @@ async function main() {
       return;
     }
 
+    if (positional[0] === "daemon") {
+      const subcommand = positional[1] || "status";
+      switch (subcommand) {
+        case "start":
+          output(startDaemon());
+          break;
+        case "stop":
+          output(stopDaemon());
+          break;
+        case "status":
+          output(getDaemonStatus());
+          break;
+        default:
+          outputError({
+            code: 85,
+            type: "invalid_argument",
+            message: "Unknown daemon subcommand. Use: start|stop|status",
+            recoverable: false,
+          });
+      }
+      return;
+    }
+
     if (positional[0] === "commands") {
       const config = await loadConfig(SERVER);
       const namespaceFilter = flags.namespace
@@ -959,20 +984,15 @@ async function main() {
       data: result,
     };
 
-    // Post job record (async, non-blocking)
-    if (hasServer) {
-      fetch(`${SERVER}/api/jobs`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          command: `${namespace}.${resource}.${action}`,
-          args: uFlags,
-          status: "success",
-          duration_ms: duration,
-          timestamp: new Date().toISOString(),
-        }),
-      }).catch(() => {}); // silent fail
-    }
+    // Write job record to local log (daemon will sync to server)
+    writeLog({
+      command: `${namespace}.${resource}.${action}`,
+      args: uFlags,
+      status: "success",
+      duration_ms: duration,
+      timestamp: new Date().toISOString(),
+      client_id: getClientId(),
+    });
 
     if (humanMode) {
       process.stderr.write(

package/docs/changelog-2026-04.html

@@ -158,6 +158,11 @@
             <li>Add server dashboard with command overview and job monitoring</li>
             <li>Add adapter management UI with package installation and configuration</li>
             <li>Add 12 new plugins: biome, bore, ccf-deadlines, code2prompt, dua-cli, forever, gitmoji-cli, quarto, readme-md-generator, vale, volta, wgcf</li>
+            <li>Add authentication system for API endpoints with public_access flag and API key management</li>
+            <li>Add daemon for background job log syncing to server</li>
+            <li>Add client tracking with client_id in job records</li>
+            <li>Add API keys management UI with create, list, copy, and delete functionality</li>
+            <li>Add clients.ejs for client management view</li>
           </ul>
         </section>
 
@@ -188,6 +193,7 @@
           </h2>
           <ul class="space-y-2 text-slate-300">
             <li>Bump version to 1.1.14</li>
+            <li>Bump version to 1.1.23</li>
           </ul>
         </section>
 

package/docs/index.html

@@ -103,6 +103,9 @@
         background: #333333;
         transform: scale(1.05);
       }
+      .radial-gradient {
+        background: radial-gradient(circle at 30% 50%, rgba(0, 0, 0, 0.03) 0%, transparent 70%);
+      }
     </style>
   </head>
   <body class="bg-[#FBFBFA]">
@@ -114,6 +117,9 @@
             <h1 class="text-2xl font-semibold mt-3 text-[#111111]">supercli</h1>
             <p class="text-sm text-[#787774] mt-1">Universal Capability Router</p>
           </div>
+          <div id="backToServerUI" class="hidden">
+            <a href="/" class="block px-3 py-2 text-sm text-[#1F6C9F] hover:bg-[#F7F6F3] rounded-md">← Back to Server UI</a>
+          </div>
           <nav class="space-y-6">
             <div>
               <p class="text-xs uppercase tracking-widest text-[#787774] mb-3">Overview</p>
@@ -155,6 +161,46 @@
         </header>
 
         <main class="flex-1 overflow-y-auto bg-[#FBFBFA]">
+          <!-- Hero Section -->
+          <section class="relative px-8 py-20 bg-[#FBFBFA]">
+            <div class="absolute inset-0 opacity-[0.03] radial-gradient"></div>
+            <div class="max-w-5xl relative z-10">
+              <div class="space-y-8 scroll-reveal">
+                <div class="space-y-4">
+                  <span class="tag px-3 py-1 inline-block">The Capability Layer</span>
+                  <h2 class="editorial-heading text-6xl font-medium text-[#111111] leading-[1.1]">
+                    Turn every tool into<br/>a discoverable capability
+                  </h2>
+                </div>
+                
+                <div class="max-w-2xl space-y-4 text-[#2F3437] text-lg">
+                  <p>supercli standardizes inputs, outputs, and execution across 999+ bundled plugins — from AWS, GitHub, Docker, to Kubernetes and beyond.</p>
+                </div>
+
+                <div class="flex flex-wrap gap-8 pt-4">
+                  <div class="space-y-1">
+                    <p class="text-4xl font-semibold text-[#111111]">999+</p>
+                    <p class="text-sm text-[#787774]">Bundled plugins</p>
+                  </div>
+                  <div class="space-y-1">
+                    <p class="text-4xl font-semibold text-[#111111]">Zero</p>
+                    <p class="text-sm text-[#787774]">Setup required</p>
+                  </div>
+                  <div class="space-y-1">
+                    <p class="text-4xl font-semibold text-[#111111]">One</p>
+                    <p class="text-sm text-[#787774]">Consistent interface</p>
+                  </div>
+                </div>
+
+                <div class="pt-6">
+                  <a href="plugins.html" class="inline-block px-8 py-4 bg-[#111111] text-white text-sm font-medium rounded-md hover:bg-[#333333] transition-colors">
+                    Explore 999+ Plugins
+                  </a>
+                </div>
+              </div>
+            </div>
+          </section>
+
           <section class="border-b border-[#EAEAEA] bg-white px-8 py-12">
             <div class="max-w-5xl">
               <p class="text-xs uppercase tracking-[0.2em] text-[#787774] mb-4">Quick filter</p>
@@ -195,14 +241,21 @@ supercli skills get beads.issue.create</code></pre>
                 <h2 class="editorial-heading text-5xl font-medium text-[#111111]">Capability Sources</h2>
               </div>
               <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+                <div class="bento-card p-6 md:col-span-2 bg-[#E1F3FE]/10 border-[#E1F3FE]/30">
+                  <div class="flex items-start justify-between gap-4">
+                    <div class="space-y-3">
+                      <h3 class="font-semibold text-[#111111]">Plugin Harnesses</h3>
+                      <p class="text-[#2F3437] text-sm">999 bundled plugins (gh, aws, gcloud, az, docker, kubectl, terraform, stripe, supabase, and many more) via <code class="mono-text bg-[#F7F6F3] px-1 py-0.5 rounded text-xs border border-[#EAEAEA]">supercli plugins install</code>.</p>
+                    </div>
+                    <a href="plugins.html" class="inline-flex items-center px-4 py-2 bg-[#111111] text-white text-sm font-medium rounded-md hover:bg-[#333333] transition-colors whitespace-nowrap">
+                      Explore Plugins
+                    </a>
+                  </div>
+                </div>
                 <div class="bento-card p-6">
                   <h3 class="font-semibold text-[#111111] mb-2">Built-in Adapters</h3>
                   <p class="text-[#2F3437] text-sm">OpenAPI specs, raw HTTP, and MCP servers become capabilities automatically.</p>
                 </div>
-                <div class="bento-card p-6">
-                  <h3 class="font-semibold text-[#111111] mb-2">Plugin Harnesses</h3>
-                  <p class="text-[#2F3437] text-sm">999 bundled plugins (gh, aws, gcloud, az, docker, kubectl, terraform, stripe, supabase, and many more) via <code class="mono-text bg-[#F7F6F3] px-1 py-0.5 rounded text-xs border border-[#EAEAEA]">supercli plugins install</code>.</p>
-                </div>
                 <div class="bento-card p-6">
                   <h3 class="font-semibold text-[#111111] mb-2">AI Plans / Workflows</h3>
                   <p class="text-[#2F3437] text-sm">Natural language <code class="mono-text bg-[#F7F6F3] px-1 py-0.5 rounded text-xs border border-[#EAEAEA]">ask</code> and <code class="mono-text bg-[#F7F6F3] px-1 py-0.5 rounded text-xs border border-[#EAEAEA]">plan</code> commands create DAGs of capabilities.</p>
@@ -281,14 +334,21 @@ supercli plugins show &lt;name&gt;</code></pre>
                 <h2 class="editorial-heading text-5xl font-medium text-[#111111]">More Documentation</h2>
               </div>
               <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+                <a href="plugins.html" class="bento-card p-6 md:col-span-2 bg-[#E1F3FE]/10 border-[#E1F3FE]/30 hover:border-[#E1F3FE]/50 transition-colors">
+                  <div class="flex items-start justify-between gap-4">
+                    <div class="space-y-2">
+                      <h3 class="font-semibold text-[#111111] mono-text text-sm">Plugin Directory</h3>
+                      <p class="text-[#2F3437] text-sm">Browse all 999+ plugins — from AWS and GitHub to Docker, Kubernetes, and beyond.</p>
+                    </div>
+                    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#111111" stroke-width="2" class="flex-shrink-0 mt-1">
+                      <path d="M5 12h14M12 5l7 7-7 7"/>
+                    </svg>
+                  </div>
+                </a>
                 <div class="bento-card p-6">
                   <h3 class="font-semibold text-[#111111] mb-2 mono-text text-sm">README.md</h3>
                   <p class="text-[#2F3437] text-sm">Repository root documentation</p>
                 </div>
-                <a href="plugins.html" class="bento-card p-6 hover:border-[#111111] transition-colors">
-                  <h3 class="font-semibold text-[#111111] mb-2 mono-text text-sm">Plugin Directory</h3>
-                  <p class="text-[#2F3437] text-sm">Browse all 999 plugins</p>
-                </a>
                 <div class="bento-card p-6">
                   <h3 class="font-semibold text-[#111111] mb-2 mono-text text-sm">docs/skills-catalog.md</h3>
                   <p class="text-[#2F3437] text-sm">Skills reference catalog</p>
@@ -434,6 +494,33 @@ supercli plugins show &lt;name&gt;</code></pre>
       }
       loadServerDocs();
 
+      // Show "Back to Server UI" link if fromServerUI parameter is present
+      const urlParams = new URLSearchParams(window.location.search);
+      const fromServerUI = urlParams.get('fromServerUI') === '1';
+      
+      if (fromServerUI) {
+        const backToServerUI = document.getElementById('backToServerUI');
+        if (backToServerUI) {
+          backToServerUI.classList.remove('hidden');
+        }
+        
+        // Propagate fromServerUI parameter to all sidebar links (except back to server UI)
+        const sidebarLinks = document.querySelectorAll('#sidebar a');
+        sidebarLinks.forEach(link => {
+          const href = link.getAttribute('href');
+          // Skip the back to server UI link
+          if (link.closest('#backToServerUI')) return;
+          
+          if (href && !href.startsWith('http') && !href.startsWith('#')) {
+            // Get current path to preserve /docs/ base
+            const currentPath = window.location.pathname.substring(0, window.location.pathname.lastIndexOf('/') + 1);
+            const url = new URL(currentPath + href, window.location.origin);
+            url.searchParams.set('fromServerUI', '1');
+            link.setAttribute('href', url.pathname + url.search);
+          }
+        });
+      }
+
       // Load adapters documentation dynamically
       async function loadAdaptersDocs() {
         try {

package/docs/plugins.html

@@ -109,6 +109,9 @@
             <h1 class="text-2xl font-semibold mt-3 text-[#111111]">supercli</h1>
             <p class="text-sm text-[#787774] mt-1">Plugin Directory</p>
           </div>
+          <div id="backToServerUI" class="hidden">
+            <a href="/" class="block px-3 py-2 text-sm text-[#1F6C9F] hover:bg-[#F7F6F3] rounded-md">← Back to Server UI</a>
+          </div>
           <nav class="space-y-6">
             <div>
               <p class="text-xs uppercase tracking-widest text-[#787774] mb-3">Navigation</p>
@@ -345,6 +348,33 @@
         if (e.target === mobileDrawer) mobileDrawer.classList.add('hidden');
       });
 
+      // Show "Back to Server UI" link if fromServerUI parameter is present
+      const urlParams = new URLSearchParams(window.location.search);
+      const fromServerUI = urlParams.get('fromServerUI') === '1';
+      
+      if (fromServerUI) {
+        const backToServerUI = document.getElementById('backToServerUI');
+        if (backToServerUI) {
+          backToServerUI.classList.remove('hidden');
+        }
+        
+        // Propagate fromServerUI parameter to all sidebar links (except back to server UI)
+        const sidebarLinks = document.querySelectorAll('#sidebar a');
+        sidebarLinks.forEach(link => {
+          const href = link.getAttribute('href');
+          // Skip the back to server UI link
+          if (link.closest('#backToServerUI')) return;
+          
+          if (href && !href.startsWith('http') && !href.startsWith('#')) {
+            // Get current path to preserve /docs/ base
+            const currentPath = window.location.pathname.substring(0, window.location.pathname.lastIndexOf('/') + 1);
+            const url = new URL(currentPath + href, window.location.origin);
+            url.searchParams.set('fromServerUI', '1');
+            link.setAttribute('href', url.pathname + url.search);
+          }
+        });
+      }
+
       // Scroll to top button
       const scrollTopBtn = document.getElementById('scrollTopBtn');
       

package/docs/server.md

@@ -41,6 +41,86 @@ Manage OpenAPI specifications at `/specs`. Upload OpenAPI/Swagger JSON or YAML f
 
 Manage Model Context Protocol server connections at `/mcp`. Connect to MCP servers via SSE or stdio to expose their tools as supercli commands.
 
+### MCP Transport Modes
+
+The supercli MCP adapter supports multiple transport modes:
+
+#### HTTP/SSE MCP
+- Use `adapterConfig.url` for HTTP-based MCP servers
+- Supercli MCP adapter automatically supports SSE streaming
+- Sends `Accept: text/event-stream, application/json` header
+- Parses SSE responses and returns accumulated results
+- Uses JSON-RPC 2.0 format for requests
+
+Example configuration:
+```json
+{
+  "adapterConfig": {
+    "url": "http://localhost:3002",
+    "tool": "get_deep_directory_tree"
+  }
+}
+```
+
+#### Stdio MCP with Daemon
+- Use `adapterConfig.server` + `adapterConfig.stateful: true` for stdio MCPs
+- Best for local stdio MCP servers
+- Routes through MCP daemon for stateful stdio handling
+- **Daemon runs on CLI side** (not server) - starts on-demand when first command is executed via CLI
+- Daemon runs as detached background process with Unix socket at `~/.supercli/mcp-daemon.sock`
+- Persists across command executions to maintain MCP server sessions
+- Manual control: `supercli mcp daemon start/stop/status`
+
+Example configuration:
+```json
+{
+  "adapterConfig": {
+    "server": "deep-directory-tree",
+    "tool": "tool_name",
+    "stateful": true,
+    "timeout_ms": 60000
+  }
+}
+```
+
+#### Stdio MCP Direct
+- Use `adapterConfig.command` for direct stdio calls
+- May have compatibility issues with different MCP implementations
+
+### Using mcp-proxy with Supercli
+
+The mcp-proxy tool transforms stdio MCPs into HTTP/SSE. Here's how to use it:
+
+1. Start mcp-proxy:
+```bash
+npx -y mcp-proxy --port 3002 -- npx -y @andredezzy/deep-directory-tree-mcp
+```
+
+2. Add MCP server to supercli:
+```bash
+supercli server mcp add '{"name":"deep-tree","url":"http://localhost:3002"}'
+```
+
+3. Create command:
+```bash
+supercli server commands add '{"namespace":"tree","resource":"deep","action":"list","adapter":"mcp","adapterConfig":{"url":"http://localhost:3002","tool":"get_deep_directory_tree"}}'
+```
+
+4. Sync and use:
+```bash
+supercli sync
+supercli tree deep list --path /some/dir --depth 3
+```
+
+**Note:** Use space syntax for arguments: `--path /dir` not `--path=/dir`
+
+### MCP Adapter Features
+
+- **Auto-detection**: Automatically detects SSE responses and falls back to JSON
+- **JSON-RPC Support**: Uses JSON-RPC 2.0 format for HTTP MCP calls
+- **SSE Parsing**: Parses Server-Sent Events and accumulates results
+- **Stream Flag**: Reserved for future streaming output support (`--stream`)
+
 ## Plugins
 
 Manage server plugins at `/plugins`. Upload plugin ZIP files, enable/disable plugins, and view plugin manifests. Server plugins extend CLI capabilities with custom commands and harnesses.