@ivotoby/openapi-mcp-server 1.4.1 → 1.5.1

package/README.md

@@ -1,5 +1,7 @@
 # OpenAPI MCP Server
 
+[![smithery badge](https://smithery.ai/badge/@ivo-toby/mcp-openapi-server)](https://smithery.ai/server/@ivo-toby/mcp-openapi-server)
+
 A Model Context Protocol (MCP) server that exposes OpenAPI endpoints as MCP resources. This server allows Large Language Models to discover and interact with REST APIs defined by OpenAPI specifications through the MCP protocol.
 
 ## Overview
@@ -63,7 +65,7 @@ npx @ivotoby/openapi-mcp-server \
 # Initialize a session (first request)
 curl -X POST http://localhost:3000/mcp \
   -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"client":{"name":"curl-client","version":"1.0.0"},"protocol":{"name":"mcp","version":"2025-03-26"}}}'
+  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl-client","version":"1.0.0"}}}'
 
 # The response includes a Mcp-Session-Id header that you must use for subsequent requests
 # and the InitializeResult directly in the POST response body.
@@ -118,6 +120,8 @@ The server can be configured through environment variables or command line argum
 
 - `API_BASE_URL` - Base URL for the API endpoints
 - `OPENAPI_SPEC_PATH` - Path or URL to OpenAPI specification
+- `OPENAPI_SPEC_FROM_STDIN` - Set to "true" to read OpenAPI spec from standard input
+- `OPENAPI_SPEC_INLINE` - Provide OpenAPI spec content directly as a string
 - `API_HEADERS` - Comma-separated key:value pairs for API headers
 - `SERVER_NAME` - Name for the MCP server (default: "mcp-openapi-server")
 - `SERVER_VERSION` - Version of the server (default: "1.0.0")
@@ -136,7 +140,7 @@ npx @ivotoby/openapi-mcp-server \
   --openapi-spec https://api.example.com/openapi.json \
   --headers "Authorization:Bearer token123,X-API-Key:your-api-key" \
   --name "my-mcp-server" \
-  --version "1.0.0" \
+  --server-version "1.0.0" \
   --transport http \
   --port 3000 \
   --host 127.0.0.1 \
