# 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

```bash
# 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):

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

### Available Tools

#### 1. `blazon_to_parameters`

Translate heraldic blazon into visual generation parameters.

```python
# 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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

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

3. **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.

4. **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.

5. **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:

```bash
# 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`:

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

2. Deploy:

```bash
fastmcp deploy
```

3. 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](https://github.com/dmarsters)

## Project Status

Production-ready v0.1.0 - Deployed on FastMCP Cloud