heraldic-blazonry-mcp

Heraldic Blazonry MCP Server

A Model Context Protocol server that translates heraldic blazon descriptions into visual generation parameters using 900 years of compositional refinement from the heraldic tradition.

Overview

This MCP server enables AI systems to work with formal heraldic descriptions (blazons) and translate them into structured visual parameters for image generation. Rather than forcing users to learn visual design vocabulary, they can use the time-tested language of heraldry that has precisely specified coat of arms designs since the 12th century.

Core Insight

Heraldic blazon syntax already is a categorical olog:

• Types: Tinctures, Ordinaries, Charges, Attitudes, Positions
• Morphisms: Placement rules (chief/base/dexter/sinister), counterchanging, marshalling
• Composition: Quarters, impalement, escutcheon follow associative composition laws

When a herald says "Azure, a lion rampant Or," they're invoking a formal compositional system that automatically generates:

• Color specifications (Azure = #0047AB, Or = #FFD700)
• Shape and attitude parameters (lion in rearing pose)
• Layout and positioning (centered, large scale)
• Style rendering rules (following heraldic conventions)

Installation

# Clone the repository
git clone https://github.com/dmarsters/heraldic-blazonry.git
cd heraldic-blazonry

# Install dependencies
pip install -e .

# For development with tests
pip install -e ".[dev]"

Usage

As MCP Server

Configure in your MCP client (e.g., Claude Desktop):

{
  "mcpServers": {
    "heraldic-blazonry": {
      "command": "python",
      "args": ["-m", "heraldic_blazonry.server"]
    }
  }
}

Available Tools

1. blazon_to_parameters

Translate heraldic blazon into visual generation parameters.

# Example: Classic English lion
blazon_to_parameters(
    blazon="Azure, a lion rampant Or",
    style="medieval"
)

# Returns:
{
    "field": {
        "tincture": "azure",
        "color": "#0047AB",
        "color_name": "blue"
    },
    "charges": [{
        "type": "lion",
        "attitude": "rampant",
        "tincture": "#FFD700",
        "description": "lion rearing up on hind legs"
    }],
    "composition_grid": {...},
    "style_modifiers": {
        "texture": "hand_painted_vellum",
        "line_quality": "confident_brush_strokes",
        "gold_treatment": "leaf_gilding_with_burnish"
    },
    "prompt_components": {...}
}

Supported Styles:

• medieval: Hand-painted vellum, gilded gold, flat heraldic
• victorian: Engraved crosshatch, technical precision, subtle depth
• modern_minimal: Clean vector, geometric, pure flat design

2. validate_blazon

Check if blazon follows heraldic composition rules.

validate_blazon("Or, a lion rampant Argent")

# Returns:
{
    "valid": False,
    "tincture_rule_compliant": False,
    "violations": [{
        "rule": "tincture_rule",
        "description": "Metal on metal detected. Violates fundamental heraldic rule.",
        "severity": "error",
        "remedy": "Place metal charges on color fields"
    }]
}

Rules Checked:

• Tincture Rule: Metal must not touch metal, color must not touch color
• Ordinary Validity: Ordinaries must be recognized heraldic forms
• Field Specification: Proper field tincture or division

3. compose_blazons

Compose two coats of arms using traditional marshalling methods.

compose_blazons(
    primary_blazon="Gules, a castle Or",
    secondary_blazon="Argent, a lion rampant Purpure",
    method="quarterly"
)

# Returns:
{
    "method": "quarterly",
    "quarters": {
        "1": {"position": "upper_dexter", "blazon": "Gules, a castle Or", ...},
        "2": {"position": "upper_sinister", "blazon": "Argent, a lion...", ...},
        "3": {"position": "lower_dexter", "blazon": "Argent, a lion...", ...},
        "4": {"position": "lower_sinister", "blazon": "Gules, a castle Or", ...}
    },
    "layout_grid": "2x2"
}

Marshalling Methods:

• quarterly: Divide shield into 4 quarters, alternating arms (used for grand quarters of inheritance)
• impalement: Split shield vertically (traditionally for marriage)
• escutcheon: Small shield overlaid on main shield (for inheritance or office)

4. get_tincture_palette

Get complete heraldic color palette with hex codes.

get_tincture_palette()

# Returns:
{
    "metals": {
        "or": {"color": "#FFD700", "name": "gold"},
        "argent": {"color": "#F5F5F5", "name": "silver/white"}
    },
    "colors": {
        "gules": {"color": "#DC143C", "name": "red"},
        "azure": {"color": "#0047AB", "name": "blue"},
        ...
    },
    "furs": {...},
    "tincture_rule": {...}
}

5. list_charges

List available heraldic charges with properties.

list_charges(category="natural")

# Returns:
{
    "natural": {
        "lion": {"category": "beast", "default_attitude": "rampant"},
        "eagle": {"category": "bird", "default_attitude": "displayed"},
        ...
    }
}

6. get_intentionality_principles

Get the "why" behind heraldic design rules.

get_intentionality_principles()

# Returns:
{
    "visibility": {
        "principle": "Arms must be identifiable at distance on battlefield",
        "implementation": "High contrast, clear shapes, tincture rule"
    },
    "symbolic_hierarchy": {...},
    "marshalling_logic": {...},
    "temporal_coherence": {...}
}

Blazon Syntax Examples

Simple Arms

"Azure, a lion rampant Or"
→ Blue field with gold lion rearing up

"Argent, three roses Gules"
→ White field with three red roses

"Gules, a castle Or"
→ Red field with gold castle

With Ordinaries

"Azure, a chevron Or"
→ Blue field with gold chevron

"Argent, a chief Gules"
→ White field with red top section

"Per pale Or and Azure, a cross counterchanged"
→ Vertical split gold/blue with cross swapping colors

Quartered Arms

"Quarterly, 1st and 4th Gules a castle Or, 2nd and 3rd Argent a lion rampant Purpure"
→ Four-part shield alternating castles and lions (arms of Spain)

Heraldic Composition Rules

The Tincture Rule

Principle: Metal must not touch metal, color must not touch color.

Metals: Or (gold), Argent (silver) Colors: Gules (red), Azure (blue), Vert (green), Sable (black), Purpure (purple)

Why: Ensures maximum visibility and contrast for battlefield identification. A metal charge on a metal field would blend together at distance.

Exception: Furs (ermine, vair) can touch anything.

Precedence Hierarchy

Blazon descriptions follow a strict order:

1. Field tincture
2. Field division (per pale, quarterly, etc.)
3. Ordinaries (by size, largest first)
4. Charges (by position, dexter before sinister)
5. Modifications (armed, langued, crowned, etc.)

Positional Terms

• Dexter: Viewer's left (bearer's right) - position of honor
• Sinister: Viewer's right (bearer's left)
• Chief: Upper portion of shield
• Base: Lower portion of shield
• Fess Point: Center point of shield

