volute-ppt 1.3.2

MCP server for PowerPoint analysis and multimodal AI integration - comprehensive metadata extraction and slide image capture for agents

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

• 🔧 Tools: Mathematical calculations, text processing, JSON manipulation, hashing, encoding/decoding
• 📊 PowerPoint Tools: Comprehensive PowerPoint analysis, metadata extraction, and content processing
• 🖼️ Multimodal AI: Slide image capture with base64-encoded PNG data URLs for vision-based AI analysis
• 📁 Resources: System status, user data, configuration sections, simulated logs
• 📝 Prompts: Data analysis prompts, code review templates
• 🌐 HTTP Endpoints: Health checks and server information
• 🏷️ Tag-based Filtering: Organize components with flexible tag system
• ⚙️ Configuration: Environment-based configuration with Pydantic models

🚀 Quick Start

Option 1: Cloud Integration (Recommended for Most Developers)

Perfect for cloud-deployed AI agents, serverless functions, and web applications:

# Install from PyPI
pip install volute-ppt

# Use in your cloud AI agent
from volute_ppt.sdk import VoluteMCPCloudClient

volute = VoluteMCPCloudClient()
result = await volute.calculate("2 + 3 * 4")
print(result)  # 14.0

Option 2: Local Development Setup

For local development and PowerPoint COM integration:

# 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

# Copy environment template
cp .env.example .env

# Edit .env with your settings
# SERVER_NAME=VoluteMCP
# SERVER_HOST=127.0.0.1
# SERVER_PORT=8000

3. Run the Server

HTTP Transport (Web Service)

python server.py

Server will be available at: http://127.0.0.1:8000

STDIO Transport (Local Tool)

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 and processing capabilities with multimodal AI support: || Tool | Description | |------|-------------| | extract_powerpoint_metadata | Extract comprehensive metadata from PowerPoint presentations | | analyze_powerpoint_content | Analyze content of specific slides or entire presentations | | get_powerpoint_summary | Get high-level summary of a PowerPoint presentation | | validate_powerpoint_file | Validate PowerPoint files and check for common issues | | manage_presentation_slides | NEW: Add, delete, move, and duplicate slides using DSL commands | | capture_powerpoint_slides | NEW: Capture slide images as base64 PNG data URLs for multimodal AI analysis |

PowerPoint Features

• 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
• 🆕 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

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)

Prompts

• analyze_data - Generate data analysis prompts
• code_review_prompt - Generate code review prompts

Custom HTTP Routes

• GET /health - Health check endpoint
• GET /info - Server information

🔧 Integration Approaches

VoluteMCP offers flexible integration options for different use cases:

🌐 Cloud Integration (Serverless/Web Apps)

Best for: AWS Lambda, Vercel, Netlify, cloud-deployed AI agents

# Ultra-simple SDK integration
from volute_ppt.sdk import VoluteMCPCloudClient

class MyAIAgent:
    def __init__(self):
        self.volute = VoluteMCPCloudClient()
    
    async def process_calculation(self, expression):
        return await self.volute.calculate(expression)

# Works in FastAPI, Flask, Express.js, Next.js, etc.

🖥️ Local MCP Integration (Desktop Apps)

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

{
  "volutemcp-local": {
    "command": "python",
    "args": ["-m", "volute_ppt.server_local", "stdio"],
    "env": {},
    "working_directory": "/path/to/volutemcp"
  }
}

🔄 Hybrid Architecture (Best of Both)

Best for: Comprehensive AI systems needing both cloud and local capabilities, multimodal AI workflows

# Use both cloud and local servers
from volute_ppt.sdk import VoluteMCPCloudClient

class HybridAIAgent:
    def __init__(self):
        self.cloud = VoluteMCPCloudClient()  # For general tools
        # Local MCP for PowerPoint (via separate config)
    
    async def process_request(self, user_input):
        # Use cloud for calculations
        if "calculate" in user_input:
            return await self.cloud.calculate("2 + 3")
        # Use local for PowerPoint (via MCP client)
        # ...

📚 Documentation

• Installation Guide - Multiple installation methods
• Cloud Integration - SDK usage for cloud deployments
• Developer Guide - Comprehensive integration examples
• Hybrid Architecture - Cloud + local setup
• Deployment Guide - Production deployment options

Usage Examples

Using with MCP Clients

The server can be used with any MCP-compatible client. Here are some examples:

Call a Tool

# Using an MCP client library
result = client.call_tool("calculate", {"expression": "2 + 3 * 4"})
print(result)  # 14.0

Access a Resource

# Get server config
config = client.read_resource("config://server")
print(config)

# Get specific user
user = client.read_resource("users://1")
print(user)

Use a Prompt

# Generate analysis prompt
prompt = client.get_prompt("analyze_data", {
    "data_description": "Sales data for Q1 2024",
    "analysis_type": "trends"
})

