# Volute-PPT Server

A FastMCP 2.0-based Model Context Protocol (MCP) server providing various tools, resources, and prompts for AI model interaction with **multimodal AI capabilities** including PowerPoint slide image capture.

## Features

- **Core Tools**: Mathematical calculations, text processing, JSON manipulation, hashing, encoding/decoding
- **PowerPoint Analysis**: Comprehensive metadata extraction, content analysis, file validation
- **PowerPoint Editing**: Smart text editing with bullet conversion, shape formatting, content management
- **Slide Management**: Add, delete, move, duplicate slides with DSL commands and bulk operations
- **Multimodal AI**: Slide image capture with base64-encoded PNG data URLs for vision-based AI analysis

## Quick Start

### 1. Local Development Setup

For local development and PowerPoint COM integration:

```bash
# Clone the project
git clone https://gitlab.com/coritan/volute-ppt.git
cd volute-ppt

# Create and activate virtual environment
python -m venv venv
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

### 2. Configure Environment

```bash
# Copy environment template
cp .env.example .env

# Edit .env with your settings
# SERVER_NAME=Volute-PPT
# SERVER_HOST=127.0.0.1
# SERVER_PORT=8001
```

### 3. Run the Server

#### HTTP Transport (Web Service)
```bash
python server.py
```
Server will be available at: http://127.0.0.1:8001

#### STDIO Transport (Local Tool)
```bash
python server.py stdio
```

## Server Components

### Tools

| Tool | Description | Tags |
|------|-------------|------|
| `echo` | Echo back messages for testing | utility, public |
| `calculate` | Safely evaluate math expressions | math, utility |
| `get_server_info` | Get server environment info | system, info |
| `format_text` | Format text (upper, lower, title, reverse) | utility, text |
| `process_json` | Process JSON (pretty, minify, keys, validate) | data, json |
| `get_timestamp` | Get timestamps in various formats | system, time |
| `list_operations` | Perform operations on string lists | data, list |
| `hash_text` | Generate text hashes (SHA256, SHA1, MD5) | security, hash |
| `encode_decode` | Encode/decode text (base64, URL, hex) | development, base64 |

### PowerPoint Tools

Advanced PowerPoint analysis, editing, and processing capabilities with **multimodal AI support**:

#### 📊 Core Analysis Tools
| Tool | Description | Key Features |
|------|-------------|-------------|
| `extract_powerpoint_metadata` | Extract comprehensive metadata from presentations | Complete technical metadata, shapes, formatting, layouts |
| `analyze_powerpoint_content` | Analyze content of specific slides | Text extraction, content focus, selective slide analysis |
| `get_powerpoint_summary` | Get high-level presentation overview | Quick stats, multimedia detection, slide summaries |
| `validate_powerpoint_file` | Validate file integrity and compatibility | Format validation, corruption detection, structure checks |

#### 🎯 Slide Management Tools
| Tool | Description | Key Features |
|------|-------------|-------------|
| `manage_presentation_slides` | Add, delete, move, duplicate slides using DSL | DSL commands, COM automation, batch operations |
| `bulk_slide_operations` | Execute multiple slide operations with validation | Transaction-like behavior, pre-validation, error handling |

#### 🖼️ Visual & Multimodal Tools
| Tool | Description | Key Features |
|------|-------------|-------------|
| `capture_slide_images` | Capture slides as base64 PNG images | Multimodal AI integration, configurable resolution, batch capture |
| `compare_presentation_versions` | Compare two presentation versions | Visual diffs, metadata changes, version control support |

#### ✏️ Content Editing Tools
| Tool | Description | Key Features |
|------|-------------|-------------|
| `edit_slide_text_content` | Edit text with intelligent bullet conversion | Smart bullet detection, multi-level indentation, format preservation |
| `apply_shape_formatting` | Apply comprehensive shape formatting | Font styling, positioning, colors, bulk operations |
| `manage_slide_shapes` | Add, delete, copy, transform shapes | Shape lifecycle, z-order, grouping, transformations |

#### 🎨 Advanced Tools
| Tool | Description | Key Features |
|------|-------------|-------------|
| `extract_presentation_templates` | Extract reusable design templates | Master slides, color schemes, layout patterns, design systems |
| `get_slide_capture_capabilities` | Report system capabilities | COM availability, system requirements, capability checks |

#### PowerPoint Features

**Analysis & Extraction:**
- **Comprehensive Metadata Extraction**: Core properties, slide dimensions, layout information
- **Shape Analysis**: Position, size, formatting, and content of all shapes
- **Text Content**: Fonts, colors, alignment, paragraph and run-level formatting
- **Multimedia Elements**: Images with crop information, tables with cell data
- **Formatting Details**: Fill, line, shadow formatting for all objects
- **Slide Structure**: Master slides, layouts, notes, and comments
- **Content Summarization**: Automatic extraction of slide titles and content
- **File Validation**: Format checking, corruption detection, structural integrity

**Editing & Content Management:**
- **🆕 Smart Text Processing**: Intelligent bullet detection and conversion to native PowerPoint bullets
- **🆕 Multi-level Bullet Support**: Proper indentation and nesting for complex bullet structures
- **🆕 Enhanced Newline Handling**: Converts `\n` to line breaks, `\\n` to literal text
- **🆕 Shape Editing**: Add, delete, copy, transform shapes with comprehensive property control
- **🆕 Text Formatting**: Font styling, colors, alignment, positioning with format preservation
- **🆕 Auto-resize**: Automatic shape resizing to accommodate new content

**Slide Management:**
- **🆕 Bulk Operations**: Execute multiple slide operations with transaction-like validation
- **🆕 Error Handling**: Pre-validation, rollback support, detailed operation tracking

**Multimodal & Visual:**
- **🆕 Multimodal AI Integration**: Slide image capture as base64 PNG data URLs for vision-capable LLMs
- **🆕 Visual Content Analysis**: Export slides as images for AI-powered visual understanding
- **🆕 Version Comparison**: Visual and metadata diffs between presentation versions

**Advanced Features:**
- **🆕 Template Extraction**: Extract reusable design systems, masters, and layouts
- **🆕 Theme Management**: Color schemes, font themes, and design pattern extraction

### Resources

#### Static Resources
- `config://server` - Server configuration
- `data://environment` - Environment information  
- `system://status` - System status
- `data://sample-users` - Sample user data
- `config://features` - Available features

