PyGithub MCP Server

# Active Context ## Current Development Focus We're focused on implementing comprehensive test coverage improvements following ADR-002 principles while continuing to refine the modular tool architecture (ADR-006) and completing the Pydantic-First Architecture implementation (ADR-007). Key areas of current work: 1. Improving test coverage for high and medium priority modules 2. Implementing real API testing across all components (ADR-002) 3. Refining unit testing techniques without using mocks 4. Creating reusable test fixtures and patterns for integration testing 5. Maintaining the modular tool architecture (ADR-006) 6. Establishing patterns for testing future tool group implementations 7. Aligning test suite with Pydantic-First Architecture (ADR-007) ## Recent Changes ### Coverage Analysis Tool Refactoring - Reorganized `analyze_coverage.py` into a proper Python package: - Created `scripts/coverage/` package with modular components - Implemented dedicated modules for parser, runner, models, and reports - Added comprehensive HTML reporting with test failure display - Created clean package structure with well-defined interfaces - Added explicit package exports in `__init__.py` - Fixed issues with the --run-integration flag in test collection - Created a direct module entry point using `__main__.py` ### Testing Infrastructure Improvements - Created a more maintainable and modular approach to coverage analysis: - Separated concerns with dedicated modules for each responsibility - Implemented a cleaner object model for coverage data - Enhanced HTML reporting with interactive features - Added proper packaging for easier imports - Fixed redundant --run-integration flag in test collection - Implemented readable priority categorization for modules ### Comprehensive Test Improvement Plan - Created detailed test improvement strategy with: - Coverage analysis for all modules with priority categorization - Specific line-level targeting for high-priority modules - Test pattern standardization using dataclasses instead of mocks - Implementation templates for unit and integration tests - Tooling for test generation and coverage analysis - CI/CD integration for test coverage reporting - Clear timeline and completion criteria ### Integration Test Standardization - Fixed skipped repository integration tests by standardizing environment variable handling - Created robust `test_cleanup` fixture with proper resource tracking and cleanup - Added standardized `with_retry` mechanism for all GitHub API calls to handle rate limits - Developed consistent pattern for test fixtures (test_owner, test_repo_name, unique_id) - Created comprehensive documentation in `tests/integration/README.md` with best practices and examples ### Test Maintenance & Error Handling Improvements - Fixed repository tests to match operation function signatures - Updated config tests to use DEFAULT_CONFIG for dynamic validation - Enhanced schema validation in repository models with strict mode - Added field validators for all critical string fields (path, branch, etc.) - Documented maintainable test strategies in system_patterns.md - Updated GitHubError constructor pattern documentation in .clinerules - Fixed all test failures for a clean test suite ### Repository Tools Implementation - Implemented Repository Tools Group as part of ADR-006 - Created `operations/repositories.py` with comprehensive repository operations - Implemented `tools/repositories/` module following modular architecture - Added support for repository management, file operations, and branch operations - Created extensive unit tests using dataclasses instead of mocks (ADR-002) - Added safe integration tests for read operations - Enabled repository tools group by default in configuration ### Pagination Implementation - Created unified pagination in `converters/common/pagination.py` - Implemented safe handling of GitHub's PaginatedList objects - Added comprehensive unit and integration tests - Fixed naming conflicts and improved error handling - Made list operations consistently use the pagination utility ## Next Steps 1. Fix Coverage Analysis Tool Issues: - Investigate and fix the inaccurate coverage report (currently showing 28% instead of expected ~90%) - Review coverage configuration in pyproject.toml and the tool - Add debug output to identify where the issue is occurring - Ensure all modules are properly included in coverage calculation - Verify the coverage data parsing logic in parser.py 2. Execute Enhanced Test Improvement Plan: - Phase 1: Complete dataclass framework for PyGithub objects - Phase 2: Improve tools/repositories/tools.py coverage (63% → 80%+) - Phase 2: Enhance repositories.py operations coverage (77% → 90%+) - Phase 3: Standardize remaining integration tests with fixtures - Phase 3: Create test generation scripts for rapid test creation 3. Expand Modular Architecture: - Implement additional tool groups (pull_requests, users, etc.) - Create consistent patterns for new tool groups - Develop configuration templates for different scenarios - Enhance modularity with pluggable architecture 4. Performance Optimization: - Optimize tool loading based on configuration - Implement lazy loading for tool groups - Add caching strategies for frequently accessed data - Improve memory usage for large number of tools 5. Documentation: - Create detailed guide for adding new tool groups - Document configuration best practices - Add examples for common configuration scenarios - Create architectural diagrams for better understanding ## Design Decisions ### 1. Modular Coverage Analysis Architecture - Organize code into well-defined responsibilities (runner, parser, reporting) - Use dataclasses for structured coverage data representation - Implement a Python package structure for proper imports - Provide direct module execution capability through __main__.py - Remove external entry points in favor of module-based execution ### 2. Modular Architecture Approach - Use decorator-based registration for tools - Organize tools by domain (issues, repositories, etc.) - Support selective enabling/disabling of tool groups - Maintain backward compatibility during transition ### 3. Configuration System Design - Support both file-based and environment variable configuration - Establish clear precedence rules for configuration sources - Provide sensible defaults for all settings - Document all configuration options clearly ### 4. Testing Strategy - Follow ADR-002's real API testing approach - Test configuration components without mocks - Create integration tests for tool functionality - Ensure proper cleanup of test resources ### 5. Code Organization - Group related tools in dedicated modules - Keep tool implementations separate from registration - Maintain clear separation between configuration and execution - Establish consistent patterns across all modules ## Implementation Lessons ### Python Package Best Practices - Proper package structure improves import experience and usability - Direct module execution via __main__.py is cleaner than external scripts - Package exports in __init__.py make the API clear and discoverable - Separation of concerns with dedicated modules enhances maintainability - Good object model design simplifies data flow and transformation ### Coverage Analysis Challenges - Coverage calculation is sensitive to test execution approach - Existing .coverage data files can lead to inaccurate results - Direct coverage.py invocation may produce different results than pytest-cov - Coverage configuration in pyproject.toml needs careful alignment with analysis tools - Multiple coverage outputs (HTML, JSON, terminal) require careful configuration to avoid conflicts ### Datetime Handling and Testing Lessons - Function roles should be clearly differentiated and documented: - convert_iso_string_to_datetime: Parses ISO strings but doesn't enforce timezone awareness - ensure_utc_datetime: Handles timezone normalization and adding UTC timezone to naive datetimes - Tests should match actual function behavior rather than assumed behavior - Pydantic schema validation is the proper layer for enforcing data requirements (not utility functions) - Utility functions should be flexible to support various internal use cases - Test failures often indicate misunderstood function behavior rather than bugs ### Real API Testing (ADR-002) - Real API testing provides higher confidence than mocked tests - Test fixtures with proper cleanup prevent test pollution - Tests should focus on behaviors rather than implementation details - Dataclasses can replace mock objects for cleaner, type-safe tests - Context managers simplify test environment setup and teardown - Tests should respect class hierarchies and implementation details ### Modular Tool Architecture (ADR-006) - Decorator-based registration simplifies tool management - Dynamic import provides flexibility but requires careful error handling - Clear separation of concerns improves maintainability - Configuration-driven loading enables customization without code changes - Factory pattern in server.py centralizes server creation and configuration ### Pydantic-First Architecture (ADR-007) - Passing Pydantic models directly to operations improves type safety - Built-in Pydantic validation eliminates need for custom validation code - Validation happens automatically at model instantiation time - Reducing parameter unpacking/repacking improves maintainability - Clear ownership of validation in Pydantic models reduces duplication - No need for validation decorator since Pydantic handles it naturally ### PyGithub Integration Lessons - PyGithub's `get_issues()` doesn't directly accept per_page parameter - Need to handle pagination through PaginatedList objects instead - API behavior differs from documentation in some cases - Tests need to be resilient to real-world repository state