powerpoint-python-pptx-mcp core.instructions.md

Core Services Development

These instructions apply to core service implementations in src/mcp_server/core/.

Core services overview

Core services provide the fundamental PPTX manipulation capabilities. They must be:

• Reliable: No data loss, no corruption
• Safe: Validate all inputs, handle all errors
• Efficient: Use caching, lazy loading
• Maintainable: Clear abstractions, well-tested

Critical requirements

• Never modify PPTX structure accidentally - Preserve animations, transitions, layouts
• Always validate file integrity - Check PPTX is valid before and after operations
• Use context managers - Properly close file handles
• Handle encoding carefully - Support Unicode (especially Vietnamese characters)
• Log all operations - Structured logging with context

PPTX Handler pattern

from typing import Optional, List, Dict, Any
from pptx import Presentation
from pathlib import Path
import logging

logger = logging.getLogger(__name__)

class PPTXHandler:
    """Handle PPTX file operations safely and efficiently."""
    
    def __init__(self, cache_size: int = 100):
        """Initialize handler with optional caching.
        
        Args:
            cache_size: Maximum number of presentations to cache
        """
        self._cache = LRUCache(cache_size)
        
    async def read_presentation(
        self,
        pptx_path: str,
        use_cache: bool = True
    ) -> Presentation:
        """Read presentation from file with optional caching.
        
        Args:
            pptx_path: Path to PPTX file
            use_cache: Whether to use cache
            
        Returns:
            Presentation object
            
        Raises:
            FileOperationError: If file cannot be read
        """
        try:
            # Check cache first
            if use_cache and pptx_path in self._cache:
                logger.debug(f"Cache hit for {pptx_path}")
                return self._cache[pptx_path]
            
            # Validate file exists and is readable
            path = Path(pptx_path)
            if not path.exists():
                raise FileOperationError(f"File not found: {pptx_path}")
            
            # Load presentation
            logger.info(f"Loading presentation: {pptx_path}")
            prs = Presentation(pptx_path)
            
            # Cache if requested
            if use_cache:
                self._cache[pptx_path] = prs
                
            return prs
            
        except Exception as e:
            logger.error(f"Failed to read presentation: {e}", exc_info=True)
            raise FileOperationError(f"Cannot read PPTX: {e}")