api-spec-cli 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-spec-cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Agent-friendly CLI for exploring and calling OpenAPI and GraphQL APIs",
   "type": "module",
   "bin": {

package/src/args.js

@@ -2,7 +2,7 @@
 // Supports: --flag value, --flag=value, and positional args
 // Repeatable flags (--query, --header, --var) are collected into arrays.
 
-const REPEATABLE = new Set(["query", "header", "var", "env"]);
+const REPEATABLE = new Set(["query", "header", "var", "env", "allow-tool", "disable-tool"]);
 
 export function parseArgs(args) {
   const flags = {};

package/src/cli.js

@@ -6,6 +6,7 @@ import { validateSpec } from "./commands/validate.js";
 import { typesCmd } from "./commands/types.js";
 import { addCmd } from "./commands/add.js";
 import { specsCmd, registryMutate } from "./commands/specs.js";
+import { grepCmd } from "./commands/grep.js";
 import { out, err, setFormat } from "./output.js";
 
 const HELP = `spec-cli — Explore and call APIs from the command line.
@@ -29,6 +30,9 @@ REGISTRY (register once, use anywhere):
   spec add <name> --mcp-stdio "<cmd>"  Register an MCP server (stdio)
     Options: --description <text>  --base-url <url>  --auth <token>
              --header k=v (repeatable)  --env KEY=VAL (repeatable, stdio only)
+             --cwd <path> (stdio only)
+             --allow-tool <glob> (repeatable, MCP only)
+             --disable-tool <glob> (repeatable, MCP only)
 
   spec specs                           List all registered specs
   spec specs --compact false           Show full entry config
@@ -43,6 +47,8 @@ DISCOVER:
   spec list --spec <name> --tag pets          OpenAPI tag or GraphQL kind
   spec list --spec <name> --limit 10          Paginate
   spec list --mcp-http <url>           Inline: no registration needed
+  spec grep <pattern>                  Search across all registered specs
+  spec grep <pattern> --spec <name>    Search within one spec
 
 INSPECT:
   spec show --spec <name> <op>         Operation details (params, body, responses)
@@ -55,6 +61,7 @@ CALL:
   spec call --spec <name> <op> --query status=available  Query params
   spec call --spec <name> <op> --data '{"name":"Rex"}'   JSON body / MCP args
   spec call --spec <name> <op> --data-file args.json     Body from file
+  echo '{"query":"foo"}' | spec call --spec <name> <op>  Pipe JSON from stdin
   spec call --spec <name> <op> --header X-Custom=val     Extra headers
   spec call --spec <name> <op> --method PUT              Override HTTP method
 
@@ -74,6 +81,10 @@ OTHER:
   spec validate <file-or-url>          Check OpenAPI spec for errors
   --format json|text|yaml              Output format (default: json)
 
+ENV VARS (MCP):
+  MCP_MAX_RETRIES=3        Retry attempts on connection failure (default: 3)
+  MCP_RETRY_DELAY=1000     Base retry delay in ms, doubles each attempt (default: 1000)
+
 EXAMPLES:
   spec add agno --mcp-http https://docs.agno.com/mcp --description "Agno docs"
   spec add petstore --openapi https://petstore3.swagger.io/api/v3/openapi.json \\
@@ -148,6 +159,9 @@ export async function run(args) {
       case "refresh":
         await registryMutate("refresh", args.slice(1));
         break;
+      case "grep":
+        await grepCmd(args.slice(1));
+        break;
       default:
         err(`Unknown command: ${cmd}. Run 'spec help' for usage.`);
     }

package/src/commands/add.js

@@ -44,6 +44,7 @@ export async function addCmd(args) {
     entry.transport = "stdio";
     entry.command = parts[0];
     entry.args = parts.slice(1);
+    if (flags.cwd) entry.cwd = flags.cwd;
     entry.config = { env: parseKV(flags.env) };
   } else if (flags["mcp-sse"]) {
     entry.type = "mcp";
@@ -61,6 +62,14 @@ export async function addCmd(args) {
     );
   }
 
+  // Tool filtering (MCP only)
+  if (entry.type === "mcp") {
+    const allowed = flags["allow-tool"];
+    const disabled = flags["disable-tool"];
+    if (allowed?.length) entry.config.allowedTools = allowed;
+    if (disabled?.length) entry.config.disabledTools = disabled;
+  }
+
   registry.push(entry);
   saveRegistry(registry);
   out({ ok: true, name, type: entry.type, transport: entry.transport });

package/src/commands/call.js

@@ -15,6 +15,20 @@ export async function callOperation(args) {
     flags.data = readFileSync(flags["data-file"], "utf-8").trim();
   }
 
+  // Read from stdin when piped and no --data/--data-file provided.
+  // isTTY is true in a terminal, undefined when piped — so !isTTY catches piped input.
+  // Wrapped in try-catch so test runners with closed stdin don't crash.
+  if (!flags.data && !process.stdin.isTTY) {
+    try {
+      const chunks = [];
+      for await (const chunk of process.stdin) chunks.push(chunk);
+      const piped = Buffer.concat(chunks).toString("utf-8").trim();
+      if (piped) flags.data = piped;
+    } catch {
+      // stdin unavailable (test runner, closed pipe) — ignore
+    }
+  }
+
   const { spec, entry } = await resolveActiveSpec(flags);
   const config = resolveConfig(flags, entry);
 

package/src/commands/grep.js

@@ -0,0 +1,63 @@
+import { out } from "../output.js";
+import { parseArgs } from "../args.js";
+import { getRegistry, getEntry, getCachedSpec, saveCachedSpec } from "../registry.js";
+import { resolveSpec, matchGlob } from "./load.js";
+
+export async function grepCmd(args) {
+  const { flags, positional } = parseArgs(args);
+  const pattern = positional[0];
+  if (!pattern) throw new Error(
+    "Usage: spec grep <pattern> [--spec <name>]\n" +
+    "  Glob patterns: * matches anything, ? matches one char\n" +
+    "  Plain text: substring match across name and description"
+  );
+
+  const entries = flags.spec
+    ? [getEntry(flags.spec)]
+    : getRegistry().filter((e) => e.enabled);
+
+  if (entries.length === 0) throw new Error("No registered specs. Run 'spec add' first.");
+
+  const results = [];
+
+  for (const entry of entries) {
+    let spec = getCachedSpec(entry.name);
+    if (!spec) {
+      spec = await resolveSpec(entry);
+      saveCachedSpec(entry.name, spec);
+    }
+
+    const matches = [];
+
+    if (spec.type === "mcp") {
+      for (const tool of spec.tools) {
+        const nameMatch = matchGlob(pattern, tool.name);
+        const descMatch = tool.description && matchGlob(pattern, tool.description);
+        if (nameMatch || descMatch) {
+          matches.push({ id: tool.name, description: tool.description });
+        }
+      }
+    } else if (spec.type === "openapi") {
+      for (const op of spec.operations) {
+        if (matchGlob(pattern, op.id) || matchGlob(pattern, op.path) ||
+            (op.summary && matchGlob(pattern, op.summary))) {
+          matches.push({ id: op.id, method: op.method, path: op.path });
+        }
+      }
+    } else if (spec.type === "graphql") {
+      for (const op of spec.operations) {
+        if (matchGlob(pattern, op.name) ||
+            (op.description && matchGlob(pattern, op.description))) {
+          matches.push({ id: op.name, kind: op.kind });
+        }
+      }
+    }
+
+    if (matches.length > 0) {
+      results.push({ spec: entry.name, type: spec.type, matches });
+    }
+  }
+
+  const total = results.reduce((s, r) => s + r.matches.length, 0);
+  out({ pattern, total, results });
+}

package/src/commands/load.js

@@ -88,6 +88,7 @@ export function inlineEntryFromFlags(flags) {
       transport: "stdio",
       command: parts[0],
       args: parts.slice(1),
+      cwd: flags.cwd,
       config: { env: parseKV(flags.env) },
     };
   }
@@ -118,10 +119,35 @@ export function inlineEntryFromFlags(flags) {
 
 // --- Internal loaders ---
 
+function matchGlob(pattern, str) {
+  // If no glob chars, use case-insensitive substring match
+  if (!pattern.includes("*") && !pattern.includes("?")) {
+    return str.toLowerCase().includes(pattern.toLowerCase());
+  }
+  const re = new RegExp(
+    "^" + pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") + "$",
+    "i"
+  );
+  return re.test(str);
+}
+
+export { matchGlob };
+
 async function loadMCPFromEntry(entry) {
   const client = await createMcpClient(entry);
   try {
     const { tools } = await client.listTools();
+    let mapped = tools.map((t) => ({
+      name: t.name,
+      description: t.description || null,
+      inputSchema: t.inputSchema || null,
+    }));
+
+    const allowed = entry.config?.allowedTools;
+    const disabled = entry.config?.disabledTools;
+    if (allowed?.length) mapped = mapped.filter((t) => allowed.some((p) => matchGlob(p, t.name)));
+    if (disabled?.length) mapped = mapped.filter((t) => !disabled.some((p) => matchGlob(p, t.name)));
+
     return {
       type: "mcp",
       title: entry.name || "MCP Server",
@@ -129,12 +155,9 @@ async function loadMCPFromEntry(entry) {
       url: entry.url,
       command: entry.command,
       args: entry.args,
+      cwd: entry.cwd,
       config: entry.config,
-      tools: tools.map((t) => ({
-        name: t.name,
-        description: t.description || null,
-        inputSchema: t.inputSchema || null,
-      })),
+      tools: mapped,
     };
   } finally {
     await client.close();

package/src/mcp-client.js

@@ -3,15 +3,31 @@ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 
-export async function createMcpClient(spec) {
+const MAX_RETRIES = parseInt(process.env.MCP_MAX_RETRIES ?? "3");
+const RETRY_DELAY = parseInt(process.env.MCP_RETRY_DELAY ?? "1000");
+
+// Expand ${VAR} placeholders from process.env at call time
+function expandEnv(val) {
+  return val.replace(/\$\{([^}]+)\}/g, (_, name) => {
+    if (!(name in process.env)) throw new Error(`Environment variable not set: ${name}`);
+    return process.env[name];
+  });
+}
+
+async function connect(spec) {
   const client = new Client({ name: "spec-cli", version: "1.0.0" });
 
   let transport;
   if (spec.transport === "stdio") {
+    const rawEnv = spec.config?.env || {};
+    const expandedEnv = Object.fromEntries(
+      Object.entries(rawEnv).map(([k, v]) => [k, expandEnv(v)])
+    );
     transport = new StdioClientTransport({
       command: spec.command,
       args: spec.args,
-      env: spec.config?.env ? { ...process.env, ...spec.config.env } : undefined,
+      env: Object.keys(expandedEnv).length > 0 ? { ...process.env, ...expandedEnv } : undefined,
+      cwd: spec.cwd,
     });
   } else if (spec.transport === "sse") {
     const h = spec.config?.headers;
@@ -30,3 +46,18 @@ export async function createMcpClient(spec) {
   await client.connect(transport);
   return client;
 }
+
+export async function createMcpClient(spec) {
+  let lastError;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      return await connect(spec);
+    } catch (e) {
+      lastError = e;
+      if (attempt < MAX_RETRIES) {
+        await new Promise((r) => setTimeout(r, RETRY_DELAY * Math.pow(2, attempt)));
+      }
+    }
+  }
+  throw lastError;
+}