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:

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

Setup

Primary workflow with uv:

uv sync
uv run leekwars-mcp-encyclopedia

Plain venv + pip workflow:

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

leekwars-mcp-encyclopedia
leekwars-mcp-encyclopedia serve
leekwars-mcp-encyclopedia index --rebuild

Vendored encyclopedia content

The server reads encyclopedia markdown only from:

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.