swagger-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,70 @@
+# Swagger MCP Server
+
+A Model Context Protocol server for Swagger/OpenAPI endpoints. This tool allows you to expose Swagger-defined APIs through the Model Context Protocol, making them accessible to AI agents.
+
+## Installation
+
+You can install the package globally:
+
+```bash
+npm install -g swagger-mcp-server
+```
+
+Or use it directly with npx:
+
+```bash
+npx swagger-mcp-server <config-file>
+```
+
+## Usage
+
+1. Create a configuration file (JSON) that defines the Swagger endpoints you want to expose:
+
+```json
+{
+  "endpoints": [
+    {
+      "name": "example-api",
+      "url": "https://example.com/api/swagger.json"
+    }
+  ]
+}
+```
+
+2. Run the server:
+
+```bash
+swagger-mcp-server config.json
+```
+
+Or with npx:
+
+```bash
+npx swagger-mcp-server config.json
+```
+
+## Configuration Options
+
+The configuration file supports the following options:
+
+- `endpoints`: An array of Swagger endpoints to expose
+  - `name`: A unique identifier for the endpoint
+  - `url`: URL to the Swagger/OpenAPI JSON definition
+
+## Development
+
+To build the project:
+
+```bash
+npm run build
+```
+
+To run locally:
+
+```bash
+npm run run
+```
+
+## License
+
+ISC

package/build/config.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import fs from "fs";
+export const literalSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+export const jsonSchema = z.lazy(() => z.union([literalSchema, z.array(jsonSchema), z.record(jsonSchema)]));
+export const ConfigSchema = z.object({
+    endpoints: z.array(z.object({
+        name: z.string(),
+        url: z.string().url(),
+        schema: jsonSchema
+    }))
+});
+export async function loadConfig(configPath) {
+    try {
+        const configFile = fs.readFileSync(configPath, 'utf8');
+        const parsedConfig = JSON.parse(configFile);
+        const endpointsWithSchema = await Promise.all(parsedConfig.endpoints
+            .map(async ({ url, name }) => {
+            const response = await fetch(url);
+            const schema = await response.json();
+            return { url, name, schema };
+        }));
+        return ConfigSchema.parse({ endpoints: endpointsWithSchema });
+    }
+    catch (error) {
+        console.error(`Error loading config from ${configPath}:`, error);
+        process.exit(1);
+    }
+}

package/build/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { loadConfig } from './config.js';
+import { SwaggerCollection } from "./swager_collection.js";
+import { SwaggerMcpServer } from "./swagger_mcp_server.js";
+let config;
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length > 0) {
+        const configPath = args[0];
+        console.error(`Loading configuration from: ${configPath}`);
+        config = await loadConfig(configPath);
+        console.error(`Loaded ${config.endpoints.length} endpoints from config`);
+    }
+    else {
+        console.error("No config file provided. Exiting.");
+        process.exit(1);
+    }
+    const swaggerCollection = new SwaggerCollection(config.endpoints);
+    const swaggerMcpServer = new SwaggerMcpServer(swaggerCollection);
+    await swaggerMcpServer.serve();
+}
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});

package/build/swager_collection.js

@@ -0,0 +1,26 @@
+import { SwaggerParser } from "./swagger_parser.js";
+export class SwaggerCollection {
+    swaggers;
+    constructor(swaggers) {
+        this.swaggers = swaggers;
+        this.swaggers = swaggers;
+    }
+    listSwaggers() {
+        return this.swaggers.map((swagger) => this.mapSwagger(swagger));
+    }
+    getSwagger(id) {
+        let result = this.swaggers.find((swagger) => swagger.name === id);
+        if (result) {
+            return this.mapSwagger(result);
+        }
+        return null;
+    }
+    mapSwagger(swagger) {
+        return {
+            id: swagger.name,
+            url: swagger.url,
+            name: swagger.schema.info.title,
+            instance: new SwaggerParser(swagger.name, swagger.schema)
+        };
+    }
+}

package/build/swagger_mcp_server.js

