@ivotoby/openapi-mcp-server 1.4.0 → 1.5.0

package/README.md

@@ -118,6 +118,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 +138,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 +146,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.0",
+  "version": "1.5.0",
   "description": "An MCP server that exposes OpenAPI endpoints as resources",
   "license": "MIT",
   "type": "module",