eng-mcp-server: Instructions file for Claude Code

Reality Defender MCP Server

This document outlines key information for working with the Reality Defender MCP Server project.

Documentation Guidelines

Documentation Maintenance

• Keep Documentation Updated: All code changes must be accompanied by corresponding updates to CLAUDE.md and README.md
• Document New Features: Any new functionality should be documented with usage examples
• Update Configuration: Ensure any new environment variables or configuration options are documented
• Update Troubleshooting: Add common issues and solutions as they are discovered

Structured Data Guidelines

• Always Use Pydantic Models: All structured data, especially from external sources like APIs, must use Pydantic models
• Input Validation: Define explicit types and validation rules in Pydantic models for all external inputs
• Output Serialization: Use model_dump() for all data sent to external systems
• Type Annotations: Ensure all function parameters and return values have proper type annotations

Python 3.12 Standards & Best Practices

• Modern Type Annotations: Use Python 3.12 union syntax (str | None instead of Optional[str])
• Strict Type Hints: Apply type hints to all functions, parameters, and return values
• Prefer object over Any: Use object instead of Any for better type safety (similar to TypeScript's unknown over any)
• Type Parameter Syntax: Use the new Class[T] type parameter syntax for generics
• Pattern Matching: Utilize structural pattern matching for complex conditionals
• PEP 695 Type Aliases: Use the new type alias syntax: type Vec = list[float]
• Self Type: Use the Self type for methods that return instances of their own class
• Type Guards: Implement type guards to narrow types in conditional blocks

Error Handling Pattern

MCP tools use a consistent error handling pattern:

• Return Union Types: All tools return SuccessType | Error instead of raising exceptions
• Error Model: Use Error(error="message") pydantic model with single error: str property
• Wrap Operations: Surround potentially failing operations with try/catch blocks
• Consistent Logging: Log errors before returning Error objects for debugging