yandex-wiki-search-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance for working on the yandex-wiki-search-mcp package.

Project Overview

yandex-wiki-search-mcp is an MCP server for the public Yandex Wiki API with full-text search. It exposes Wiki-oriented tools through the MCP Python SDK's MCPServer and keeps the code organized around a dedicated Wiki domain model.

The SDK is pinned to mcp[cli]>=2,<3. One v2 server answers both protocol eras — every handshake revision back to 2024-11-05 plus the modern 2026-07-28 — so nothing here needs a per-era branch.

Main capabilities:

• full-text search across the whole Wiki, with server-side filters (section, type, author, date interval) and optional <em> highlighting
• read pages by page_id or slug
• fetch descendants for page trees
• read comments, resources, and attachments; read an attachment into the conversation (page_read_attachment — images as a native image block, everything else as text or a base64 blob) or stream it to a local file (page_download_attachment)
• look up the calling user (/users/me): username, personal-section slug, identity ids
• create and update pages, including setting and clearing redirects
• edit page content by exact-text replacements, without resending the whole page
• append content to pages
• delete and recover pages; delete comments and attachments
• upload local files through Wiki upload sessions and attach them to pages

Commands

task              # Run lock, format, checks, and tests
task format       # Format code with Ruff and fix imports
task check        # Run Ruff, format check, mypy, and ty
task test         # Run pytest
task test-cov     # Run tests with HTML coverage report
uv sync --dev     # Install dependencies
uv run yandex-wiki-search-mcp  # Run the server locally

Before finalizing substantial code changes, run at least:

task format
task test

Architecture

The full developer guide — layers, code map, design decisions, testing seams, CI and the release process — lives in docs/architecture.md (EN) and docs/architecture_ru.md (RU). When a change alters anything described there (structure, tool surface, contracts, CI, release flow), update both files in the same change.