quillmark-mcp by nibsbin - MCP Server

Quillmark MCP Server

A Model Context Protocol (MCP) server that exposes Quillmark's document rendering capabilities to AI models and MCP clients.

Overview

The Quillmark MCP server enables AI assistants to:

Discover available document templates (Quills)
Understand template requirements and frontmatter schemas
Validate document frontmatter before rendering
Render markdown documents to PDF or SVG formats
Receive rich error diagnostics to help users fix issues

Installation

Run with uvx (recommended):

uvx quillmark-mcp

# Using uv (recommended)
uv pip install quillmark-mcp

# Using pip
pip install quillmark-mcp

Quick Start

Running the Server

# Run using Python module
python -m quillmark_mcp

# Or using uv
uvx quillmark-mcp

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "quillmark": {
      "command": "python",
      "args": ["-m", "quillmark_mcp"]
    }
  }
}

Available Tools

1. `list_quills`

List all registered Quill templates with metadata.

{}

Returns:

{
  "quills": [
    {
      "name": "taro",
      "backend": "typst",
      "description": "",
      "tags": []
    },
    {
      "name": "usaf_memo",
      "backend": "typst",
      "description": "",
      "tags": []
    }
  ]
}

2. `get_quill_info`

Get detailed information about a specific Quill template.

{
  "quill_name": "taro"
}

Returns frontmatter schema, required fields, and the example markdown content.

3. `get_markdown_template`

Get markdown template content by template name from the templates collection.

{
  "template_name": "U.S. Air Force Memo"
}

Returns the markdown content of the specified template from list_markdown_templates.

4. `list_markdown_templates`

List available markdown templates from the templates.json manifest.

{}

Returns:

{
  "templates": [
    {
      "name": "U.S. Air Force Memo",
      "description": "AFH 33-337 compliant official memorandum for the U.S. Air Force."
    },
    {
      "name": "U.S. Space Force Memo",
      "description": "Official memorandum template for the U.S. Space Force."
    }
  ]
}

5. `render_document`

Render a markdown document to PDF or SVG.

{
  "markdown": "---\nQUILL: taro\nauthor: John\nice_cream: Taro\ntitle: My Favorite\n...",
  "output_format": "PDF"
}

The quill_name parameter is optional if the markdown contains a QUILL: directive in the frontmatter.

6. `validate_frontmatter`

Validate frontmatter without rendering.

{
  "markdown": "---\nQUILL: taro\nauthor: John\n..."
}

Returns validation status and any missing required fields.

7. `save_rendered_file`

Save a rendered document from cache to a local file. Use this after render_document to save the file to disk.

{
  "resource_uri": "quillmark://render/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "file_path": "/path/to/output.pdf"
}

Returns success status and file information:

{
  "success": true,
  "file_path": "/absolute/path/to/output.pdf",
  "file_size": 12345,
  "mime_type": "application/pdf",
  "format": "PDF"
}

Note: This tool is particularly useful when running the MCP server locally, allowing Claude Code and other clients to save rendered documents directly to your filesystem.

Usage Examples

AI-Assisted Document Writing

User: "Help me create a document using the taro template"

AI Workflow:

Call list_quills() to discover available quill templates
Call get_quill_info("taro") to learn requirements and get the example markdown
Generate markdown based on user's input
Call validate_frontmatter() to check correctness
Call render_document() to produce the final PDF (returns base64 data + resource_uri)
Call save_rendered_file() with the resource_uri to save the PDF to the user's filesystem

Note: For general-purpose templates like "U.S. Air Force Memo", use:

Call list_markdown_templates() to discover available templates
Call get_markdown_template("U.S. Air Force Memo") to get the template content
Modify the template for the specific use case
Call render_document() to produce the final PDF

Error Handling

The server provides rich diagnostics when errors occur:

{
  "success": false,
  "error_type": "ValidationError",
  "error_message": "Required fields missing",
  "diagnostics": [
    {
      "severity": "ERROR",
      "message": "Required field 'recipient' is missing",
      "code": "missing_field",
      "hint": "Add 'recipient: <value>' to your frontmatter"
    }
  ]
}

Extended YAML Metadata Standard

Quillmark supports structured content with the Extended YAML Metadata Standard:

QUILL key: Specifies which template to use
SCOPE key: Creates collections of content blocks

Example:

---
title: Product Catalog
---

Main description.

---
SCOPE: products
name: Widget
price: 19.99
---

Widget description.

---
SCOPE: products
name: Gadget
price: 29.99
---

Gadget description.

Architecture

┌──────────────────────────────┐
│       AI Model / Client      │
│    (via MCP protocol)        │
└──────────────┬───────────────┘
               │ MCP JSON-RPC
               ▼
┌──────────────────────────────┐
│     Quillmark MCP Server     │
│  - list_quills               │
│  - get_quill_info            │
│  - get_quill_template        │
│  - render_document           │
│  - validate_frontmatter      │
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│    Quillmark Engine          │
│  (Python package)            │
└──────────────────────────────┘

Design Principles

MCP-Native: Follows MCP protocol specifications
Rich Diagnostics: Provides helpful error messages with hints
Stateless: Each tool call is independent
JSON-Based: All data exchanged via JSON for compatibility

Development

Setup

# Clone the repository
git clone https://github.com/nibsbin/quillmark-mcp.git
cd quillmark-mcp

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

Testing

# Run tests
pytest

# Run type checking
mypy src/quillmark_mcp

# Run linting
ruff check src/quillmark_mcp

Security Considerations

Input Validation: Markdown size limits, YAML depth limits
Output Safety: Binary outputs are base64-encoded
Read-Only: All MCP tools are read-only operations
Sandboxing: Consider running rendering in isolated environment

License

See LICENSE file for details.

References

MCP Specification
Quillmark Documentation
- Guide for saving rendered documents to your filesystem

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Status

Version: 0.1.0
Status: Implementation Phase
Python: 3.10+
Protocol: Model Context Protocol (MCP)