# VoluteMCP 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 volutemcp
# Use in your cloud AI agent
from volutemcp.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/volutemcp.git
cd volutemcp
# 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 |
| `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 volutemcp.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", "volutemcp.server_local", "--transport", "stdio"],
"env": {}
}
}
```
### **🔄 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 volutemcp.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
```
## 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 volutemcp.server_local --transport 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
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/coritan/volutemcp",
"name": "volutemcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mcp, powerpoint, ai, agents, desktop, automation, com, multimodal, vision, slides, image-capture",
"author": "Coritan",
"author_email": "Coritan <your-email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/3b/28/061608486102cf2da02661bc606bf1aea304a9ea05538aeed7250501a0e5/volutemcp-1.1.1.tar.gz",
"platform": null,
"description": "# VoluteMCP Server\r\n\r\nA 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.\r\n\r\n## Features\r\n\r\n- \ud83d\udd27 **Tools**: Mathematical calculations, text processing, JSON manipulation, hashing, encoding/decoding\r\n- \ud83d\udcca **PowerPoint Tools**: Comprehensive PowerPoint analysis, metadata extraction, and content processing\r\n- \ud83d\uddbc\ufe0f **Multimodal AI**: Slide image capture with base64-encoded PNG data URLs for vision-based AI analysis\r\n- \ud83d\udcc1 **Resources**: System status, user data, configuration sections, simulated logs\r\n- \ud83d\udcdd **Prompts**: Data analysis prompts, code review templates\r\n- \ud83c\udf10 **HTTP Endpoints**: Health checks and server information\r\n- \ud83c\udff7\ufe0f **Tag-based Filtering**: Organize components with flexible tag system\r\n- \u2699\ufe0f **Configuration**: Environment-based configuration with Pydantic models\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n### **Option 1: Cloud Integration (Recommended for Most Developers)**\r\n\r\nPerfect for cloud-deployed AI agents, serverless functions, and web applications:\r\n\r\n```bash\r\n# Install from PyPI\r\npip install volutemcp\r\n\r\n# Use in your cloud AI agent\r\nfrom volutemcp.sdk import VoluteMCPCloudClient\r\n\r\nvolute = VoluteMCPCloudClient()\r\nresult = await volute.calculate(\"2 + 3 * 4\")\r\nprint(result) # 14.0\r\n```\r\n\r\n### **Option 2: Local Development Setup**\r\n\r\nFor local development and PowerPoint COM integration:\r\n\r\n```bash\r\n# Clone the project\r\ngit clone https://gitlab.com/coritan/volutemcp.git\r\ncd volutemcp\r\n\r\n# Create and activate virtual environment\r\npython -m venv venv\r\n# On Windows:\r\nvenv\\Scripts\\activate\r\n# On macOS/Linux:\r\nsource venv/bin/activate\r\n\r\n# Install dependencies\r\npip install -r requirements.txt\r\n```\r\n\r\n### 2. Configure Environment\r\n\r\n```bash\r\n# Copy environment template\r\ncp .env.example .env\r\n\r\n# Edit .env with your settings\r\n# SERVER_NAME=VoluteMCP\r\n# SERVER_HOST=127.0.0.1\r\n# SERVER_PORT=8000\r\n```\r\n\r\n### 3. Run the Server\r\n\r\n#### HTTP Transport (Web Service)\r\n```bash\r\npython server.py\r\n```\r\nServer will be available at: http://127.0.0.1:8000\r\n\r\n#### STDIO Transport (Local Tool)\r\n```bash\r\npython server.py stdio\r\n```\r\n\r\n## Server Components\r\n\r\n### Tools\r\n\r\n| Tool | Description | Tags |\r\n|------|-------------|------|\r\n| `echo` | Echo back messages for testing | utility, public |\r\n| `calculate` | Safely evaluate math expressions | math, utility |\r\n| `get_server_info` | Get server environment info | system, info |\r\n| `format_text` | Format text (upper, lower, title, reverse) | utility, text |\r\n| `process_json` | Process JSON (pretty, minify, keys, validate) | data, json |\r\n| `get_timestamp` | Get timestamps in various formats | system, time |\r\n| `list_operations` | Perform operations on string lists | data, list |\r\n| `hash_text` | Generate text hashes (SHA256, SHA1, MD5) | security, hash |\r\n| `encode_decode` | Encode/decode text (base64, URL, hex) | development, base64 |\r\n\r\n### PowerPoint Tools\r\n\r\nAdvanced PowerPoint analysis and processing capabilities with **multimodal AI support**:\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| `extract_powerpoint_metadata` | Extract comprehensive metadata from PowerPoint presentations |\r\n| `analyze_powerpoint_content` | Analyze content of specific slides or entire presentations |\r\n| `get_powerpoint_summary` | Get high-level summary of a PowerPoint presentation |\r\n| `validate_powerpoint_file` | Validate PowerPoint files and check for common issues |\r\n| `capture_powerpoint_slides` | **NEW**: Capture slide images as base64 PNG data URLs for multimodal AI analysis |\r\n\r\n#### PowerPoint Features\r\n\r\n- **Comprehensive Metadata Extraction**: Core properties, slide dimensions, layout information\r\n- **Shape Analysis**: Position, size, formatting, and content of all shapes\r\n- **Text Content**: Fonts, colors, alignment, paragraph and run-level formatting\r\n- **Multimedia Elements**: Images with crop information, tables with cell data\r\n- **Formatting Details**: Fill, line, shadow formatting for all objects\r\n- **Slide Structure**: Master slides, layouts, notes, and comments\r\n- **Content Summarization**: Automatic extraction of slide titles and content\r\n- **File Validation**: Format checking, corruption detection, structural integrity\r\n- **\ud83c\udd95 Multimodal AI Integration**: Slide image capture as base64 PNG data URLs for vision-capable LLMs\r\n- **\ud83c\udd95 Visual Content Analysis**: Export slides as images for AI-powered visual understanding\r\n\r\n### Resources\r\n\r\n#### Static Resources\r\n- `config://server` - Server configuration\r\n- `data://environment` - Environment information \r\n- `system://status` - System status\r\n- `data://sample-users` - Sample user data\r\n- `config://features` - Available features\r\n\r\n#### Resource Templates\r\n- `users://{user_id}` - Get user by ID\r\n- `config://{section}` - Get config section\r\n- `data://{data_type}/summary` - Get data summaries\r\n- `logs://{log_level}` - Get simulated logs\r\n- `file://{file_path}` - Read file contents (with safety checks)\r\n\r\n### Prompts\r\n\r\n- `analyze_data` - Generate data analysis prompts\r\n- `code_review_prompt` - Generate code review prompts\r\n\r\n### Custom HTTP Routes\r\n\r\n- `GET /health` - Health check endpoint\r\n- `GET /info` - Server information\r\n\r\n## \ud83d\udd27 Integration Approaches\r\n\r\nVoluteMCP offers flexible integration options for different use cases:\r\n\r\n### **\ud83c\udf10 Cloud Integration (Serverless/Web Apps)**\r\n\r\n**Best for**: AWS Lambda, Vercel, Netlify, cloud-deployed AI agents\r\n\r\n```python\r\n# Ultra-simple SDK integration\r\nfrom volutemcp.sdk import VoluteMCPCloudClient\r\n\r\nclass MyAIAgent:\r\n def __init__(self):\r\n self.volute = VoluteMCPCloudClient()\r\n \r\n async def process_calculation(self, expression):\r\n return await self.volute.calculate(expression)\r\n\r\n# Works in FastAPI, Flask, Express.js, Next.js, etc.\r\n```\r\n\r\n### **\ud83d\udda5\ufe0f Local MCP Integration (Desktop Apps)**\r\n\r\n**Best for**: Claude Desktop, local AI applications, PowerPoint integration, multimodal AI workflows\r\n\r\n```json\r\n{\r\n \"volutemcp-local\": {\r\n \"command\": \"python\",\r\n \"args\": [\"-m\", \"volutemcp.server_local\", \"--transport\", \"stdio\"],\r\n \"env\": {}\r\n }\r\n}\r\n```\r\n\r\n### **\ud83d\udd04 Hybrid Architecture (Best of Both)**\r\n\r\n**Best for**: Comprehensive AI systems needing both cloud and local capabilities, multimodal AI workflows\r\n\r\n```python\r\n# Use both cloud and local servers\r\nfrom volutemcp.sdk import VoluteMCPCloudClient\r\n\r\nclass HybridAIAgent:\r\n def __init__(self):\r\n self.cloud = VoluteMCPCloudClient() # For general tools\r\n # Local MCP for PowerPoint (via separate config)\r\n \r\n async def process_request(self, user_input):\r\n # Use cloud for calculations\r\n if \"calculate\" in user_input:\r\n return await self.cloud.calculate(\"2 + 3\")\r\n # Use local for PowerPoint (via MCP client)\r\n # ...\r\n```\r\n\r\n## \ud83d\udcda Documentation\r\n\r\n- **[Installation Guide](INSTALLATION_GUIDE.md)** - Multiple installation methods\r\n- **[Cloud Integration](CLOUD_INTEGRATION.md)** - SDK usage for cloud deployments\r\n- **[Developer Guide](DEVELOPER_GUIDE.md)** - Comprehensive integration examples\r\n- **[Hybrid Architecture](HYBRID_ARCHITECTURE.md)** - Cloud + local setup\r\n- **[Deployment Guide](DEPLOYMENT.md)** - Production deployment options\r\n\r\n## Usage Examples\r\n\r\n### Using with MCP Clients\r\n\r\nThe server can be used with any MCP-compatible client. Here are some examples:\r\n\r\n#### Call a Tool\r\n```python\r\n# Using an MCP client library\r\nresult = client.call_tool(\"calculate\", {\"expression\": \"2 + 3 * 4\"})\r\nprint(result) # 14.0\r\n```\r\n\r\n#### Access a Resource\r\n```python\r\n# Get server config\r\nconfig = client.read_resource(\"config://server\")\r\nprint(config)\r\n\r\n# Get specific user\r\nuser = client.read_resource(\"users://1\")\r\nprint(user)\r\n```\r\n\r\n#### Use a Prompt\r\n```python\r\n# Generate analysis prompt\r\nprompt = client.get_prompt(\"analyze_data\", {\r\n \"data_description\": \"Sales data for Q1 2024\",\r\n \"analysis_type\": \"trends\"\r\n})\r\n```\r\n\r\n#### PowerPoint Analysis\r\n```python\r\n# Extract comprehensive metadata from a presentation\r\nresult = client.call_tool(\"extract_powerpoint_metadata\", {\r\n \"presentation_path\": \"./presentation.pptx\",\r\n \"include_slide_content\": True,\r\n \"output_format\": \"json\"\r\n})\r\n\r\n# Get a quick summary of the presentation\r\nsummary = client.call_tool(\"get_powerpoint_summary\", {\r\n \"presentation_path\": \"./presentation.pptx\"\r\n})\r\n\r\n# Analyze specific slides only\r\ncontent = client.call_tool(\"analyze_powerpoint_content\", {\r\n \"presentation_path\": \"./presentation.pptx\",\r\n \"slide_numbers\": [1, 3, 5],\r\n \"extract_text_only\": True\r\n})\r\n\r\n# Validate a PowerPoint file\r\nvalidation = client.call_tool(\"validate_powerpoint_file\", {\r\n \"presentation_path\": \"./presentation.pptx\"\r\n})\r\n\r\n# \ud83c\udd95 Capture slide images for multimodal AI analysis\r\nslide_images = client.call_tool(\"capture_powerpoint_slides\", {\r\n \"presentation_path\": \"./presentation.pptx\",\r\n \"slide_numbers\": [1, 3, 5], # Specific slides or omit for all\r\n \"max_slides\": 10, # Safety limit\r\n \"image_width\": 1024, # Optional: control image size\r\n \"image_height\": 768\r\n})\r\n# Returns base64 PNG data URLs perfect for vision-capable AI models\r\n```\r\n\r\n## Testing\r\n\r\nThe project includes a comprehensive test suite to validate all functionality:\r\n\r\n### Running Tests\r\n\r\n```bash\r\n# Run all tests using the test runner\r\npython run_tests.py\r\n\r\n# Or run tests directly\r\npython tests/test_powerpoint_tools.py\r\n\r\n# Using pytest (if installed)\r\npytest tests/\r\n```\r\n\r\n### Test Coverage\r\n\r\nThe test suite validates:\r\n- \u2705 All module imports work correctly\r\n- \u2705 Pydantic data models function properly\r\n- \u2705 PowerPoint tools register and integrate correctly\r\n- \u2705 Server startup and configuration\r\n- \u2705 Error handling for edge cases\r\n- \u2705 FastMCP 2.0 async/await patterns\r\n\r\n### Test Results\r\n\r\n- **5 PowerPoint tools** properly registered (including multimodal slide capture)\r\n- **12 total tools** available (including core tools)\r\n- **3 resources** configured\r\n- **100% test pass rate**\r\n\r\n## Development\r\n\r\n### Project Structure\r\n\r\n```\r\nvolutemcp/\r\n\u251c\u2500\u2500 server.py # Main server entry point\r\n\u251c\u2500\u2500 server_modular.py # Modular server implementation\r\n\u251c\u2500\u2500 config.py # Configuration management\r\n\u251c\u2500\u2500 tools.py # Core tool implementations\r\n\u251c\u2500\u2500 resources.py # Resource implementations\r\n\u251c\u2500\u2500 powerpoint_metadata.py # PowerPoint metadata extraction\r\n\u251c\u2500\u2500 powerpoint_tools.py # PowerPoint tool implementations\r\n\u251c\u2500\u2500 powerpoint_image_capture.py # \ud83c\udd95 Multimodal slide image capture\r\n\u251c\u2500\u2500 tests/ # Test directory\r\n\u2502 \u251c\u2500\u2500 __init__.py # Test package initialization\r\n\u2502 \u251c\u2500\u2500 test_powerpoint_tools.py # PowerPoint tools test suite\r\n\u2502 \u2514\u2500\u2500 README.md # Test documentation\r\n\u251c\u2500\u2500 run_tests.py # Test runner script\r\n\u251c\u2500\u2500 pytest.ini # Pytest configuration\r\n\u251c\u2500\u2500 requirements.txt # Python dependencies\r\n\u251c\u2500\u2500 .env.example # Environment template\r\n\u251c\u2500\u2500 .gitignore # Git ignore rules\r\n\u2514\u2500\u2500 README.md # This file\r\n```\r\n\r\n### Adding New Components\r\n\r\n#### Add a Tool\r\n```python\r\n# In tools.py\r\n@mcp.tool(tags={\"custom\", \"utility\"})\r\ndef my_custom_tool(input_data: str) -> str:\r\n \"\"\"My custom tool description.\"\"\"\r\n return f\"Processed: {input_data}\"\r\n```\r\n\r\n#### Add a Resource\r\n```python\r\n# In resources.py\r\n@mcp.resource(\"custom://my-data\")\r\ndef my_custom_resource() -> dict:\r\n \"\"\"My custom resource description.\"\"\"\r\n return {\"data\": \"value\"}\r\n```\r\n\r\n#### Add a Resource Template\r\n```python\r\n# In resources.py\r\n@mcp.resource(\"items://{item_id}\")\r\ndef get_item(item_id: int) -> dict:\r\n \"\"\"Get item by ID.\"\"\"\r\n return {\"id\": item_id, \"name\": f\"Item {item_id}\"}\r\n```\r\n\r\n### Configuration\r\n\r\nThe server uses Pydantic for configuration management. Settings can be provided via:\r\n\r\n1. Environment variables (prefixed with `VOLUTE_`)\r\n2. `.env` file\r\n3. Default values in `config.py`\r\n\r\n#### Available Settings\r\n\r\n| Setting | Default | Description |\r\n|---------|---------|-------------|\r\n| `VOLUTE_NAME` | VoluteMCP | Server name |\r\n| `VOLUTE_HOST` | 127.0.0.1 | Server host |\r\n| `VOLUTE_PORT` | 8000 | Server port |\r\n| `VOLUTE_LOG_LEVEL` | INFO | Logging level |\r\n| `VOLUTE_API_KEY` | None | Optional API key |\r\n\r\n### Tag-Based Filtering\r\n\r\nFilter components by tags when creating the server:\r\n\r\n```python\r\n# Only expose utility tools\r\nmcp = FastMCP(include_tags={\"utility\"})\r\n\r\n# Hide internal tools\r\nmcp = FastMCP(exclude_tags={\"internal\"})\r\n\r\n# Combine filters\r\nmcp = FastMCP(include_tags={\"public\"}, exclude_tags={\"deprecated\"})\r\n```\r\n\r\n## Advanced Usage\r\n\r\n### Server Composition\r\n\r\n```python\r\nfrom fastmcp import FastMCP\r\nfrom tools import register_tools\r\n\r\n# Create modular servers\r\ntools_server = FastMCP(\"ToolsOnly\")\r\nregister_tools(tools_server)\r\n\r\n# Mount into main server\r\nmain_server = FastMCP(\"Main\")\r\nmain_server.mount(tools_server, prefix=\"tools\")\r\n```\r\n\r\n### Custom Serialization\r\n\r\n```python\r\nimport yaml\r\n\r\ndef yaml_serializer(data):\r\n return yaml.dump(data, sort_keys=False)\r\n\r\nmcp = FastMCP(tool_serializer=yaml_serializer)\r\n```\r\n\r\n## Deployment\r\n\r\n### Docker\r\n\r\n```dockerfile\r\nFROM python:3.11-slim\r\n\r\nWORKDIR /app\r\nCOPY requirements.txt .\r\nRUN pip install -r requirements.txt\r\n\r\nCOPY . .\r\n\r\nEXPOSE 8000\r\nCMD [\"python\", \"server.py\"]\r\n```\r\n\r\n### systemd Service\r\n\r\n```ini\r\n[Unit]\r\nDescription=VoluteMCP Server\r\nAfter=network.target\r\n\r\n[Service]\r\nType=simple\r\nUser=volute\r\nWorkingDirectory=/opt/volutemcp\r\nExecStart=/opt/volutemcp/venv/bin/python server.py\r\nRestart=always\r\n\r\n[Install]\r\nWantedBy=multi-user.target\r\n```\r\n\r\n## Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Add your changes with tests\r\n4. Submit a pull request\r\n\r\n## License\r\n\r\nMIT License - see LICENSE file for details.\r\n\r\n## \ud83c\udf10 Live Deployments\r\n\r\n- **Cloud Server**: https://volutemcp-server.onrender.com\r\n- **PyPI Package**: https://pypi.org/project/volutemcp/\r\n- **GitLab Repository**: https://gitlab.com/coritan/volutemcp\r\n- **Health Check**: https://volutemcp-server.onrender.com/health\r\n\r\n## \ud83d\udce6 Package Information\r\n\r\n```bash\r\n# Installation\r\npip install volutemcp\r\n\r\n# CLI Commands\r\nvolutemcp-local --help # Local PowerPoint server\r\nvolutemcp-server --help # Cloud server\r\n\r\n# Python Module\r\npython -m volutemcp.server_local --transport stdio\r\n```\r\n\r\n## Resources\r\n\r\n- **[VoluteMCP on PyPI](https://pypi.org/project/volutemcp/)** - Official package\r\n- **[FastMCP Documentation](https://github.com/jlowin/fastmcp)** - Framework docs\r\n- **[Model Context Protocol](https://modelcontextprotocol.io)** - MCP standard\r\n- **[MCP Specification](https://spec.modelcontextprotocol.io)** - Technical specs\r\n- **[GitLab Issues](https://gitlab.com/coritan/volutemcp/-/issues)** - Bug reports & features\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for PowerPoint analysis and multimodal AI integration - comprehensive metadata extraction and slide image capture for agents",
"version": "1.1.1",
"project_urls": {
"Documentation": "https://gitlab.com/coritan/volutemcp/-/blob/main/DEVELOPER_GUIDE.md",
"Homepage": "https://gitlab.com/coritan/volutemcp",
"Issues": "https://gitlab.com/coritan/volutemcp/-/issues",
"Repository": "https://gitlab.com/coritan/volutemcp.git"
},
"split_keywords": [
"mcp",
" powerpoint",
" ai",
" agents",
" desktop",
" automation",
" com",
" multimodal",
" vision",
" slides",
" image-capture"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f1b1f1771d5ca970d149d6533528e7f4b2b4dffedfec784376e1abdabd2fa13a",
"md5": "52f2fbb55789cdd9218e6f3c15718f34",
"sha256": "9cc16d0d39a45644983a3ae3f40a5e79e6e669a5f48b7e59c1c8e008993c4568"
},
"downloads": -1,
"filename": "volutemcp-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "52f2fbb55789cdd9218e6f3c15718f34",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 32791,
"upload_time": "2025-08-27T01:19:11",
"upload_time_iso_8601": "2025-08-27T01:19:11.427639Z",
"url": "https://files.pythonhosted.org/packages/f1/b1/f1771d5ca970d149d6533528e7f4b2b4dffedfec784376e1abdabd2fa13a/volutemcp-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3b28061608486102cf2da02661bc606bf1aea304a9ea05538aeed7250501a0e5",
"md5": "9b0f828dda836de77d5ff116656b0d0f",
"sha256": "62dbf2e2e5f7bda0a54c90780edf7117b1f34b444eaaf8bdb62d3aeef2131313"
},
"downloads": -1,
"filename": "volutemcp-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "9b0f828dda836de77d5ff116656b0d0f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 67933,
"upload_time": "2025-08-27T01:19:14",
"upload_time_iso_8601": "2025-08-27T01:19:14.089493Z",
"url": "https://files.pythonhosted.org/packages/3b/28/061608486102cf2da02661bc606bf1aea304a9ea05538aeed7250501a0e5/volutemcp-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-27 01:19:14",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "coritan",
"gitlab_project": "volutemcp",
"lcname": "volutemcp"
}
JSON