@mcp-s/cli 0.0.17 → 0.0.18

package/SKILL.md

@@ -14,6 +14,8 @@ Access a single MCP server through the command line. MCP enables interaction wit
 | `mcp-s-cli`                      | List all available tools                          |
 | `mcp-s-cli info <tool>`          | Get tool JSON schema                              |
 | `mcp-s-cli grep <query>`         | Search tools by name (case-insensitive substring) |
+| `mcp-s-cli grep <query> -d`      | Search tools by name, include descriptions        |
+| `mcp-s-cli get-servers`          | List available servers (slug, name, description) |
 | `mcp-s-cli call <tool>`          | Call tool (reads JSON from stdin if no args)      |
 | `mcp-s-cli call <tool> '<json>'` | Call tool with arguments                          |
 
@@ -30,7 +32,7 @@ mcp-s-cli check-auth
 
 ## Workflow
 
-1. **Discover**: `mcp-s-cli grep <query>` → find tools by keyword; fall back to `mcp-s-cli` only when you need a full inventory
+1. **Discover**: find the right tool (see discovery ladder below)
 2. **Inspect**: `mcp-s-cli info <tool>` → get full JSON schema
 3. **Execute**: `mcp-s-cli call <tool> '<json>'` → run with arguments
 
@@ -38,13 +40,14 @@ mcp-s-cli check-auth
 
 Every command consumes tokens. Pick the cheapest operation that gets the job done.
 
-### Discovery: start narrow
+### Discovery ladder (follow in order, stop as soon as you're confident)
 
-- **`grep <query>`** — cheapest. Use when you can guess a keyword from the user's request (e.g., "read a github file" → `grep file` or `grep content`).
-- **`mcp-s-cli`** (names only) — moderate. Use when you need a full inventory (e.g., "what tools do I have?" or "analyze logs from all tools").
-- **`mcp-s-cli -d`** (names + descriptions) — most expensive. Use only when names alone aren't enough to pick the right tool.
+1. **`grep <query>`** — cheapest. Guess a keyword from the user's request (e.g., "read a github file" → `grep file`). If the results clearly contain the right tool, skip to **Inspect**.
+2. **`get-servers`** — lightweight REST call, returns each server's **slug**, name, and description. Use when grep results are ambiguous or empty and you need to understand which servers/domains are available.
+3. **`grep <query>` scoped to a slug** — now that you know the relevant server slug(s), grep again to narrow results. If you're not confident you and still need more details, continue to step 4.
+4. **`grep <query> -d`** — includes tool descriptions in the output. Use to disambiguate between similar-sounding candidates.
 
-**Rule: if you can guess a keyword, grep first.**
+**Rule: always start with a plain `grep`. Escalate only when you're not confident you found the right tool.**
 
 ### Execution: keep responses small
 
@@ -63,7 +66,9 @@ When you pipe through a filter and get empty output, **do not** fall back to the
 ### Decision heuristic
 
 - User mentions a specific tool or domain keyword → `grep` for it.
-- User asks a broad question across all tools → list tools first, then act.
+- Grep results are empty or ambiguous → `get-servers` to see available servers, then grep again with a better keyword or scoped to the relevant slug.
+- You have candidates but can't tell them apart by name → `grep -d` for descriptions.
+- User asks a broad question across all tools → `get-servers` first, then grep per relevant server.
 - Task involves multiple items of the same type → use one bulk/list call, not N individual calls.
 - Tool may return large payloads → use filter params + pipe to trim output.
 - Filter script produced no output → **probe one item** to learn the shape, then re-run with a corrected filter. Never fall back to the raw unfiltered call.

package/dist/SKILL.md

@@ -14,6 +14,8 @@ Access a single MCP server through the command line. MCP enables interaction wit
 | `mcp-s-cli`                      | List all available tools                          |
 | `mcp-s-cli info <tool>`          | Get tool JSON schema                              |
 | `mcp-s-cli grep <query>`         | Search tools by name (case-insensitive substring) |
+| `mcp-s-cli grep <query> -d`      | Search tools by name, include descriptions        |
+| `mcp-s-cli get-servers`          | List available servers (slug, name, description) |
 | `mcp-s-cli call <tool>`          | Call tool (reads JSON from stdin if no args)      |
 | `mcp-s-cli call <tool> '<json>'` | Call tool with arguments                          |
 
@@ -30,7 +32,7 @@ mcp-s-cli check-auth
 
 ## Workflow
 
-1. **Discover**: `mcp-s-cli grep <query>` → find tools by keyword; fall back to `mcp-s-cli` only when you need a full inventory
+1. **Discover**: find the right tool (see discovery ladder below)
 2. **Inspect**: `mcp-s-cli info <tool>` → get full JSON schema
 3. **Execute**: `mcp-s-cli call <tool> '<json>'` → run with arguments
 
