skmprb/s3-md-pdf-converter-mcp

s3-md-pdf-converter-mcp

A powerful Model Context Protocol (MCP) server that converts Markdown files and content to beautifully styled PDFs with S3 integration, Mermaid diagrams and ApexCharts support. Built with MCP SDK 1.16.x featuring all transport modes: stdio, HTTP, and SSE.

✨ Features

🚀 Transport Layer Support (MCP SDK 1.16.x)

• stdio: Perfect for Claude Desktop integration
• Streamable HTTP: Modern web applications with session management
• SSE (Server-Sent Events): Legacy compatibility support
• CORS enabled: Browser-friendly with proper headers
• DNS rebinding protection: Enhanced security

📄 PDF Conversion

• 🔄 Three conversion modes: File-to-PDF, content-to-PDF, and S3-to-PDF
• ☁️ S3 Integration: Direct download from S3 buckets and upload PDFs back to S3
• 📊 Charts & diagrams: Mermaid diagrams + ApexCharts support
• 🎨 Modern styling: Professional typography with syntax highlighting
• 📄 Multiple formats: A4, A3, A5, Letter, Legal, Tabloid
• ⚙️ Configurable margins: Custom spacing in inches, mm, cm
• 📝 Front matter support: YAML metadata for document properties
• 🎯 Accessibility: Tagged PDFs with proper outline structure
• 📦 Large content support: JSON structure for handling 10,000+ line documents

🚀 Quick Start

Option 1: Use with npx (Recommended)

# Default stdio mode (for Claude Desktop)
npx s3-md-pdf-converter-mcp

# HTTP server mode
npx s3-md-pdf-converter-mcp http 3000

# SSE server mode (legacy)
npx s3-md-pdf-converter-mcp sse 3001

Option 2: Global Installation

npm install -g s3-md-pdf-converter-mcp

# Run in different modes
s3-md-pdf-converter-mcp              # stdio (default)
s3-md-pdf-converter-mcp http 3000    # HTTP server
s3-md-pdf-converter-mcp sse 3001     # SSE server

🔧 Integration Options

Claude Desktop (stdio)

Add to your Claude Desktop configuration:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "s3-markdown-pdf": {
      "command": "npx",
      "args": ["s3-md-pdf-converter-mcp"]
    }
  }
}

HTTP Server

# Start HTTP server on port 3000
npx s3-md-pdf-converter-mcp http 3000

# Or with npm
npm run start:http

SSE Server (Legacy)

# Start SSE server on port 3001
npx s3-md-pdf-converter-mcp sse 3001

# Or with npm
npm run start:sse

Restart Claude Desktop after configuration.

📖 Usage Examples

Convert Markdown File to PDF

"Convert my README.md file to PDF and save it as documentation.pdf"

Convert Markdown Content to PDF

"Take this markdown content and create a PDF with A4 format:
# My Document
This is **bold** text with a [link](https://example.com)
"

S3 Integration

"Convert S3 markdown from bucket 'my-docs' key 'report.md' and save to 'output.pdf'"
"Convert S3 markdown from bucket 'docs' key 'readme.md' and upload PDF to S3 with key 'readme.pdf' and uploadToS3 true"

Large Content Support

"Convert this large markdown content to PDF: {content: 'Main content...', chunks: ['Section 1...', 'Section 2...']}"

Custom Formatting

"Convert the markdown file with custom margins of 1 inch on all sides and Letter format"

Charts & Diagrams

ApexCharts:

# Sales Data

```chart
{
  "chart": { "type": "line", "height": 350 },
  "series": [{ "name": "Sales", "data": [30, 40, 35, 50, 49, 60, 70] }],
  "xaxis": { "categories": ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul"] }
}

**Mermaid:**
```markdown
```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]

## 🚀 Transport Modes (MCP SDK 1.16.x)

This server implements **all transport modes** from the latest MCP SDK, making it compatible with various integration scenarios:

### 💻 stdio (Default) - Claude Desktop Ready
**Perfect for**: Claude Desktop, command-line tools, direct integrations
```bash
npx md-mermaid-chart-pdf-mcp

Features:

• Zero configuration required
• Direct stdin/stdout communication
• Ideal for desktop AI applications
• Automatic process lifecycle management

🌐 Streamable HTTP - Modern Web Applications

Perfect for: Web applications, microservices, cloud deployments

npx md-mermaid-chart-pdf-mcp http 3000

Features:

• Endpoints: POST/GET/DELETE /mcp
• Session management with mcp-session-id header
• CORS enabled for browser clients
• DNS rebinding protection for security
• Stateful sessions with automatic cleanup
• Error handling with proper HTTP status codes

Integration Example:

// Browser/Node.js client
const response = await fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'mcp-session-id': sessionId // Optional for new sessions
  },
  body: JSON.stringify(mcpRequest)
});

