Context Mapper MCP Server

An MCP (Model Context Protocol) server that enables AI assistants to work with Domain-Driven Design models using Context Mapper's CML (Context Mapping Language).

Features

• Parse and serialize CML files - Full support for Context Mapper's CML syntax
• Manage bounded contexts - Create, update, delete bounded contexts
• Work with aggregates - Define entities, value objects, domain events, commands, and services
• Context map relationships - Define and manage relationships between bounded contexts (Partnership, SharedKernel, Upstream-Downstream with patterns like OHS, PL, ACL, CF)
• Generate PlantUML diagrams - Visualize context maps and aggregate structures
• Real-time validation - Catch errors at creation time, not at save time
• ID Value Objects - Dedicated tool for creating DDD-compliant identifier types

Validation Features

The server validates models in real-time to prevent common CML errors:

| Validation | When | Example Error | |------------|------|---------------| | Duplicate names | On create | 'AgentId' already exists in ContextA... | | Invalid types | On create | Map<K,V> is not supported in CML... | | Reserved names | On create | 'Resource' is a reserved keyword... | | Reserved attributes | On save | Auto-escaped with ^ prefix |

Valid Attribute Types

• Primitives: String, int, long, boolean, DateTime, BigDecimal, UUID
• Collections: List<Type>, Set<Type>
• References: - TypeName (reference to domain objects)

Invalid Types (Rejected)

• Map<K,V>, Any, Tuple, Runnable, Callbacks, nested generics

Installation

Claude Code

claude mcp add context-mapper -- npx -y context-mapper-mcp

Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "context-mapper": {
      "command": "npx",
      "args": ["-y", "context-mapper-mcp"]
    }
  }
}

Available Tools

Model Management

| Tool | Description | |------|-------------| | cml_create_model | Create a new empty CML model | | cml_load_model | Load a CML file | | cml_save_model | Save model to disk | | cml_validate_model | Validate CML syntax and semantics | | cml_get_model_info | Get model statistics |

Query Tools

| Tool | Description | |------|-------------| | cml_list_bounded_contexts | List all bounded contexts | | cml_get_bounded_context | Get context details | | cml_list_aggregates | List aggregates (optionally filtered by context) | | cml_get_aggregate | Get aggregate with all its elements | | cml_find_elements | Search by name pattern (regex) | | cml_list_relationships | List context map relationships |

Context Tools

| Tool | Description | |------|-------------| | cml_create_context_map | Create a context map | | cml_create_bounded_context | Create a bounded context | | cml_update_bounded_context | Update a bounded context | | cml_delete_bounded_context | Delete a bounded context |

Aggregate Tools

| Tool | Description | |------|-------------| | cml_create_aggregate | Create an aggregate | | cml_update_aggregate | Update an aggregate | | cml_delete_aggregate | Delete an aggregate | | cml_add_entity | Add entity to aggregate | | cml_add_value_object | Add value object | | cml_add_identifier | Add ID value object (DDD best practice) | | cml_add_domain_event | Add domain event | | cml_add_command | Add command | | cml_add_service | Add domain service | | cml_batch_add_elements | Batch create multiple domain objects in one call | | cml_delete_entity | Delete entity | | cml_delete_value_object | Delete value object | | cml_delete_domain_event | Delete domain event | | cml_delete_command | Delete command | | cml_delete_service | Delete service |

Batch Creation (cml_batch_add_elements)

Create multiple domain objects in a single call for improved efficiency:

{
  "contextName": "CustomerManagement",
  "aggregateName": "Customer",
  "identifiers": [
    { "name": "CustomerId" }
  ],
  "entities": [
    {
      "name": "Customer",
      "aggregateRoot": true,
      "attributes": [
        { "name": "id", "type": "- CustomerId", "key": true },
        { "name": "email", "type": "String" }
      ]
    }
  ],
  "valueObjects": [
    {
      "name": "Address",
      "attributes": [
        { "name": "street", "type": "String" },
        { "name": "city", "type": "String" }
      ]
    }
  ],
  "domainEvents": [
    { "name": "CustomerRegistered", "attributes": [{ "name": "customerId", "type": "- CustomerId" }] }
  ],
  "commands": [
    { "name": "RegisterCustomer", "attributes": [{ "name": "email", "type": "String" }] }
  ]
}

Benefits:

• Faster: Single round-trip instead of 8+ individual calls
• Atomic validation: All elements validated before any are created
• Error handling: Use failFast: false to collect all errors at once

Relationship Tools

| Tool | Description | |------|-------------| | cml_create_relationship | Create context map relationship | | cml_update_relationship | Update relationship | | cml_delete_relationship | Delete relationship | | cml_get_relationship | Get relationship details |

Supported relationship types:

• Partnership - Symmetric, both contexts cooperate
• SharedKernel - Symmetric, shared code/models
• UpstreamDownstream - Asymmetric with patterns:
  • Upstream: OHS (Open Host Service), PL (Published Language)
  • Downstream: ACL (Anticorruption Layer), CF (Conformist)

Generation Tools

| Tool | Description | |------|-------------| | cml_generate_context_map_diagram | Generate PlantUML context map | | cml_generate_aggregate_diagram | Generate aggregate class diagram | | cml_generate_full_diagram | Generate full model diagram |

Example CML File

ContextMap ECommerceContextMap {
    type = AS_IS
    contains CustomerManagement, OrderManagement, Inventory

    CustomerManagement [U,OHS,PL] -> [D,ACL] OrderManagement
    OrderManagement [U] -> [D,CF] Inventory
}

BoundedContext CustomerManagement {
    domainVisionStatement = "Manages customer data"
    implementationTechnology = "TypeScript"

    Aggregate Customer {
        Entity Customer {
            aggregateRoot
            key String customerId
            String email
            String firstName
        }

        ValueObject Address {
            String street
            String city
        }

        DomainEvent CustomerRegistered {
            String customerId
            Date registeredAt
        }

        Command RegisterCustomer {
            String email
            String firstName
        }
    }
}

Development

git clone https://github.com/thijs-hakkenberg/contextmapper_mcp.git
cd contextmapper_mcp
npm install
npm run build
npm test

Architecture

• Parser: Chevrotain-based lexer and parser for CML syntax
• Writer: Serializes model back to CML format
• Validation: Checks model consistency and semantic rules
• Tools: MCP tool implementations for all operations
• Generators: PlantUML diagram generators

License

MIT