api-spec-cli 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # api-spec-cli
 
-CLI for AI agents to explore and call OpenAPI and GraphQL APIs. Output is JSON by default — compact, parseable, token-efficient.
+CLI for AI agents to explore and call OpenAPI, GraphQL, and MCP APIs. Output is JSON by default — compact, parseable, token-efficient.
 
 ## Install
 
@@ -8,7 +8,7 @@ CLI for AI agents to explore and call OpenAPI and GraphQL APIs. Output is JSON b
 npm install -g api-spec-cli
 ```
 
-Works with Node.js 18+ or Bun. No other dependencies.
+Works with Node.js 18+. No other dependencies.
 
 ```bash
 # Or run without installing
@@ -22,22 +22,34 @@ The CLI follows a progressive discovery pattern. You never dump an entire API sp
 ### Step 1: Load the spec
 
 ```bash
-spec load https://petstore3.swagger.io/api/v3/openapi.json   # OpenAPI
-spec load ./openapi.yaml                                       # Local file
-spec load https://gql.hashnode.com                             # GraphQL (introspection)
+# OpenAPI
+spec load https://petstore3.swagger.io/api/v3/openapi.json
+spec load ./openapi.yaml
+
+# GraphQL (auto-introspects)
+spec load https://gql.hashnode.com
+
+# MCP — stdio transport (spawn a local server)
+spec load --mcp-stdio "npx -y @modelcontextprotocol/server-filesystem /tmp"
+
+# MCP — SSE transport
+spec load --mcp-sse http://localhost:3000/sse
+
+# MCP — Streamable HTTP transport
+spec load --mcp-http https://docs.agno.com/mcp
 ```
 
 Output tells you what was loaded:
 ```json
-{ "ok": true, "type": "graphql", "operationCount": 114, "source": "https://gql.hashnode.com" }
+{ "ok": true, "type": "mcp", "transport": "streamable-http", "toolCount": 1 }
 ```
 
 ### Step 2: Find what you need
 
-`list` is compact by default — just operation IDs, no schemas. Use `--filter`, `--tag`, `--limit` to narrow down.
+`list` is compact by default — just IDs, no schemas. Use `--filter`, `--tag`, `--limit` to narrow down.
 
 ```bash
-spec list                          # All operations (compact IDs only)
+spec list                          # All operations/tools (compact IDs only)
 spec list --filter publish         # Search by keyword
 spec list --tag pets               # OpenAPI: filter by tag
 spec list --tag mutation           # GraphQL: filter by kind (query/mutation/subscription)
@@ -48,32 +60,32 @@ spec list --limit 10 --offset 10   # Next 10
 Compact output (token-efficient):
 ```json
 {
-  "type": "graphql",
-  "total": 5,
-  "showing": 5,
+  "type": "mcp",
+  "total": 1,
+  "showing": 1,
   "operations": [
-    { "id": "publishPost", "kind": "mutation" },
-    { "id": "publishDraft", "kind": "mutation" }
+    { "id": "search_agno", "description": "Search across the Agno knowledge base..." }
   ]
 }
 ```
 
-Use `--compact false` for full details (summary, tags, args).
+Use `--compact false` for full details (including `inputSchema` for MCP tools).
 
-### Step 3: Inspect one operation
+### Step 3: Inspect one operation or tool
 
-`show` gives you everything you need to call an operation — params, body schema, response, and related types — in one call.
+`show` gives you everything you need to make a call — params, body schema, response, and related types — in one call.
 
 ```bash
 spec show publishPost              # GraphQL: by operation name
 spec show getPetById               # OpenAPI: by operationId
 spec show /pet/{petId}             # OpenAPI: by path
 spec show "GET /pet/{petId}"       # OpenAPI: by method + path
+spec show search_agno              # MCP: by tool name
 ```
 
-Schemas are compact. Nested `$ref` references show as type names (not exploded), so the output stays small. If you need details on a referenced type, use `spec types <name>`.
+MCP output includes the full `inputSchema` so you know exactly what arguments to pass.
 
-### Step 4: Drill into types (if needed)
+### Step 4: Drill into types (OpenAPI/GraphQL only)
 
 ```bash
 spec types                         # List all schema/type names
@@ -81,12 +93,10 @@ spec types Pet                     # Inspect one schema
 spec types PublishPostInput        # Inspect a GraphQL input type
 ```
 
-This is optional — `show` already includes related types inline. Use `types` only when you need a type that wasn't included in the `show` output.
-
 ### Step 5: Call the API
 
 ```bash
-# Set base URL and auth first (persisted across calls)
+# Set base URL and auth first (persisted across calls — OpenAPI/GraphQL)
 spec config set baseUrl https://petstore3.swagger.io/api/v3
 spec config set auth YOUR_TOKEN
 