📡 SSE (Server-Sent Events) - Legacy Support

Perfect for: Backwards compatibility, existing SSE-based systems

npx md-mermaid-chart-pdf-mcp sse 3001

Features:

• SSE endpoint: GET /sse for real-time notifications
• Message endpoint: POST /messages for client requests
• Session-based communication
• Legacy compatibility with older MCP implementations

Integration Example:

// SSE connection for notifications
const eventSource = new EventSource('http://localhost:3001/sse');

// POST messages for requests
fetch('http://localhost:3001/messages?sessionId=abc123', {
  method: 'POST',
  body: JSON.stringify(mcpRequest)
});

🛠️ Available Tools

convert_markdown_to_pdf

Converts a markdown file to PDF (supports local files, URLs, and S3 URLs).

Parameters:

• markdownPath (string): Path to the markdown file (local path or URL)
• outputPath (string): Where to save the PDF
• format (optional): Page format (A4, A3, A5, Letter, Legal, Tabloid)
• margin (optional): Custom margins object

convert_s3_markdown_to_pdf

Converts a markdown file from S3 bucket to PDF using bucket and key parameters.

Parameters:

• bucket (string): S3 bucket name
• key (string): S3 object key (path to the markdown file)
• outputPath (string): Where to save the PDF (local path or S3 key for upload)
• uploadToS3 (boolean, optional): Whether to upload the PDF back to the same S3 bucket
• region (string, optional): AWS region (defaults to us-east-1)
• format (optional): Page format (A4, A3, A5, Letter, Legal, Tabloid)
• margin (optional): Custom margins object

markdown_content_to_pdf

Converts markdown content directly to PDF (supports large content with JSON structure).

Parameters:

• markdownContent (string or object): Markdown content to convert (string or JSON object with content/chunks)
• outputPath (string): Where to save the PDF
• title (optional): Document title
• format (optional): Page format
• margin (optional): Custom margins object

📚 API Documentation

MCP Protocol Methods

tools/list

Returns available tools for PDF conversion.

Response:

{
  "tools": [
    {
      "name": "convert_markdown_to_pdf",
      "title": "Convert Markdown File to PDF",
      "description": "Convert a markdown file to PDF",
      "inputSchema": { /* Zod schema */ }
    },
    {
      "name": "markdown_content_to_pdf",
      "title": "Convert Markdown Content to PDF",
      "description": "Convert markdown content directly to PDF",
      "inputSchema": { /* Zod schema */ }
    }
  ]
}

tools/call

Execute PDF conversion tools.

Request:

{
  "name": "convert_markdown_to_pdf",
  "arguments": {
    "markdownPath": "./README.md",
    "outputPath": "./output.pdf",
    "format": "A4",
    "margin": {
      "top": "1in",
      "right": "0.5in",
      "bottom": "1in",
      "left": "0.5in"
    }
  }
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "Successfully converted markdown to PDF!\nInput: ./README.md\nOutput: /full/path/output.pdf"
    }
  ]
}

HTTP API Endpoints (HTTP Transport)

