# Leekwars MCP Encyclopedia

A standalone, Leekwars-aware MCP server dedicated to encyclopedia search and retrieval.

## Goal

This project exists to separate **knowledge tools** from the main Leekwars MCP server.

The main `leekwars-mcp` repository should focus on authenticated game actions, such as fetching leeks, running fights, managing AIs, buying items, and interacting with the Leekwars API.

This repository focuses only on read-only encyclopedia knowledge:

- searching the Leekwars encyclopedia
- retrieving encyclopedia pages by path
- returning useful snippets and metadata for agents
- exposing domain-aware tools for Leekwars concepts such as chips, weapons, effects, entities, and game mechanics

## Why a separate server?

The encyclopedia search stack may use Python-specific tooling such as `bm25s`. Keeping it in a separate repository avoids adding Python dependencies to the mostly TypeScript game-action server.

This split also creates a clearer MCP model:

- **Leekwars action server**: authenticated, state-changing, game/API operations
- **Leekwars encyclopedia server**: unauthenticated, read-only, knowledge retrieval

An MCP client or agent can connect to both servers when it needs both knowledge and actions.

## Intended MCP tools

Initial tools could include:

- `search_encyclopedia(query, k?)` — search the encyclopedia and return ranked Leekwars-aware results
- `get_encyclopedia_page(path)` — read a full encyclopedia page by path
- `list_encyclopedia_pages()` — list known encyclopedia documents

Future tools may become more domain-specific:

- `find_chip(name)`
- `find_weapon(name)`
- `find_effect(name)`
- `search_game_mechanics(query)`

## Design direction

The server should return structured, domain-aware results rather than generic text blobs. A search result should ideally include:

- title
- path
- score
- snippet
- document/category metadata when available

Example shape:

```json
{
  "title": "Chip: Flame",
  "path": "chips/flame.md",
  "score": 12.34,
  "snippet": "Flame deals fire damage...",
  "kind": "chip"
}
```

## Setup

Primary workflow with `uv`:

```bash
uv sync
uv run leekwars-mcp-encyclopedia
```

Plain `venv` + `pip` workflow:

```bash
python -m venv .venv
.venv/bin/pip install -e .
.venv/bin/leekwars-mcp-encyclopedia
```

The default command starts the stdio MCP server. The index is generated at startup if `.cache/bm25/` is missing.

## CLI

```bash
leekwars-mcp-encyclopedia
leekwars-mcp-encyclopedia serve
leekwars-mcp-encyclopedia index --rebuild
```

## Vendored encyclopedia content

The server reads encyclopedia markdown only from:

```text
vendor/encyclopedia/root/
```

Generated search indexes live under `.cache/bm25/` and are git-ignored.

## Relationship with `leekwars-mcp`

This repository is intended to replace the encyclopedia-related tools currently living in `leekwars-mcp`, especially:

- `search_encyclopedia`
- `get_encyclopedia_page`

Once this project exists, those tools can be removed from the action server or kept temporarily as deprecated compatibility wrappers.