yandex-tracker-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP Yandex Tracker is a Model Context Protocol (MCP) server that provides tools for interacting with Yandex Tracker API. It implements a FastMCP server with protocol-based architecture and optional Redis caching.

Commands

task              # Run all checks (format, lint, type checking, tests) - REQUIRED before commits
task format       # Auto-format code
task check        # Run type and format checking
task test         # Run tests
uv sync           # Install dependencies
uv run mcp-tracker # Run the server

Architecture

• Protocols (mcp_tracker/tracker/proto/): Define API contracts (IssueProtocol, QueuesProtocol, etc.)
• Client (mcp_tracker/tracker/custom/client.py): Implements protocols, handles HTTP requests
• Caching (mcp_tracker/tracker/caching/client.py): Wraps protocols with Redis caching
• MCP Server (mcp_tracker/mcp/server.py): Server creation and configuration
• MCP Tools (mcp_tracker/mcp/tools/): Tool definitions organized by category
  • _access.py: Access control helpers (check_issue_access, check_queue_access)
  • queue.py / queue_write.py: Queue read-only / write tools
  • field.py: Global field and metadata tools (read-only)
  • issue_read.py / issue_write.py: Issue read-only / write tools
  • user.py: User tools (read-only)
  • __init__.py: Exports register_all_tools() which orchestrates tool registration
  • *_write.py modules are only registered when settings.tracker_read_only=False
• Settings (mcp_tracker/settings.py): Pydantic settings from environment variables
• All protocol methods accept optional auth: YandexAuth | None parameter for OAuth support.
• All Pydantic models for Yandex Tracker entities inherit from BaseTrackerEntity.

Testing

Rules

• Use pytest with asyncio mode auto
• Use aioresponses for HTTP mocking in TrackerClient tests and @tests/aioresponses_utils.py for capturing request/response pairs.
• Use AsyncMock with spec= for protocol mocking in MCP tool tests
• Always type-hint all parameters including fixtures
• Never import inside functions - all imports at top of file
• Never use loops for test cases - use @pytest.mark.parametrize
• Use model_construct() for creating Pydantic model fixtures (skips validation)