# Openapi Directory Mcp

> An MCP Server for APIs.guru remarkable Wikipedia for Web APIs. Providing tools, prompts and resources to help eliminate LLM Coding Agent hallucinations.

- **Type:** MCP server
- **Install:** `agentstack add mcp-rawveg-openapi-directory-mcp`
- **Verified:** Pending review
- **Seller:** [rawveg](https://agentstack.voostack.com/s/rawveg)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [rawveg](https://github.com/rawveg)
- **Source:** https://github.com/rawveg/openapi-directory-mcp
- **Website:** https://www.openapidirectory.com

## Install

```sh
agentstack add mcp-rawveg-openapi-directory-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

OpenAPI Directory MCP Server

  
  
  
  

---

A Model Context Protocol (MCP) server that provides access to the APIs.guru directory - the world's largest repository of OpenAPI specifications with over 3,000 API Specs from 600+ providers. **Now with custom OpenAPI spec import** - seamlessly integrate your own APIs alongside the public directory.

## Table of Contents

- [Acknowledgments](#acknowledgments)
- [Features](#features)
- [Context Optimization & Progressive Discovery](#-context-optimization--progressive-discovery)
- [Quick Start](#-quick-start)
- [Custom OpenAPI Specifications](#-custom-openapi-specifications)
- [Available Tools](#%EF%B8%8F-available-tools)
- [Available Resources](#-available-resources)
- [Available Prompts](#-available-prompts-context-optimized)
- [Configuration](#configuration)
- [Example Usage](#-example-usage)
- [Architecture](#%EF%B8%8F-architecture)
- [Performance](#-performance)
- [Development](#development)
- [Contributing](#-contributing)
- [License](#-license)
- [Support This Project](#%EF%B8%8F-support-this-project)
- [Support](#support)
- [Credits](#-credits)

---

## Acknowledgments

This project builds upon the exceptional work of [APIs.guru](https://apis.guru) and their comprehensive [OpenAPI Directory](https://github.com/APIs-guru/openapi-directory). The APIs.guru project maintains the largest repository of machine-readable API definitions, providing an invaluable resource to the developer community through their free API service at https://api.apis.guru/v2.

Their dedication to creating and maintaining this comprehensive directory of OpenAPI specifications makes projects like this possible. We are deeply grateful for their contribution to the open source ecosystem and their commitment to making API discovery accessible to everyone.

The source data is provided under the Creative Commons Zero v1.0 Universal License, reflecting their generous approach to knowledge sharing.

---

## Features

| Feature                       | Description                                                  |
|-------------------------------|--------------------------------------------------------------|
| **Zero Configuration**        | Works out of the box with sensible defaults                  |
| **Comprehensive API Coverage**| Access to 3,000+ API specs from APIs.guru                    |
| **Custom OpenAPI Import**     | Import and manage your own APIs with zero-touch integration  |
| **Context-Aware Security**    | Smart security scanning with legitimate pattern recognition  |
| **Context Optimized**         | Progressive discovery reduces context usage by ~95%          |
| **Smart Search Results**      | Relevance ranking + newest versions first + provider priority |
| **Intelligent Caching**       | 24-hour TTL persistent caching with management tools         |
| **Rich Tool Set**             | 22 specialized tools for API discovery and endpoint analysis |
| **Slash Commands**            | All prompts auto-exposed as Claude Code slash commands       |
| **Paginated Resources**       | Efficient data access with pagination support                |
| **NPX Ready**                 | Install and run with a single command                        |
| **Type Safe**                 | Built with TypeScript for reliability                        |

---

## 🎯 Context Optimization & Progressive Discovery

This MCP server implements a **progressive discovery approach** that dramatically reduces context usage, allowing you to explore many more APIs before hitting context limits.

### The Problem
Traditional API discovery tools return massive amounts of data that quickly saturate LLM context windows. For example, searching for "social media APIs" and fetching their full specifications could exhaust your context before providing useful answers.

### Our Solution: 95% Context Reduction
We've redesigned the discovery workflow into three efficient phases:

**🔍 Phase 1: Initial Discovery**
- `search_apis` returns minimal, paginated results (20 per page)
- `openapi://apis/summary` provides directory overview
- Quick browsing of 1,000+ APIs without context overload

**📋 Phase 2: Basic Evaluation**  
- `get_api_summary` provides essential details without endpoints
- Authentication, documentation, categories, and provider info
- Compare multiple APIs efficiently

**⚙️ Phase 3: Detailed Analysis**
- `get_endpoints` shows paginated endpoint lists (30 per page)
- `get_endpoint_details` for specific endpoint information
- `get_endpoint_schema` and `get_endpoint_examples` for implementation

### Smart Prompts Guide You
All 22 built-in prompts automatically use this progressive approach:
- `api_discovery` guides you through efficient API exploration
- `api_integration_guide` uses progressive endpoint discovery
- Each prompt prevents context saturation while maximizing useful information

---

## 🚀 Quick Start

### Local Development Setup

1. **Clone and build**:
```bash
git clone https://github.com/rawveg/openapi-directory-mcp.git
cd openapi-directory-mcp
npm install
npm run build
```

2. **Test locally**:
```bash
node dist/index.js
```

### Configuration for Local Development

#### Claude Desktop (Local)
```json
{
  "mcpServers": {
    "openapi-directory": {
      "command": "node",
      "args": ["/path/to/openapi-directory-mcp/dist/index.js"],
      "cwd": "/path/to/openapi-directory-mcp"
    }
  }
}
```

#### Claude Code (Local)
```bash
claude mcp add openapi-directory -- node /absolute/path/to/openapi-directory-mcp/dist/index.js
```

#### Cursor (Local)
```json
{
  "mcpServers": {
    "openapi-directory": {
      "command": "node",
      "args": ["/path/to/openapi-directory-mcp/dist/index.js"],
      "cwd": "/path/to/openapi-directory-mcp"
    }
  }
}
```

#### Windsurf (Local)
```json
{
  "servers": {
    "openapi-directory": {
      "command": "node /path/to/openapi-directory-mcp/dist/index.js"
    }
  }
}
```

### NPX Installation

```bash
npx -y openapi-directory-mcp
```

#### Claude Desktop (NPX)
```json
{
  "mcpServers": {
    "openapi-directory": {
      "command": "npx",
      "args": ["-y", "openapi-directory-mcp"]
    }
  }
}
```

#### Claude Code (NPX)
```bash
claude mcp add openapi-directory -- npx -y openapi-directory-mcp
```

**Claude Code MCP Management**:
```bash
# List all configured MCP servers
claude mcp list

# Get details about the server
claude mcp get openapi-directory

# Remove the server
claude mcp remove openapi-directory

# Check server status in chat
/mcp
```

**🎯 Claude Code Slash Commands**: All 22 MCP prompts are automatically available as slash commands!

**Core Discovery & Analysis:**
- `/openapi-directory:api_discovery` - Discover APIs for specific use cases
- `/openapi-directory:api_integration_guide` - Generate integration guides
- `/openapi-directory:api_comparison` - Compare multiple APIs
- `/openapi-directory:authentication_guide` - Understand API authentication
- `/openapi-directory:code_generation` - Generate code examples
- `/openapi-directory:api_documentation_analysis` - Analyze API capabilities
- `/openapi-directory:troubleshooting_guide` - Debug integration issues

**Action-Oriented Code Generation:**
- `/openapi-directory:retrofit_api_client` - Retrofit existing codebase with typed API client
- `/openapi-directory:api_type_generator` - Generate TypeScript/language types from specs
- `/openapi-directory:api_test_suite` - Create comprehensive test suites
- `/openapi-directory:api_error_handler` - Build robust error handling with retry logic
- `/openapi-directory:api_migration_assistant` - Migrate between API versions/providers
- `/openapi-directory:api_sdk_wrapper` - Generate custom SDK wrappers
- `/openapi-directory:api_webhook_scaffold` - Scaffold webhook handlers
- `/openapi-directory:api_rate_limiter` - Implement intelligent rate limiting
- `/openapi-directory:api_graphql_wrapper` - Create GraphQL wrappers for REST APIs
- `/openapi-directory:api_batch_processor` - Build batch processing systems

**Authentication-Focused:**
- `/openapi-directory:api_auth_implementation` - Complete auth implementation
- `/openapi-directory:api_auth_flow_generator` - Generate OAuth2/OIDC flows
- `/openapi-directory:api_auth_middleware` - Build auth middleware for frameworks
- `/openapi-directory:api_auth_test_harness` - Create auth testing tools
- `/openapi-directory:api_auth_debugger` - Debug authentication issues

#### Cursor (NPX)
```json
{
  "mcpServers": {
    "openapi-directory": {
      "command": "npx",
      "args": ["-y", "openapi-directory-mcp"]
    }
  }
}
```

#### Windsurf (NPX)
```json
{
  "servers": {
    "openapi-directory": {
      "command": "npx -y openapi-directory-mcp"
    }
  }
}
```

---

## 📁 Custom OpenAPI Specifications

Import and manage your own OpenAPI specifications alongside the public API directory. Custom specs are treated as **first-class citizens** with complete integration across all tools and prompts.

### ✨ Key Features

- **🎯 Frictionless Import**: Single command import from files or URLs
- **🔒 Context-Aware Security Scanning**: Intelligent detection of security issues with legitimate pattern recognition
- **⚡ Zero-Touch Integration**: Works seamlessly with all 22 existing tools and prompts  
- **🏆 Custom Always Wins**: Custom specs take precedence over any conflicts
- **📊 Interactive Management**: Full CLI for listing, removing, and maintaining specs
- **🔄 YAML/JSON Support**: Automatic conversion and validation
- **📂 Hierarchical Storage**: Organized in `custom/name/version` structure

### 🚀 Quick Start

#### Import a Custom Spec

```bash
# Interactive guided import (recommended for first time)
openapi-directory-mcp --import

# Direct import from local file
openapi-directory-mcp --import ./my-api.yaml --name my-api --version v1

# Import from URL with strict security scanning
openapi-directory-mcp --import https://api.example.com/openapi.json --name example-api --version v2 --strict-security

# Import with custom security options
openapi-directory-mcp --import ./internal-api.yaml --name internal-api --version v1 --skip-security
```

#### Manage Custom Specs

```bash
# List all imported custom specs
openapi-directory-mcp --list-custom

# Remove a custom spec
openapi-directory-mcp --remove-custom my-api:v1

# Re-run security scan on existing spec
openapi-directory-mcp --rescan-security my-api:v1

# Validate integrity of all custom specs
openapi-directory-mcp --validate-integrity

# Repair any integrity issues
openapi-directory-mcp --repair-integrity
```

### 🛡️ Security Scanning

Built-in context-aware security scanner that understands the difference between legitimate code patterns and actual security risks:

#### Security Rules

| Rule | Severity | Description |
|------|----------|-------------|
| **Code Injection** | Critical | Detects `eval()`, `exec()`, script injection patterns |
| **Path Traversal** | High | Identifies `../`, directory traversal attempts |
| **SQL Injection** | High | Finds SQL injection patterns and keywords |
| **XSS Patterns** | High | Detects cross-site scripting vulnerabilities |
| **Hardcoded Secrets** | Medium | Identifies API keys, tokens, passwords |
| **Unsafe URLs** | Medium | Flags suspicious domains and protocols |
| **Command Execution** | Critical | Detects system command execution patterns |

#### Context-Aware Intelligence

The scanner understands **legitimate patterns in examples**:

```yaml
# ✅ This is SAFE - Scanner recognizes it's in an example
paths:
  /logs/analyze:
    post:
      examples:
        datadog_query:
          value: 
            query: "eval(sum:system.cpu.usage{*})"  # Datadog query syntax
```

#### Security Modes

- **Normal** (default): Scans and reports issues, allows import
- **Strict**: Blocks import if any high/critical issues found
- **Skip**: Bypasses security scanning entirely

### 📂 Storage Architecture

Custom specs are stored in a hierarchical structure matching the API directory format:

```
~/.cache/openapi-directory-mcp/custom-specs/
├── manifest.json                    # Master index of all custom specs
└── custom/                          # All custom specs use "custom" provider
    ├── my-api/
    │   ├── v1.json                  # Normalized OpenAPI spec
    │   └── v2.json
    ├── internal-api/
    │   └── v1.json
    └── third-party-api/
        └── v1.json
```

### 🔄 Triple-Source Architecture

The MCP server now operates as a **triple-source system**:

```mermaid
graph TD
    A[MCP Client Request] --> B[Triple-Source API Client]
    B --> C[Custom Specs - Highest Priority]
    B --> D[Secondary APIs - Medium Priority]  
    B --> E[APIs.guru - Base Priority]
    
    C --> F{Found in Custom?}
    F -->|Yes| G[Return Custom Result]
    F -->|No| H{Found in Secondary?}
    H -->|Yes| I[Return Secondary Result]
    H -->|No| J[Return Primary Result]
```

**Precedence Rules**: Custom > Secondary > Primary (**Custom Always Wins**)

### 🔧 CLI Reference

#### Import Commands

```bash
--import [PATH/URL]     # Import spec (interactive if no path provided)
--name NAME             # Specify name for the imported spec  
--version VERSION       # Specify version for the imported spec
--skip-security         # Skip security scanning during import
--strict-security       # Block import on any medium+ security issues
```

#### Management Commands

```bash
--list-custom           # List all imported custom specs with details
--remove-custom ID      # Remove a custom spec (format: name:version)
--rescan-security ID    # Re-run security scan on existing spec
--validate-integrity    # Check integrity of custom spec storage
--repair-integrity      # Repair integrity issues automatically
```

#### General Commands

```bash
--help, -h              # Show help message with all commands
```

### 💡 Usage Examples

#### Interactive Import Workflow

```bash
$ openapi-directory-mcp --import

📋 Custom OpenAPI Spec Import Wizard
==================================================

📂 Enter the path or URL to your OpenAPI spec: ./company-api.yaml
🔍 Validating specification...
✅ Valid OpenAPI specification detected
📝 Enter a name for this API: company-api
🏷️  Enter a version identifier: v1.2.0
🔒 Security scanning? (strict/normal/skip) [normal]: normal

📦 Ready to import:
   Source: ./company-api.yaml
   Name: company-api
   Version: v1.2.0
   Security: normal

Proceed with import? (Y/n): y

📥 Importing OpenAPI spec from: ./company-api.yaml
📝 Name: company-api, Version: v1.2.0
🔍 Processing and validating specification...
🔒 Security scan completed:
✅ No security issues found
💾 Storing specification...
✅ Successfully imported custom spec: custom:company-api:v1.2.0
```

#### Direct Import Examples

```bash
# Import internal API with security scanning disabled
openapi-directory-mcp --import ./internal-api.yaml --name internal --version v1 --skip-security

# Import public API with strict security requirements
openapi-directory-mcp --import https://api.github.com/openapi.json --name github --version v3 --strict-security

# Import development API with normal security scanning
openapi-directory-mcp --import ./dev-api.json --name dev-api --version latest
```

#### Management Examples

```bash
# List all custom specifications
$ openapi-directory-mcp --list-custom

📚 Custom OpenAPI Specifications (3)
============================================================

1. company-api:v1.2.0
   📋 Company Internal API
   📄 Internal API for company services and data access
   📅 Imported: 12/15/2024 | 📊 156KB YAML
   🔒 Security: ✅ 0 issues | 📦 Source: file

2. github:v3
   📋 GitHub REST API
   📄 GitHub's REST API for repository and user management
   📅 Imported: 12/14/2024 | 📊 2.1MB JSON
   🔒 Security: ⚠️ 2 issues | 📦 Source: url

3. dev-api:latest
   📋 Development API
   📄 Development environment API for testing
   📅 Imported: 12/13/2024 | 📊 45KB JSON
   🔒 Security: ✅ 0 issues | 📦 Source: file

💾 Total: 3 specs, 2.3MB
```

### 🔌 Seamless Inte

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [rawveg](https://github.com/rawveg)
- **Source:** [rawveg/openapi-directory-mcp](https://github.com/rawveg/openapi-directory-mcp)
- **License:** MIT
- **Homepage:** https://www.openapidirectory.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** yes

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-rawveg-openapi-directory-mcp
- Seller: https://agentstack.voostack.com/s/rawveg
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.