PowerPoint Analysis

# Extract comprehensive metadata from a presentation
result = client.call_tool("extract_powerpoint_metadata", {
    "presentation_path": "./presentation.pptx",
    "include_slide_content": True,
    "output_format": "json"
})

# Get a quick summary of the presentation
summary = client.call_tool("get_powerpoint_summary", {
    "presentation_path": "./presentation.pptx"
})

# Analyze specific slides only
content = client.call_tool("analyze_powerpoint_content", {
    "presentation_path": "./presentation.pptx",
    "slide_numbers": [1, 3, 5],
    "extract_text_only": True
})

# Validate a PowerPoint file
validation = client.call_tool("validate_powerpoint_file", {
    "presentation_path": "./presentation.pptx"
})

# 🆕 Capture slide images for multimodal AI analysis
slide_images = client.call_tool("capture_powerpoint_slides", {
    "presentation_path": "./presentation.pptx",
    "slide_numbers": [1, 3, 5],  # Specific slides or omit for all
    "max_slides": 10,           # Safety limit
    "image_width": 1024,        # Optional: control image size
    "image_height": 768
})
# Returns base64 PNG data URLs perfect for vision-capable AI models

# 🆕 Manage presentation slides with DSL commands
manage_result = client.call_tool("manage_presentation_slides", {
    "presentation_path": "./presentation.pptx",
    "dsl_operations": "add_slide: position=1, layout=\"Title Slide\" | move_slide: from=3, to=5 | duplicate_slide: source=2, position=end"
})
# Supports: add_slide, delete_slide, move_slide, duplicate_slide with pipe-separated operations

Testing

The project includes a comprehensive test suite to validate all functionality:

Running Tests

# Run all tests using the test runner
python run_tests.py

# Or run tests directly
python tests/test_powerpoint_tools.py

# Using pytest (if installed)
pytest tests/

Test Coverage

The test suite validates:

• ✅ All module imports work correctly
• ✅ Pydantic data models function properly
• ✅ PowerPoint tools register and integrate correctly
• ✅ Server startup and configuration
• ✅ Error handling for edge cases
• ✅ FastMCP 2.0 async/await patterns

Test Results

• 5 PowerPoint tools properly registered (including multimodal slide capture)
• 12 total tools available (including core tools)
• 3 resources configured
• 100% test pass rate

Development

Project Structure

volutemcp/
├── server.py                    # Main server entry point
├── server_modular.py           # Modular server implementation
├── config.py                   # Configuration management
├── tools.py                    # Core tool implementations
├── resources.py                # Resource implementations
├── powerpoint_metadata.py      # PowerPoint metadata extraction
├── powerpoint_tools.py         # PowerPoint tool implementations
├── powerpoint_image_capture.py # 🆕 Multimodal slide image capture
├── tests/                      # Test directory
│   ├── __init__.py            # Test package initialization
│   ├── test_powerpoint_tools.py # PowerPoint tools test suite
│   └── README.md              # Test documentation
├── run_tests.py               # Test runner script
├── pytest.ini                # Pytest configuration
├── requirements.txt           # Python dependencies
├── .env.example              # Environment template
├── .gitignore               # Git ignore rules
└── README.md                # This file

Adding New Components

Add a Tool

# In tools.py
@mcp.tool(tags={"custom", "utility"})
def my_custom_tool(input_data: str) -> str:
    """My custom tool description."""
    return f"Processed: {input_data}"

Add a Resource

# In resources.py
@mcp.resource("custom://my-data")
def my_custom_resource() -> dict:
    """My custom resource description."""
    return {"data": "value"}

Add a Resource Template

# In resources.py
@mcp.resource("items://{item_id}")
def get_item(item_id: int) -> dict:
    """Get item by ID."""
    return {"id": item_id, "name": f"Item {item_id}"}

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
VOLUTE_API_KEY	None	Optional API key

Tag-Based Filtering

Filter components by tags when creating the server:

# 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

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

import yaml

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

mcp = FastMCP(tool_serializer=yaml_serializer)

Deployment

Docker

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

[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.

🌐 Live Deployments

• Cloud Server: https://volutemcp-server.onrender.com
• PyPI Package: https://pypi.org/project/volutemcp/
• GitLab Repository: https://gitlab.com/coritan/volutemcp
• Health Check: https://volutemcp-server.onrender.com/health

📦 Package Information

# Installation
pip install volutemcp

# CLI Commands
volutemcp-local --help          # Local PowerPoint server
volutemcp-server --help         # Cloud server

# Python Module
python -m volute_ppt.server_local stdio

Resources

• VoluteMCP on PyPI - Official package
• FastMCP Documentation - Framework docs
• Model Context Protocol - MCP standard
• MCP Specification - Technical specs
• GitLab Issues - Bug reports & features