@@ -0,0 +1,186 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+export class SwaggerMcpServer {
+    swaggerCollection;
+    server;
+    constructor(swaggerCollection) {
+        this.swaggerCollection = swaggerCollection;
+        this.server = new McpServer({
+            name: "swagger",
+            version: "1.0.0",
+        });
+        this.server.tool("list-swaggers", "List all connected swagger endpoints", async () => {
+            const swaggers = this.swaggerCollection.listSwaggers();
+            let result = "List of available swaggers (id | name | url):\n";
+            for (const swagger of swaggers) {
+                result += `${swagger.id} | ${swagger.name} | ${swagger.url}\n`;
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: result
+                    }
+                ]
+            };
+        });
+        this.server.tool("list-endpoints", "List all available endpoints with a short description. " +
+            "If swagger is provided, only endpoints from that swagger will be listed.", {
+            swagger: z.string().optional().describe("Swagger id returned by list-swaggers")
+        }, async ({ swagger }) => {
+            let swaggers = swagger
+                ? [swagger]
+                : this.swaggerCollection.listSwaggers().map((s) => s.id);
+            let endpoints = [];
+            for (const swaggerId of swaggers) {
+                const swagger = this.swaggerCollection.getSwagger(swaggerId);
+                if (swagger) {
+                    endpoints.push(...swagger.instance.listEndpoints());
+                }
+            }
+            let result = "List of available endpoints (endpointId | method | path | description):\n";
+            for (const endpoint of endpoints) {
+                const mergedText = endpoint.summary ? `${endpoint.summary}${endpoint.summary.endsWith('.') ? '' : '.'} ${endpoint.description}`.trim() : endpoint.description;
+                result += [
+                    `${endpoint.swaggerName}-${endpoint.operationId}`,
+                    endpoint.method.toUpperCase() + ' ' + endpoint.path,
+                    mergedText
+                ].join(' | ') + '\n';
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: result
+                    }
+                ]
+            };
+        });
+        this.server.tool("get-endpoints", "Get detailed information about specific endpoints", {
+            endpointIds: z.array(z.string())
+                .describe("List of endpoint IDs to retrieve details for. " +
+                "Endpoint ids can be found in the list-endpoints tool.")
+        }, async ({ endpointIds }) => {
+            let result = [];
+            for (const endpointId of endpointIds) {
+                const lastHyphenIndex = endpointId.lastIndexOf('-');
+                if (lastHyphenIndex === -1) {
+                    result.push(`Invalid endpoint ID format: ${endpointId}`);
+                    continue;
+                }
+                const swaggerName = endpointId.substring(0, lastHyphenIndex);
+                const operationId = endpointId.substring(lastHyphenIndex + 1);
+                if (!swaggerName || !operationId) {
+                    result.push(`Invalid endpoint ID format: ${endpointId}`);
+                    continue;
+                }
+                const swagger = this.swaggerCollection.getSwagger(swaggerName);
+                if (!swagger) {
+                    result.push(`Swagger not found: ${swaggerName} for endpoint ${endpointId}`);
+                    continue;
+                }
+                const endpoints = swagger.instance.listEndpoints();
+                const endpoint = Array.from(endpoints).find(e => e.operationId === operationId);
+                if (!endpoint) {
+                    result.push(`Endpoint not found: ${operationId} in swagger ${swaggerName}`);
+                    continue;
+                }
+                result.push(this.formatEndpointDetails(endpoint));
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: result.join("\n\n---\n\n") || "No endpoint details found."
+                    }
+                ]
+            };
+        });
+    }
+    formatEndpointDetails(endpoint) {
+        let result = "";
+        result += `## ${endpoint.operationId} ${endpoint.summary}\n`;
+        result += `### URL: ${endpoint.method.toUpperCase()} ${endpoint.path}\n`;
+        if (endpoint.description) {
+            result += `### Description\n${endpoint.description}\n`;
+        }
+        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));
+        if (pathParams.length > 0) {
+            result += `### Path Parameters\n`;
+            for (const param of pathParams) {
+                result += `- \`${param.name}\` (${param.type}${param.required ? ', required' : ''}): ${param.description}\n`;
+            }
+            result += `\n`;
+        }
+        if (queryParams.length > 0) {
+            result += `### Query Parameters\n`;
+            for (const param of queryParams) {
+                result += `- \`${param.name}\` (${param.type}${param.required ? ', required' : ''}): ${param.description}\n`;
+            }
+            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) {
+                result += `- \`${param.name}\` (${param.in}, ${param.type}${param.required ? ', required' : ''}): ${param.description}\n`;
+            }
+            result += `\n`;
+        }
+        let exampleUrl = endpoint.path;
+        for (const param of pathParams) {
+            exampleUrl = exampleUrl.replace(`{${param.name}}`, param.example || `{${param.name}}`);
+        }
+        if (queryParams.length > 0) {
+            exampleUrl += '?';
+            exampleUrl += queryParams
+                .map(p => `${p.name}=${encodeURIComponent(p.example || `{${p.name}}`)}`)
+                .join('&');
+        }
+        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";
+        }
+        for (const param of otherParams) {
+            if (param.in === 'header') {
+                result += `${param.name}: ${param.example || 'example-value'}\n`;
+            }
+        }
+        if (hasRequestBody) {
+            result += "\n";
+            result += JSON.stringify(endpoint.requestBodyExample, null, 2);
+        }
+        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 += `### 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```";
+        return result;
+    }
+    async serve() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error("Swagger MCP Server running on stdio");
+    }
+}