@@ -38,13 +40,14 @@ mcp-s-cli check-auth
 
 Every command consumes tokens. Pick the cheapest operation that gets the job done.
 
-### Discovery: start narrow
+### Discovery ladder (follow in order, stop as soon as you're confident)
 
-- **`grep <query>`** — cheapest. Use when you can guess a keyword from the user's request (e.g., "read a github file" → `grep file` or `grep content`).
-- **`mcp-s-cli`** (names only) — moderate. Use when you need a full inventory (e.g., "what tools do I have?" or "analyze logs from all tools").
-- **`mcp-s-cli -d`** (names + descriptions) — most expensive. Use only when names alone aren't enough to pick the right tool.
+1. **`grep <query>`** — cheapest. Guess a keyword from the user's request (e.g., "read a github file" → `grep file`). If the results clearly contain the right tool, skip to **Inspect**.
+2. **`get-servers`** — lightweight REST call, returns each server's **slug**, name, and description. Use when grep results are ambiguous or empty and you need to understand which servers/domains are available.
+3. **`grep <query>` scoped to a slug** — now that you know the relevant server slug(s), grep again to narrow results. If you're not confident you and still need more details, continue to step 4.
+4. **`grep <query> -d`** — includes tool descriptions in the output. Use to disambiguate between similar-sounding candidates.
 
-**Rule: if you can guess a keyword, grep first.**
+**Rule: always start with a plain `grep`. Escalate only when you're not confident you found the right tool.**
 
 ### Execution: keep responses small
 
@@ -63,7 +66,9 @@ When you pipe through a filter and get empty output, **do not** fall back to the
 ### Decision heuristic
 
 - User mentions a specific tool or domain keyword → `grep` for it.
-- User asks a broad question across all tools → list tools first, then act.
+- Grep results are empty or ambiguous → `get-servers` to see available servers, then grep again with a better keyword or scoped to the relevant slug.
+- You have candidates but can't tell them apart by name → `grep -d` for descriptions.
+- User asks a broad question across all tools → `get-servers` first, then grep per relevant server.
 - Task involves multiple items of the same type → use one bulk/list call, not N individual calls.
 - Tool may return large payloads → use filter params + pipe to trim output.
 - Filter script produced no output → **probe one item** to learn the shape, then re-run with a corrected filter. Never fall back to the raw unfiltered call.

package/dist/daemon.js

@@ -427,7 +427,7 @@ import { join as join2 } from "path";
 import { fileURLToPath } from "url";
 
 // src/version.ts