POST /mcp

Main MCP communication endpoint.

Headers:

• Content-Type: application/json
• mcp-session-id: <session-id> (optional for new sessions)

Request Body: Standard MCP JSON-RPC 2.0 message

GET /mcp

Server-to-client notifications via Server-Sent Events.

Headers:

• mcp-session-id: <session-id> (required)

DELETE /mcp

Terminate MCP session.

Headers:

• mcp-session-id: <session-id> (required)

SSE API Endpoints (SSE Transport)

GET /sse

Establish SSE connection for notifications.

Response: Server-Sent Events stream

POST /messages

Send MCP messages to server.

Query Parameters:

• sessionId: <session-id> (required)

Request Body: Standard MCP JSON-RPC 2.0 message

🎨 Supported Markdown Features

• Headers: H1-H6 with modern styling
• Text formatting: Bold, italic, strikethrough
• Lists: Ordered and unordered with custom bullets
• Tables: Styled with alternating row colors
• Code blocks: Syntax highlighting for 100+ languages
• Blockquotes: Elegant left-border styling
• Links: Styled with hover effects
• Images: Embedded with proper scaling
• Charts: ApexCharts (line, bar, pie, area, etc.) via chart blocks
• Mermaid diagrams: Flowcharts, sequence, gantt, and more

🛠️ Installation & Deployment

Local Development

# Clone and install
git clone https://github.com/skmprb/s3-md-pdf-converter-mcp.git
cd s3-md-pdf-converter-mcp
npm install
npm run build

# Run in different modes
npm start              # stdio mode
npm run start:http     # HTTP server on port 3000
npm run start:sse      # SSE server on port 3001

Production Deployment

Docker (Recommended)

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "run", "start:http"]

PM2 Process Manager

# Install globally
npm install -g s3-md-pdf-converter-mcp pm2

# Start with PM2
pm2 start "s3-md-pdf-converter-mcp http 3000" --name s3-mcp-pdf-server
pm2 startup
pm2 save

Systemd Service

[Unit]
Description=MCP PDF Converter Server
After=network.target

[Service]
Type=simple
User=mcp
WorkingDirectory=/opt/mcp-pdf
ExecStart=/usr/bin/node /opt/mcp-pdf/build/index.js http 3000
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Cloud Deployment

Vercel/Netlify Functions

// api/mcp.js
import { createServer, setupServer } from '../src/index.js';

export default async function handler(req, res) {
  const server = createServer();
  setupServer(server);
  // Handle MCP requests
}

AWS Lambda

// lambda.js
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

export const handler = async (event, context) => {
  // Lambda handler for MCP requests
};

📋 Requirements & Compatibility

System Requirements

• Node.js 18+ (LTS recommended)
• Chrome/Chromium (automatically installed with Puppeteer)
• Memory: 512MB+ available RAM for PDF generation
• Disk: 200MB+ for Chromium and dependencies

MCP Compatibility

• MCP SDK: 1.16.x (latest with all transport modes)
• Protocol Version: 2024-11-05 and later
• Backwards Compatible: Supports legacy SSE transport
• Client Support: Claude Desktop, custom MCP clients

Transport-Specific Requirements

🔧 Configuration Examples

Custom Margins

{
  "margin": {
    "top": "1in",
    "right": "0.5in",
    "bottom": "1in",
    "left": "0.5in"
  }
}

Front Matter Support

---
title: My Document
author: John Doe
date: 2024-01-01
---

# Document Content
Your markdown content here...

Environment Variables

# Server configuration
MCP_PORT=3000                    # HTTP server port
MCP_HOST=localhost               # HTTP server host
MCP_CORS_ORIGIN=*               # CORS allowed origins
MCP_SESSION_TIMEOUT=3600000     # Session timeout (ms)

# PDF generation
PDF_TIMEOUT=30000               # PDF generation timeout (ms)
PDF_QUALITY=100                 # PDF quality (1-100)
CHROME_ARGS="--no-sandbox"      # Additional Chrome arguments

