api-spec-cli 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-spec-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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;
+}