From 45241f985324571c15318a502ccd882e197af5cd Mon Sep 17 00:00:00 2001
From: Juan Puelpan <juan@puelpan.com>
Date: Tue, 30 Sep 2025 18:18:24 -0300
Subject: [PATCH] add readme

---
 README.md | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 168 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..36880f4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,168 @@
+# OpenAPI MCP Server
+
+A Model Context Protocol (MCP) server that provides tools for querying and
+exploring OpenAPI specifications. This server allows you to search endpoints,
+get detailed endpoint information, and list all available API endpoints from
+OpenAPI/Swagger documentation.
+
+## Features
+
+- **Search Endpoints**: Find API endpoints by keyword matching in paths,
+  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
+{
+  "mcpServers": {
+    "myapidocs": {
+      "command": "/path/to/main.py",
+      "args": [
+        "/path/to/project/openapi-spec.json"
+      ]
+    },
+    "otherapidocs": {
+      "command": "/path/to/main.py",
+      "args": [
+        "https://api.example.com/openapi.json"
+      ]
+    }
+  }
+}
+```
+
+## Error Handling
+
+- Invalid file paths or URLs will be logged and handled gracefully
+- Unsupported file formats will raise clear error messages
+- Network issues with remote URLs are caught and reported
+- Missing or malformed OpenAPI specs return empty results with appropriate
+  logging
+
+## Logging
+
+The server provides comprehensive logging at multiple levels:
+
+- **INFO**: General operation status
+- **DEBUG**: Detailed operation information
+- **ERROR**: Error conditions and failures
+
+Log output includes timestamps and structured information for debugging.