# OpenAPI MCP Server

A Model Context Protocol (MCP) server that dynamically exposes OpenAPI/Swagger APIs as tools for AI assistants.

## Overview

This MCP server automatically generates tools from OpenAPI specifications, allowing AI assistants to interact with any API that has an OpenAPI/Swagger definition. Each API endpoint becomes a callable tool with proper parameter handling and authentication support.

## Features

- **Dynamic Tool Generation**: Automatically creates MCP tools from OpenAPI operations
- **Multiple Authentication Methods**: Supports Bearer tokens, custom headers, and API keys
- **Flexible Spec Loading**: Load OpenAPI specs from local files or URLs
- **Full HTTP Method Support**: GET, POST, PUT, DELETE, PATCH operations
- **Parameter Handling**: Supports path, query, header parameters and request bodies
- **Error Handling**: Comprehensive error reporting and logging

## Installation

1. Clone this repository
2. Create a virtual environment (recommended):
   ```bash
   python -m venv myenv
   source myenv/bin/activate  # On Windows: myenv\Scripts\activate
   ```
3. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

### Why Use a Virtual Environment?

Using a virtual environment is strongly recommended because:
- **Isolation**: Keeps project dependencies separate from system Python packages
- **Version Control**: Ensures consistent package versions across different machines
- **Clean Development**: Prevents conflicts between different projects' dependencies
- **Easy Cleanup**: Simply delete the virtual environment folder to remove all packages

### Virtual Environment Commands

**Creating and activating:**
```bash
# Create virtual environment
python -m venv myenv

# Activate on macOS/Linux
source myenv/bin/activate

# Activate on Windows
myenv\Scripts\activate

# Activate on Windows (PowerShell)
myenv\Scripts\Activate.ps1
```

**Deactivating:**
```bash
deactivate
```

**Verifying activation:**
```bash
# Check if virtual environment is active
which python  # On macOS/Linux
where python  # On Windows

# Should show path to your virtual environment's Python
```

## Usage

### Basic Usage

Run the server with a local OpenAPI spec file:
```bash
python openapi-mcp-server.py petstore.yaml
```

Or using environment variables:
```bash
export OPENAPI_SPEC_PATH=petstore.yaml
python openapi-mcp-server.py
```

### Configuration

The server can be configured using environment variables:

- `OPENAPI_SPEC_PATH`: Path or URL to the OpenAPI specification
- `OPENAPI_BASE_URL`: Override the base URL from the spec (optional)
- `API_KEY`: Bearer token for API authentication (optional)

### Authentication

The server supports multiple authentication methods:

1. **Bearer Token**: Set via `API_KEY` environment variable
2. **Custom Headers**: Pass auth parameters in tool calls:
   - `_auth_profileId`: For X-IHR-Profile-ID header
   - `_auth_sessionId`: For X-IHR-Session-ID header
   - `_auth_token`: For Authorization Bearer token

## MCP Integration

To use this server with an MCP client, add it to your MCP configuration:

```json
{
  "mcpServers": {
    "openapi": {
      "command": "python",
      "args": ["/path/to/openapi-mcp-server.py"],
      "env": {
        "OPENAPI_SPEC_PATH": "/path/to/your-api-spec.yaml",
        "OPENAPI_BASE_URL": "https://api.example.com",
        "API_KEY": "your-api-key"
      }
    }
  }
}
```

## How It Works

1. **Spec Loading**: The server loads and parses the OpenAPI specification
2. **Tool Generation**: Each API operation becomes an MCP tool with:
   - Name from `operationId`
   - Description from operation `description` or `summary`
   - Input schema generated from parameters and request body
3. **Tool Execution**: When a tool is called:
   - Path parameters are substituted
   - Query parameters are added to the URL
   - Headers are set (including auth)
   - Request body is sent as JSON
   - Response is returned as formatted JSON

## Example Tools

For a typical OpenAPI spec, the server might generate tools like:

- `getPetById`: Fetch a pet by ID
- `addPet`: Add a new pet to the store
- `updatePet`: Update an existing pet
- `deletePet`: Delete a pet

Each tool will have appropriate parameters based on the API definition.

## Development

### Testing

The repository includes several utility scripts:

- `test-mcp-server.py`: Test the MCP server functionality
- `inspect-mcp-api.py`: Inspect available MCP APIs
- `check-mcp-install.py`: Verify MCP installation
- `mcp-openapi-generator-python.py`: Generate Python code from OpenAPI specs

### Logging

The server includes comprehensive logging. Set the log level via the standard Python logging configuration.

## Requirements

- Python 3.7+
- Dependencies listed in `requirements.txt`:
  - mcp>=0.1.0
  - httpx>=0.25.0
  - pyyaml>=6.0
  - pydantic>=2.0.0

## License

[Specify your license here]

## Contributing

[Add contribution guidelines if applicable]