ReAPI's MCP OpenAPI Specification Aggregator

This server component, implementing the Model Context Protocol (MCP), is engineered to load, process, and serve a collection of OpenAPI specification documents. Its primary role is to act as an intermediary, connecting your structured API definitions with sophisticated, language-model-driven development tooling, such as Cursor and other AI-assisted code editors.

Core Capabilities

• Ingestion of multiple OpenAPI definitions from a specified local file system location.
• Exposure of all discovered API endpoints and data structures via the standardized MCP interface.
• Equipping Large Language Models (LLMs) with comprehensive, in-IDE knowledge of your proprietary APIs.
• Automated resolution and inclusion of all referenced components (full schema dereferencing).
• Systematic maintenance of an inventory, or catalog, of all integrated API services.

Supported By ReAPI

This open-source MCP service is backed by ReAPI, a cutting-edge platform dedicated to streamlining the entire lifecycle of API development, from initial design through rigorous testing.

🎨 API Content Management System (CMS)

• Intuitive, visual interface for API specification design (low-code).
• Automatic generation and publishing of current OpenAPI documentation.
• Real-time collaborative editing environment for teams.
• Integrated version control and lifecycle management for specifications.

🧪 Advanced API Testing Suite

• The most developer-centric, no-code solution for API validation.
• Simplified creation and orchestration of test scenarios.
• Robust assertion frameworks and data validation capabilities.
• Serverless execution environment in the cloud.
• Optimized for both Quality Assurance personnel and software engineers.
• Seamless integration hooks for Continuous Integration/Continuous Deployment (CI/CD) pipelines.

Explore the full potential of API development by trying ReAPI for complimentary access at reapi.com.

Configuration for Cursor Integration

To connect this OpenAPI aggregation service with the Cursor IDE, select one of the following configuration scopes:

Approach A: Local Project Configuration (Recommended)

Define the server settings within a .cursor/mcp.json file placed in your root project directory. This compartmentalization is preferred for managing distinct API contexts across separate codebases.

{ "mcpServers": { "@reapi/mcp-openapi": { "command": "npx", "args": ["-y", "@reapi/mcp-openapi@latest", "--dir", "./specs"], "env": {} } } }

Pro Tip: Utilizing a relative directory path (e.g., ./specs) ensures the configuration remains self-contained and easily transferable among team members.

Guidance: We advise targeting the @latest release channel, as active development frequently introduces performance enhancements and new functionalities.

Crucial Note: Project-level configuration is essential for respecting LLM context window limitations. Consolidating too many specification metadata objects into a single location risks exceeding the token budget, causing operational failures. Organizing specs by project helps maintain context size within acceptable bounds.

Approach B: Global Configuration

Establish or modify ~/.cursor/mcp.json in your user's home directory to make this service universally accessible across all projects:

{ "mcpServers": { "@reapi/mcp-openapi": { "command": "npx", "args": ["-y", "@reapi/mcp-openapi@latest", "--dir", "/path/to/your/specs"], "env": {} } } }

Activating the Server in Cursor Settings

Once the configuration file is saved:

1. Launch the Cursor IDE.
2. Navigate to Settings > Cursor Settings > MCP.
3. Toggle the @reapi/mcp-openapi server to the 'enabled' state.
4. Click the synchronization icon adjacent to the server entry to enforce the new settings.

Note: By default, Cursor mandates user consent before executing any MCP tool. To bypass this prompt and enable silent execution, activate Yolo mode within the Cursor configuration panel.

The service is now operational. Should you incorporate new OpenAPI documentation files into the monitored directory, you can prompt a metadata reload via the Cursor chat interface using commands such as:

"Please refresh the API catalog" "Reload the OpenAPI specifications"

OpenAPI Document Requirements

1. Place all OpenAPI 3.x compliant definitions within the designated directory:
2. Support extends to both JSON and YAML serialization formats.
3. Files must bear extensions: .json, .yaml, or .yml.

4. The internal scanner automatically detects and parses all eligible specification files.

5. Custom Specification Identification (specId):

6. By default, the filename (excluding the extension) serves as the unique ID for the specification.
7. To override this default, incorporate the vendor extension x-spec-id within the OpenAPI info object: yaml openapi: 3.0.0 info: title: My API version: 1.0.0 x-spec-id: my-custom-api-id # Override identifier

Criticality: Assigning a distinct x-spec-id is vital when dealing with multiple specifications that exhibit: - Overlapping or identical endpoint paths. - Duplicated resource schema names. - Conflicts in defined operation identifiers.

The specification ID ensures unambiguous resolution of these resources. For instance: yaml

user-service.yaml

info: x-spec-id: user-service paths: /users: get: ...

admin-service.yaml

info: x-spec-id: admin-service paths: /users: get: ...

This structure allows specific referencing, such as user-service/users versus admin-service/users.

