@ivotoby/openapi-mcp-server 1.2.0 → 1.2.2

package/README.md

@@ -125,6 +125,7 @@ The server can be configured through environment variables or command line argum
 - `HTTP_PORT` - Port for HTTP transport (default: 3000)
 - `HTTP_HOST` - Host for HTTP transport (default: "127.0.0.1")
 - `ENDPOINT_PATH` - Endpoint path for HTTP transport (default: "/mcp")
+- `TOOLS_MODE` - Tools loading mode: "all" (load all endpoint-based tools) or "dynamic" (load only meta-tools) (default: "all")
 
 ### Command Line Arguments
 
@@ -141,6 +142,61 @@ npx @ivotoby/openapi-mcp-server \
   --path /mcp
 ```
 
+### OpenAPI Schema Processing
+
+#### Reference Resolution
+
+This MCP server implements robust OpenAPI reference (`$ref`) resolution to ensure accurate representation of API schemas:
+
+- **Parameter References**: Fully resolves `$ref` pointers to parameter components in the OpenAPI spec
+- **Schema References**: Handles nested schema references within parameters and request bodies
+- **Recursive References**: Prevents infinite loops by detecting and handling circular references
+- **Nested Properties**: Preserves complex nested object and array structures with all their attributes
+
+### Input Schema Composition
+
+The server intelligently merges parameters and request bodies into a unified input schema for each tool:
+
+- **Parameters + Request Body Merging**: Combines path, query, and body parameters into a single schema
+- **Collision Handling**: Resolves naming conflicts by prefixing body properties that conflict with parameter names
+- **Type Preservation**: Maintains the original type information for all schema elements
+- **Metadata Retention**: Preserves descriptions, formats, defaults, enums, and other schema attributes
+
+### Complex Schema Support
+
+The MCP server handles various OpenAPI schema complexities:
+
+- **Primitive Type Bodies**: Wraps non-object request bodies in a "body" property
+- **Object Bodies**: Flattens object properties into the tool's input schema
+- **Array Bodies**: Properly handles array schemas with their nested item definitions
+- **Required Properties**: Tracks and preserves which parameters and properties are required
+
+## Tool Loading & Filtering Options
+
+Based on the Stainless article "What We Learned Converting Complex OpenAPI Specs to MCP Servers" (https://www.stainless.com/blog/what-we-learned-converting-complex-openapi-specs-to-mcp-servers), the following flags were added to control which API endpoints (tools) are loaded:
+
+- `--tools <all|dynamic>`: Choose to load all tools (default) or only dynamic meta-tools (`list-api-endpoints`, `get-api-endpoint-schema`, `invoke-api-endpoint`).
+- `--tool <toolId>`: Import only specified tool IDs or names. Can be used multiple times.
+- `--tag <tag>`: Import only tools with the specified OpenAPI tag. Can be used multiple times.
+- `--resource <resource>`: Import only tools under the specified resource path prefixes. Can be used multiple times.
+- `--operation <method>`: Import only tools for the specified HTTP methods (get, post, etc). Can be used multiple times.
+
+**Examples:**
+
+```bash
+# Load only dynamic meta-tools
+npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tools dynamic
+
+# Load only the GET /users endpoint tool
+npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tool GET-users
+
+# Load tools tagged with "user" under the "/users" resource
+npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tag user --resource users
+
+# Load only POST operations
+npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --operation post
+```
+
 ## Security Considerations
 
 - The HTTP transport validates Origin headers to prevent DNS rebinding attacks
@@ -187,6 +243,32 @@ To see debug logs:
 4. Run tests and linting: `npm run typecheck && npm run lint`
 5. Submit a pull request
 
+## FAQ
+
+**Q: What is a "tool"?**
+A: A tool corresponds to a single API endpoint derived from your OpenAPI specification, exposed as an MCP resource.
+
+**Q: How do I filter which tools are loaded?**
+A: Use the `--tool`, `--tag`, `--resource`, and `--operation` flags, or set `TOOLS_MODE=dynamic` for meta-tools only.
+
+**Q: When should I use dynamic mode?**
+A: Dynamic mode provides meta-tools (`list-api-endpoints`, `get-api-endpoint-schema`, `invoke-api-endpoint`) to inspect and interact with endpoints without preloading all operations, which is useful for large or changing APIs.
+
+**Q: How do I specify custom headers for API requests?**
+A: Use the `--headers` flag or `API_HEADERS` environment variable with `key:value` pairs separated by commas.
+
+**Q: Which transport methods are supported?**
+A: The server supports stdio transport (default) for integration with AI systems and HTTP transport (with streaming via SSE) for web clients.
+
+**Q: How does the server handle complex OpenAPI schemas with references?**
+A: The server fully resolves `$ref` references in parameters and schemas, preserving nested structures, default values, and other attributes. See the "OpenAPI Schema Processing" section for details on reference resolution and schema composition.
+
+**Q: What happens when parameter names conflict with request body properties?**
+A: The server detects naming conflicts and automatically prefixes body property names with `body_` to avoid collisions, ensuring all properties are accessible.
+
+**Q: Where can I find development and contribution guidelines?**
+A: See the "For Developers" section above for commands (`npm run build`, `npm run dev`, etc) and pull request workflow.
+
 ## License
 
 MIT

package/dist/bundle.js

@@ -14399,6 +14399,50 @@ var OpenAPISpecLoader = class {
       }
     }
   }
+  /**
+   * Inline `$ref` schemas from components and drop recursive cycles
+   */
+  inlineSchema(schema2, components, visited) {
+    if ("$ref" in schema2 && typeof schema2.$ref === "string") {
+      const ref = schema2.$ref;
+      const match = ref.match(/^#\/components\/schemas\/(.+)$/);
+      if (match && components) {
+        const name = match[1];
+        if (visited.has(name)) {
+          return {};
+        }
+        const comp = components[name];
+        if (!comp) {
+          return {};
+        }
+        visited.add(name);
+        return this.inlineSchema(comp, components, visited);
+      }
+    }
+    const schemaObj = schema2;
+    if (schemaObj.type === "object" && schemaObj.properties) {
+      const newProps = {};
+      for (const [propName, propSchema] of Object.entries(schemaObj.properties)) {
+        newProps[propName] = this.inlineSchema(
+          propSchema,
+          components,
+          new Set(visited)
+        );
+      }
+      return { ...schemaObj, properties: newProps };
+    }
+    if (schemaObj.type === "array" && schemaObj.items) {
+      return {
+        ...schemaObj,
+        items: this.inlineSchema(
+          schemaObj.items,
+          components,
+          new Set(visited)
+        )
+      };
+    }
+    return schemaObj;
+  }
   /**
    * Parse an OpenAPI specification into a map of tools
    */
@@ -14408,6 +14452,9 @@ var OpenAPISpecLoader = class {
       if (!pathItem) continue;
       for (const [method, operation] of Object.entries(pathItem)) {
         if (method === "parameters" || !operation) continue;
+        if (!["get", "put", "post", "delete", "options", "head", "patch", "trace"].includes(method)) {
+          continue;
+        }
         const op = operation;
         const cleanPath = path.replace(/^\//, "").replace(/\{([^}]+)\}/g, "$1");
         const toolId = `${method.toUpperCase()}-${cleanPath}`.replace(/[^a-zA-Z0-9-]/g, "-");
@@ -14421,25 +14468,83 @@ var OpenAPISpecLoader = class {
             properties: {}
           }
         };
+        const requiredParams = [];
         if (op.parameters) {
-          const requiredParams = [];
           for (const param of op.parameters) {
-            if ("name" in param && "in" in param) {
-              const paramSchema = param.schema;
-              if (tool.inputSchema && tool.inputSchema.properties) {
-                tool.inputSchema.properties[param.name] = {
-                  type: paramSchema.type || "string",
-                  description: param.description || `${param.name} parameter`
-                };
+            let paramObj;
+            if (!("name" in param)) {
+              if ("$ref" in param && typeof param.$ref === "string") {
+                const refMatch = param.$ref.match(/^#\/components\/parameters\/(.+)$/);
+                if (refMatch && spec.components?.parameters) {
+                  const paramName = refMatch[1];
+                  const resolvedParam = spec.components.parameters[paramName];
+                  if (!resolvedParam || !("name" in resolvedParam)) continue;
+                  paramObj = resolvedParam;
+                } else {
+                  continue;
+                }
+              } else {
+                continue;
               }
-              if (param.required === true) {
-                requiredParams.push(param.name);
+            } else {
+              paramObj = param;
+            }
+            if (paramObj.schema) {
+              const paramSchema = this.inlineSchema(
+                paramObj.schema,
+                spec.components?.schemas,
+                /* @__PURE__ */ new Set()
+              );
+              const paramDef = {
+                description: paramObj.description || `${paramObj.name} parameter`
+              };
+              if (paramSchema.type) {
+                paramDef.type = paramSchema.type;
+              } else {
+                paramDef.type = "string";
+              }
+              for (const [key, value] of Object.entries(paramSchema)) {
+                if (key === "type" || key === "description") continue;
+                paramDef[key] = value;
+              }
+              tool.inputSchema.properties[paramObj.name] = paramDef;
+              if (paramObj.required === true) {
+                requiredParams.push(paramObj.name);
               }
             }
           }
-          if (requiredParams.length > 0 && tool.inputSchema) {
-            tool.inputSchema.required = requiredParams;
+        }
+        if (op.requestBody && "content" in op.requestBody) {
+          const requestBodyObj = op.requestBody;
+          let mediaTypeObj;
+          if (requestBodyObj.content["application/json"]) {
+            mediaTypeObj = requestBodyObj.content["application/json"];
+          } else if (Object.keys(requestBodyObj.content).length > 0) {
+            const firstContentType = Object.keys(requestBodyObj.content)[0];
+            mediaTypeObj = requestBodyObj.content[firstContentType];
           }
+          if (mediaTypeObj?.schema) {
+            const inlinedSchema = this.inlineSchema(
+              mediaTypeObj.schema,
+              spec.components?.schemas,
+              /* @__PURE__ */ new Set()
+            );
+            if (inlinedSchema.type === "object" && inlinedSchema.properties) {
+              for (const [propName, propSchema] of Object.entries(inlinedSchema.properties)) {
+                const paramName = tool.inputSchema.properties[propName] ? `body_${propName}` : propName;
+                tool.inputSchema.properties[paramName] = propSchema;
+                if (inlinedSchema.required && inlinedSchema.required.includes(propName)) {
+                  requiredParams.push(paramName);
+                }
+              }
+            } else {
+              tool.inputSchema.properties["body"] = inlinedSchema;
+              requiredParams.push("body");
+            }
+          }
+        }
+        if (requiredParams.length > 0) {
+          tool.inputSchema.required = requiredParams;
         }
         tools.set(toolId, tool);
       }
@@ -14567,16 +14672,103 @@ var OpenAPISpecLoader = class {
 var ToolsManager = class {
   constructor(config) {
     this.config = config;
+    this.config.toolsMode = this.config.toolsMode || "all";
     this.specLoader = new OpenAPISpecLoader();
   }
   tools = /* @__PURE__ */ new Map();
   specLoader;
+  /**
+   * Create dynamic discovery meta-tools
+   */
+  createDynamicTools() {
+    const dynamicTools = /* @__PURE__ */ new Map();
+    dynamicTools.set("LIST-API-ENDPOINTS", {
+      name: "list-api-endpoints",
+      description: "List all available API endpoints",
+      inputSchema: { type: "object", properties: {} }
+    });
+    dynamicTools.set("GET-API-ENDPOINT-SCHEMA", {
+      name: "get-api-endpoint-schema",
+      description: "Get the JSON schema for a specified API endpoint",
+      inputSchema: {
+        type: "object",
+        properties: {
+          endpoint: { type: "string", description: "Endpoint path (e.g. /users/{id})" }
+        },
+        required: ["endpoint"]
+      }
+    });
+    dynamicTools.set("INVOKE-API-ENDPOINT", {
+      name: "invoke-api-endpoint",
+      description: "Invoke an API endpoint with provided parameters",
+      inputSchema: {
+        type: "object",
+        properties: {
+          endpoint: { type: "string", description: "Endpoint path to invoke" },
+          params: {
+            type: "object",
+            description: "Parameters for the API call",
+            properties: {}
+          }
+        },
+        required: ["endpoint"]
+      }
+    });
+    return dynamicTools;
+  }
   /**
    * Initialize tools from the OpenAPI specification
    */
   async initialize() {
     const spec = await this.specLoader.loadOpenAPISpec(this.config.openApiSpec);
-    this.tools = this.specLoader.parseOpenAPISpec(spec);
+    if (this.config.toolsMode === "dynamic") {
+      this.tools = this.createDynamicTools();
+      return;
+    }
+    const rawTools = this.specLoader.parseOpenAPISpec(spec);
+    const filtered = /* @__PURE__ */ new Map();
+    const includeToolsLower = this.config.includeTools?.map((t) => t.toLowerCase()) || [];
+    const includeOperationsLower = this.config.includeOperations?.map((op) => op.toLowerCase()) || [];
+    const includeResourcesLower = this.config.includeResources || [];
+    const includeTagsLower = this.config.includeTags?.map((tag) => tag.toLowerCase()) || [];
+    const resourcePathsLower = includeResourcesLower.map((res) => ({
+      exact: `/${res}`.toLowerCase(),
+      prefix: `/${res}/`.toLowerCase()
+    }));
+    for (const [toolId, tool] of rawTools.entries()) {
+      if (includeToolsLower.length > 0) {
+        const toolIdLower = toolId.toLowerCase();
+        const toolNameLower = tool.name.toLowerCase();
+        if (!includeToolsLower.includes(toolIdLower) && !includeToolsLower.includes(toolNameLower)) {
+          continue;
+        }
+      }
+      if (includeOperationsLower.length > 0) {
+        const { method } = this.parseToolId(toolId);
+        if (!includeOperationsLower.includes(method.toLowerCase())) {
+          continue;
+        }
+      }
+      if (resourcePathsLower.length > 0) {
+        const { path } = this.parseToolId(toolId);
+        const pathLower = path.toLowerCase();
+        const match = resourcePathsLower.some(
+          (res) => pathLower === res.exact || pathLower.startsWith(res.prefix)
+        );
+        if (!match) continue;
+      }
+      if (includeTagsLower.length > 0) {
+        const { method, path } = this.parseToolId(toolId);
+        const methodLower = method.toLowerCase();
+        const pathItem = spec.paths[path];
+        if (!pathItem) continue;
+        const opObj = pathItem[methodLower];
+        const tags = Array.isArray(opObj?.tags) ? opObj.tags : [];
+        if (!tags.some((tag) => includeTagsLower.includes(tag.toLowerCase()))) continue;
+      }
+      filtered.set(toolId, tool);
+    }
+    this.tools = filtered;
     for (const [toolId, tool] of this.tools.entries()) {
       console.error(`Registered tool: ${toolId} (${tool.name})`);
     }
@@ -14591,11 +14783,14 @@ var ToolsManager = class {
    * Find a tool by ID or name
    */
   findTool(idOrName) {
-    if (this.tools.has(idOrName)) {
-      return { toolId: idOrName, tool: this.tools.get(idOrName) };
+    const lowerIdOrName = idOrName.toLowerCase();
+    for (const [toolId, tool] of this.tools.entries()) {
+      if (toolId.toLowerCase() === lowerIdOrName) {
+        return { toolId, tool };
+      }
     }
     for (const [toolId, tool] of this.tools.entries()) {
-      if (tool.name === idOrName) {
+      if (tool.name.toLowerCase() === lowerIdOrName) {
         return { toolId, tool };
       }
     }
@@ -22976,6 +23171,26 @@ function loadConfig() {
     alias: "v",
     type: "string",
     description: "Server version"
+  }).option("tools", {
+    type: "string",
+    choices: ["all", "dynamic"],
+    description: "Which tools to load: all or dynamic meta-tools"
+  }).option("tool", {
+    type: "array",
+    string: true,
+    description: "Import only specified tool IDs or names"
+  }).option("tag", {
+    type: "array",
+    string: true,
+    description: "Import only tools with specified OpenAPI tags"
+  }).option("resource", {
+    type: "array",
+    string: true,
+    description: "Import only tools under specified resource path prefixes"
+  }).option("operation", {
+    type: "array",
+    string: true,
+    description: "Import only tools for specified HTTP methods (e.g., get, post)"
   }).help().parseSync();
   let transportType;
   if (argv.transport === "http" || process.env.TRANSPORT_TYPE === "http") {
@@ -23004,7 +23219,12 @@ function loadConfig() {
     transportType,
     httpPort,
     httpHost,
-    endpointPath
+    endpointPath,
+    includeTools: argv.tool,
+    includeTags: argv.tag,
+    includeResources: argv.resource,
+    includeOperations: argv.operation,
+    toolsMode: argv.tools || process.env.TOOLS_MODE || "all"
   };
 }
 

package/package.json

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