api-spec-cli 0.2.1 → 0.2.3

package/README.md

@@ -56,6 +56,19 @@ Inline fetches every call, nothing cached.
 
 ## Discovery
 
+### Search across specs
+
+`grep` searches operation/tool names and descriptions across all registered specs.
+
+```bash
+spec grep search                        # Substring match across all specs
+spec grep "get*"                        # Glob: anything starting with "get"
+spec grep "*list*"                      # Glob: anything containing "list"
+spec grep search --spec agno            # Limit to one spec
+```
+
+Matches on name and description. Case-insensitive. Plain text = substring, `*`/`?` = glob.
+
 ### List all specs in the registry
 
 ```bash
@@ -131,6 +144,10 @@ spec call --spec hashnode publication --var host=blog.hashnode.dev
 spec call --spec agno search_agno --var query="how to create an agent"
 spec call --spec agno search_agno --data '{"query":"agents"}'
 
+# Read body from stdin (explicit --data -)
+echo '{"query":"agents"}' | spec call --spec agno search_agno --data -
+cat body.json | spec call --spec petstore addPet --data -
+
 # Inline (no registration)
 spec call --openapi https://petstore3.swagger.io/api/v3/openapi.json \
   getPetById --var petId=1 --base-url https://petstore3.swagger.io/api/v3
@@ -164,13 +181,38 @@ spec refresh <name>   # Force re-fetch and update cache
 ```bash
 spec add <name> --openapi <url-or-file>   [--base-url <url>] [--auth <token>] [--header k=v]
 spec add <name> --graphql <url>            [--auth <token>] [--header k=v]
