contextmapper-mcp

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
• Bounded Context Canvas - Create DDD Crew Bounded Context Canvases (v5), derived from the model and enriched with canvas-only sections
• HTML artifacts - Interactive, self-contained HTML context map linked to an HTML canvas per bounded context (works offline, no Java needed)
• 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@latest

Claude Desktop

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

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

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
cml_generate_context_map_html	Generate an interactive HTML context map plus a linked canvas page per context

Bounded Context Canvas Tools

Tool	Description
cml_set_bounded_context_canvas	Set canvas sections CML cannot express (strategic classification, domain roles, business decisions, assumptions, verification metrics, open questions, extra collaborators and terms)
cml_get_bounded_context_canvas	Get a context's canvas in the DDD Crew canonical format (JSON or YAML)
cml_generate_bounded_context_canvas	Write canvases as HTML pages or as DDD Crew YAML for one or all contexts

Canvas sections are filled from the model where possible:

Canvas section	Derived from
Purpose	domainVisionStatement
Inbound / outbound communication	Context map relationships: downstreams receive the domain events of the upstream's exposed aggregates (all aggregates when none are exposed); commands are attributed to downstreams only when aggregates are exposed explicitly. Relationship patterns (OHS, PL, ACL, CF, Partnership, Shared Kernel) become the relationship label.
Ubiquitous language	Aggregates, entities and value objects (identifier-only value objects are skipped), with their documentation as definition

Explicitly set entries take precedence over derived ones with the same collaborator or term. Canvas data is saved by cml_save_model to a sidecar file next to the model (model.cml → model.canvas.yaml) in the DDD Crew YAML format, one YAML document per bounded context, and loaded again by cml_load_model.

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, HTML context map and Bounded Context Canvas generators, Context Mapper CLI integration

License

MIT