bt-or-markdown-pdf-converter

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 bt-or-markdown-pdf-converter

# HTTP server mode
npx bt-or-markdown-pdf-converter http 3000

# SSE server mode (legacy)
npx bt-or-markdown-pdf-converter sse 3001

Option 2: Global Installation

npm install -g bt-or-markdown-pdf-converter

# Run in different modes
bt-or-markdown-pdf-converter              # stdio (default)
bt-or-markdown-pdf-converter http 3000    # HTTP server
bt-or-markdown-pdf-converter 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": {
    "bt-or-markdown-pdf": {
      "command": "npx",
      "args": ["bt-or-markdown-pdf-converter"]
    }
  }
}

HTTP Server

# Start HTTP server on port 3000
npx bt-or-markdown-pdf-converter http 3000

# Or with npm
npm run start:http

SSE Server (Legacy)

# Start SSE server on port 3001
npx bt-or-markdown-pdf-converter 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 bt-or-markdown-pdf-converter

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 bt-or-markdown-pdf-converter 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 bt-or-markdown-pdf-converter 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

🛠️ Installation & Deployment

Local Development

# Clone and install
git clone https://github.com/skmprb/bt-or-markdown-pdf-converter.git
cd bt-or-markdown-pdf-converter
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

PM2 Process Manager

# Install globally
npm install -g bt-or-markdown-pdf-converter pm2

# Start with PM2
pm2 start "bt-or-markdown-pdf-converter http 3000" --name bt-or-mcp-pdf-server
pm2 startup
pm2 save

🐛 Issues & Support

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

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