# Start.gg MCP Server

A Model Context Protocol (MCP) server that provides access to the [Start.gg](https://start.gg) GraphQL API. This server allows LLMs to query tournament information, event standings, player sets, and report bracket results directly.

## Features

- **Tournament & Event Discovery**: Look up tournaments and events by their slugs and IDs.
- **Standings & Statistics**: Fetch event standings, entrants, and recent sets for specific players.
- **Bracket Management**: Retrieve bracket sets (matches) and report winners.
- **Game Search**: Find videogame IDs to filter tournament searches.

## Prerequisites

- **Node.js**: Version 22.0.0 or higher.
- **Start.gg API Key**: You must have a valid Personal Access Token from [Start.gg Developer Settings](https://start.gg/admin/profile/developer).

## Setup & Configuration

### 1. Get an API Key

1. Log in to [Start.gg](https://start.gg).
2. Go to **Developer Settings** in your profile.
3. Create a new **Personal Access Token**.
4. Copy the token and keep it secure.

### 2. Environment Variables

The server requires the following environment variable to be set:

- `STARTGG_API_KEY`: Your Start.gg Personal Access Token.

### 3. Build & Run locally

Clone the repository and install dependencies:

```bash
npm install
npm run build
npm run start:stdio
```

## Available Tools

| Tool | Description |
| :--- | :--- |
| `get_tournament` | Retrieves details for a tournament by slug, including its events. |
| `get_event` | Retrieves details for an event by slug (e.g., `tournament/genesis-9/event/ultimate-singles`). |
| `get_event_standings` | Retrieves paginated standings (placements) for an event ID. |
| `get_event_entrants` | Retrieves a paginated list of entrants for an event ID. |
| `get_event_sets` | Retrieves paginated bracket sets (matches) for an event ID. |
| `get_player_sets` | Retrieves the most recent sets played by a player by their player ID. |
| `search_videogame` | Retrieves the Start.gg videogame ID for a given game name. |
| `report_bracket_set` | Reports the winner of a specific bracket set. |

## Usage with MCP Clients

### Claude Desktop

Add the following configuration to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "startgg": {
      "command": "node",
      "args": ["/path/to/startgg-mcp/dist/index.js"],
      "env": {
        "STARTGG_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Example Prompts

Once configured, you can ask Claude things like:

- "Who won the Melee singles at Genesis X?"
- "Find the Start.gg ID for Super Smash Bros. Melee."
- "Show me the top 8 standings for the Ultimate event at Smash Con 2024."
- "What are the most recent sets played by Mang0?"

## Troubleshooting

### API Key Issues

- Ensure `STARTGG_API_KEY` is correctly set in your environment or client config.
- Verify the key is a "Personal Access Token" and not a "Client ID".
- Check if your key has expired or has been revoked in Start.gg settings.

### Connection Errors

- If running via HTTP, ensure the server is listening on the correct port and accessible from your client.
- Check the server logs (outputted to stderr in stdio mode) for detailed error messages.

## Development

- **Build**: `npm run build`
- **Watch mode**: `npm run dev:stdio`
- **Lint & Format**: `bun run devcheck`
- **Test**: `npm test`

## License

Apache-2.0