mcp-panther: Instructions file for Claude Code

Code Guidelines

• Always use and commit changes in feature branches containing the human's git user
• Use the @Makefile commands for local linting, formatting, and testing
• Always update the init.py when adding new files for prompts, resources, or tools
• Always update the @README.md when adding or updating tool names, changing supported installations, and any user-facing information that's important. For developer-oriented instructions, update @src/README.md

Development Documentation

For comprehensive development guidance, refer to:

• @docs/mcp-development-best-practices.md - Core principles, parameter patterns, error handling, security practices
• @docs/mcp-testing-guide.md - Testing strategies and patterns
• @docs/tool-design-patterns.md - Tool design patterns and anti-patterns
• @docs/server-architecture-guide.md - Server architecture and context management

Validation Guidelines

What FastMCP/Pydantic Handles Automatically

• Basic type validation: str, int, list[str], etc. are validated automatically
• Field constraints: ge, le, min_length, max_length work perfectly
• List type validation: list[str] automatically validates that all items are strings
• Optional types: str | None works correctly

When to Use BeforeValidator

Only use BeforeValidator for:

• Custom domain validation - validating specific enum values (e.g., ["OPEN", "TRIAGED", "RESOLVED", "CLOSED"])
• Complex validation logic - date format parsing, custom business rules
• Value transformation - converting or normalizing input values
• Cross-field validation - validating combinations of parameters

When NOT to Use BeforeValidator

Avoid BeforeValidator for basic validation that Field constraints can handle:

• ❌ _validate_positive_integer → ✅ Use Field(ge=1)
• ❌ _validate_non_empty_string → ✅ Use Field(min_length=1)
• ❌ _validate_string_list → ✅ Use list[str] type hint