kazphd/quarto-typst-mcp

Quarto-Typst MCP 🚀

A modern Python package that provides seamless integration between Quarto and Typst for document generation, with an MCP (Model Context Protocol) server for AI agents, featuring revolutionary AI-powered chart analysis.

✨ Features

• 📄 Quarto to Typst Conversion: Parse and convert Quarto markdown files to Typst format
• 🚀 MCP Server: Built-in Model Context Protocol server for AI agent integration
• 📝 Template Support: Pre-built templates for articles, reports, and presentations
• ⚡ Async Operations: Fully asynchronous for optimal performance
• 🔒 Type Safety: Built with Pydantic v2 for robust data validation
• 🎨 Rich CLI: Beautiful command-line interface with Rich formatting
• 📊 Enhanced Plotly Integration: AI-powered interactive visualizations with 100x improvements
• 🤖 AI Chart Analysis: Automated insights generation with OpenAI integration and cost tracking
• 💰 Token Management: Comprehensive cost estimation and budget controls

📦 Installation

Basic Installation

pip install quarto-typst-mcp

With AI Analysis Features

pip install "quarto-typst-mcp[ai]"

Full Installation (All Features)

pip install "quarto-typst-mcp[all]"

Development Installation

git clone https://github.com/KazPhD/quarto-typst-mcp
cd quarto-typst-mcp
pip install -e ".[dev,ai]"

Quick Start

As a Python Library

from quarto_typst_mcp import QuartoTypstConverter

# Convert a Quarto document to Typst
converter = QuartoTypstConverter()
typst_content = await converter.convert(
    input_file="paper.qmd",
    template="article"
)

# Render to PDF
pdf_path = await converter.render_pdf(typst_content)

Enhanced HTML with Plotly

from quarto_typst_mcp import QuartoProcessor
from quarto_typst_mcp.plotly import InteractivePlotlyHtmlGenerator

# Process Quarto document with Plotly charts
processor = QuartoProcessor()
doc = await processor.process_file("document.qmd")

# Generate interactive HTML
html_generator = InteractivePlotlyHtmlGenerator()
html_doc = await html_generator.generate(doc, interactive=True)

As an MCP Server

from quarto_typst_mcp.mcp import create_server

# Start the MCP server
server = create_server()
await server.run()

CLI Usage

# Convert Quarto to Typst
quarto-typst-mcp convert input.qmd -o output.typ

# Generate interactive HTML with Plotly
quarto-typst-mcp convert input.qmd --html --interactive

# Start MCP server
quarto-typst-mcp serve --port 8080

🤖 AI-Powered Chart Analysis (NEW!)

Automated insights generation with comprehensive cost tracking:

✨ Features

• 📊 Automated Chart Analysis: Extract insights from line, bar, pie, and complex charts
• 💰 Cost-Effective: Uses gpt-4o-mini by default (~$0.36 per 1,000 reports)
• 🎯 Token Tracking: Real-time monitoring with budget controls
• 📈 Batch Processing: Analyze multiple reports concurrently
• 🔄 Priority Ordering: Process critical reports first when budget-limited
• 📝 Multiple Outputs: JSON, Markdown, and HTML summaries

Example Usage

# Single chart analysis
from quarto_typst_mcp.ai_analysis import ChartAnalyzer, ChartData

analyzer = ChartAnalyzer(model="gpt-4o-mini")

chart = ChartData(
    chart_type="line",
    title="Revenue Growth",
    data={"series": [{"name": "Q4 Revenue", "y": [42.3, 45.1, 48.7]}]},
    context={"currency": "USD millions"}
)

result = await analyzer.analyze_chart(chart, analysis_type="business")
print(f"Insights: {result.content}")
print(f"Cost: ${result.estimated_cost:.6f}")

Batch Analysis with Budget Control

from quarto_typst_mcp.ai_analysis import BatchAnalyzer

batch_analyzer = BatchAnalyzer()
results = await batch_analyzer.analyze_reports_batch(
    report_paths=[Path("report1.html"), Path("report2.html")],
    budget_usd=1.00,  # $1 budget = ~2,000 reports
    priority_order=["clinical", "business"]
)

Cost Estimation

📊 Enhanced Plotly Integration

Revolutionary 100x improvements for data visualization:

Features

• 🧠 AI-Powered Chart Recommendations: Automatically suggests optimal chart types
• ⚡ Performance Optimization: Multi-level caching and WebGL acceleration
• 🔒 Secure Execution: Sandboxed code execution for safety
• 🎨 Interactive Controls: Download, fullscreen, zoom, and export capabilities
• 📱 Responsive Design: Professional styling that works on all devices

Example Usage

# AI-recommended visualization
from quarto_typst_mcp.plotly import PlotlyEngine
import pandas as pd

engine = PlotlyEngine()
data = pd.read_csv("data.csv")

# AI will recommend the best chart type
result = await engine.execute_plotly_code("""
import plotly.express as px
# AI analyzes data structure and suggests optimal visualization
fig = px.scatter(data, x='x', y='y', color='category')
""", data={'data': data})

MCP Tools Available

The MCP server provides the following tools for AI agents:

• create_document: Generate new documents from templates
• convert_quarto: Convert Quarto files to Typst format
• render_typst: Compile Typst documents to PDF
• analyze_document: Extract structure and metadata
• update_content: Modify existing documents

Templates

Pre-built Typst templates included:

• Article: Academic papers and journal articles
• Report: Technical reports and documentation
• Presentation: Slides and presentations

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/yourusername/quarto-typst-mcp
cd quarto-typst-mcp

# Install with development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests

pytest

Code Quality

# Format code
ruff format

# Lint code
ruff check

# Type checking
mypy src

📁 Examples

Check out the examples/ directory for:

Sample Reports

• piq_unified_dashboard.html: Complete PIQ-style analytics dashboard with theme switching
• clinical_drug_trends.html: Comprehensive pharmaceutical pipeline analysis
• piq_style_business_report.html: Business metrics with interactive charts

AI Analysis

• ai_analysis/analyze_reports.py: Complete demo of AI-powered chart analysis
• ai_analysis/README.md: Detailed documentation and cost analysis

Core Functionality

• plotly_demo.py: Complete Plotly integration showcase
• jupyter_plotly_demo.ipynb: Interactive Jupyter notebook demo
• demo.py: Basic package functionality
• example.qmd: Sample Quarto document

Documentation

Full documentation is available at https://quarto-typst-mcp.readthedocs.io

Contributing

Contributions are welcome! Please see our for details.

License

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

Acknowledgments

• Built on top of the excellent Typst typesetting system
• Uses FastMCP for Model Context Protocol implementation
• Inspired by Quarto for scientific and technical publishing
• Enhanced with Plotly for world-class interactive visualizations