package/build/swagger_parser.js

@@ -0,0 +1,184 @@
+export class SwaggerParser {
+    name;
+    schema;
+    constructor(name, schema) {
+        this.name = name;
+        this.schema = schema;
+    }
+    extractParameters(operation) {
+        const parameters = [];
+        if (operation.parameters) {
+            for (const param of operation.parameters) {
+                parameters.push({
+                    name: param.name,
+                    in: param.in || 'query', // Default to query if not specified
+                    type: param.schema?.type || param.type || 'string',
+                    description: param.description || '',
+                    required: param.required || false,
+                    example: param.example || this.generateExampleForType(param.schema?.type || param.type || 'string')
+                });
+            }
+        }
+        return parameters;
+    }
+    generateExampleForType(type) {
+        switch (type) {
+            case 'string': return 'example_string';
+            case 'integer': return '123';
+            case 'number': return '123.45';
+            case 'boolean': return 'true';
+            default: return '';
+        }
+    }
+    generateSampleFromSchema(schema) {
+        if (!schema)
+            return {};
+        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]);
+            }
+            return {};
+        }
+        switch (schema.type) {
+            case 'object':
+                const result = {};
+                if (schema.properties) {
+                    for (const propName in schema.properties) {
+                        result[propName] = this.generateSampleFromSchema(schema.properties[propName]);
+                    }
+                }
+                return result;
+            case 'array':
+                if (schema.items) {
+                    return [this.generateSampleFromSchema(schema.items)];
+                }
+                return [];
+            case 'string':
+                if (schema.enum && schema.enum.length > 0) {
+                    return schema.enum[0];
+                }
+                if (schema.format === 'date-time')
+                    return new Date().toISOString();
+                if (schema.format === 'date')
+                    return new Date().toISOString().split('T')[0];
+                if (schema.format === 'email')
+                    return 'user@example.com';
+                if (schema.format === 'uuid')
+                    return '00000000-0000-0000-0000-000000000000';
+                return 'string';
+            case 'number':
+            case 'integer':
+                return 0;
+            case 'boolean':
+                return false;
+            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 {};
+        }
+    }
+    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);
+                }
+            }
+        }
+        return {};
+    }
+    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);
+                }
+            }
+        }
+        return {};
+    }
+    resolveErrorExampleResponse(operation) {
+        if (operation.responses) {
+            for (const code in operation.responses) {
+                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 {
+            error: {
+                code: 400,
+                message: "Bad Request"
+            }
+        };
+    }
+    listEndpoints() {
+        const endpoints = [];
+        const schemaObj = this.schema;
+        const paths = schemaObj?.paths || {};
+        for (const path in paths) {
+            const pathItem = paths[path];
+            for (const method in pathItem) {
+                if (['get', 'post', 'put', 'delete', 'patch', 'options', 'head'].includes(method)) {
+                    const operation = pathItem[method];
+                    endpoints.push({
+                        swaggerName: this.name,
+                        path,
+                        operationId: operation.operationId || `${method}${path.replace(/\//g, '_')}`,
+                        method,
+                        summary: operation.summary || '',
+                        description: operation.description || '',
+                        parameters: this.extractParameters(operation),
+                        requestBodyExample: this.extractRequestBodyExample(operation),
+                        successExampleResponse: this.resolveSuccessExampleResponse(operation),
+                        errorExampleResponse: this.resolveErrorExampleResponse(operation)
+                    });
+                }
+            }
+        }
+        return endpoints;
+    }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "swagger-mcp-server",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "swagger-mcp-server": "build/index.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js",
+    "run": "npx @modelcontextprotocol/inspector node build/index.js test_config.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "swagger",
+    "openapi",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "api"
+  ],
+  "author": "Marcin Sucharski",
+  "license": "ISC",
+  "description": "Model Context Protocol server for swagger endpoints",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yourusername/swagger-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourusername/swagger-mcp-server/issues"
+  },
+  "homepage": "https://github.com/yourusername/swagger-mcp-server#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.7.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "typescript": "^5.8.2"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": [
+    "build/**/*"
+  ]
+}