mcpcn-office-powerpoint-mcp-server 2.0.7__py3-none-any.whl

tools/hyperlink_tools.py

@@ -0,0 +1,138 @@
+"""
+Hyperlink management tools for PowerPoint MCP Server.
+Implements hyperlink operations for text shapes and runs.
+"""
+
+from typing import Dict, List, Optional, Any
+
+def register_hyperlink_tools(app, presentations, get_current_presentation_id, validate_parameters, 
+                          is_positive, is_non_negative, is_in_range, is_valid_rgb):
+    """Register hyperlink management tools with the FastMCP app."""
+    
+    @app.tool()
+    def manage_hyperlinks(
+        operation: str,
+        slide_index: int,
+        shape_index: int = None,
+        text: str = None, 
+        url: str = None,
+        run_index: int = 0,
+        presentation_id: str = None
+    ) -> Dict:
+        """
+        Manage hyperlinks in text shapes and runs.
+        
+        Args:
+            operation: Operation type ("add", "remove", "list", "update")
+            slide_index: Index of the slide (0-based)
+            shape_index: Index of the shape on the slide (0-based)
+            text: Text to make into hyperlink (for "add" operation)
+            url: URL for the hyperlink
+            run_index: Index of text run within the shape (0-based)
+            presentation_id: Optional presentation ID (uses current if not provided)
+            
+        Returns:
+            Dictionary with operation results
+        """
+        try:
+            # Get presentation
+            pres_id = presentation_id or get_current_presentation_id()
+            if pres_id not in presentations:
+                return {"error": "Presentation not found"}
+            
+            pres = presentations[pres_id]
+            
+            # Validate slide index
+            if not (0 <= slide_index < len(pres.slides)):
+                return {"error": f"Slide index {slide_index} out of range"}
+            
+            slide = pres.slides[slide_index]
+            
+            if operation == "list":
+                # List all hyperlinks in the slide
+                hyperlinks = []
+                for shape_idx, shape in enumerate(slide.shapes):
+                    if hasattr(shape, 'text_frame') and shape.text_frame:
+                        for para_idx, paragraph in enumerate(shape.text_frame.paragraphs):
+                            for run_idx, run in enumerate(paragraph.runs):
+                                if run.hyperlink.address:
+                                    hyperlinks.append({
+                                        "shape_index": shape_idx,
+                                        "paragraph_index": para_idx,
+                                        "run_index": run_idx,
+                                        "text": run.text,
+                                        "url": run.hyperlink.address
+                                    })
+                
+                return {
+                    "message": f"Found {len(hyperlinks)} hyperlinks on slide {slide_index}",
+                    "hyperlinks": hyperlinks
+                }
+            
+            # For other operations, validate shape index
+            if shape_index is None or not (0 <= shape_index < len(slide.shapes)):
+                return {"error": f"Shape index {shape_index} out of range"}
+            
+            shape = slide.shapes[shape_index]
+            
+            # Check if shape has text
+            if not hasattr(shape, 'text_frame') or not shape.text_frame:
+                return {"error": "Shape does not contain text"}
+            
+            if operation == "add":
+                if not text or not url:
+                    return {"error": "Both 'text' and 'url' are required for adding hyperlinks"}
+                
+                # Add new text run with hyperlink
+                paragraph = shape.text_frame.paragraphs[0]
+                run = paragraph.add_run()
+                run.text = text
+                run.hyperlink.address = url
+                
+                return {
+                    "message": f"Added hyperlink '{text}' -> '{url}' to shape {shape_index}",
+                    "text": text,
+                    "url": url
+                }
+            
+            elif operation == "update":
+                if not url:
+                    return {"error": "URL is required for updating hyperlinks"}
+                
+                # Update existing hyperlink
+                paragraphs = shape.text_frame.paragraphs
+                if run_index < len(paragraphs[0].runs):
+                    run = paragraphs[0].runs[run_index]
+                    old_url = run.hyperlink.address
+                    run.hyperlink.address = url
+                    
+                    return {
+                        "message": f"Updated hyperlink from '{old_url}' to '{url}'",
+                        "old_url": old_url,
+                        "new_url": url,
+                        "text": run.text
+                    }
+                else:
+                    return {"error": f"Run index {run_index} out of range"}
+            
+            elif operation == "remove":
+                # Remove hyperlink from specific run
+                paragraphs = shape.text_frame.paragraphs
+                if run_index < len(paragraphs[0].runs):
+                    run = paragraphs[0].runs[run_index]
+                    old_url = run.hyperlink.address
+                    run.hyperlink.address = None
+                    
+                    return {
+                        "message": f"Removed hyperlink '{old_url}' from text '{run.text}'",
+                        "removed_url": old_url,
+                        "text": run.text
+                    }
+                else:
+                    return {"error": f"Run index {run_index} out of range"}
+            
+            else:
+                return {"error": f"Unsupported operation: {operation}. Use 'add', 'remove', 'list', or 'update'"}
+                
+        except Exception as e:
+            return {"error": f"Failed to manage hyperlinks: {str(e)}"}