@@ -144,6 +148,105 @@ npx @ivotoby/openapi-mcp-server \
   --disable-abbreviation true
 ```
 
+## OpenAPI Specification Loading
+
+The MCP server supports multiple methods for loading OpenAPI specifications, providing flexibility for different deployment scenarios:
+
+### 1. URL Loading (Default)
+
+Load the OpenAPI spec from a remote URL:
+
+```bash
+npx @ivotoby/openapi-mcp-server \
+  --api-base-url https://api.example.com \
+  --openapi-spec https://api.example.com/openapi.json
+```
+
+### 2. Local File Loading
+
+Load the OpenAPI spec from a local file:
+
+```bash
+npx @ivotoby/openapi-mcp-server \
+  --api-base-url https://api.example.com \
+  --openapi-spec ./path/to/openapi.yaml
+```
+
+### 3. Standard Input Loading
+
+Read the OpenAPI spec from standard input (useful for piping or containerized environments):
+
+```bash
+# Pipe from file
+cat openapi.json | npx @ivotoby/openapi-mcp-server \
+  --api-base-url https://api.example.com \
+  --spec-from-stdin
+
+# Pipe from curl
+curl -s https://api.example.com/openapi.json | npx @ivotoby/openapi-mcp-server \
+  --api-base-url https://api.example.com \
+  --spec-from-stdin
+
+# Using environment variable
+export OPENAPI_SPEC_FROM_STDIN=true
+echo '{"openapi": "3.0.0", ...}' | npx @ivotoby/openapi-mcp-server \
+  --api-base-url https://api.example.com
+```
+
+### 4. Inline Specification
+
+Provide the OpenAPI spec content directly as a command line argument:
+
+```bash
+npx @ivotoby/openapi-mcp-server \
+  --api-base-url https://api.example.com \
+  --spec-inline '{"openapi": "3.0.0", "info": {"title": "My API", "version": "1.0.0"}, "paths": {}}'
+
+# Using environment variable
+export OPENAPI_SPEC_INLINE='{"openapi": "3.0.0", ...}'
+npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com
+```
+
+### Supported Formats
+
+All loading methods support both JSON and YAML formats. The server automatically detects the format and parses accordingly.
+
+### Docker and Container Usage
+
+For containerized deployments, you can mount OpenAPI specs or use stdin:
+
+```bash
+# Mount local file
+docker run -v /path/to/spec:/app/spec.json your-mcp-server \
+  --api-base-url https://api.example.com \
+  --openapi-spec /app/spec.json
+
+# Use stdin with docker
+cat openapi.json | docker run -i your-mcp-server \
+  --api-base-url https://api.example.com \
+  --spec-from-stdin
+```
+
+### Error Handling
+
+The server provides detailed error messages for spec loading failures:
+
+- **URL loading**: HTTP status codes and network errors
+- **File loading**: File system errors (not found, permissions, etc.)
+- **Stdin loading**: Empty input or read errors
+- **Inline loading**: Missing content errors
+- **Parsing errors**: Detailed JSON/YAML syntax error messages
+
+### Validation
+
+Only one specification source can be used at a time. The server will validate that exactly one of the following is provided:
+
+- `--openapi-spec` (URL or file path)
+- `--spec-from-stdin`
+- `--spec-inline`
+
+If multiple sources are specified, the server will exit with an error message.
+
 ### OpenAPI Schema Processing
 
 #### Reference Resolution

package/dist/bundle.js

@@ -14381,27 +14381,96 @@ var OpenAPISpecLoader = class {
     this.disableAbbreviation = config?.disableAbbreviation ?? false;
   }
   /**
-   * Load an OpenAPI specification from a file path or URL
+   * Load an OpenAPI specification from various sources
    */
-  async loadOpenAPISpec(specPathOrUrl) {
+  async loadOpenAPISpec(specPathOrUrl, inputMethod = "url", inlineContent) {
     let specContent;
-    if (specPathOrUrl.startsWith("http://") || specPathOrUrl.startsWith("https://")) {
-      const response = await fetch(specPathOrUrl);
-      if (!response.ok) {
-        throw new Error(`Failed to fetch OpenAPI spec from URL: ${specPathOrUrl}`);
+    try {
+      switch (inputMethod) {
+        case "url":
+          specContent = await this.loadFromUrl(specPathOrUrl);
+          break;
+        case "file":
+          specContent = await this.loadFromFile(specPathOrUrl);
+          break;
+        case "stdin":
+          specContent = await this.loadFromStdin();
+          break;
+        case "inline":
+          if (!inlineContent) {
+            throw new Error("Inline content is required when using 'inline' input method");
+          }
+          specContent = inlineContent;
+          break;
+        default:
+          throw new Error(`Unsupported input method: ${inputMethod}`);
       }
-      specContent = await response.text();
-    } else {
-      specContent = await readFile(specPathOrUrl, "utf-8");
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error(`Failed to load OpenAPI spec from ${inputMethod}: ${error.message}`);
+      }
+      throw error;
+    }
+    return this.parseSpecContent(specContent, inputMethod);
+  }
+  /**
+   * Load spec content from URL
+   */
+  async loadFromUrl(url2) {
+    const response = await fetch(url2);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    return await response.text();
+  }
+  /**
+   * Load spec content from local file
+   */
+  async loadFromFile(filePath) {
+    return await readFile(filePath, "utf-8");
+  }
+  /**
+   * Load spec content from standard input
+   */
+  async loadFromStdin() {
+    return new Promise((resolve5, reject) => {
+      let data = "";
+      process.stdin.setEncoding("utf8");
+      process.stdin.on("data", (chunk) => {
+        data += chunk;
+      });
+      process.stdin.on("end", () => {
+        if (data.trim().length === 0) {
+          reject(new Error("No data received from stdin"));
+        } else {
+          resolve5(data);
+        }
+      });
+      process.stdin.on("error", (error) => {
+        reject(new Error(`Error reading from stdin: ${error.message}`));
+      });
+      process.stdin.resume();
+    });
+  }
+  /**
+   * Parse spec content as JSON or YAML
+   */
+  parseSpecContent(specContent, source) {
+    if (!specContent || specContent.trim().length === 0) {
+      throw new Error(`Empty or invalid spec content from ${source}`);
     }
     try {
       return JSON.parse(specContent);
     } catch (jsonError) {
       try {
-        return js_yaml_default.load(specContent);
+        const yamlResult = js_yaml_default.load(specContent);
+        if (!yamlResult || typeof yamlResult !== "object") {
+          throw new Error("YAML parsing resulted in invalid object");
+        }
+        return yamlResult;
       } catch (yamlError) {
         throw new Error(
-          `Failed to parse OpenAPI spec as JSON or YAML: ${jsonError.message} | ${yamlError.message}`
+          `Failed to parse as JSON or YAML. JSON error: ${jsonError.message}. YAML error: ${yamlError.message}`
         );
       }
     }
@@ -14782,7 +14851,11 @@ var ToolsManager = class {
    * Initialize tools from the OpenAPI specification
    */
   async initialize() {
-    const spec = await this.specLoader.loadOpenAPISpec(this.config.openApiSpec);
+    const spec = await this.specLoader.loadOpenAPISpec(
+      this.config.openApiSpec,
+      this.config.specInputMethod,
+      this.config.inlineSpecContent
+    );
     if (this.config.toolsMode === "dynamic") {
       this.tools = this.createDynamicTools();
       return;
@@ -23293,6 +23366,12 @@ function loadConfig() {
     alias: "s",
     type: "string",
     description: "Path or URL to OpenAPI specification"
+  }).option("spec-from-stdin", {
+    type: "boolean",
+    description: "Read OpenAPI spec from standard input"
+  }).option("spec-inline", {
+    type: "string",
+    description: "Provide OpenAPI spec content directly as a string"
   }).option("headers", {
     alias: "H",
     type: "string",
@@ -23301,7 +23380,7 @@ function loadConfig() {
     alias: "n",
     type: "string",
     description: "Server name"
-  }).option("version", {
+  }).option("server-version", {
     alias: "v",
     type: "string",
     description: "Server version"
@@ -23338,21 +23417,51 @@ function loadConfig() {
   const httpPort = argv.port ?? (process.env.HTTP_PORT ? parseInt(process.env.HTTP_PORT, 10) : 3e3);
   const httpHost = argv.host || process.env.HTTP_HOST || "127.0.0.1";
   const endpointPath = argv.path || process.env.ENDPOINT_PATH || "/mcp";
-  const apiBaseUrl = argv["api-base-url"] || process.env.API_BASE_URL;
+  const specFromStdin = argv["spec-from-stdin"] || process.env.OPENAPI_SPEC_FROM_STDIN === "true";
+  const specInline = argv["spec-inline"] || process.env.OPENAPI_SPEC_INLINE;
   const openApiSpec = argv["openapi-spec"] || process.env.OPENAPI_SPEC_PATH;
+  const specInputCount = [specFromStdin, !!specInline, !!openApiSpec].filter(Boolean).length;
+  if (specInputCount === 0) {
+    throw new Error(
+      "OpenAPI spec is required. Use one of: --openapi-spec, --spec-from-stdin, or --spec-inline"
+    );
+  }
+  if (specInputCount > 1) {
+    throw new Error("Only one OpenAPI spec input method can be specified at a time");
+  }
+  let specInputMethod;
+  let specPath;
+  let inlineSpecContent;
+  if (specFromStdin) {
+    specInputMethod = "stdin";
+    specPath = "stdin";
+  } else if (specInline) {
+    specInputMethod = "inline";
+    specPath = "inline";
+    inlineSpecContent = specInline;
+  } else if (openApiSpec) {
+    if (openApiSpec.startsWith("http://") || openApiSpec.startsWith("https://")) {
+      specInputMethod = "url";
+    } else {
+      specInputMethod = "file";
+    }
+    specPath = openApiSpec;
+  } else {
+    throw new Error("OpenAPI spec is required");
+  }
+  const apiBaseUrl = argv["api-base-url"] || process.env.API_BASE_URL;
   const disableAbbreviation = argv["disable-abbreviation"] || (process.env.DISABLE_ABBREVIATION ? process.env.DISABLE_ABBREVIATION === "true" : false);
   if (!apiBaseUrl) {
     throw new Error("API base URL is required (--api-base-url or API_BASE_URL)");
   }
-  if (!openApiSpec) {
-    throw new Error("OpenAPI spec is required (--openapi-spec or OPENAPI_SPEC_PATH)");
-  }
   const headers = parseHeaders(argv.headers || process.env.API_HEADERS);
   return {
     name: argv.name || process.env.SERVER_NAME || "mcp-openapi-server",
-    version: argv.version || process.env.SERVER_VERSION || "1.0.0",
+    version: argv["server-version"] || process.env.SERVER_VERSION || "1.0.0",
     apiBaseUrl,
-    openApiSpec,
+    openApiSpec: specPath,
+    specInputMethod,
+    inlineSpecContent,
     headers,
     transportType,
     httpPort,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ivotoby/openapi-mcp-server",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "description": "An MCP server that exposes OpenAPI endpoints as resources",
   "license": "MIT",
   "type": "module",