mcp-swagger by genideas-labs - MCP Server

MCP Swagger Server

Version: 1.2 Last Updated: 2025-08-03

1. Overview

This project is a dual-mode server designed to analyze API specifications and provide intelligent search capabilities. It can run as a standard MCP (Meta-programming Co-pilot) Server or as a standalone HTTP server.

The server takes the URL of an online API documentation page (Swagger/OpenAPI), analyzes the specification, and provides functionality to find the most relevant API endpoints based on natural language queries.

When run in MCP mode, it aims to seamlessly integrate with various development tools (like AI code assistants) to automate and intelligentize the API integration process.

2. Core Features

F1: Load OpenAPI Specification: Extracts and saves the specification (spec.json) by analyzing a Swagger/OpenAPI documentation URL.
F2: Intelligent Endpoint Search:
- Comprehensive Search: Uses a natural language query to search not only the endpoint's path, summary, and operationId, but also the names and properties of all associated data schemas.
- LLM-based Semantic Analysis: Forwards the pre-filtered results to the Gemini API to find the most semantically similar endpoints.
- Intelligent Response: Dynamically returns either a single, most accurate result for specific queries or a list of up to 5 relevant results for ambiguous queries.
F3: Dual-Mode Operation:
- MCP Server Mode: Runs in compliance with the standard MCP specification, providing load_spec and search_endpoints tools.
- HTTP Server Mode: Runs as a standalone REST API web server.

3. Getting Started

Prerequisites

Node.js (v18 or higher recommended)
npm

Installation

Clone the repository:

git clone https://github.com/genideas-labs/mcp-swagger.git
cd mcp-swagger

Install dependencies:
```
npm install
```

Configuration

Create a .env file in the project root and add your Gemini API key:

GEMINI_API_KEY="YOUR_API_KEY_HERE"

4. Usage

Running the Server

Run the HTTP development server (with nodemon):
```
npm run dev
```
The server will run at http://localhost:3000 and automatically restart on file changes.
Run the HTTP production server:
```
npm run start:http
```
Run the MCP server:
```
npm start
# or
npm run start:mcp
```

API / Tool Reference (HTTP Mode Examples)

Load API Specification: Loads the spec from the given URL and saves it locally.

curl -X POST -H "Content-Type: application/json" \
  -d '{"docsUrl": "https://food-manager.fly.dev/docs"}' \
  http://localhost:3000/api/v1/spec/load-from-url

Expected Response:

{"message":"Specification loaded and saved successfully."}

Intelligent Search (Ambiguous Query): Searches for endpoints related to "food". Returns an array of relevant endpoints.

curl -G "http://localhost:3000/api/v1/endpoints/search" --data-urlencode "q=food"

Example Response:

[
    {
        "endpoint": {
            "summary": "Public Calculate Calories",
            "operationId": "public_calculate_calories_public_calories_post",
            ...
        },
        "schemas": { ... }
    },
    {
        "endpoint": {
            "summary": "Create Meal",
            "operationId": "create_meal_meals__post",
            ...
        },
        "schemas": { ... }
    }
]

Intelligent Search (Specific Query): Searches for an endpoint to "Update Current User". Returns a single object.

curl -G "http://localhost:3000/api/v1/endpoints/search" --data-urlencode "q=Update Current User"

Example Response:

{
    "endpoint": {
        "summary": "Update Current User",
        "operationId": "update_current_user_auth_me_put",
        ...
    },
    "schemas": { ... }
}

5. Contributing

Contributions are welcome! Please feel free to open an issue to report a bug or suggest an enhancement. If you'd like to contribute code, please follow the standard GitHub workflow (Fork -> Create Branch -> Commit -> Pull Request).

6. Sponsor

If you like this project, please consider sponsoring to help support its continued development and maintenance.

GitHub Sponsors (Not Active Yet)