Reapi/mcp Openapi

1# @reapi/mcp-openapi
2 
3A 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.
4 
5## Features
6 
7- Loads multiple OpenAPI specifications from a directory
8- Exposes API operations and schemas through MCP protocol
9- Enables LLMs to understand and work with your APIs directly in your IDE
10- Supports dereferenced schemas for complete API context
11- Maintains a catalog of all available APIs
12 
13## Powered by [ReAPI](https://reapi.com)
14 
15This 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:
16 
17### 🎨 API CMS
18- Design APIs using an intuitive no-code editor
19- Generate and publish OpenAPI specifications automatically
20- Collaborate with team members in real-time
21- Version control and change management
22 
23### 🧪 API Testing
24- The most developer-friendly no-code API testing solution
25- Create and manage test cases with an intuitive interface
26- Powerful assertion and validation capabilities
27- Serverless cloud test executor
28- Perfect for both QA teams and developers
29- CI/CD integration ready
30 
31Try ReAPI for free at [reapi.com](https://reapi.com) and experience the future of API development.
32 
33## Cursor Configuration
34 
35To integrate the MCP OpenAPI server with Cursor IDE, you have two options for configuration locations:
36 
37### Option 1: Project-specific Configuration (Recommended)
38Create 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
39 
40```json
41{
42  "mcpServers": {
43    "@reapi/mcp-openapi": {
44      "command": "npx",
45      "args": ["-y", "@reapi/mcp-openapi@latest", "--dir", "./specs"],
46      "env": {}
47    }
48  }
49}
50```
51 
52> **Tip**: Using a relative path like `./specs` makes the configuration portable and easier to share across team members.
53> 
54> **Note**: We recommend using `@latest` tag as we frequently update the server with new features and improvements.
55>
56> **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.
57 
58### Option 2: Global Configuration
59Create or edit `~/.cursor/mcp.json` in your home directory to make the server available across all projects:
60 
61```json
62{
63  "mcpServers": {
64    "@reapi/mcp-openapi": {
65      "command": "npx",
66      "args": ["-y", "@reapi/mcp-openapi@latest", "--dir", "/path/to/your/specs"],
67      "env": {}
68    }
69  }
70}
71```
72 
73### Enable in Cursor Settings
74 
75After adding the configuration:
76 
771. Open Cursor IDE
782. Go to Settings > Cursor Settings > MCP
793. Enable the @reapi/mcp-openapi server
804. Click the refresh icon next to the server to apply changes
81 
82> **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.
83 
84The server is now ready to use. When you add new OpenAPI specifications to your directory, you can refresh the catalog by:
85 
861. Opening Cursor's chat panel
872. Typing one of these prompts:
88   ```
89   "Please refresh the API catalog"
90   "Reload the OpenAPI specifications"
91   ```
92 
93### OpenAPI Specification Requirements
94 
951. Place your OpenAPI 3.x specifications in the target directory:
96   - Supports both JSON and YAML formats
97   - Files should have `.json`, `.yaml`, or `.yml` extensions
98   - Scanner will automatically discover and process all specification files
99 
1002. Specification ID Configuration:
101   - By default, the filename (without extension) is used as the specification ID
102   - To specify a custom ID, add `x-spec-id` in the OpenAPI info object:
103   ```yaml
104   openapi: 3.0.0
105   info:
106     title: My API
107     version: 1.0.0
108     x-spec-id: my-custom-api-id  # Custom specification ID
109   ```
110   
111   > **Important**: Setting a custom `x-spec-id` is crucial when working with multiple specifications that have:
112   > - Similar or identical endpoint paths
113   > - Same schema names
114   > - Overlapping operation IDs
115   >
116   > The spec ID helps distinguish between these similar resources and prevents naming conflicts. For example:
117   > ```yaml
118   > # user-service.yaml
119   > info:
120   >   x-spec-id: user-service
121   > paths:
122   >   /users:
123   >     get: ...
124   > 
125   > # admin-service.yaml
126   > info:
127   >   x-spec-id: admin-service
128   > paths:
129   >   /users:
130   >     get: ...
131   > ```
132   > Now you can reference these endpoints specifically as `user-service/users` and `admin-service/users`
133 
134## How It Works
135 
1361. The server scans the specified directory for OpenAPI specification files
1372. It processes and dereferences the specifications for complete context
1383. Creates and maintains a catalog of all API operations and schemas
1394. Exposes this information through the MCP protocol
1405. IDE integrations can then use this information to:
141   - Provide API context to LLMs
142   - Enable intelligent code completion
143   - Assist in API integration
144   - Generate API-aware code snippets
145 
146 
147## Tools
148 
1491. `refresh-api-catalog`
150   - Refresh the API catalog
151   - Returns: Success message when catalog is refreshed
152 
1532. `get-api-catalog`
154   - Get the API catalog, the catalog contains metadata about all openapi specifications, their operations and schemas
155   - Returns: Complete API catalog with all specifications, operations, and schemas
156 
1573. `search-api-operations`
158   - Search for operations across specifications
159   - Inputs:
160     - `query` (string): Search query
161     - `specId` (optional string): Specific API specification ID to search within
162   - Returns: Matching operations from the API catalog
163 
1644. `search-api-schemas`
165   - Search for schemas across specifications
166   - Inputs:
167     - `query` (string): Search query
168     - `specId` (optional string): Specific API specification ID to search
169   - Returns: Matching schemas from the API catalog
170 
1715. `load-api-operation-by-operationId`
172   - Load an operation by operationId
173   - Inputs:
174     - `specId` (string): API specification ID
175     - `operationId` (string): Operation ID to load
176   - Returns: Complete operation details
177 
1786. `load-api-operation-by-path-and-method`
179   - Load an operation by path and method
180   - Inputs:
181     - `specId` (string): API specification ID
182     - `path` (string): API endpoint path
183     - `method` (string): HTTP method
184   - Returns: Complete operation details
185 
1867. `load-api-schema-by-schemaName`
187   - Load a schema by schemaName
188   - Inputs:
189     - `specId` (string): API specification ID
190     - `schemaName` (string): Name of the schema to load
191   - Returns: Complete schema details
192 
193## Roadmap
194 
1951. **Semantic Search**
196   - Enable natural language queries for API operations and schemas
197   - Improve search accuracy with semantic understanding
198 
1992. **Remote Specs Sync**
200   - Support syncing OpenAPI specifications from remote sources
201 
2023. **Code Templates**
203   - Expose code templates through MCP protocol
204   - Provide reference patterns for LLM code generation
205 
2064. **Community Contributions**
207   - Submit feature requests and bug reports
208   - Contribute to improve the server
209 
210## Example Prompts in Cursor
211 
212Here are some example prompts you can use in Cursor IDE to interact with your APIs:
213 
2141. **Explore Available APIs**
215   ```
216   "Show me all available APIs in the catalog with their operations"
217   "List all API specifications and their endpoints"
218   ```
219 
2202. **API Operation Details**
221   ```
222   "Show me the details of the create pet API endpoint"
223   "What are the required parameters for creating a new pet?"
224   "Explain the response schema for the pet creation endpoint"
225   ```
226 
2273. **Schema and Mock Data**
228   ```
229   "Generate mock data for the Pet schema"
230   "Create a valid request payload for the create pet endpoint"
231   "Show me examples of valid pet objects based on the schema"
232   ```
233 
2344. **Code Generation**
235   ```
236   "Generate an Axios client for the create pet API"
237   "Create a TypeScript interface for the Pet schema"
238   "Write a React hook that calls the create pet endpoint"
239   ```
240 
2415. **API Integration Assistance**
242   ```
243   "Help me implement error handling for the pet API endpoints"
244   "Generate unit tests for the pet API client"
245   "Create a service class that encapsulates all pet-related API calls"
246   ```
247 
2486. **Documentation and Usage**
249   ```
250   "Show me example usage of the pet API with curl"
251   "Generate JSDoc comments for the pet API client methods"
252   "Create a README section explaining the pet API integration"
253   ```
254 
2557. **Validation and Types**
256   ```
257   "Generate Zod validation schema for the Pet model"
258   "Create TypeScript types for all pet-related API responses"
259   "Help me implement request payload validation for the pet endpoints"
260   ```
261 
2628. **API Search and Discovery**
263   ```
264   "Find all endpoints related to pet management"
265   "Show me all APIs that accept file uploads"
266   "List all endpoints that return paginated responses"
267   ```
268 
269These 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.
270 
271## Contributing
272 
273Contributions are welcome! Please feel free to submit a Pull Request.