Attitudes (for animate charges)

• Rampant: Rearing up on hind legs (aggressive, powerful)
• Passant: Walking, right paw raised (in motion, vigilant)
• Sejant: Sitting (at rest, observant)
• Displayed: Wings spread, facing viewer (majestic, protective) - for birds
• Couchant: Lying down, head raised (watchful, patient)

Theoretical Framework

Three-Layer Olog Architecture

Layer 1: Categorical Structure (blazon_olog.yaml)

• Types: Tinctures, Divisions, Ordinaries, Charges, Attitudes
• Morphisms: Placement, Arrangement, Modification
• Composition rules: Tincture rule, precedence, marshalling

Layer 2: Intentionality Reasoning

• Visibility principle: Battlefield identification requirements
• Symbolic hierarchy: Position and size communicate importance
• Marshalling logic: Preserving lineages in combined arms
• Temporal coherence: Formal syntax enables exact reproduction across centuries

Layer 3: MCP Implementation

• FastMCP server with tool decorators
• YAML olog parser
• Visual parameter compiler
• Validation and composition engines

Why This Works

1. 900 years of refinement: The tincture rule, positioning conventions, and marshalling logic have been battle-tested (literally) for maximum clarity and symbolic coherence.

1. Categorical composition is built-in: Quartering follows associative composition laws—you can quarter quartered arms recursively while maintaining coherence.

1. Expert-to-novice translation: Someone who knows "Azure, a lion rampant Or" doesn't need to learn "deep blue background, golden lion in rearing pose, medieval heraldic style"—the formal syntax carries all that information.

