docs: updated readme
This commit is contained in:
182
README.md
182
README.md
@@ -1,147 +1,40 @@
|
|||||||
# OpenAPI MCP Server
|
# OpenAPI MCP Server
|
||||||
|
|
||||||
A Model Context Protocol (MCP) server that provides tools for querying and
|
MCP server that turns any OpenAPI/Swagger spec into queryable tools for your
|
||||||
exploring OpenAPI specifications. This server allows you to search endpoints,
|
LLM. Search endpoints, get endpoint details, and explore schemas from your API
|
||||||
get detailed endpoint information, and list all available API endpoints from
|
documentation.
|
||||||
OpenAPI/Swagger documentation.
|
|
||||||
|
|
||||||
## Features
|
## Setup for Claude Code
|
||||||
|
|
||||||
- **Search Endpoints**: Find API endpoints by keyword matching in paths,
|
Add to your `claude_desktop_config.json`:
|
||||||
summaries, descriptions, or tags
|
|
||||||
- **Get Endpoint Details**: Retrieve complete information for a specific
|
|
||||||
endpoint
|
|
||||||
- **List All Endpoints**: Get an overview of all available API endpoints
|
|
||||||
- **Flexible Input**: Supports both local files (YAML/JSON) and remote URLs
|
|
||||||
- **Auto-format Detection**: Automatically detects JSON or YAML format
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
This script uses `uv` for dependency management. The required dependencies are
|
|
||||||
defined inline:
|
|
||||||
|
|
||||||
- `mcp`: Model Context Protocol library
|
|
||||||
- `pyyaml`: YAML parsing support
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
### Basic Usage
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Using a local OpenAPI spec file
|
|
||||||
./main.py /path/to/openapi.yaml
|
|
||||||
|
|
||||||
# Using a remote OpenAPI spec URL
|
|
||||||
./main.py https://api.example.com/openapi.json
|
|
||||||
|
|
||||||
# With custom log level
|
|
||||||
./main.py /path/to/openapi.yaml --log-level DEBUG
|
|
||||||
```
|
|
||||||
|
|
||||||
### Command Line Arguments
|
|
||||||
|
|
||||||
- `docs_path` (required): Path to OpenAPI specification file (YAML or JSON) or
|
|
||||||
URL to remote spec
|
|
||||||
- `--log-level` (optional): Set logging level (DEBUG, INFO, WARNING, ERROR).
|
|
||||||
Default: INFO
|
|
||||||
|
|
||||||
### Supported File Formats
|
|
||||||
|
|
||||||
- **Local files**: `.yaml`, `.yml`, `.json`
|
|
||||||
- **Remote URLs**: Any URL ending in `.yaml`, `.yml`, `.json`, or auto-detected
|
|
||||||
format
|
|
||||||
|
|
||||||
## Available Tools
|
|
||||||
|
|
||||||
When running as an MCP server, the following tools are available:
|
|
||||||
|
|
||||||
### 1. search_endpoints
|
|
||||||
|
|
||||||
Search for API endpoints using keywords.
|
|
||||||
|
|
||||||
**Parameters:**
|
|
||||||
|
|
||||||
- `query` (string): Search term to match against paths, summaries, descriptions,
|
|
||||||
or tags
|
|
||||||
|
|
||||||
**Example Response:**
|
|
||||||
|
|
||||||
```json
|
|
||||||
[
|
|
||||||
{
|
|
||||||
"path": "/users/{id}",
|
|
||||||
"method": "GET",
|
|
||||||
"summary": "Get user by ID",
|
|
||||||
"tags": ["users"]
|
|
||||||
}
|
|
||||||
]
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. get_endpoint
|
|
||||||
|
|
||||||
Get detailed information for a specific endpoint.
|
|
||||||
|
|
||||||
**Parameters:**
|
|
||||||
|
|
||||||
- `path` (string): The API path (e.g., "/users/{id}")
|
|
||||||
- `method` (string): HTTP method (GET, POST, PUT, DELETE, PATCH)
|
|
||||||
|
|
||||||
**Example Response:**
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"path": "/users/{id}",
|
|
||||||
"method": "GET",
|
|
||||||
"details": {
|
|
||||||
"summary": "Get user by ID",
|
|
||||||
"description": "Retrieve a specific user by their unique identifier",
|
|
||||||
"parameters": [...],
|
|
||||||
"responses": {...}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. list_all_endpoints
|
|
||||||
|
|
||||||
List all available API endpoints.
|
|
||||||
|
|
||||||
**Example Response:**
|
|
||||||
|
|
||||||
```json
|
|
||||||
[
|
|
||||||
{
|
|
||||||
"path": "/users",
|
|
||||||
"method": "GET",
|
|
||||||
"summary": "List all users"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"path": "/users/{id}",
|
|
||||||
"method": "GET",
|
|
||||||
"summary": "Get user by ID"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
```
|
|
||||||
|
|
||||||
## Integration with MCP Clients
|
|
||||||
|
|
||||||
This server implements the Model Context Protocol and can be used with any
|
|
||||||
MCP-compatible client. The server communicates via stdio and provides structured
|
|
||||||
access to OpenAPI documentation.
|
|
||||||
|
|
||||||
## Claude code
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"mcpServers": {
|
"mcpServers": {
|
||||||
"myapidocs": {
|
"my-api": {
|
||||||
"command": "/path/to/main.py",
|
"command": "uvx",
|
||||||
"args": [
|
"args": [
|
||||||
"/path/to/project/openapi-spec.json"
|
"--from",
|
||||||
|
"git+https://github.com/puelpan/openapi-spec-mcp.git@main",
|
||||||
|
"openapi-spec-mcp",
|
||||||
|
"/path/to/your/openapi.yaml"
|
||||||
]
|
]
|
||||||
},
|
}
|
||||||
"otherapidocs": {
|
}
|
||||||
"command": "/path/to/main.py",
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Or use a remote URL:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"my-api": {
|
||||||
|
"command": "uvx",
|
||||||
"args": [
|
"args": [
|
||||||
|
"--from",
|
||||||
|
"git+https://github.com/puelpan/openapi-spec-mcp.git@main",
|
||||||
|
"openapi-spec-mcp",
|
||||||
"https://api.example.com/openapi.json"
|
"https://api.example.com/openapi.json"
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
@@ -149,20 +42,15 @@ access to OpenAPI documentation.
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Error Handling
|
## Available Tools
|
||||||
|
|
||||||
- Invalid file paths or URLs will be logged and handled gracefully
|
- **search_endpoints**: Find endpoints by keyword
|
||||||
- Unsupported file formats will raise clear error messages
|
- **get_endpoint**: Get detailed endpoint info (parameters, responses, etc.)
|
||||||
- Network issues with remote URLs are caught and reported
|
- **list_all_endpoints**: List all available endpoints
|
||||||
- Missing or malformed OpenAPI specs return empty results with appropriate
|
- **search_schemas**: Find schema definitions by name
|
||||||
logging
|
- **get_schema**: Get schema details with resolved references
|
||||||
|
|
||||||
## Logging
|
## Supported Formats
|
||||||
|
|
||||||
The server provides comprehensive logging at multiple levels:
|
- Local files: `.yaml`, `.yml`, `.json`
|
||||||
|
- Remote URLs: Any OpenAPI spec URL (format auto-detected)
|
||||||
- **INFO**: General operation status
|
|
||||||
- **DEBUG**: Detailed operation information
|
|
||||||
- **ERROR**: Error conditions and failures
|
|
||||||
|
|
||||||
Log output includes timestamps and structured information for debugging.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user