# liquipedia-dota2-mcp

Read-only MCP server and Codex skill for sourced Dota 2 tournament, team, player, schedule, and result data from Liquipedia.

This is an unofficial community project. It is not affiliated with or endorsed by Liquipedia, Team Liquid, Valve, or OpenAI.

## Features

- Five structured MCP tools for entity search, tournament, team, player, and match queries.
- Revision-level source metadata, coverage indicators, and explicit parse warnings.
- Persistent SQLite cache, duplicate-request coalescing, and Liquipedia-compliant request queues.
- Local `stdio` transport for Codex, ChatGPT desktop, Claude Desktop, and other MCP clients.
- Bundled `liquipedia-dota2` Skill under `skills/liquipedia-dota2`.

## Requirements

- Node.js 22 or newer. The server uses Node's built-in SQLite module and does not require a native dependency build.
- A custom `LIQUIPEDIA_USER_AGENT` containing a project name, version, and contact URL or email.

Example:

```text
MyDotaAssistant/1.0 (developer@example.com)
```

The server refuses to start without a valid identifying User-Agent. It only sends automated requests to `https://liquipedia.net/dota2/api.php`; it does not scrape rendered website pages.

## Install and run

After the package is published to npm:

```powershell
$env:LIQUIPEDIA_USER_AGENT = "MyDotaAssistant/1.0 (developer@example.com)"
npx -y liquipedia-dota2-mcp
```

Directly from GitHub, without npm publishing:

```powershell
$env:LIQUIPEDIA_USER_AGENT = "MyDotaAssistant/1.0 (developer@example.com)"
npx -y github:Mooooooon/liquipedia-dota2-mcp
```

On npm 12 and newer, git package installs are disabled by default, so add `--allow-git=root`:

```powershell
$env:LIQUIPEDIA_USER_AGENT = "MyDotaAssistant/1.0 (developer@example.com)"
npx -y --allow-git=root github:Mooooooon/liquipedia-dota2-mcp
```

`dist/` is built automatically on install (`prepare` on npm 11 and earlier, pack-time `prepack` on npm 12), so the installer needs no build step.

From a source checkout:

```powershell
npm install
npm run build
$env:LIQUIPEDIA_USER_AGENT = "MyDotaAssistant/1.0 (developer@example.com)"
node dist/cli.js
```

Logs use stderr so stdout remains a valid MCP transport.

## Codex setup

Codex CLI and the ChatGPT desktop app share local MCP configuration. Add the published package with:

```powershell
codex mcp add liquipedia-dota2 --env "LIQUIPEDIA_USER_AGENT=MyDotaAssistant/1.0 (developer@example.com)" -- npx -y liquipedia-dota2-mcp
```

Or add this to `~/.codex/config.toml`:

```toml
[mcp_servers.liquipedia_dota2]
command = "npx"
args = ["-y", "liquipedia-dota2-mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 120

[mcp_servers.liquipedia_dota2.env]
LIQUIPEDIA_USER_AGENT = "MyDotaAssistant/1.0 (developer@example.com)"
```

Install the bundled Skill by copying `skills/liquipedia-dota2` into either the repository's `.agents/skills` directory or the user's `.agents/skills` directory. The Skill intentionally has no remote MCP dependency URL; configure the local server separately.

## Claude Desktop setup

Add the server to the Claude Desktop MCP configuration:

```json
{
  "mcpServers": {
    "liquipedia-dota2": {
      "command": "npx",
      "args": ["-y", "liquipedia-dota2-mcp"],
      "env": {
        "LIQUIPEDIA_USER_AGENT": "MyDotaAssistant/1.0 (developer@example.com)"
      }
    }
  }
}
```

## Tools

| Tool | Purpose |
| --- | --- |
| `search_dota2_entities` | Find tournament, team, and player candidates. |
| `get_dota2_tournament` | Read tournament metadata, participants, and placements. |
| `get_dota2_team` | Read team metadata, roster, and coaches. |
| `get_dota2_player` | Read player identity and team history. |
| `list_dota2_matches` | Read match schedule/result rows for a confirmed tournament or team. |

Every call returns `data`, section-level `coverage`, `warnings`, `source`, and a typed `error`. A section marked `unavailable` means the current parser could not establish the data; it does not mean that the source contains no records.

## Cache and limits

The server enforces minimum intervals of 2.1 seconds for ordinary MediaWiki requests and 31 seconds for `action=parse`. These minimums cannot be weakened through environment variables. Defaults are:

- Search: 6 hours
- Team/player: 24 hours
- Upcoming or ongoing tournament: 30 minutes
- Completed tournament: 7 days
- Match list: 15 minutes

Set `LIQUIPEDIA_CACHE_PATH` to choose the SQLite file. When Liquipedia is unavailable, an expired cache entry may be returned with `source.is_stale: true` and its stale age.

## Development

```powershell
npm run check
npm test
npm run build
npm pack --dry-run
```

Default tests are completely offline. An opt-in live smoke test performs a small number of compliant API calls:

```powershell
$env:LIQUIPEDIA_LIVE_TEST = "1"
$env:LIQUIPEDIA_USER_AGENT = "MyDotaAssistant/1.0 (developer@example.com)"
npm run test:live
```

## Data and licensing

Project code is MIT licensed. Liquipedia text/data is separately provided under CC BY-SA 3.0 and remains subject to Liquipedia's API terms. Tool results include attribution, license, source page, revision, and fetch time. Media such as logos and player photographs is not downloaded or redistributed.

See [Liquipedia API terms](https://liquipedia.net/api-terms-of-use) before deploying or modifying request behavior.