# Presenton MCP Server

An MCP (Model Context Protocol) server that provides AI agents with the ability to generate presentations using Presenton.

## Features

The MCP server exposes the following tool for AI agents:

### `generate_presentation`
Generate a PPTX or PDF presentation from a prompt.

**Parameters:**
- `prompt` (string, required): The main topic or content for the presentation
- `output_path` (string, required): Local file path where the presentation should be saved
- `n_slides` (number, optional): Number of slides (5-15, default: 8)
- `language` (string, optional): Language for the presentation (default: English)
- `theme` (string, optional): Presentation theme - one of: `dark`, `light`, `royal_blue`, `cream`, `light_red`, `dark_pink`, `faint_yellow`
- `export_format` (string, optional): Export format - `pptx` or `pdf` (default: pptx)
- `documents` (array, optional): Array of document file paths to include as source material

**Returns:**
```json
{
  "success": true,
  "message": "Presentation generated successfully!",
  "file_path": "/path/to/presentation.pptx",
  "presentation_id": "uuid",
  "edit_url": "http://localhost:5000/presentation?id=uuid"
}
```


## Setup

### Prerequisites
1. **Presenton server must be running**: Start with `docker-compose up development`
2. **Node.js 18+** installed
3. **npm** package manager

### Installation

```bash
cd /Users/jamie/Code/presenton/mcp

# Install dependencies
npm install

# Start the MCP server
npm run dev
```

### Configuration

The MCP server connects to Presenton at `http://localhost:5000` by default. You can customize this using the `PRESENTON_URL` environment variable:

```bash
# Use a different host/port
PRESENTON_URL=http://localhost:8080 npm run dev

# Use a remote server
PRESENTON_URL=https://my-presenton-server.com npm run dev
```

The URL can also be configured by:
1. Setting the `PRESENTON_URL` environment variable (recommended)
2. Modifying the default in `PresentonService` constructor in `src/core/services/presenton-service.ts`

## Usage Examples

### For AI Agents

When an AI agent connects to this MCP server, it can generate presentations like this:

```typescript
// Generate a simple presentation
await mcp.call_tool("generate_presentation", {
  prompt: "Introduction to Machine Learning",
  output_path: "./ml_intro.pptx",
  n_slides: 8,
  theme: "royal_blue"
});

// Generate with source documents
await mcp.call_tool("generate_presentation", {
  prompt: "Quarterly Business Review",
  output_path: "./q4_review.pptx",
  n_slides: 12,
  theme: "light",
  documents: ["./q4_data.pdf", "./market_analysis.docx"]
});

```

### Testing the MCP Server

You can test the server using any MCP client or the built-in testing tools:

```bash
# Start the development server
npm run dev

# Run the test script
npm run test:presenton

# The server will be available for MCP connections
# Test with Claude Desktop, Cline, or other MCP clients
```

## Integration with AI Assistants

### Claude Desktop

Add this to your Claude Desktop MCP configuration:

```json
{
  "mcpServers": {
    "presenton": {
      "command": "npx",
      "args": ["tsx", "/Users/jamie/Code/presenton/mcp/src/index.ts"],
      "env": {
        "PRESENTON_URL": "http://localhost:5000"
      }
    }
  }
}
```

### Cline (VS Code Extension)

Configure Cline to use this MCP server for presentation generation capabilities.

## Example Agent Interactions

**Agent:** "Create a presentation about climate change with 10 slides"

**MCP Call:**
```json
{
  "tool": "generate_presentation",
  "parameters": {
    "prompt": "Climate Change: Causes, Effects, and Solutions",
    "output_path": "./climate_change.pptx",
    "n_slides": 10,
    "theme": "light_red"
  }
}
```

**Agent:** "Generate a business presentation using the quarterly report data"

**MCP Call:**
```json
{
  "tool": "generate_presentation",
  "parameters": {
    "prompt": "Q4 2024 Business Review and 2025 Strategy",
    "output_path": "./business_review.pptx",
    "n_slides": 12,
    "theme": "royal_blue",
    "documents": ["./q4_report.pdf", "./strategy_doc.docx"]
  }
}
```

## Error Handling

The MCP server provides comprehensive error handling:

- **Server connectivity issues**: Returns detailed error messages
- **Invalid parameters**: Validates input parameters with Zod schemas
- **File system errors**: Handles file creation and download failures
- **API failures**: Provides clear error messages from the Presenton API

## Architecture

```
MCP Server
├── Core Tool (tools.ts)
│   └── generate_presentation
├── Presenton Service (presenton-service.ts)
│   ├── API communication
│   ├── File handling
│   ├── Error management
│   └── Server connectivity handling
└── FastMCP Framework
    ├── Parameter validation (Zod)
    ├── Tool registration
    └── MCP protocol handling
```

## Development

### Adding New Features

1. **Add new methods** to `PresentonService`
2. **Register new tools** in `registerTools()` function
3. **Update types** and validation schemas
4. **Test** with MCP clients

### Debugging

```bash
# Run with debug logging
DEBUG=* npm run dev

# Check server health
curl http://localhost:5000/
```

## Troubleshooting

**Q: "Presenton server not accessible"**
A: Make sure Presenton is running: `docker-compose up development`

**Q: "File download failed"**
A: Check file permissions and ensure the output directory exists

**Q: "MCP connection failed"**
A: Verify the MCP server is running and accessible on the configured port

**Q: "Tool not found"**
A: Make sure the MCP server is properly registered in your AI assistant's configuration

**Q: "Server connection failed"**
A: The generate_presentation tool will automatically detect server connectivity issues and return appropriate error messages