trakt_mcpserver: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Project Overview

Model Context Protocol (MCP) server bridging AI models with Trakt.tv API. Built with FastMCP, providing entertainment data access with OAuth authentication.

Trakt API Reference: https://developer.trakt.tv. For field names, request bodies, response shapes and status codes, use the OpenAPI spec at https://developer.trakt.tv/openapi.json. Guides are under https://developer.trakt.tv/docs/<page>; https://developer.trakt.tv/sitemap.xml lists every page. The pages are a JavaScript app, so fetch them with curl and strip the HTML.

Architecture - Single Responsibility Principle

CRITICAL REQUIREMENT: Every file must have exactly ONE clear purpose. No exceptions.

BEFORE ADDING FEATURES: Examine existing code patterns, design style, and architectural conventions to ensure consistency.

Domain boundaries mirror the Trakt API reference: Each top-level API resource (shows, movies, seasons, episodes, etc.) is its own domain — do NOT nest one domain's tools/clients inside another.

Current Structure

server/           # MCP server modules by domain
├── auth/         # Authentication tools/resources
├── shows/        # Show-specific tools/resources
├── seasons/      # Season-specific tools
├── movies/       # Movie-specific tools/resources
├── user/         # User data tools/resources
├── comments/     # Comment tools
├── search/       # Search tools
├── checkin/      # Check-in tools
└── prompts/      # MCP prompts

client/           # HTTP clients by domain
├── auth/         # Authentication client
├── shows/        # Show API client
├── seasons/      # Season API client
├── movies/       # Movie API client
├── comments/     # Comments API client
├── user/         # User API client
├── search/       # Search API client
└── checkin/      # Check-in API client

models/           # Pydantic models by domain
├── auth/         # Authentication models
├── formatters/   # Domain-specific formatters
├── movies/       # Movie models
├── shows/        # Show models
└── user/         # User models

config/           # Configuration by domain
├── auth/         # Auth constants
├── api/          # API constants  
├── endpoints/    # API endpoints by domain
└── mcp/          # MCP resource/tool definitions
    ├── resources/ # Domain-specific MCP resources
    └── tools/     # Domain-specific MCP tools

utils/api/        # API utilities
├── errors.py     # Error handling decorator
└── responses.py  # Response helpers