⚡ Performance & Optimization

PDF Generation Performance

• Average conversion time: 2-5 seconds for typical documents
• Memory usage: 100-300MB per conversion
• Concurrent requests: Supports multiple simultaneous conversions
• Caching: Automatic font and resource caching

Optimization Tips

// Optimize for large documents
const options = {
  format: 'A4',
  margin: { top: '0.5in', right: '0.5in', bottom: '0.5in', left: '0.5in' },
  // Reduce quality for faster generation
  printBackground: false,
  // Disable animations for better performance
  preferCSSPageSize: true
};

Scaling Considerations

• Horizontal scaling: Deploy multiple instances behind load balancer
• Resource limits: Set appropriate memory limits (1GB+ recommended)
• Queue management: Implement request queuing for high load
• Monitoring: Track conversion times and error rates

🔍 Troubleshooting

Common Issues

"Chrome not found" Error

# Install Chrome/Chromium manually
sudo apt-get install chromium-browser  # Ubuntu/Debian
brew install chromium                  # macOS

# Or set custom Chrome path
export CHROME_PATH=/path/to/chrome

Memory Issues

# Increase Node.js memory limit
node --max-old-space-size=4096 build/index.js

# Or set environment variable
export NODE_OPTIONS="--max-old-space-size=4096"

Port Already in Use

# Find process using port
lsof -i :3000

# Kill process
kill -9 <PID>

# Or use different port
npx s3-md-pdf-converter-mcp http 3001

CORS Issues

// Custom CORS configuration
app.use(cors({
  origin: ['https://yourdomain.com'],
  credentials: true,
  exposedHeaders: ['Mcp-Session-Id']
}));

Debug Mode

# Enable debug logging
DEBUG=mcp:* npx s3-md-pdf-converter-mcp http 3000

# Verbose Puppeteer logging
DEBUG=puppeteer:* npx s3-md-pdf-converter-mcp

Health Check Endpoint

# Add to your HTTP server
app.get('/health', (req, res) => {
  res.json({
    status: 'healthy',
    version: '1.0.0',
    uptime: process.uptime(),
    memory: process.memoryUsage()
  });
});

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

📊 Feature Comparison

🛡️ Security Considerations

HTTP Transport Security

• DNS Rebinding Protection: Enabled by default
• CORS Configuration: Properly configured origins
• Session Validation: Secure session ID generation
• Input Sanitization: All inputs validated with Zod schemas

Production Security Checklist

• Use HTTPS in production
• Configure specific CORS origins (not *)
• Set up proper firewall rules
• Enable rate limiting
• Monitor for suspicious activity
• Regular security updates

// Production CORS configuration
app.use(cors({
  origin: [
    'https://yourdomain.com',
    'https://app.yourdomain.com'
  ],
  credentials: true,
  exposedHeaders: ['Mcp-Session-Id'],
  allowedHeaders: ['Content-Type', 'mcp-session-id']
}));

📜 Related Projects

• MCP TypeScript SDK: Official MCP SDK
• Claude Desktop: AI assistant with MCP support
• Puppeteer: Headless Chrome for PDF generation
• Mermaid: Diagram and flowchart library
• ApexCharts: Interactive chart library

🐛 Issues & Support

Found a bug or need help? Please open an issue on GitHub.

Before Opening an Issue

1. Check existing issues for duplicates
2. Include your Node.js version
3. Specify which transport mode you're using
4. Provide sample markdown content (if applicable)
5. Include error logs and stack traces

🌟 Show Your Support

Give a ⭐️ if this project helped you!

Ways to Contribute

• ⭐ Star the repository
• 🐛 Report bugs and issues
• 💡 Suggest new features
• 📝 Improve documentation
• 🔧 Submit pull requests
• 💬 Share your use cases

Built with ❤️ using MCP SDK 1.16.x and AWS SDK v3