# Magento 2 REST API MCP Server

A local STDIO MCP server that provides tools to search and retrieve Magento 2 REST API documentation from OpenAPI (swagger) specifications.

## Features

- **Search Endpoints**: Full-text search across all Magento 2 REST API endpoints
- **Get Endpoint Details**: Retrieve complete documentation for specific API endpoints
- **List Categories**: Browse endpoints by category tags (carts, customers, products, etc.)
- **Search Schemas**: Find data models and schema definitions
- **Get Schema Details**: View complete schema/model definitions with all properties
- **Offline Operation**: Works entirely offline using local swagger.json file
- **Fast Startup**: Only re-parses if swagger.json has been modified

## How it Works

1. **Parsing**: On startup, the server parses the OpenAPI 3.0 swagger.json file
2. **Indexing**: Extracts endpoints, parameters, responses, and schemas
3. **Storage**: Stores data in a local SQLite database with FTS5 indexes
4. **Searching**: Provides full-text search across paths, descriptions, parameters, and schemas

## Installation

### Requirements

- Python 3.10 or higher
- uv (recommended) or pip

### Install from Source

```bash
cd magento-api-mcp
pip install -e .
```

## Usage

### Running the Server

```bash
magento-api-mcp
```

The server starts immediately and parses the swagger.json file on first run or when the file has been modified.

### Configuration

- **Database Location**: Default is `~/.mcp/magento-api/database.db`
  - Override with `MAGENTO_API_DB_PATH` environment variable
- **Swagger File**: Default is `data/swagger.json` in the package directory
  - Override with `MAGENTO_API_SWAGGER_PATH` environment variable

### Using with an MCP Client

Configure your MCP client to run the `magento-api-mcp` command:

```json
{
  "mcpServers": {
    "magento-api": {
      "command": "magento-api-mcp"
    }
  }
}
```

Or with custom swagger file:

```json
{
  "mcpServers": {
    "magento-api": {
      "command": "magento-api-mcp",
      "env": {
        "MAGENTO_API_SWAGGER_PATH": "/path/to/your/swagger.json"
      }
    }
  }
}
```

## MCP Tools

### 1. `search_endpoints`

Search for API endpoints using keywords.

**Parameters:**
- `queries`: List of 1-3 short keyword queries (e.g., ["cart", "customer"])
- `filter_by_method`: Optional HTTP method filter (GET, POST, PUT, DELETE)
- `filter_by_tag`: Optional category filter (e.g., "carts/mine")

**Example:**
```python
search_endpoints(queries=["cart operations"], filter_by_method="GET")
```

### 2. `get_endpoint_details`

Get complete documentation for a specific endpoint.

**Parameters:**
- `path`: Exact API path (e.g., "/V1/carts/mine")
- `method`: Optional HTTP method (if omitted, returns all methods for this path)

**Example:**
```python
get_endpoint_details(path="/V1/carts/mine", method="GET")
```

**Returns:**
- HTTP method and path
- Category and operation ID
- Summary and description
- Parameters table with types and descriptions
- Request body schema (if applicable)
- Response codes and schemas

### 3. `list_tags`

List all available API category tags.

**Returns:** Hierarchical list of all endpoint categories with counts.

### 4. `search_schemas`

Search for data schemas/models by keyword.

**Parameters:**
- `query`: Keyword to search for

**Example:**
```python
search_schemas(query="customer")
```

### 5. `get_schema`

Get complete definition of a schema/model.

**Parameters:**
- `schema_name`: Exact schema name (e.g., "quote-data-cart-interface")

**Returns:** Full schema with type, description, and all properties in JSON format.

## Verification Scripts

Test each component independently:

```bash
# Test the OpenAPI parser
python3 tests/verify_parser.py

# Test database ingestion
python3 tests/verify_db.py

# Test MCP server and all tools
python3 tests/verify_server.py
```

## Database Schema

The server uses SQLite with the following tables:

- **endpoints**: All API endpoints with FTS5 index
- **parameters**: Endpoint parameters
- **responses**: Response definitions
- **schemas**: Data model definitions with FTS5 index
- **metadata**: Ingestion tracking

## Advantages Over Web Scraping

1. **No Network Dependency**: Works completely offline
2. **Instant Startup**: ~2-5 seconds vs minutes of web scraping
3. **Structured Data**: Access to complete OpenAPI metadata
4. **Precise Search**: Filter by method, category, response code
5. **Schema Resolution**: Navigate complex nested data structures
6. **Deterministic**: No HTML parsing or website structure changes

## Example Queries

| Query | Tool | Purpose |
|-------|------|---------|
| `["cart"]` | search_endpoints | Find all cart-related endpoints |
| `["customer", "authentication"]` | search_endpoints | Find customer auth endpoints |
| `/V1/carts/mine` | get_endpoint_details | Get complete cart endpoint docs |
| `customer` | search_schemas | Find customer-related schemas |
| `quote-data-cart-interface` | get_schema | View cart data structure |

## Development

### Project Structure

```
magento-api-mcp/
├── magento_api_mcp/
│   ├── __init__.py
│   ├── config.py          # Configuration
│   ├── parser.py          # OpenAPI parser
│   ├── ingest.py          # Database ingestion
│   └── server.py          # MCP server with tools
├── tests/
│   ├── verify_parser.py   # Parser verification
│   ├── verify_db.py       # Database verification
│   └── verify_server.py   # Server verification
├── data/
│   └── swagger.json       # OpenAPI specification
├── pyproject.toml
└── README.md
```

### Adding New Tools

To add new MCP tools, edit `magento_api_mcp/server.py` and use the `@mcp.tool()` decorator.

### Using Different Swagger Files

The server can work with any OpenAPI 3.0 swagger file. Simply set the `MAGENTO_API_SWAGGER_PATH` environment variable:

```bash
export MAGENTO_API_SWAGGER_PATH=/path/to/different-api-swagger.json
magento-api-mcp
```

## License

MIT

## Contributing

Contributions welcome! Please test all changes with the verification scripts before submitting.

## Support

For issues or questions, please check:
1. Run verification scripts to diagnose issues
2. Check database location and permissions
3. Verify swagger.json is valid OpenAPI 3.0 format