JSPM

s3-md-pdf-converter-mcp

1.2.3
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 10
  • Score
    100M100P100Q97839F
  • License MIT

A powerful MCP server with stdio/HTTP/SSE transport support for converting Markdown files and content to beautifully styled PDFs with S3 integration, Mermaid diagrams and ApexCharts. Features modern typography, multiple page formats, and professional styling.

Package Exports

    This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (s3-md-pdf-converter-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

    Readme

    s3-md-pdf-converter-mcp

    npm version License: MIT MCP SDK Node.js

    A powerful Model Context Protocol (MCP) server that converts Markdown files and content to beautifully stylegd 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

    # 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

    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

    Transport Port Dependencies Use Case
    stdio N/A None Claude Desktop, CLI
    HTTP 3000+ express, cors Web apps, APIs
    SSE 3001+ express Legacy systems

    🔧 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 LICENSE file for details.

    📊 Feature Comparison

    Feature stdio HTTP SSE Notes
    Claude Desktop ✅ ❌ ❌ Primary use case
    Web Applications ❌ ✅ ✅ HTTP recommended
    Session Management ❌ ✅ ✅ Stateful connections
    CORS Support N/A ✅ ✅ Browser compatibility
    Real-time Notifications ❌ ✅ ✅ Server-to-client
    DNS Protection N/A ✅ ❌ Security feature
    Process Lifecycle Auto Manual Manual Automatic cleanup
    Scalability Low High Medium Concurrent connections
    Setup Complexity None Low Medium Configuration required

    🛡️ 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']
}));

    🐛 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