MCP OpenAPI Server

mcp-openapi
# @reapi/mcp-openapi

A Model Context Protocol (MCP) server that loads and serves multiple OpenAPI specifications to enable LLM-powered IDE integrations. This server acts as a bridge between your OpenAPI specifications and LLM-powered development tools like Cursor and other code editors.

## Features

- Loads multiple OpenAPI specifications from a directory
- Exposes API operations and schemas through MCP protocol
- Enables LLMs to understand and work with your APIs directly in your IDE
- Supports dereferenced schemas for complete API context
- Maintains a catalog of all available APIs

## Powered by [ReAPI](https://reapi.com)

This open-source MCP server is sponsored by [ReAPI](https://reapi.com), a next-generation API platform that simplifies API design and testing. While this server provides local OpenAPI integration for development, ReAPI offers two powerful modules:

### 🎨 API CMS
- Design APIs using an intuitive no-code editor
- Generate and publish OpenAPI specifications automatically
- Collaborate with team members in real-time
- Version control and change management

### 🧪 API Testing
- The most developer-friendly no-code API testing solution
- Create and manage test cases with an intuitive interface
- Powerful assertion and validation capabilities
- Serverless cloud test executor
- Perfect for both QA teams and developers
- CI/CD integration ready

Try ReAPI for free at [reapi.com](https://reapi.com) and experience the future of API development.

## Cursor Configuration

To integrate the MCP OpenAPI server with Cursor IDE, you have two options for configuration locations:

### Option 1: Project-specific Configuration (Recommended)
Create a `.cursor/mcp.json` file in your project directory. This option is recommended as it allows you to maintain different sets of specs for different projects

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

> **Tip**: Using a relative path like `./specs` makes the configuration portable and easier to share across team members.
> 
> **Note**: We recommend using `@latest` tag as we frequently update the server with new features and improvements.
>
> **Important**: Project-specific configuration helps manage LLM context limits. When all specifications are placed in a single folder, the combined metadata could exceed the LLM's context window, leading to errors. Organizing specs by project keeps the context size manageable.

### Option 2: Global Configuration
Create or edit `~/.cursor/mcp.json` in your home directory to make the server available across all projects:

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

### Enable in Cursor Settings

After adding the configuration:

1. Open Cursor IDE
2. Go to Settings > Cursor Settings > MCP
3. Enable the @reapi/mcp-openapi server
4. Click the refresh icon next to the server to apply changes

> **Note**: By default, Cursor requires confirmation for each MCP tool execution. If you want to allow automatic execution without confirmation, you can enable [Yolo mode](https://docs.cursor.com/context/model-context-protocol#yolo-mode) in Cursor settings.

The server is now ready to use. When you add new OpenAPI specifications to your directory, you can refresh the catalog by:

1. Opening Cursor's chat panel
2. Typing one of these prompts:
   ```
   "Please refresh the API catalog"
   "Reload the OpenAPI specifications"
   ```

### OpenAPI Specification Requirements

1. Place your OpenAPI 3.x specifications in the target directory:
   - Supports both JSON and YAML formats
   - Files should have `.json`, `.yaml`, or `.yml` extensions
   - Scanner will automatically discover and process all specification files

2. Specification ID Configuration:
   - By default, the filename (without extension) is used as the specification ID
   - To specify a custom ID, add `x-spec-id` in the OpenAPI info object:
   ```yaml
   openapi: 3.0.0
   info:
     title: My API
     version: 1.0.0
     x-spec-id: my-custom-api-id  # Custom specification ID
   ```
   
   > **Important**: Setting a custom `x-spec-id` is crucial when working with multiple specifications that have:
   > - Similar or identical endpoint paths
   > - Same schema names
   > - Overlapping operation IDs
   >
   > The spec ID helps distinguish between these similar resources and prevents naming conflicts. For example:
   > ```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: ...
   > ```
   > Now you can reference these endpoints specifically as `user-service/users` and `admin-service/users`

## How It Works

1. The server scans the specified directory for OpenAPI specification files
2. It processes and dereferences the specifications for complete context
3. Creates and maintains a catalog of all API operations and schemas
4. Exposes this information through the MCP protocol
5. IDE integrations can then use this information to:
   - Provide API context to LLMs
   - Enable intelligent code completion
   - Assist in API integration
   - Generate API-aware code snippets


## Tools

1. `refresh-api-catalog`
   - Refresh the API catalog
   - Returns: Success message when catalog is refreshed

2. `get-api-catalog`
   - Get the API catalog, the catalog contains metadata about all openapi specifications, their operations and schemas
   - Returns: Complete API catalog with all specifications, operations, and schemas

3. `search-api-operations`
   - Search for operations across specifications
   - Inputs:
     - `query` (string): Search query
     - `specId` (optional string): Specific API specification ID to search within
   - Returns: Matching operations from the API catalog

4. `search-api-schemas`
   - Search for schemas across specifications
   - Inputs:
     - `query` (string): Search query
     - `specId` (optional string): Specific API specification ID to search
   - Returns: Matching schemas from the API catalog

5. `load-api-operation-by-operationId`
   - Load an operation by operationId
   - Inputs:
     - `specId` (string): API specification ID
     - `operationId` (string): Operation ID to load
   - Returns: Complete operation details

6. `load-api-operation-by-path-and-method`
   - Load an operation by path and method
   - Inputs:
     - `specId` (string): API specification ID
     - `path` (string): API endpoint path
     - `method` (string): HTTP method
   - Returns: Complete operation details

7. `load-api-schema-by-schemaName`
   - Load a schema by schemaName
   - Inputs:
     - `specId` (string): API specification ID
     - `schemaName` (string): Name of the schema to load
   - Returns: Complete schema details

## Roadmap

1. **Semantic Search**
   - Enable natural language queries for API operations and schemas
   - Improve search accuracy with semantic understanding

2. **Remote Specs Sync**
   - Support syncing OpenAPI specifications from remote sources

3. **Code Templates**
   - Expose code templates through MCP protocol
   - Provide reference patterns for LLM code generation

4. **Community Contributions**
   - Submit feature requests and bug reports
   - Contribute to improve the server

## Example Prompts in Cursor

Here are some example prompts you can use in Cursor IDE to interact with your APIs:

1. **Explore Available APIs**
   ```
   "Show me all available APIs in the catalog with their operations"
   "List all API specifications and their endpoints"
   ```

2. **API Operation Details**
   ```
   "Show me the details of the create pet API endpoint"
   "What are the required parameters for creating a new pet?"
   "Explain the response schema for the pet creation endpoint"
   ```

3. **Schema and Mock Data**
   ```
   "Generate mock data for the Pet schema"
   "Create a valid request payload for the create pet endpoint"
   "Show me examples of valid pet objects based on the schema"
   ```

4. **Code Generation**
   ```
   "Generate an Axios client for the create pet API"
   "Create a TypeScript interface for the Pet schema"
   "Write a React hook that calls the create pet endpoint"
   ```

5. **API Integration Assistance**
   ```
   "Help me implement error handling for the pet API endpoints"
   "Generate unit tests for the pet API client"
   "Create a service class that encapsulates all pet-related API calls"
   ```

6. **Documentation and Usage**
   ```
   "Show me example usage of the pet API with curl"
   "Generate JSDoc comments for the pet API client methods"
   "Create a README section explaining the pet API integration"
   ```

7. **Validation and Types**
   ```
   "Generate Zod validation schema for the Pet model"
   "Create TypeScript types for all pet-related API responses"
   "Help me implement request payload validation for the pet endpoints"
   ```

8. **API Search and Discovery**
   ```
   "Find all endpoints related to pet management"
   "Show me all APIs that accept file uploads"
   "List all endpoints that return paginated responses"
   ```

These prompts demonstrate how to leverage the MCP server's capabilities for API development. Feel free to adapt them to your specific needs or combine them for more complex tasks.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. 