swagger-mcp-server 1.0.0 → 1.0.2

package/build/swagger_mcp_server.js

@@ -98,6 +98,26 @@ export class SwaggerMcpServer {
             };
         });
     }
+    formatBodyExample(body) {
+        if (!body.hasBody) {
+            return "";
+        }
+        if (body.isJson) {
+            return JSON.stringify(body.value ?? {}, null, 2);
+        }
+        return String(body.value ?? '<non-JSON response body>');
+    }
+    appendResponseExample(result, response) {
+        result += "```http\n";
+        result += `HTTP/2 ${response.statusCode}${response.statusText ? ` ${response.statusText}` : ''}\n`;
+        if (response.hasBody) {
+            result += `Content-Type: ${response.contentType || (response.isJson ? 'application/json' : 'application/octet-stream')}\n\n`;
+            result += this.formatBodyExample(response);
+            result += "\n";
+        }
+        result += "```";
+        return result;
+    }
     formatEndpointDetails(endpoint) {
         let result = "";
         result += `## ${endpoint.operationId} ${endpoint.summary}\n`;
@@ -107,8 +127,7 @@ export class SwaggerMcpServer {
         }
         const pathParams = endpoint.parameters.filter(p => p.in === 'path');
         const queryParams = endpoint.parameters.filter(p => p.in === 'query');
-        const bodyParams = endpoint.parameters.filter(p => p.in === 'body');
-        const otherParams = endpoint.parameters.filter(p => !['path', 'query', 'body'].includes(p.in));
+        const otherParams = endpoint.parameters.filter(p => !['path', 'query'].includes(p.in));
         if (pathParams.length > 0) {
             result += `### Path Parameters\n`;
             for (const param of pathParams) {
@@ -123,13 +142,6 @@ export class SwaggerMcpServer {
             }
             result += `\n`;
         }
-        if (bodyParams.length > 0) {
-            result += `### Body Parameters\n`;
-            for (const param of bodyParams) {
-                result += `- \`${param.name}\` (${param.type}${param.required ? ', required' : ''}): ${param.description}\n`;
-            }
-            result += `\n`;
-        }
         if (otherParams.length > 0) {
             result += `### Other Parameters\n`;
             for (const param of otherParams) {
@@ -150,32 +162,24 @@ export class SwaggerMcpServer {
         result += `### Example Request\n`;
         result += "```http\n";
         result += `${endpoint.method.toUpperCase()} ${exampleUrl}\n`;
-        const hasRequestBody = bodyParams.length > 0;
-        if (hasRequestBody) {
-            result += "Content-Type: application/json\n";
+        if (endpoint.requestBodyExample.hasBody) {
+            result += `Content-Type: ${endpoint.requestBodyExample.contentType || 'application/json'}\n`;
         }
         for (const param of otherParams) {
             if (param.in === 'header') {
                 result += `${param.name}: ${param.example || 'example-value'}\n`;
             }
         }
-        if (hasRequestBody) {
+        if (endpoint.requestBodyExample.hasBody) {
             result += "\n";
-            result += JSON.stringify(endpoint.requestBodyExample, null, 2);
+            result += this.formatBodyExample(endpoint.requestBodyExample);
         }
         result += "\n```\n\n";
         result += `### Example Response\n`;
-        result += "```http\n";
-        result += "HTTP/2 200 OK\n";
-        result += "Content-Type: application/json\n\n";
-        result += JSON.stringify(endpoint.successExampleResponse, null, 2);
-        result += "\n```\n\n";
+        result = this.appendResponseExample(result, endpoint.successExampleResponse);
+        result += "\n\n";
         result += `### Error Response Example\n`;
-        result += "```http\n";
-        result += "HTTP/2 400 Bad Request\n";
-        result += "Content-Type: application/json\n\n";
-        result += JSON.stringify(endpoint.errorExampleResponse, null, 2);
-        result += "\n```";
+        result = this.appendResponseExample(result, endpoint.errorExampleResponse);
         return result;
     }
     async serve() {

package/build/swagger_parser.js

@@ -1,3 +1,4 @@
+import { STATUS_CODES } from "node:http";
 export class SwaggerParser {
     name;
     schema;
@@ -30,29 +31,185 @@ export class SwaggerParser {
             default: return '';
         }
     }
-    generateSampleFromSchema(schema) {
+    resolveRef(ref) {
+        if (!ref.startsWith('#/')) {
+            return undefined;
+        }
+        const path = ref
+            .slice(2)
+            .split('/')
+            .map((part) => decodeURIComponent(part.replace(/~1/g, '/').replace(/~0/g, '~')));
+        let current = this.schema;
+        for (const part of path) {
+            if (current === undefined || current === null) {
+                return undefined;
+            }
+            current = current[part];
+        }
+        return current;
+    }
+    normalizeMediaType(mediaType) {
+        return mediaType.split(';', 1)[0].trim().toLowerCase();
+    }
+    isJsonMediaType(mediaType) {
+        const normalized = this.normalizeMediaType(mediaType);
+        return normalized === 'application/json'
+            || normalized === 'application/*+json'
+            || normalized.endsWith('+json');
+    }
+    resolveSchemaType(schema) {
+        if (Array.isArray(schema?.type)) {
+            return schema.type.find((type) => type !== 'null');
+        }
+        if (schema?.type) {
+            return schema.type;
+        }
+        if (schema?.properties || schema?.additionalProperties) {
+            return 'object';
+        }
+        return undefined;
+    }
+    schemaRepresentsBinary(schema, seenRefs = new Set()) {
+        if (!schema || typeof schema !== 'object') {
+            return false;
+        }
+        if (schema.$ref) {
+            if (seenRefs.has(schema.$ref)) {
+                return false;
+            }
+            const resolved = this.resolveRef(schema.$ref);
+            if (!resolved) {
+                return false;
+            }
+            seenRefs.add(schema.$ref);
+            const result = this.schemaRepresentsBinary(resolved, seenRefs);
+            seenRefs.delete(schema.$ref);
+            return result;
+        }
+        const schemaType = this.resolveSchemaType(schema);
+        if (schemaType === 'string' && ['binary', 'byte'].includes(schema.format)) {
+            return true;
+        }
+        return ['oneOf', 'anyOf', 'allOf'].some((key) => Array.isArray(schema[key]) && schema[key].some((subSchema) => this.schemaRepresentsBinary(subSchema, seenRefs)));
+    }
+    wildcardContentLooksJson(media) {
+        if (!media) {
+            return false;
+        }
+        if (media.schema) {
+            return !this.schemaRepresentsBinary(media.schema);
+        }
+        return media.example !== undefined || this.extractFirstExample(media.examples) !== undefined;
+    }
+    selectJsonContent(content) {
+        if (!content || typeof content !== 'object') {
+            return undefined;
+        }
+        const entries = Object.entries(content);
+        const applicationJson = entries.find(([mediaType]) => this.normalizeMediaType(mediaType) === 'application/json');
+        if (applicationJson) {
+            return { mediaType: applicationJson[0], media: applicationJson[1] };
+        }
+        const jsonLike = entries.find(([mediaType]) => this.isJsonMediaType(mediaType));
+        if (jsonLike) {
+            return { mediaType: jsonLike[0], media: jsonLike[1] };
+        }
+        const wildcard = entries.find(([mediaType, media]) => this.normalizeMediaType(mediaType) === '*/*' && this.wildcardContentLooksJson(media));
+        if (wildcard) {
+            return { mediaType: 'application/json', media: wildcard[1] };
+        }
+        return undefined;
+    }
+    selectFirstContent(content) {
+        if (!content || typeof content !== 'object') {
+            return undefined;
+        }
+        const [first] = Object.entries(content);
+        if (!first) {
+            return undefined;
+        }
+        return { mediaType: first[0], media: first[1] };
+    }
+    extractFirstExample(examples) {
+        if (!examples || typeof examples !== 'object') {
+            return undefined;
+        }
+        for (const example of Object.values(examples)) {
+            if (example && typeof example === 'object' && 'value' in example) {
+                return example.value;
+            }
+            if (example !== undefined && (typeof example !== 'object' || example === null)) {
+                return example;
+            }
+        }
+        return undefined;
+    }
+    extractMediaValue(media) {
+        if (media?.example !== undefined) {
+            return media.example;
+        }
+        const example = this.extractFirstExample(media?.examples);
+        if (example !== undefined) {
+            return example;
+        }
+        if (media?.schema?.example !== undefined) {
+            return media.schema.example;
+        }
+        if (media?.schema) {
+            return this.generateSampleFromSchema(media.schema);
+        }
+        return {};
+    }
+    generateSampleFromSchema(schema, seenRefs = new Set()) {
         if (!schema)
             return {};
+        if (schema.example !== undefined) {
+            return schema.example;
+        }
         if (schema.$ref) {
-            const refPath = schema.$ref.replace('#/components/schemas/', '');
-            const schemaObj = this.schema;
-            if (schemaObj?.components?.schemas?.[refPath]) {
-                return this.generateSampleFromSchema(schemaObj.components.schemas[refPath]);
+            if (seenRefs.has(schema.$ref)) {
+                return {};
+            }
+            const resolvedSchema = this.resolveRef(schema.$ref);
+            if (resolvedSchema) {
+                seenRefs.add(schema.$ref);
+                const result = this.generateSampleFromSchema(resolvedSchema, seenRefs);
+                seenRefs.delete(schema.$ref);
+                return result;
             }
             return {};
         }
-        switch (schema.type) {
+        if (schema.allOf && schema.allOf.length > 0) {
+            let result = {};
+            for (const subSchema of schema.allOf) {
+                result = { ...result, ...this.generateSampleFromSchema(subSchema, seenRefs) };
+            }
+            if (schema.properties) {
+                result = { ...result, ...this.generateSampleFromSchema({ type: 'object', properties: schema.properties }, seenRefs) };
+            }
+            return result;
+        }
+        if (schema.oneOf && schema.oneOf.length > 0) {
+            return this.generateSampleFromSchema(schema.oneOf[0], seenRefs);
+        }
+        if (schema.anyOf && schema.anyOf.length > 0) {
+            return this.generateSampleFromSchema(schema.anyOf[0], seenRefs);
+        }
+        switch (this.resolveSchemaType(schema)) {
             case 'object':
                 const result = {};
                 if (schema.properties) {
                     for (const propName in schema.properties) {
-                        result[propName] = this.generateSampleFromSchema(schema.properties[propName]);
+                        result[propName] = this.generateSampleFromSchema(schema.properties[propName], seenRefs);
                     }
                 }
+                if (Object.keys(result).length === 0 && schema.additionalProperties && typeof schema.additionalProperties === 'object') {
+                    result.additionalProperty = this.generateSampleFromSchema(schema.additionalProperties, seenRefs);
+                }
                 return result;
             case 'array':
                 if (schema.items) {
-                    return [this.generateSampleFromSchema(schema.items)];
+                    return [this.generateSampleFromSchema(schema.items, seenRefs)];
                 }
                 return [];
             case 'string':
@@ -76,56 +233,83 @@ export class SwaggerParser {
             case 'null':
                 return null;
             default:
-                if (schema.oneOf && schema.oneOf.length > 0) {
-                    return this.generateSampleFromSchema(schema.oneOf[0]);
-                }
-                if (schema.anyOf && schema.anyOf.length > 0) {
-                    return this.generateSampleFromSchema(schema.anyOf[0]);
-                }
-                if (schema.allOf && schema.allOf.length > 0) {
-                    let result = {};
-                    for (const subSchema of schema.allOf) {
-                        result = { ...result, ...this.generateSampleFromSchema(subSchema) };
-                    }
-                    return result;
-                }
                 return {};
         }
     }
+    noBodyExample() {
+        return {
+            hasBody: false,
+            isJson: false
+        };
+    }
+    jsonBodyExample(contentType, media) {
+        const normalizedContentType = this.normalizeMediaType(contentType);
+        const displayContentType = normalizedContentType === 'application/*+json' ? 'application/json' : contentType;
+        return {
+            contentType: displayContentType,
+            hasBody: true,
+            isJson: true,
+            value: this.extractMediaValue(media)
+        };
+    }
+    nonJsonBodyExample(contentType, media) {
+        const normalizedContentType = this.normalizeMediaType(contentType);
+        const displayContentType = normalizedContentType === '*/*' ? 'application/octet-stream' : contentType;
+        const isBinary = normalizedContentType.startsWith('image/')
+            || normalizedContentType === 'application/octet-stream'
+            || this.schemaRepresentsBinary(media?.schema);
+        return {
+            contentType: displayContentType,
+            hasBody: true,
+            isJson: false,
+            value: isBinary ? '<binary response body>' : '<non-JSON response body>'
+        };
+    }
+    extractJsonBodyExampleFromContent(content) {
+        const selectedContent = this.selectJsonContent(content);
+        if (!selectedContent) {
+            return this.noBodyExample();
+        }
+        return this.jsonBodyExample(selectedContent.mediaType, selectedContent.media);
+    }
+    extractResponseBodyExample(content) {
+        const selectedJsonContent = this.selectJsonContent(content);
+        if (selectedJsonContent) {
+            return this.jsonBodyExample(selectedJsonContent.mediaType, selectedJsonContent.media);
+        }
+        const selectedContent = this.selectFirstContent(content);
+        if (selectedContent) {
+            return this.nonJsonBodyExample(selectedContent.mediaType, selectedContent.media);
+        }
+        return this.noBodyExample();
+    }
     extractRequestBodyExample(operation) {
-        if (operation.requestBody && operation.requestBody.content) {
-            const content = operation.requestBody.content['application/json'];
-            if (content) {
-                if (content.example) {
-                    return content.example;
-                }
-                if (content.schema && content.schema.example) {
-                    return content.schema.example;
-                }
-                if (content.schema) {
-                    return this.generateSampleFromSchema(content.schema);
-                }
-            }
+        if (operation.requestBody?.content) {
+            return this.extractJsonBodyExampleFromContent(operation.requestBody.content);
         }
-        return {};
+        return this.noBodyExample();
+    }
+    statusText(statusCode) {
+        return STATUS_CODES[statusCode] || '';
+    }
+    responseExample(statusCode, body) {
+        return {
+            ...body,
+            statusCode,
+            statusText: this.statusText(statusCode)
+        };
     }
     resolveSuccessExampleResponse(operation) {
-        if (operation.responses && operation.responses['200']) {
-            const successResponse = operation.responses['200'];
-            if (successResponse.content && successResponse.content['application/json']) {
-                const content = successResponse.content['application/json'];
-                if (content.example) {
-                    return content.example;
-                }
-                if (content.schema && content.schema.example) {
-                    return content.schema.example;
-                }
-                if (content.schema) {
-                    return this.generateSampleFromSchema(content.schema);
+        if (operation.responses) {
+            for (const code in operation.responses) {
+                const codeNum = parseInt(code, 10);
+                if (!isNaN(codeNum) && Math.floor(codeNum / 100) === 2) {
+                    const successResponse = operation.responses[code];
+                    return this.responseExample(codeNum, this.extractResponseBodyExample(successResponse.content));
                 }
             }
         }
-        return {};
+        return this.responseExample(200, this.noBodyExample());
     }
     resolveErrorExampleResponse(operation) {
         if (operation.responses) {
@@ -133,27 +317,21 @@ export class SwaggerParser {
                 const codeNum = parseInt(code, 10);
                 if (!isNaN(codeNum) && Math.floor(codeNum / 100) >= 4) {
                     const errorResponse = operation.responses[code];
-                    if (errorResponse.content && errorResponse.content['application/json']) {
-                        const content = errorResponse.content['application/json'];
-                        if (content.example) {
-                            return content.example;
-                        }
-                        if (content.schema && content.schema.example) {
-                            return content.schema.example;
-                        }
-                        if (content.schema) {
-                            return this.generateSampleFromSchema(content.schema);
-                        }
-                    }
+                    return this.responseExample(codeNum, this.extractResponseBodyExample(errorResponse.content));
                 }
             }
         }
-        return {
-            error: {
-                code: 400,
-                message: "Bad Request"
+        return this.responseExample(400, {
+            contentType: 'application/json',
+            hasBody: true,
+            isJson: true,
+            value: {
+                error: {
+                    code: 400,
+                    message: "Bad Request"
+                }
             }
-        };
+        });
     }
     listEndpoints() {
         const endpoints = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swagger-mcp-server",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "main": "build/index.js",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "scripts": {
     "build": "tsc && chmod 755 build/index.js",
+    "test": "npm run build && node test/swagger_parser.test.mjs",
     "run": "npx @modelcontextprotocol/inspector node build/index.js test_config.json",
     "prepublishOnly": "npm run build"
   },
@@ -24,12 +25,12 @@
   "description": "Model Context Protocol server for swagger endpoints",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/yourusername/swagger-mcp-server.git"
+    "url": "git+https://github.com/marcin-sucharski/swagger-mcp-server.git"
   },
   "bugs": {
-    "url": "https://github.com/yourusername/swagger-mcp-server/issues"
+    "url": "https://github.com/marcin-sucharski/swagger-mcp-server/issues"
   },
-  "homepage": "https://github.com/yourusername/swagger-mcp-server#readme",
+  "homepage": "https://github.com/marcin-sucharski/swagger-mcp-server#readme",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.7.0",
     "zod": "^3.24.2"