Operational Flow

1. The server initiates a recursive scan of the configured repository path for API schema files.
2. It systematically parses and resolves all internal references within the documents.
3. It constructs and maintains a comprehensive catalog detailing all accessible endpoints and data contracts.
4. This catalog information is subsequently exposed through the MCP communication layer.
5. LLM integrations utilize this context to:
6. Enrich the knowledge base for the language model.
7. Power context-aware intelligent code suggestion.
8. Aid developers in correct API integration patterns.
9. Facilitate generation of API-aware code blocks.

Available MCP Functions (Tools)

1. refresh-api-catalog
2. Triggers an immediate reprocessing and update of the API metadata index.

3. Output: Confirmation message upon successful catalog refresh.

4. get-api-catalog

5. Retrieves the current, comprehensive catalog, encompassing metadata for all specifications, their respective operations, and schemas.

6. Output: The entirety of the indexed API catalog structure.

7. search-api-operations

8. Executes a search query across all registered API operations.
9. Inputs:
   • query (String): The textual search term.
   • specId (Optional String): Filter results to a specific API document ID.

10. Output: A list of matching operation objects.

11. search-api-schemas

12. Queries the indexed data schemas based on a specified term.
13. Inputs:
    • query (String): The textual search term.
    • specId (Optional String): Scope the search to a particular specification ID.

14. Output: A list of matching schema definitions.

15. load-api-operation-by-operationId

16. Fetches the full definition for an operation identified by its unique ID.
17. Inputs:
    • specId (String): Identifier of the source API specification.
    • operationId (String): The target operation's unique identifier.

18. Output: The complete operation definition object.

19. load-api-operation-by-path-and-method

20. Retrieves an operation using its URL path and HTTP verb.
21. Inputs:
    • specId (String): Identifier of the source API specification.
    • path (String): The resource path (e.g., "/resource/{id}").
    • method (String): The HTTP verb (e.g., "POST").

22. Output: The complete operation definition object.

23. load-api-schema-by-schemaName

24. Retrieves a specific data schema definition by its name.
25. Inputs:
    • specId (String): Identifier of the source API specification.
    • schemaName (String): The name of the required schema component.
26. Output: The complete schema definition object.

Development Trajectory (Roadmap)

1. Semantically Informed Search
2. Implementation of natural language processing for more accurate discovery of operations and schemas.

3. Refinement of search logic through deep semantic comprehension.

4. External Source Synchronization

5. Introduction of capabilities to pull and update specifications directly from remote repositories (e.g., Git, API Gateways).

6. Code Pattern Exposure

7. Providing pre-vetted code templates through the MCP protocol.

8. Offering LLMs standardized reference patterns for reliable code scaffolding.

9. Community Involvement

10. Encouraging feature proposals and defect reports.
11. Welcoming external contributions to enhance the server's functionality.

Illustrative Prompts for Cursor Interaction

These examples show how to leverage the aggregation service within the Cursor IDE context:

1. Catalog Exploration

"Enumerate all integrated APIs and detail their available endpoints" "Provide a list of all loaded specification manifests and their associated paths"

1. Endpoint Specification Retrieval

"Display the full contract for the 'create pet' API call" "Identify all mandatory input arguments required for submitting a new pet object?" "Detail the expected data structure returned upon successful execution of the pet creation endpoint"

1. Data Modeling and Mocking

"Generate representative mock payload data conforming to the Pet schema" "Construct a syntactically correct request body for the pet creation operation" "Present several valid examples of the Pet object structure based on the schema definition"

1. Code Artifact Generation

"Generate an Axios-based client library dedicated to the pet API" "Draft a TypeScript interface definition corresponding to the Pet data model" "Write a standard React hook designed to interface with the pet creation endpoint"

1. Integration Support

"Assist in implementing robust error handling routines for the pet API calls" "Produce a set of unit tests targeting the generated pet API client module" "Develop a cohesive service class that centrally manages all interactions with the pet resource"

1. Reference Documentation

"Generate a cURL command demonstrating typical usage of the pet API" "Create comprehensive JSDoc annotations for the methods within the pet API client" "Draft a dedicated README section detailing the integration procedure for the pet API"

1. Validation and Type Safety

"Generate a Zod schema validator for the Pet entity" "Create definitive TypeScript types for all anticipated response payloads from the pet endpoints" "Outline the steps to enforce strict input validation on request payloads for pet-related operations"

1. Discovery and Filtering

"Locate every endpoint associated with the management of pet entities" "Isolate all API methods that support binary file transmission" "List all operations that return results presented in a paginated format"

These examples illustrate the utility of the MCP server for accelerating API-centric development tasks. Feel empowered to customize or combine these directives for highly specific requirements.

Collaboration

We welcome contributions! Please submit any proposed enhancements or fixes via a Pull Request to the repository.