# OpenAPI to MCP Server Generator

A Python tool that automatically converts OpenAPI specifications into fully functional Model Context Protocol (MCP) servers. Generates Docker-ready implementations with support for SSE/IO communication protocols, authentication, and comprehensive error handling.

## Key features:

- 🔄 OpenAPI to MCP tools/resources conversion
- 🐳 Docker-ready with multi-stage builds
- 🔐 Multiple authentication methods
- ⚡ Async operations & rate limiting
- 📡 SSE/IO communication protocols
- 📦 Modular code structure with package support

## Modular Code Structure

The generator has been refactored into a proper Python package while maintaining backward compatibility:

1. **Original Entry Point**: The `generator.py` script still works exactly as before
2. **Modular Organization**: Code is now split into focused modules
3. **Package Installation**: Can be installed as a proper Python package
4. **Same Templates**: Uses the exact same templates in the `/templates` directory
5. **Docker Support**: Preserves all Docker functionality

You can use the tool in whatever way you prefer:
1. Run `generator.py` directly (original approach)
2. Install as a package and use `mcp-generator` command
3. Use the module programmatically in your own Python code

For more details on the modular code structure, see [MODULAR_REFACTORING.md](MODULAR_REFACTORING.md).

## Features

- Convert OpenAPI specifications to MCP servers
- Docker-ready implementation with multi-stage builds
- Support for multiple authentication methods
- Choice of SSE or IO communication protocols
- Comprehensive error handling and logging
- Built-in rate limiting and security features
- Async operations for optimal performance
- Extensive test suite with coverage reporting

## Prerequisites

- Python 3.10+
- Docker (for running the generated server)
- pip or uv (Python package manager)

## Installation

### From Source

```bash
# Clone the repository
git clone https://github.com/abutbul/openapi-mcp-generator.git
cd openapi-mcp-generator

# Install as a package (development mode)
pip install -e .

# Or using uv
uv venv
source .venv/bin/activate
uv pip install -e .
```

### Using pip (once published)

```bash
pip install openapi-mcp-generator
```

## Usage

```bash
# Using the original script (still works the same way)
python generator.py openapi.yaml --output-dir ./output --api-url https://api.example.com

# Using the new modular CLI tool after installation
mcp-generator openapi.yaml --output-dir ./output --api-url https://api.example.com

# Using the python module directly
python -m openapi_mcp_generator.cli openapi.yaml --output-dir ./output
```

### Command Line Options

- `openapi_file`: Path to the OpenAPI YAML file (required)
- `--output-dir`: Output directory for the generated project (default: '.')
- `--api-url`: Base URL for the API
- `--auth-type`: Authentication type (bearer, token, basic)
- `--api-token`: API token for authentication
- `--api-username`: Username for basic authentication
- `--api-password`: Password for basic authentication

## Running the Generated Server

After generating the server, you can build and run it using Docker:

```bash
cd output/openapi-mcp-*
./docker.sh build
./docker.sh start --transport=sse --port=8000
```

### Docker Script Options

The generated `docker.sh` script supports the following commands:

- `build`: Build the Docker image
- `start`: Start the container
  - `--port=PORT`: Set the port (default: 8000)
  - `--transport=TYPE`: Set transport type: 'sse' or 'io' (default: sse)
  - `--log-level=LEVEL`: Set logging level (default: info)
- `stop`: Stop the container
- `clean`: Remove the container and image
- `logs`: View container logs

## Project Structure

The modular generator has the following structure:

```
openapi-mcp-generator/
├── generator.py              # Original entry point (maintained for backward compatibility)
├── mcp_generator.py          # New entry point (uses the modular structure)
├── openapi_mcp_generator/    # Main package (new modular structure)
│   ├── __init__.py           # Package initialization
│   ├── cli.py                # Command-line interface
│   ├── generator.py          # Main generator module
│   ├── generators.py         # Code generators for tools/resources
│   ├── http.py               # HTTP client utilities
│   ├── parser.py             # OpenAPI parser
│   └── project.py            # Project builder
├── templates/                # Original templates directory (used by the modular code)
│   ├── config/
│   ├── docker/
│   ├── server/
│   ├── pyproject.toml
│   └── requirements.txt
├── samples/                  # Sample implementations
├── tests/                    # Test cases
├── LICENSE                   # License file
├── README.md                 # This file
├── pyproject.toml            # Project metadata
└── setup.py                  # Package setup
```

The modular structure preserves all the existing functionality while making the code more maintainable:

1. The original entry point (`generator.py`) can still be used as before
2. The existing templates in `/templates` are used by the new modular code
3. All Docker-related functionality is preserved exactly as it was
4. The project can now be installed as a proper Python package

## Sample Implementations

Check out our sample implementations to see the generator in action:

- [Trilium Notes ETAPI Server](./samples/TriliumNext/README.md) - An MCP server for the Trilium Notes knowledge management system's ETAPI

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run the test suite
5. Submit a pull request

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Usage Examples

### 1. Using the library without installing (direct from source)

To generate an MCP server from the Elasticsearch 6.1 spec folder:

```bash
# Run the original script directly
python generator.py samples/elasticsearch_6.1/api

# Or use the modular entry point
python mcp_generator.py samples/elasticsearch_6.1/api
```

### 2. Using the library after installing with pip

First, install the package (from the project root):

```bash
pip install .
```

Then use the CLI tool to convert the Trilium ETAPI spec:

```bash
mcp-generator samples/TriliumNext/etapi.openapi.yaml
```

Or use it programmatically in your own Python code:

```python
from openapi_mcp_generator import generator

generator.generate('samples/TriliumNext/etapi.openapi.yaml')
```