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

MCP Tools Development

These instructions apply to all MCP tool implementations in src/mcp_server/tools/.

Critical requirements

• All tools must validate inputs using mcp_server.utils.validators
• All tools must use async/await (never block the event loop)
• All tools must return structured dictionaries with success key
• All file paths must be validated (no path traversal)
• All tools must handle errors gracefully with custom exceptions

Tool structure pattern

from typing import Dict, Any
from mcp_server.utils.validators import validate_file_path, validate_slide_number
from mcp_server.exceptions import ValidationError, FileOperationError

async def handle_tool_name(arguments: Dict[str, Any]) -> Dict[str, Any]:
    """Handle MCP tool request for [specific operation].
    
    Args:
        arguments: Tool arguments from MCP client containing:
            - required_param: Description
            - optional_param: Description (optional)
        
    Returns:
        Dictionary with:
            - success (bool): Operation success status
            - data (Any): Tool result data
            - message (str): Optional status message
        
    Raises:
        ValidationError: If arguments are invalid
        FileOperationError: If file operation fails
    """
    try:
        # 1. Validate inputs
        pptx_path = arguments.get("pptx_path")
        validate_file_path(pptx_path)
        
        # 2. Get service from container
        service = get_service_from_container()
        
        # 3. Perform operation
        result = await service.operation(pptx_path)
        
        # 4. Return structured result
        return {
            "success": True,
            "data": result,
            "message": "Operation completed successfully"
        }
        
    except ValidationError as e:
        return {
            "success": False,
            "error": str(e),
            "error_type": "validation_error"
        }
    except Exception as e:
        # Log full exception details server-side for debugging
        logger.error(f"Unexpected error in tool", exc_info=True)
        return {
            "success": False,
            "error": "An unexpected internal error occurred. Please try again later.",
            "error_type": "internal_error"
        }