# MCP GoodPass API Server

A Model Context Protocol (MCP) server that provides access to the GoodPass API, allowing AI assistants to search for products, retrieve product details, check availability, get pricing, and manage orders.

## Overview

This MCP server exposes the GoodPass API through a standardized interface, enabling AI assistants like Claude Desktop to interact with GoodPass services. The server provides tools for:

- Searching products with filters
- Retrieving product details
- Checking available dates
- Getting pricing information
- Creating temporary orders
- Retrieving order forms

## Prerequisites

- Python 3.12 or higher
- `uv` package manager (recommended) or `pip`
- A GoodPass API key

## Installation

### Using `uv` (Recommended)

1. Clone or navigate to this repository:
   ```bash
   cd mcp-goodpass-api
   ```

2. Install dependencies using `uv`:
   ```bash
   uv sync
   ```

### Using `pip`

1. Install dependencies:
   ```bash
   pip install -e .
   ```

   Or install directly:
   ```bash
   pip install httpx mcp[cli] python-dotenv requests
   ```

## Configuration

### Environment Variables

Create a `.env` file in the project root directory with the following variables:

```env
GOODPASS_API_KEY=your_api_key_here
GOODPASS_BASE_URL=https://partner-api.goodpass.club/v1
```

**Required:**
- `GOODPASS_API_KEY`: Your GoodPass API key (required)

**Optional:**
- `GOODPASS_BASE_URL`: The base URL for the GoodPass API (defaults to `https://partner-api.goodpass.club/v1`)

### Creating the `.env` file

1. Create a `.env` file in the project root:
   ```bash
   touch .env
   ```

2. Add your configuration:
   ```bash
   echo "GOODPASS_API_KEY=your_actual_api_key" >> .env
   echo "GOODPASS_BASE_URL=https://partner-api.goodpass.club/v1" >> .env
   ```

## Running the Server

### Direct Execution

Run the server directly:

```bash
python goodpass_server.py
```

Or using `uv`:

```bash
uv run goodpass_server.py
```

The server runs over stdio (standard input/output), which is the standard transport for MCP servers.

### Testing with MCP Inspector

You can test the server using the MCP Inspector. Open `MCP Inspector.html` in your browser to interact with the server.

## Configuring in Claude Desktop

To use this MCP server with Claude Desktop:

1. **Locate Claude Desktop configuration file:**
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **Linux**: `~/.config/Claude/claude_desktop_config.json`

2. **Edit the configuration file** and add the MCP server:

   ```json
   {
     "mcpServers": {
       "mcp-goodpass-api": {
         "command": "python",
         "args": [
           "/absolute/path/to/mcp-goodpass-api/goodpass_server.py"
         ],
         "env": {
           "GOODPASS_API_KEY": "your_api_key_here",
           "GOODPASS_BASE_URL": "https://partner-api.goodpass.club/v1"
         }
       }
     }
   }
   ```

   **Note:** Replace `/absolute/path/to/mcp-goodpass-api/goodpass_server.py` with the actual absolute path to your `goodpass_server.py` file.

3. **Alternative using `uv`:**
   If you're using `uv`, you can configure it like this:

   ```json
   {
     "mcpServers": {
       "mcp-goodpass-api": {
         "command": "uv",
         "args": [
           "run",
           "/absolute/path/to/mcp-goodpass-api/goodpass_server.py"
         ],
         "env": {
           "GOODPASS_API_KEY": "your_api_key_here"
         }
       }
     }
   }
   ```

4. **Restart Claude Desktop** for the changes to take effect.

## Available Tools

The MCP server provides the following tools:

### `find_products`
Search products with filters.

**Parameters:**
- `page` (int, default: 1): Page number
- `limit` (int, default: 10): Results per page
- `categories` (List[str], optional): Filter by categories
- `themes` (List[str], optional): Filter by themes
- `destination` (str, optional): Filter by destination
- `search` (str, optional): Search query
- `minPrice` (float, optional): Minimum price filter
- `maxPrice` (float, optional): Maximum price filter
- `productType` (str, optional): Filter by product type
- `currency` (str, optional): Currency code

### `retrieve_product`
Retrieve a single product by ID.

**Parameters:**
- `id` (str, required): Product ID

### `get_available_dates`
List available dates for a product.

**Parameters:**
- `id` (str, required): Product ID

### `get_prices_for_date`
Get pricing for a product on a specific date.

**Parameters:**
- `id` (str, required): Product ID
- `date` (str, required): Date in YYYY-MM-DD format

### `create_temp_order`
Create a temporary order.

**Parameters:**
- `productId` (str, required): Product ID
- `date` (str, required): Date in YYYY-MM-DD format
- `ticketSelections` (Dict[str, int], required): Ticket selections mapping
- `usercode` (str, required): User code

### `get_order_forms`
Retrieve required form fields for an order.

**Parameters:**
- `orderId` (str, required): Order ID

## Troubleshooting

### Server won't start

1. **Check Python version:**
   ```bash
   python --version
   ```
   Ensure you have Python 3.12 or higher.

2. **Verify API key:**
   Make sure `GOODPASS_API_KEY` is set in your `.env` file or environment variables.

3. **Check dependencies:**
   ```bash
   pip list | grep -E "httpx|mcp|dotenv"
   ```
   Or with `uv`:
   ```bash
   uv pip list
   ```

### Claude Desktop can't connect

1. **Verify the path:**
   Ensure the absolute path in `claude_desktop_config.json` is correct.

2. **Check permissions:**
   Make sure the script is executable:
   ```bash
   chmod +x goodpass_server.py
   ```

3. **Test manually:**
   Run the server directly to check for errors:
   ```bash
   python goodpass_server.py
   ```

4. **Check logs:**
   Claude Desktop logs may contain error messages. Check the console or log files.

### API errors

- Verify your API key is valid and has the necessary permissions
- Check the `GOODPASS_BASE_URL` is correct
- Ensure your network connection is working
- Review the API response for specific error messages

## Development

### Project Structure

```
mcp-goodpass-api/
├── goodpass_server.py    # Main MCP server implementation
├── main.py               # Entry point (optional)
├── pyproject.toml        # Project dependencies
├── README.md             # This file
└── .env                  # Environment variables (create this)
```

### Adding New Tools

To add new tools to the MCP server:

1. Add a new function decorated with `@mcp.tool()` in `goodpass_server.py`
2. Use the `_get()` or `_post()` helper functions for API calls
3. Document the function with a docstring
4. Restart the server to load the new tool

## License

[Add your license information here]

## Support

For issues related to:
- **MCP Server**: Open an issue in this repository
- **GoodPass API**: Contact GoodPass support
- **Claude Desktop**: Check Claude Desktop documentation