From 96d3dfb76a2506b874a697e22b3f7b360c3ba77a Mon Sep 17 00:00:00 2001
From: Juan Puelpan <juan@puelpan.com>
Date: Thu, 16 Oct 2025 20:39:49 -0300
Subject: [PATCH] docs: updated readme

---
 README.md | 182 +++++++++++-------------------------------------------
 1 file changed, 35 insertions(+), 147 deletions(-)

diff --git a/README.md b/README.md
index 36880f4..9e26bac 100644
--- a/README.md
+++ b/README.md
@@ -1,147 +1,40 @@
 # 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.
+MCP server that turns any OpenAPI/Swagger spec into queryable tools for your
+LLM. Search endpoints, get endpoint details, and explore schemas from your API
+documentation.
 
-## Features
+## Setup for Claude Code
 
-- **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
+Add to your `claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
-    "myapidocs": {
-      "command": "/path/to/main.py",
+    "my-api": {
+      "command": "uvx",
       "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": [
+        "--from",
+        "git+https://github.com/puelpan/openapi-spec-mcp.git@main",
+        "openapi-spec-mcp",
         "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
-- 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
+- **search_endpoints**: Find endpoints by keyword
+- **get_endpoint**: Get detailed endpoint info (parameters, responses, etc.)
+- **list_all_endpoints**: List all available endpoints
+- **search_schemas**: Find schema definitions by name
+- **get_schema**: Get schema details with resolved references
 
-## Logging
+## Supported Formats
 
-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.
+- Local files: `.yaml`, `.yml`, `.json`
+- Remote URLs: Any OpenAPI spec URL (format auto-detected)