-var VERSION = "0.0.17";
+var VERSION = "0.0.18";
 
 // src/client.ts
 function getRetryConfig(settings) {

package/dist/index.js

@@ -358,6 +358,48 @@ async function clearTokens(url) {
   tokens.delete(origin);
   await saveAuthData();
 }
+async function fetchWithAuth(url, options = {}) {
+  const { timeout = 6e4, ...fetchOptions } = options;
+  const tokens = await getStoredTokens(url);
+  if (tokens) {
+    fetchOptions.headers = {
+      ...fetchOptions.headers,
+      Authorization: `Bearer ${tokens.access_token}`
+    };
+  }
+  let response = await fetch(url, {
+    ...fetchOptions,
+    signal: AbortSignal.timeout(timeout)
+  });
+  if (response.status === 401) {
+    const wwwAuthHeader = response.headers.get("WWW-Authenticate");
+    if (wwwAuthHeader) {
+      const challenge = parseWWWAuthenticateHeader(wwwAuthHeader);
+      if (challenge.resource_metadata) {
+        const resourceMetadata = await fetchProtectedResourceMetadata(
+          challenge.resource_metadata
+        );
+        if (resourceMetadata?.authorization_servers?.[0]) {
+          const newTokens = await performOAuthFlow(
+            resourceMetadata.authorization_servers[0],
+            resourceMetadata.resource
+          );
+          if (newTokens) {
+            fetchOptions.headers = {
+              ...fetchOptions.headers,
+              Authorization: `Bearer ${newTokens.access_token}`
+            };
+            response = await fetch(url, {
+              ...fetchOptions,
+              signal: AbortSignal.timeout(timeout)
+            });
+          }
+        }
+      }
+    }
+  }
+  return response;
+}
 
 // src/config.ts
 import { createHash } from "crypto";
@@ -1313,7 +1355,7 @@ async function cleanupOrphanedDaemons() {
 }
 
 // src/version.ts
-var VERSION = "0.0.17";
+var VERSION = "0.0.18";
 
 // src/client.ts
 function getRetryConfig(settings) {
@@ -2270,6 +2312,87 @@ function configCommand(opts) {
   }
 }
 
+// src/commands/get-servers.ts
+async function getServersCommand(options) {
+  const { configPath } = options;
+  let raw;
+  let serverConfig;
+  try {
+    const loaded = await loadConfig(configPath);
+    raw = loaded.raw;
+    serverConfig = loaded.serverConfig;
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1 /* CLIENT_ERROR */);
+  }
+  if (!isHttpServer(serverConfig)) {
+    console.error(
+      "get-servers is only supported for HTTP servers (org/baseUrl config)."
+    );
+    process.exit(1 /* CLIENT_ERROR */);
+  }
+  const mcpUrl = serverConfig.url.replace(/\/+$/, "");
+  const url = `${mcpUrl}/servers`;
+  const headers = {};
+  if (raw.token) {
+    headers.Authorization = `Bearer ${raw.token}`;
+  }
+  if (raw.mcp) {
+    headers["x-mcp"] = raw.mcp;
+  }
+  if (raw.toolkit) {
+    headers["x-toolkit"] = raw.toolkit;
+  }
+  let response;
+  try {
+    response = await fetchWithAuth(url, { headers });
+  } catch (error) {
+    const msg = error.message;
+    if (msg.includes("ECONNREFUSED") || msg.includes("ENOTFOUND") || msg.includes("fetch failed")) {
+      console.error(
+        `Network error: could not connect to ${mcpUrl}. Is the server running?`
+      );
+      process.exit(3 /* NETWORK_ERROR */);
+    }
+    console.error(`Request failed: ${msg}`);
+    process.exit(2 /* SERVER_ERROR */);
+  }
+  if (response.status === 401) {
+    console.error("Not authenticated. Run: mcp-s-cli login");
+    process.exit(4 /* AUTH_ERROR */);
+  }
+  if (!response.ok) {
+    console.error(`Server returned ${response.status}: ${response.statusText}`);
+    process.exit(2 /* SERVER_ERROR */);
+  }
+  let data;
+  try {
+    data = await response.json();
+  } catch {
+    console.error("Invalid JSON response from server.");
+    process.exit(2 /* SERVER_ERROR */);
+  }
+  const servers = data.data ?? [];
+  if (servers.length === 0) {
+    console.log("No servers available.");
+    return;
+  }
+  const lines = [];
+  for (const server of servers) {
+    lines.push(`slug: ${server.slug}`);
+    if (server.description) {
+      lines.push(`${server.name} - ${server.description}`);
+    } else {
+      lines.push(server.name);
+    }
+    lines.push("");
+  }
+  if (lines.length > 0 && lines[lines.length - 1] === "") {
+    lines.pop();
+  }
+  console.log(lines.join("\n"));
+}
+
 // src/commands/grep.ts
 function matchesToolName(name, query) {
   return name.toLowerCase().includes(query.toLowerCase());
@@ -3334,6 +3457,10 @@ function parseArgs2(args) {
     result.command = "disable";
     return result;
   }
+  if (firstArg === "get-servers") {
+    result.command = "get-servers";
+    return result;
+  }
   if (firstArg === "config") {
     result.command = "config";
     const sub = positional[1];
@@ -3398,6 +3525,7 @@ Usage:
   mcp-s-cli login                            Log in to the configured server via OAuth
   mcp-s-cli logout                           Log out (remove stored OAuth tokens)
   mcp-s-cli check-auth                       Check auth state offline (no network); exits 0=ok, 4=needs login
+  mcp-s-cli get-servers                      List available MCP servers
   mcp-s-cli config set <key> <value>         Set a value in config.json
   mcp-s-cli config get <key>                 Get a value from config.json
   mcp-s-cli config show                      Print full config.json
@@ -3440,6 +3568,7 @@ Examples:
   mcp-s-cli login                            # Authenticate via OAuth
   mcp-s-cli logout                           # Remove stored OAuth tokens
   mcp-s-cli check-auth                       # Check auth state offline (fast preflight)
+  mcp-s-cli get-servers                      # List available MCP servers
   mcp-s-cli config set settings.timeout 30   # Set request timeout to 30s
   mcp-s-cli clear                            # Reset server config
   mcp-s-cli clear-auth                       # Clear stored auth data
@@ -3568,6 +3697,11 @@ async function main() {
     case "check-auth":
       await checkAuthCommand({ configPath: args.configPath });
       break;
+    case "get-servers":
+      await getServersCommand({
+        configPath: args.configPath
+      });
+      break;
     case "clear":
       await clearCommand();
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-s/cli",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "description": "A lightweight CLI for connecting AI agents to the Webrix MCP Gateway",
   "type": "module",
   "main": "dist/index.js",