# 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:

```bash
# 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:

```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=VoluteMCP
# SERVER_HOST=127.0.0.1
# SERVER_PORT=8000
```

### 3. Run the Server

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

#### 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 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

```python
# 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

```json
{
  "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

```python
# 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](INSTALLATION_GUIDE.md)** - Multiple installation methods
- **[Cloud Integration](CLOUD_INTEGRATION.md)** - SDK usage for cloud deployments
- **[Developer Guide](DEVELOPER_GUIDE.md)** - Comprehensive integration examples
- **[Hybrid Architecture](HYBRID_ARCHITECTURE.md)** - Cloud + local setup
- **[Deployment Guide](DEPLOYMENT.md)** - 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
```python
# Using an MCP client library
result = client.call_tool("calculate", {"expression": "2 + 3 * 4"})
print(result)  # 14.0
```

#### Access a Resource
```python
# 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
```python
# Generate analysis prompt
prompt = client.get_prompt("analyze_data", {
    "data_description": "Sales data for Q1 2024",
    "analysis_type": "trends"
})
```

#### PowerPoint Analysis
```python
# 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

```bash
# 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
```python
# 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
```python
# In resources.py
@mcp.resource("custom://my-data")
def my_custom_resource() -> dict:
    """My custom resource description."""
    return {"data": "value"}
```

#### Add a Resource Template
```python
# 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:

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

## 🌐 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

```bash
# 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](https://pypi.org/project/volutemcp/)** - Official package
- **[FastMCP Documentation](https://github.com/jlowin/fastmcp)** - Framework docs
- **[Model Context Protocol](https://modelcontextprotocol.io)** - MCP standard
- **[MCP Specification](https://spec.modelcontextprotocol.io)** - Technical specs
- **[GitLab Issues](https://gitlab.com/coritan/volutemcp/-/issues)** - Bug reports & features
