leafwiki-mcp: Instructions file for Codex

AGENTS.md

Project overview

This repository implements a Python MCP server for a LeafWiki instance. It exposes LeafWiki page discovery, organization, revision, favorite, and mutation operations as MCP tools over stdio. The package uses a src layout and requires Python 3.12 or newer.

The canonical repository is https://github.com/ipapadop/leafwiki-mcp, the default branch is main, and the conventional remote name is origin.

Keep changes focused on this integration. Consult README.md for user-facing setup and the current tool inventory; update it when configuration, commands, or exposed tools change.

Setup and commands

Use uv for dependency management and command execution:

uv sync
uv run leafwiki-mcp

These commands set up and run a source checkout. Do not describe the project as installable from PyPI unless a published distribution and its installation workflow have been verified.

Canonical quality checks are:

uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest

The Quality GitHub Actions workflow runs Ruff lint, Ruff formatting verification, Pyright, and Pytest for pull requests, pushes to main, and manual dispatches. These are the same canonical quality checks required locally before completion.

During development, run the narrowest relevant test first, for example:

uv run pytest tests/test_client.py -q
uv run pytest tests/test_server.py -q
uv run pytest tests/test_client.py::test_get_page_by_path_encodes_query -q

Do not assume a live LeafWiki instance is available for tests. To exercise the server manually, configure LEAFWIKI_URL, LEAFWIKI_USERNAME, and LEAFWIKI_PASSWORD as described in README.md. Authentication-disabled instances need only the URL.

Architecture and boundaries

• src/leafwiki_mcp/client.py is the LeafWiki HTTP/API boundary. It owns URL normalization, the cookie-preserving HTTPX session, authentication, CSRF handling, request encoding, response validation, API error translation, and page models.
• src/leafwiki_mcp/server.py is the MCP adaptation layer. LeafWikiTools should remain a collection of typed, synchronous operations that delegate API behavior to LeafWikiClient. create_server() explicitly registers the public tools.
• src/leafwiki_mcp/__main__.py owns CLI parsing, LEAFWIKI_* environment defaults, client lifetime, authentication, and starting FastMCP with transport="stdio".
• tests/test_client.py verifies HTTP contracts with httpx.MockTransport, including methods, paths, query parameters, headers, cookies, bodies, parsing, and failures.
• tests/test_server.py verifies that MCP-facing operations preserve semantics while delegating to a mocked LeafWikiClient.