@@ -98,6 +108,10 @@ spec call addPet --data '{"name":"Rex","photoUrls":[]}'
 # GraphQL calls (auto-generates query from schema)
 spec call me
 spec call publication --var host=blog.hashnode.dev
+
+# MCP calls — use --var for individual args or --data for the full JSON object
+spec call search_agno --var query="how to create an agent"
+spec call read_file --data '{"path":"/tmp/hello.txt"}'
 ```
 
 ## Config

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-spec-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Agent-friendly CLI for exploring and calling OpenAPI and GraphQL APIs",
   "type": "module",
   "bin": {
@@ -35,6 +35,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
     "yaml": "^2.7.0"
   }
 }

package/src/cli.js

@@ -12,7 +12,10 @@ All output is JSON. Designed for AI agents but works for humans too.
 
 WORKFLOW (follow this order):
   1. spec load <file-or-url>           Load an OpenAPI or GraphQL spec
-  2. spec list                         Browse operations (compact IDs)
+     spec load --mcp-stdio <cmd>       Load an MCP server via stdio
+     spec load --mcp-sse <url>         Load an MCP server via SSE
+     spec load --mcp-http <url>        Load an MCP server via streamable HTTP
+  2. spec list                         Browse operations/tools (compact IDs)
   3. spec show <operation>             Get params, body, response for one op
   4. spec call <operation> [options]   Execute the request
 
@@ -30,16 +33,26 @@ INSPECT:
   spec show /pet/{petId}               Match by path
   spec show "GET /pet/{petId}"         Match by method + path
   spec show publishPost                GraphQL operation name
+  spec show read_file                  MCP tool name
   spec types                           List all schema/type names
   spec types Pet                       Inspect one schema (compact, no $ref explosion)
 
 EXECUTE:
   spec call <op> --var petId=1                       Path or GraphQL variables
   spec call <op> --query status=available             Query string params
-  spec call <op> --data '{"name":"Rex"}'              JSON body
+  spec call <op> --data '{"name":"Rex"}'              JSON body / MCP tool arguments
   spec call <op> --data-file /tmp/query.json          JSON body from file (avoids shell escaping)
-  spec call <op> --header X-Custom=val                Extra headers
-  spec call <op> --method PUT                         Override HTTP method
+  spec call <op> --header X-Custom=val                Extra headers (OpenAPI/GraphQL)
+  spec call <op> --method PUT                         Override HTTP method (OpenAPI)
+
+MCP EXAMPLES:
+  spec load --mcp-stdio "npx -y @modelcontextprotocol/server-filesystem /tmp"
+  spec load --mcp-sse http://localhost:3000/sse
+  spec load --mcp-http https://example.com/mcp
+  spec list
+  spec show read_file
+  spec call read_file --var path=/tmp/hello.txt
+  spec call read_file --data '{"path":"/tmp/hello.txt"}'
 
 CONFIG (persisted in .spec-cli/config.json):
   spec config set baseUrl https://api.example.com

package/src/commands/call.js

@@ -2,6 +2,7 @@ import { readFileSync } from "fs";
 import { getSpec, getConfig } from "../store.js";
 import { out } from "../output.js";
 import { parseArgs, parseKV } from "../args.js";
+import { createMcpClient } from "../mcp-client.js";
 
 export async function callOperation(args) {
   const { flags, positional } = parseArgs(args);
@@ -20,11 +21,39 @@ export async function callOperation(args) {
 
   if (spec.type === "openapi") {
     await callOpenAPI(spec, config, target, flags);
+  } else if (spec.type === "mcp") {
+    await callMCP(spec, target, flags);
   } else {
     await callGraphQL(spec, config, target, flags);
   }
 }
 
+async function callMCP(spec, target, flags) {
+  const tool = spec.tools.find((t) => t.name.toLowerCase() === target.toLowerCase());
+  if (!tool) throw new Error(`Tool not found: ${target}. Run 'spec list' to see available tools.`);
+
+  // Build arguments: --data for full JSON object, --var for individual keys
+  let toolArgs = {};
+  if (flags.data) {
+    try {
+      toolArgs = JSON.parse(flags.data);
+    } catch {
+      throw new Error("--data must be valid JSON when calling an MCP tool");
+    }
+  }
+  // --var key=value overrides / extends --data args
+  const varOverrides = parseKV(flags.var);
+  toolArgs = { ...toolArgs, ...varOverrides };
+
+  const client = await createMcpClient(spec);
+  try {
+    const result = await client.callTool({ name: tool.name, arguments: toolArgs });
+    out({ tool: tool.name, arguments: toolArgs, result });
+  } finally {
+    await client.close();
+  }
+}
+
 async function callOpenAPI(spec, config, target, flags) {
   const lower = target.toLowerCase();
 

package/src/commands/list.js

@@ -36,6 +36,12 @@ export async function listOperations(args) {
         fullOps[i].tags?.some((t) => t.toLowerCase().includes(tag))
       );
     }
+  } else if (spec.type === "mcp") {
+    operations = spec.tools.map((t) =>
+      compact
+        ? { id: t.name, description: t.description }
+        : { id: t.name, description: t.description, inputSchema: t.inputSchema }
+    );
   } else {
     // graphql
     operations = spec.operations.map((op) =>

package/src/commands/load.js

@@ -3,6 +3,8 @@ import { resolve } from "path";
 import YAML from "yaml";
 import { saveSpec } from "../store.js";
 import { out, err } from "../output.js";
+import { parseArgs } from "../args.js";
+import { createMcpClient } from "../mcp-client.js";
 
 const INTROSPECTION_QUERY = `{
   __schema {
@@ -60,8 +62,24 @@ fragment TypeRef on __Type {
 }`;
 
 export async function loadSpec(args) {
-  const source = args[0];
-  if (!source) throw new Error("Usage: spec load <file-or-url>");
+  const { flags, positional } = parseArgs(args);
+
+  // MCP transport flags
+  if (flags["mcp-stdio"] || flags["mcp-sse"] || flags["mcp-http"]) {
+    const spec = await loadMCP(flags);
+    saveSpec(spec);
+    out({
+      ok: true,
+      type: "mcp",
+      title: spec.title,
+      transport: spec.transport,
+      toolCount: spec.tools.length,
+    });
+    return;
+  }
+
+  const source = positional[0];
+  if (!source) throw new Error("Usage: spec load <file-or-url>  |  spec load --mcp-stdio <cmd>  |  spec load --mcp-sse <url>  |  spec load --mcp-http <url>");
 
   // Detect if it's a URL or file
   const isUrl = source.startsWith("http://") || source.startsWith("https://");
@@ -84,6 +102,48 @@ export async function loadSpec(args) {
   });
 }
 
+async function loadMCP(flags) {
+  let transportConfig;
+
+  if (flags["mcp-stdio"]) {
+    const raw = flags["mcp-stdio"];
+    // Split on whitespace, respecting that the value is already a single flag string
+    const parts = raw.match(/(?:[^\s"]+|"[^"]*")+/g).map((p) => p.replace(/^"|"$/g, ""));
+    transportConfig = {
+      transport: "stdio",
+      command: parts[0],
+      args: parts.slice(1),
+    };
+  } else if (flags["mcp-sse"]) {
+    transportConfig = {
+      transport: "sse",
+      url: flags["mcp-sse"],
+    };
+  } else {
+    transportConfig = {
+      transport: "streamable-http",
+      url: flags["mcp-http"],
+    };
+  }
+
+  const client = await createMcpClient(transportConfig);
+  try {
+    const { tools } = await client.listTools();
+    return {
+      type: "mcp",
+      title: "MCP Server",
+      ...transportConfig,
+      tools: tools.map((t) => ({
+        name: t.name,
+        description: t.description || null,
+        inputSchema: t.inputSchema || null,
+      })),
+    };
+  } finally {
+    await client.close();
+  }
+}
+
 async function loadFromUrl(url) {
   // Try GraphQL introspection first if URL doesn't end with known extensions
   const lowerUrl = url.toLowerCase();

package/src/commands/show.js

@@ -12,6 +12,8 @@ export async function showOperation(args) {
 
   if (spec.type === "openapi") {
     showOpenAPI(spec, target);
+  } else if (spec.type === "mcp") {
+    showMCP(spec, target);
   } else {
     showGraphQL(spec, target);
   }
@@ -87,6 +89,18 @@ function showGraphQL(spec, target) {
   });
 }
 
+function showMCP(spec, target) {
+  const tool = spec.tools.find((t) => t.name.toLowerCase() === target.toLowerCase());
+  if (!tool) {
+    throw new Error(`Tool not found: ${target}. Run 'spec list' to see available tools.`);
+  }
+  out({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+  });
+}
+
 // --- Helpers ---
 
 function resolveRef(obj, root) {

package/src/mcp-client.js

@@ -0,0 +1,25 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+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 client = new Client({ name: "spec-cli", version: "1.0.0" });
+
+  let transport;
+  if (spec.transport === "stdio") {
+    transport = new StdioClientTransport({
+      command: spec.command,
+      args: spec.args,
+    });
+  } else if (spec.transport === "sse") {
+    transport = new SSEClientTransport(new URL(spec.url));
+  } else if (spec.transport === "streamable-http") {
+    transport = new StreamableHTTPClientTransport(new URL(spec.url));
+  } else {
+    throw new Error(`Unknown MCP transport: ${spec.transport}. Supported: stdio, sse, streamable-http`);
+  }
+
+  await client.connect(transport);
+  return client;
+}