-spec add <name> --mcp-http <url>           [--header k=v]
-spec add <name> --mcp-sse <url>            [--header k=v]
-spec add <name> --mcp-stdio "<cmd args>"   [--env KEY=VAL]
+spec add <name> --mcp-http <url>           [--auth <token>] [--header k=v]
+spec add <name> --mcp-sse <url>            [--auth <token>] [--header k=v]
+spec add <name> --mcp-stdio "<cmd args>"   [--env KEY=VAL] [--cwd <path>]
                                            [--description <text>]  (all types)
 ```
 
-Headers are sent on every request. For stdio MCP, use `--env` to pass environment variables to the subprocess.
+All options are repeatable where it makes sense (`--header`, `--env`). `--auth` adds `Authorization: Bearer <token>` unless the header is already set.
+
+Operation filtering works for all spec types — MCP, OpenAPI, and GraphQL:
+
+```bash
+# MCP: allow only read/list tools
+spec add <name> --mcp-http <url> \
+  --allow-tool "read_*" --allow-tool "list_*" \
+  --disable-tool "delete_*"
+
+# OpenAPI: allow only GET operations (by operationId)
+spec add <name> --openapi <url> \
+  --allow-tool "get*" --allow-tool "find*"
+
+# GraphQL: allow specific operations by exact name
+spec add <name> --graphql <url> \
+  --allow-tool "me" --allow-tool "publication"
+```
+
+`--allow-tool` keeps only matching operations. `--disable-tool` removes matching operations (applied after allow). Both are repeatable.
+
+**Matching rules:**
+- Plain text → **exact match** (case-insensitive): `"me"` matches only `me`
+- Glob patterns → anchored match: `"get*"` matches `getPetById`, `"*post*"` matches `createPost`
+
+Use `grep` for search (substring) — `--allow-tool` / `--disable-tool` for precise whitelists (exact or glob).
 
 ---
 
@@ -214,6 +256,23 @@ spec list --spec petstore --format=json    # equals syntax also works
 - `--limit` / `--offset` paginate large APIs
 - `--filter` and `--tag` narrow results before output
 
+## MCP Options
+
+```bash
+# Retry on connection failure (useful for stdio servers that take time to start)
+MCP_MAX_RETRIES=3       # Attempts (default: 3)
+MCP_RETRY_DELAY=1000    # Base delay in ms, doubles each attempt, capped at 5s (default: 1000)
+
+# HTTP timeout for OpenAPI/GraphQL calls
+SPEC_HTTP_TIMEOUT=30000 # ms (default: 30000)
+```
+
+Stdio env vars support `${VAR}` expansion from the host environment:
+
+```bash
+spec add fs --mcp-stdio "npx -y server /tmp" --env "TOKEN=${MY_SECRET}"
+```
+
 ## Storage
 
 | Path | Purpose |

package/package.json

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

package/src/cli.js

@@ -31,8 +31,8 @@ REGISTRY (register once, use anywhere):
     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)
+             --allow-tool <glob> (repeatable)
+             --disable-tool <glob> (repeatable)
 
   spec specs                           List all registered specs
   spec specs --compact false           Show full entry config
@@ -61,7 +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> --data -                  Read JSON body from stdin (pipe)
   spec call --spec <name> <op> --header X-Custom=val     Extra headers
   spec call --spec <name> <op> --method PUT              Override HTTP method
 

package/src/commands/add.js

@@ -50,25 +50,27 @@ export async function addCmd(args) {
     entry.type = "mcp";
     entry.transport = "sse";
     entry.url = flags["mcp-sse"];
-    entry.config = { headers: parseKV(flags.header) };
+    const headers = parseKV(flags.header);
+    if (flags.auth && !headers["Authorization"]) headers["Authorization"] = `Bearer ${flags.auth}`;
+    entry.config = { headers };
   } else if (flags["mcp-http"]) {
     entry.type = "mcp";
     entry.transport = "streamable-http";
     entry.url = flags["mcp-http"];
-    entry.config = { headers: parseKV(flags.header) };
+    const headers = parseKV(flags.header);
+    if (flags.auth && !headers["Authorization"]) headers["Authorization"] = `Bearer ${flags.auth}`;
+    entry.config = { headers };
   } else {
     throw new Error(
       "Specify a source: --openapi <url>, --graphql <url>, --mcp-http <url>, --mcp-sse <url>, or --mcp-stdio \"<cmd>\""
     );
   }
 
-  // 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;
-  }
+  // Operation filtering (all types)
+  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);

package/src/commands/call.js

@@ -2,34 +2,30 @@ import { readFileSync } from "fs";
 import { out } from "../output.js";
 import { parseArgs, parseKV } from "../args.js";
 import { createMcpClient } from "../mcp-client.js";
-import { resolveActiveSpec, resolveConfig } from "../resolve.js";
+import { resolveSpec, resolveConfig } from "../resolve.js";
+
+const HTTP_TIMEOUT = parseInt(process.env.SPEC_HTTP_TIMEOUT ?? "30000");
 
 export async function callOperation(args) {
   const { flags, positional } = parseArgs(args);
   const target = positional[0];
   if (!target) throw new Error(
-    "Usage: spec call <operation> [--spec <name> | --openapi <url> | ...] [--data '{}'] [--var k=v] [--header k=v]"
+    "Usage: spec call <operation> [--spec <name> | --openapi <url> | ...] [--data '{}' | --data -] [--var k=v] [--header k=v]"
   );
 
   if (flags["data-file"] && !flags.data) {
     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
-    }
+  // Read from stdin only when --data - is explicitly passed.
+  // Agents run in non-TTY environments — auto-detecting stdin would add latency on every call.
+  if (flags.data === "-") {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    flags.data = Buffer.concat(chunks).toString("utf-8").trim();
   }
 
-  const { spec, entry } = await resolveActiveSpec(flags);
+  const { spec, entry } = await resolveSpec(flags);
   const config = resolveConfig(flags, entry);
 
   if (spec.type === "openapi") {
@@ -60,7 +56,10 @@ async function callMCP(spec, entry, target, flags) {
   const client = await createMcpClient(entry);
   try {
     const result = await client.callTool({ name: tool.name, arguments: toolArgs });
-    out({ tool: tool.name, arguments: toolArgs, result });
+    // Normalize MCP result: expose isError and content at the top level
+    const isError = result.isError === true;
+    out({ tool: tool.name, arguments: toolArgs, isError, content: result.content, result });
+    if (isError) process.exit(1);
   } finally {
     await client.close();
   }
@@ -82,7 +81,13 @@ async function callOpenAPI(spec, config, target, flags) {
 
   const vars = parseKV(flags.var);
   for (const [key, val] of Object.entries(vars)) {
-    path = path.replace(`{${key}}`, encodeURIComponent(val));
+    path = path.replaceAll(`{${key}}`, encodeURIComponent(val));
+  }
+
+  // Detect unreplaced path parameters and error clearly
+  const missing = [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
+  if (missing.length > 0) {
+    throw new Error(`Missing required path parameters: ${missing.join(", ")}. Pass --var ${missing[0]}=<value>`);
   }
 
   const queryParams = parseKV(flags.query);
@@ -98,7 +103,7 @@ async function callOpenAPI(spec, config, target, flags) {
     if (!headers["Content-Type"]) headers["Content-Type"] = "application/json";
   }
 
-  const res = await fetch(url, { method, headers, body });
+  const res = await fetch(url, { method, headers, body, signal: AbortSignal.timeout(HTTP_TIMEOUT) });
   const contentType = res.headers.get("content-type") || "";
   const responseBody = contentType.includes("json") ? await res.json() : await res.text();
 
@@ -146,15 +151,16 @@ async function callGraphQL(spec, config, target, flags) {
     variables: Object.keys(variables).length > 0 ? variables : undefined,
   });
 
-  const res = await fetch(endpoint, { method: "POST", headers, body });
-  const responseBody = await res.json();
+  const res = await fetch(endpoint, { method: "POST", headers, body, signal: AbortSignal.timeout(HTTP_TIMEOUT) });
+  const contentType = res.headers.get("content-type") || "";
+  const responseBody = contentType.includes("json") ? await res.json() : await res.text();
 
   out({
     status: res.status,
     query,
     variables: Object.keys(variables).length > 0 ? variables : undefined,
-    data: responseBody.data || null,
-    errors: responseBody.errors || null,
+    data: responseBody?.data || null,
+    errors: responseBody?.errors || null,
   });
 }
 

package/src/commands/{load.js → fetch.js}

@@ -3,6 +3,7 @@ import { resolve } from "path";
 import YAML from "yaml";
 import { parseKV } from "../args.js";
 import { createMcpClient } from "../mcp-client.js";
+import { matchFilter } from "../glob.js";
 
 const INTROSPECTION_QUERY = `{
   __schema {
@@ -59,6 +60,13 @@ fragment TypeRef on __Type {
   }
 }`;
 
+function applyFilter(items, nameFn, allowed, disabled) {
+  let result = items;
+  if (allowed?.length) result = result.filter((item) => allowed.some((p) => matchFilter(p, nameFn(item))));
+  if (disabled?.length) result = result.filter((item) => !disabled.some((p) => matchFilter(p, nameFn(item))));
+  return result;
+}
+
 /**
  * Resolve a spec from a registry entry or inline flags entry.
  * Entry shape:
@@ -66,12 +74,22 @@ fragment TypeRef on __Type {
  *   { type: "graphql", source: "<url>", config: { headers, auth } }
  *   { type: "mcp", transport: "stdio|sse|streamable-http", url?, command?, args?, config: { headers, env } }
  */
-export async function resolveSpec(entry) {
+export async function fetchSpec(entry) {
   if (entry.type === "mcp") return await loadMCPFromEntry(entry);
-  if (entry.type === "graphql") return await loadGraphQL(entry.source, entry.config?.headers);
+  if (entry.type === "graphql") {
+    const spec = await loadGraphQL(entry.source, entry.config?.headers);
+    return {
+      ...spec,
+      operations: applyFilter(spec.operations, (op) => op.name, entry.config?.allowedTools, entry.config?.disabledTools),
+    };
+  }
   // openapi — url or file; skip GraphQL probe since type is explicitly declared
   const isUrl = entry.source?.startsWith("http://") || entry.source?.startsWith("https://");
-  return isUrl ? await loadFromUrl(entry.source, true) : loadFromFile(entry.source);
+  const spec = isUrl ? await loadFromUrl(entry.source, true) : loadFromFile(entry.source);
+  return {
+    ...spec,
+    operations: applyFilter(spec.operations, (op) => op.id, entry.config?.allowedTools, entry.config?.disabledTools),
+  };
 }
 
 /**
@@ -79,6 +97,13 @@ export async function resolveSpec(entry) {
  * Returns null if no inline source flags present.
  */
 export function inlineEntryFromFlags(flags) {
+  const allowed = flags["allow-tool"];
+  const disabled = flags["disable-tool"];
+  const filterConfig = {
+    ...(allowed?.length ? { allowedTools: allowed } : {}),
+    ...(disabled?.length ? { disabledTools: disabled } : {}),
+  };
+
   if (flags["mcp-stdio"]) {
     const raw = flags["mcp-stdio"];
     const parts = (raw.trim() ? raw.match(/(?:[^\s"]+|"[^"]*")+/g) : null)?.map((p) => p.replace(/^"|"$/g, ""));
@@ -89,7 +114,7 @@ export function inlineEntryFromFlags(flags) {
       command: parts[0],
       args: parts.slice(1),
       cwd: flags.cwd,
-      config: { env: parseKV(flags.env) },
+      config: { env: parseKV(flags.env), ...filterConfig },
     };
   }
   if (flags["mcp-sse"]) {
@@ -97,7 +122,7 @@ export function inlineEntryFromFlags(flags) {
       type: "mcp",
       transport: "sse",
       url: flags["mcp-sse"],
-      config: { headers: parseKV(flags.header) },
+      config: { headers: parseKV(flags.header), ...filterConfig },
     };
   }
   if (flags["mcp-http"]) {
@@ -105,34 +130,20 @@ export function inlineEntryFromFlags(flags) {
       type: "mcp",
       transport: "streamable-http",
       url: flags["mcp-http"],
-      config: { headers: parseKV(flags.header) },
+      config: { headers: parseKV(flags.header), ...filterConfig },
     };
   }
   if (flags.graphql) {
-    return { type: "graphql", source: flags.graphql, config: { headers: parseKV(flags.header) } };
+    return { type: "graphql", source: flags.graphql, config: { headers: parseKV(flags.header), ...filterConfig } };
   }
   if (flags.openapi) {
-    return { type: "openapi", source: flags.openapi, config: { headers: parseKV(flags.header), baseUrl: flags["base-url"] || null } };
+    return { type: "openapi", source: flags.openapi, config: { headers: parseKV(flags.header), baseUrl: flags["base-url"] || null, ...filterConfig } };
   }
   return null;
 }
 
 // --- 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 {
@@ -143,10 +154,7 @@ async function loadMCPFromEntry(entry) {
       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)));
+    mapped = applyFilter(mapped, (t) => t.name, entry.config?.allowedTools, entry.config?.disabledTools);
 
     return {
       type: "mcp",

package/src/commands/grep.js

@@ -1,7 +1,8 @@
 import { out } from "../output.js";
 import { parseArgs } from "../args.js";
 import { getRegistry, getEntry, getCachedSpec, saveCachedSpec } from "../registry.js";
-import { resolveSpec, matchGlob } from "./load.js";
+import { fetchSpec } from "./fetch.js";
+import { matchGlob } from "../glob.js";
 
 export async function grepCmd(args) {
   const { flags, positional } = parseArgs(args);
@@ -23,7 +24,7 @@ export async function grepCmd(args) {
   for (const entry of entries) {
     let spec = getCachedSpec(entry.name);
     if (!spec) {
-      spec = await resolveSpec(entry);
+      spec = await fetchSpec(entry);
       saveCachedSpec(entry.name, spec);
     }
 

package/src/commands/list.js

@@ -1,12 +1,12 @@
 import { out } from "../output.js";
 import { parseArgs } from "../args.js";
-import { resolveActiveSpec } from "../resolve.js";
+import { resolveSpec } from "../resolve.js";
 
 export async function listOperations(args) {
   const opts = parseArgs(args);
   const { flags } = opts;
 
-  const { spec } = await resolveActiveSpec(flags);
+  const { spec } = await resolveSpec(flags);
 
   const filter = flags.filter?.toLowerCase();
   const compact = flags.compact !== "false";

package/src/commands/show.js

@@ -1,13 +1,13 @@
 import { out } from "../output.js";
 import { parseArgs } from "../args.js";
-import { resolveActiveSpec } from "../resolve.js";
+import { resolveSpec } from "../resolve.js";
 
 export async function showOperation(args) {
   const { flags, positional } = parseArgs(args);
   const target = positional[0];
   if (!target) throw new Error("Usage: spec show <operationId-or-path> [--spec <name> | --openapi <url> | ...]");
 
-  const { spec } = await resolveActiveSpec(flags);
+  const { spec } = await resolveSpec(flags);
 
   if (spec.type === "openapi") {
     showOpenAPI(spec, target);

package/src/commands/specs.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "../args.js";
 import { getRegistry, saveRegistry, getEntry, removeCachedSpec, saveCachedSpec } from "../registry.js";
-import { resolveSpec } from "./load.js";
+import { fetchSpec } from "./fetch.js";
 import { out } from "../output.js";
 
 export async function specsCmd(args) {
@@ -58,7 +58,7 @@ export async function registryMutate(action, args) {
   if (action === "refresh") {
     const entry = registry[idx];
     if (!entry.enabled) throw new Error(`Spec '${name}' is disabled. Enable it first.`);
-    const spec = await resolveSpec(entry);
+    const spec = await fetchSpec(entry);
     saveCachedSpec(name, spec);
     const count = spec.tools?.length ?? spec.operations?.length ?? 0;
     out({ ok: true, refreshed: name, type: spec.type, count });

package/src/commands/types.js

@@ -1,10 +1,10 @@
 import { out } from "../output.js";
 import { parseArgs } from "../args.js";
-import { resolveActiveSpec } from "../resolve.js";
+import { resolveSpec } from "../resolve.js";
 
 export async function typesCmd(args) {
   const { positional, flags } = parseArgs(args);
-  const { spec } = await resolveActiveSpec(flags);
+  const { spec } = await resolveSpec(flags);
   const target = positional[0];
 
   if (spec.type === "openapi") {

package/src/glob.js

@@ -0,0 +1,29 @@
+function globToRegex(pattern) {
+  return new RegExp(
+    "^" + pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") + "$",
+    "i"
+  );
+}
+
+/**
+ * Search match: plain text = substring, glob chars (* ?) = anchored glob.
+ * Used by grep — broad matching is desirable for search.
+ */
+export function matchGlob(pattern, str) {
+  if (!pattern.includes("*") && !pattern.includes("?")) {
+    return str.toLowerCase().includes(pattern.toLowerCase());
+  }
+  return globToRegex(pattern).test(str);
+}
+
+/**
+ * Filter match: plain text = exact (case-insensitive), glob chars (* ?) = anchored glob.
+ * Used by --allow-tool / --disable-tool — precision is required for whitelists.
+ * Use *pattern* for explicit substring matching.
+ */
+export function matchFilter(pattern, str) {
+  if (!pattern.includes("*") && !pattern.includes("?")) {
+    return str.toLowerCase() === pattern.toLowerCase();
+  }
+  return globToRegex(pattern).test(str);
+}

package/src/mcp-client.js

@@ -55,7 +55,7 @@ export async function createMcpClient(spec) {
     } catch (e) {
       lastError = e;
       if (attempt < MAX_RETRIES) {
-        await new Promise((r) => setTimeout(r, RETRY_DELAY * Math.pow(2, attempt)));
+        await new Promise((r) => setTimeout(r, Math.min(RETRY_DELAY * Math.pow(2, attempt), 5000)));
       }
     }
   }

package/src/resolve.js

@@ -1,5 +1,5 @@
 import { getEntry, getCachedSpec, saveCachedSpec } from "./registry.js";
-import { resolveSpec, inlineEntryFromFlags } from "./commands/load.js";
+import { fetchSpec, inlineEntryFromFlags } from "./commands/fetch.js";
 import { getConfig } from "./store.js";
 import { parseKV } from "./args.js";
 
@@ -10,12 +10,12 @@ import { parseKV } from "./args.js";
  *   2. Inline flags   → ad-hoc, no caching
  *   3. Error          → no spec source given
  */
-export async function resolveActiveSpec(flags) {
+export async function resolveSpec(flags) {
   if (flags.spec) {
     const entry = getEntry(flags.spec);     // throws if missing or disabled
     let spec = getCachedSpec(flags.spec);
     if (!spec) {
-      spec = await resolveSpec(entry);
+      spec = await fetchSpec(entry);
       saveCachedSpec(flags.spec, spec);
     }
     return { spec, entry };
@@ -23,7 +23,7 @@ export async function resolveActiveSpec(flags) {
 
   const inlineEntry = inlineEntryFromFlags(flags);
   if (inlineEntry) {
-    const spec = await resolveSpec(inlineEntry);
+    const spec = await fetchSpec(inlineEntry);
     return { spec, entry: inlineEntry };
   }