#### Resource Templates
- `users://{user_id}` - Get user by ID
- `config://{section}` - Get config section
- `data://{data_type}/summary` - Get data summaries
- `logs://{log_level}` - Get simulated logs
- `file://{file_path}` - Read file contents (with safety checks)



## Integration Approaches

### **Local MCP Integration (Desktop Apps)**

**Best for**: Claude Desktop, local AI applications, PowerPoint integration, multimodal AI workflows

```json
{
  "volute-ppt": {
    "command": "python",
    "args": [
      "-m",
      "volute_ppt.server_local",
      "stdio"
    ],
    "env": {},
    "working_directory": null
  }
}
```

## SDK Toolkit

The package provides a high-level toolkit that lets you directly use PowerPoint tools without dealing with MCP server setup:

```python
from volute_ppt import (
    # Core Analysis
    extract_powerpoint_metadata, analyze_powerpoint_content,
    # Multimodal & Visual
    capture_slide_images, compare_presentation_versions,
    # Content Editing
    edit_slide_text_content, manage_slide_shapes
)

# Extract metadata from a presentation
metadata = extract_powerpoint_metadata(
    presentation_path="./presentation.pptx",
    include_slide_content=True
)

# Capture slides as images for AI analysis
images = capture_slide_images(
    presentation_path="./presentation.pptx",
    slide_numbers=[1, 2, 3],  # Specific slides or omit for all
    image_width=1024,         # Optional: control image size
    image_height=768
)

# Edit slide text with intelligent bullet conversion
edit_result = edit_slide_text_content(
    presentation_path="./presentation.pptx",
    slide_number=2,
    text_updates={
        "Title 1": "New Title",
        "Content 1": "• First bullet\n• Second bullet\n  - Sub-bullet"
    },
    convert_bullets=True,  # Converts text bullets to native PowerPoint bullets
    preserve_formatting=True
)
```

### LangChain & LangGraph Integration

The toolkit functions can be easily wrapped in LangChain tools or LangGraph nodes:

```python
from langchain.tools import StructuredTool
from volute_ppt import extract_powerpoint_metadata, capture_slide_images

# Create LangChain tool for metadata extraction
metadata_tool = StructuredTool.from_function(
    func=extract_powerpoint_metadata,
    name="extract_powerpoint_metadata",
    description="Extract comprehensive metadata from PowerPoint files"
)

# Create LangChain tool for slide capture
slide_capture_tool = StructuredTool.from_function(
    func=capture_slide_images,
    name="capture_powerpoint_slides",
    description="Capture PowerPoint slides as images for multimodal AI analysis"
)

# Use in an agent
agent = Agent(
    llm=llm,
    tools=[metadata_tool, slide_capture_tool],
    # ... other agent configuration
)

# Use in LangGraph nodes
class PowerPointAnalysisNode:
    def run(self, presentation_path: str):
        # Extract metadata
        metadata = extract_powerpoint_metadata(presentation_path)
        
        # Capture first 3 slides
        images = capture_slide_images(
            presentation_path=presentation_path,
            slide_numbers=[1, 2, 3]
        )
        
        return {"metadata": metadata, "images": images}
```

### Configuration

The server uses Pydantic for configuration management. Settings can be provided via:

1. Environment variables (prefixed with `VOLUTE_`)
2. `.env` file
3. Default values in `config.py`

#### Available Settings

| Setting | Default | Description |
|---------|---------|-------------|
| `VOLUTE_NAME` | VoluteMCP | Server name |
| `VOLUTE_HOST` | 127.0.0.1 | Server host |
| `VOLUTE_PORT` | 8000 | Server port |
| `VOLUTE_LOG_LEVEL` | INFO | Logging level |

### Tag-Based Filtering

Filter components by tags when creating the server:

```python
# Only expose utility tools
mcp = FastMCP(include_tags={"utility"})

# Hide internal tools
mcp = FastMCP(exclude_tags={"internal"})

# Combine filters
mcp = FastMCP(include_tags={"public"}, exclude_tags={"deprecated"})
```

## Advanced Usage

### Server Composition

```python
from fastmcp import FastMCP
from tools import register_tools

# Create modular servers
tools_server = FastMCP("ToolsOnly")
register_tools(tools_server)

# Mount into main server
main_server = FastMCP("Main")
main_server.mount(tools_server, prefix="tools")
```

### Custom Serialization

```python
import yaml

def yaml_serializer(data):
    return yaml.dump(data, sort_keys=False)

mcp = FastMCP(tool_serializer=yaml_serializer)
```

## Deployment

### Docker

```dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

EXPOSE 8000
CMD ["python", "server.py"]
```

### systemd Service

```ini
[Unit]
Description=VoluteMCP Server
After=network.target

[Service]
Type=simple
User=volute
WorkingDirectory=/opt/volutemcp
ExecStart=/opt/volutemcp/venv/bin/python server.py
Restart=always

[Install]
WantedBy=multi-user.target
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add your changes with tests
4. Submit a pull request

## License

MIT License - see LICENSE file for details.