tools/master_tools.py

@@ -0,0 +1,114 @@
+"""
+Slide master management tools for PowerPoint MCP Server.
+Implements slide master and layout access capabilities.
+"""
+
+from typing import Dict, List, Optional, Any
+
+def register_master_tools(app, presentations, get_current_presentation_id, validate_parameters, 
+                          is_positive, is_non_negative, is_in_range, is_valid_rgb):
+    """Register slide master management tools with the FastMCP app."""
+    
+    @app.tool()
+    def manage_slide_masters(
+        operation: str,
+        master_index: int = 0,
+        layout_index: int = None,
+        presentation_id: str = None
+    ) -> Dict:
+        """
+        Access and manage slide master properties and layouts.
+        
+        Args:
+            operation: Operation type ("list", "get_layouts", "get_info")
+            master_index: Index of the slide master (0-based)
+            layout_index: Index of specific layout within master (0-based)
+            presentation_id: Optional presentation ID (uses current if not provided)
+            
+        Returns:
+            Dictionary with slide master information
+        """
+        try:
+            # Get presentation
+            pres_id = presentation_id or get_current_presentation_id()
+            if pres_id not in presentations:
+                return {"error": "Presentation not found"}
+            
+            pres = presentations[pres_id]
+            
+            if operation == "list":
+                # List all slide masters
+                masters_info = []
+                for idx, master in enumerate(pres.slide_masters):
+                    masters_info.append({
+                        "index": idx,
+                        "layout_count": len(master.slide_layouts),
+                        "name": getattr(master, 'name', f"Master {idx}")
+                    })
+                
+                return {
+                    "message": f"Found {len(masters_info)} slide masters",
+                    "masters": masters_info,
+                    "total_masters": len(pres.slide_masters)
+                }
+            
+            # Validate master index
+            if not (0 <= master_index < len(pres.slide_masters)):
+                return {"error": f"Master index {master_index} out of range"}
+            
+            master = pres.slide_masters[master_index]
+            
+            if operation == "get_layouts":
+                # Get all layouts for a specific master
+                layouts_info = []
+                for idx, layout in enumerate(master.slide_layouts):
+                    layouts_info.append({
+                        "index": idx,
+                        "name": layout.name,
+                        "placeholder_count": len(layout.placeholders) if hasattr(layout, 'placeholders') else 0
+                    })
+                
+                return {
+                    "message": f"Master {master_index} has {len(layouts_info)} layouts",
+                    "master_index": master_index,
+                    "layouts": layouts_info
+                }
+            
+            elif operation == "get_info":
+                # Get detailed info about master or specific layout
+                if layout_index is not None:
+                    if not (0 <= layout_index < len(master.slide_layouts)):
+                        return {"error": f"Layout index {layout_index} out of range"}
+                    
+                    layout = master.slide_layouts[layout_index]
+                    placeholders_info = []
+                    
+                    if hasattr(layout, 'placeholders'):
+                        for placeholder in layout.placeholders:
+                            placeholders_info.append({
+                                "idx": placeholder.placeholder_format.idx,
+                                "type": str(placeholder.placeholder_format.type),
+                                "name": getattr(placeholder, 'name', 'Unnamed')
+                            })
+                    
+                    return {
+                        "message": f"Layout info for master {master_index}, layout {layout_index}",
+                        "master_index": master_index,
+                        "layout_index": layout_index,
+                        "layout_name": layout.name,
+                        "placeholders": placeholders_info
+                    }
+                else:
+                    # Master info
+                    return {
+                        "message": f"Master {master_index} information",
+                        "master_index": master_index,
+                        "layout_count": len(master.slide_layouts),
+                        "name": getattr(master, 'name', f"Master {master_index}")
+                    }
+            
+            else:
+                return {"error": f"Unsupported operation: {operation}. Use 'list', 'get_layouts', or 'get_info'"}
+                
+        except Exception as e:
+            return {"error": f"Failed to manage slide masters: {str(e)}"}