1. Reproducible across time: A blazon written in 1300 CE can be rendered today with the same visual result, because the compositional logic is explicit and formal.

1. Multi-domain applicability: The same compositional principles apply to marshalling (combining arms), dimidiation (splitting arms), and augmentation (adding honors).

B2B Applications

Law Firms

Specify firm heraldry in formal blazon language rather than art-directing designers. Ensure consistent rendering across letterhead, websites, court documents.

Universities

Maintain historically accurate representations of institutional arms. Enable automatic generation of college/department variants through quartering and marshalling.

Municipalities

Encode civic arms in formal blazon for consistent reproduction across signage, official documents, promotional materials.

Genealogical Research

Translate textual blazon descriptions from historical records into visual reconstructions. Validate arms against heraldic rules.

Heraldic Authorities

Automate initial validation of proposed arms against tincture rule and composition standards. Generate visualizations for grant documents.

Testing

Run the comprehensive test suite:

# Run all tests
pytest

# Run with coverage
pytest --cov=heraldic_blazonry --cov-report=html

# Run specific test category
pytest tests/test_server.py::TestBlazonParsing

Test coverage includes:

• 75+ tests across unit, integration, and acceptance scenarios
• Parsing validation for all heraldic elements
• Tincture rule enforcement
• Marshalling composition logic
• Real historical examples (England, Castile, León, France)
• Edge cases and error handling

FastMCP Cloud Deployment

Configuration

1. Create fastmcp.yaml:

name: heraldic-blazonry
runtime: python
entrypoint: heraldic_blazonry.server:mcp

1. Deploy:

fastmcp deploy

1. The server will be available at your FastMCP Cloud endpoint.

Deployment Best Practices

Based on lessons learned from previous deployments:

1. Flattened Structure: All logic embedded in server.py avoids asyncio conflicts from complex import chains
2. Absolute Imports: Use heraldic_blazonry.module_name style imports
3. YAML in Package: Config files live in the package directory for reliable path resolution
4. Redeploy After Changes: Configuration changes require redeployment to propagate
5. Verify Logs: Check FastMCP Cloud logs for initialization messages

Project Structure

heraldic-blazonry/
├── heraldic_blazonry/
│   ├── __init__.py
│   ├── server.py              # Flattened MCP server with all logic
│   └── blazon_olog.yaml       # Categorical structure specification
├── tests/
│   ├── __init__.py
│   └── test_server.py         # Comprehensive test suite
├── pyproject.toml             # Python package configuration
└── README.md

Future Enhancements

Phase 2: Extended Syntax Support

• Full CFG parser for complex blazon grammar
• Support for lines of partition (engrailed, wavy, embattled)
• Cadency marks (for family branch differentiation)
• Augmentations and abatements

Phase 3: Visual Rendering

• Direct SVG/PNG generation from blazon
• Integration with ComfyUI workflows
• Shield shape variations (heater, lozenge, oval)
• Crest and supporter rendering

Phase 4: Validation Service

• Official heraldic authority rule checking
• Similarity detection (avoiding duplicates)
• Historical accuracy verification
• Regional tradition compliance

Contributing

Contributions welcome! Key areas:

• Extended blazon parser for complex syntax
• Additional historical charge designs
• Regional heraldic tradition variants
• Direct rendering implementations

License

MIT License - See LICENSE file

Academic Context

This work positions as "epistemological infrastructure" for reproducible intention transfer. The formal syntax of heraldry demonstrates how expert domains already contain structured compositional languages that can be systematically mapped to visual parameters.

Key Insight: Rather than treating visual generation as unstructured "prompt engineering," we can identify domains with proven compositional logic (like heraldry) and build compilers that preserve expert intentionality across the semantic-to-sensory boundary.

References

• Spivak, D. I. (2014). Category Theory for the Sciences. MIT Press.
• Boutell, C. (1863). Heraldry, Historical and Popular.
• Fox-Davies, A. C. (1909). A Complete Guide to Heraldry.
• Nisbet, A. (1722). A System of Heraldry.

Author

Dal Marsters GitHub: @dmarsters

Project Status

Production-ready v0.1.0 - Deployed on FastMCP Cloud