tools/presentation_tools.py

@@ -0,0 +1,212 @@
+"""
+Presentation management tools for PowerPoint MCP Server.
+Handles presentation creation, opening, saving, and core properties.
+"""
+from typing import Dict, List, Optional, Any
+import os
+from mcp.server.fastmcp import FastMCP
+import utils as ppt_utils
+
+
+def register_presentation_tools(app: FastMCP, presentations: Dict, get_current_presentation_id, get_template_search_directories):
+    """Register presentation management tools with the FastMCP app"""
+    
+    @app.tool()
+    def create_presentation(id: Optional[str] = None) -> Dict:
+        """Create a new PowerPoint presentation."""
+        # Create a new presentation
+        pres = ppt_utils.create_presentation()
+        
+        # Generate an ID if not provided
+        if id is None:
+            id = f"presentation_{len(presentations) + 1}"
+        
+        # Store the presentation
+        presentations[id] = pres
+        # Set as current presentation (this would need to be handled by caller)
+        
+        return {
+            "presentation_id": id,
+            "message": f"Created new presentation with ID: {id}",
+            "slide_count": len(pres.slides)
+        }
+
+    @app.tool()
+    def create_presentation_from_template(template_path: str, id: Optional[str] = None) -> Dict:
+        """Create a new PowerPoint presentation from a template file."""
+        # Check if template file exists
+        if not os.path.exists(template_path):
+            # Try to find the template by searching in configured directories
+            search_dirs = get_template_search_directories()
+            template_name = os.path.basename(template_path)
+            
+            for directory in search_dirs:
+                potential_path = os.path.join(directory, template_name)
+                if os.path.exists(potential_path):
+                    template_path = potential_path
+                    break
+            else:
+                env_path_info = f" (PPT_TEMPLATE_PATH: {os.environ.get('PPT_TEMPLATE_PATH', 'not set')})" if os.environ.get('PPT_TEMPLATE_PATH') else ""
+                return {
+                    "error": f"Template file not found: {template_path}. Searched in {', '.join(search_dirs)}{env_path_info}"
+                }
+        
+        # Create presentation from template
+        try:
+            pres = ppt_utils.create_presentation_from_template(template_path)
+        except Exception as e:
+            return {
+                "error": f"Failed to create presentation from template: {str(e)}"
+            }
+        
+        # Generate an ID if not provided
+        if id is None:
+            id = f"presentation_{len(presentations) + 1}"
+        
+        # Store the presentation
+        presentations[id] = pres
+        
+        return {
+            "presentation_id": id,
+            "message": f"Created new presentation from template '{template_path}' with ID: {id}",
+            "template_path": template_path,
+            "slide_count": len(pres.slides),
+            "layout_count": len(pres.slide_layouts)
+        }
+
+    @app.tool()
+    def open_presentation(file_path: str, id: Optional[str] = None) -> Dict:
+        """Open an existing PowerPoint presentation from a file."""
+        # Check if file exists
+        if not os.path.exists(file_path):
+            return {
+                "error": f"File not found: {file_path}"
+            }
+        
+        # Open the presentation
+        try:
+            pres = ppt_utils.open_presentation(file_path)
+        except Exception as e:
+            return {
+                "error": f"Failed to open presentation: {str(e)}"
+            }
+        
+        # Generate an ID if not provided
+        if id is None:
+            id = f"presentation_{len(presentations) + 1}"
+        
+        # Store the presentation
+        presentations[id] = pres
+        
+        return {
+            "presentation_id": id,
+            "message": f"Opened presentation from {file_path} with ID: {id}",
+            "slide_count": len(pres.slides)
+        }
+
+    @app.tool()
+    def save_presentation(file_path: str, presentation_id: Optional[str] = None) -> Dict:
+        """Save a presentation to a file."""
+        # Use the specified presentation or the current one
+        pres_id = presentation_id if presentation_id is not None else get_current_presentation_id()
+        
+        if pres_id is None or pres_id not in presentations:
+            return {
+                "error": "No presentation is currently loaded or the specified ID is invalid"
+            }
+        
+        # Save the presentation
+        try:
+            saved_path = ppt_utils.save_presentation(presentations[pres_id], file_path)
+            return {
+                "message": f"Presentation saved to {saved_path}",
+                "file_path": saved_path
+            }
+        except Exception as e:
+            return {
+                "error": f"Failed to save presentation: {str(e)}"
+            }
+
+    @app.tool()
+    def get_presentation_info(presentation_id: Optional[str] = None) -> Dict:
+        """Get information about a presentation."""
+        pres_id = presentation_id if presentation_id is not None else get_current_presentation_id()
+        
+        if pres_id is None or pres_id not in presentations:
+            return {
+                "error": "No presentation is currently loaded or the specified ID is invalid"
+            }
+        
+        pres = presentations[pres_id]
+        
+        try:
+            info = ppt_utils.get_presentation_info(pres)
+            info["presentation_id"] = pres_id
+            return info
+        except Exception as e:
+            return {
+                "error": f"Failed to get presentation info: {str(e)}"
+            }
+
+    @app.tool()
+    def get_template_file_info(template_path: str) -> Dict:
+        """Get information about a template file including layouts and properties."""
+        # Check if template file exists
+        if not os.path.exists(template_path):
+            # Try to find the template by searching in configured directories
+            search_dirs = get_template_search_directories()
+            template_name = os.path.basename(template_path)
+            
+            for directory in search_dirs:
+                potential_path = os.path.join(directory, template_name)
+                if os.path.exists(potential_path):
+                    template_path = potential_path
+                    break
+            else:
+                return {
+                    "error": f"Template file not found: {template_path}. Searched in {', '.join(search_dirs)}"
+                }
+        
+        try:
+            return ppt_utils.get_template_info(template_path)
+        except Exception as e:
+            return {
+                "error": f"Failed to get template info: {str(e)}"
+            }
+
+    @app.tool()
+    def set_core_properties(
+        title: Optional[str] = None,
+        subject: Optional[str] = None,
+        author: Optional[str] = None,
+        keywords: Optional[str] = None,
+        comments: Optional[str] = None,
+        presentation_id: Optional[str] = None
+    ) -> Dict:
+        """Set core document properties."""
+        pres_id = presentation_id if presentation_id is not None else get_current_presentation_id()
+        
+        if pres_id is None or pres_id not in presentations:
+            return {
+                "error": "No presentation is currently loaded or the specified ID is invalid"
+            }
+        
+        pres = presentations[pres_id]
+        
+        try:
+            ppt_utils.set_core_properties(
+                pres,
+                title=title,
+                subject=subject,
+                author=author,
+                keywords=keywords,
+                comments=comments
+            )
+            
+            return {
+                "message": "Core properties updated successfully"
+            }
+        except Exception as e:
+            return {
+                "error": f"Failed to set core properties: {str(e)}"
+            }