mattes3/mcp4ddd

mcp4ddd

A monorepo containing an MCP server that generates code based on the Domain-Driven Design methodology, along with shared runtime utilities and a testbed for safe experimentation.

Matthias Bohlen wrote it so that students of his Domain-Driven Design classes get a jumpstart with DDD.

Core Purpose

This project provides an MCP (Model Context Protocol) server that scaffolds Domain-Driven Design (DDD) components including entities, value objects, repositories, and domain services. It uses Handlebars templates to generate TypeScript code with proper DDD patterns.

Key Features

• Generate DDD entities (optionally as aggregate roots)
• Generate value objects
• Generate repository interfaces
• Generate domain services (with optional transaction-aware repository support)
• Generate DynamoDB repository implementations
• Generate PostgreSQL repository implementations
• Automatic test file generation
• Zod schema validation for inputs

Installation

mcp4ddd consists of a generator file that you need to run on your machine as a NodeJS process.

The generated code depends on a very small runtime library that you will find in the NPM package @ddd-components/runtime.

Installing the MCP Server

Download the latest release from GitHub Releases and take the file index.js. You need to have NodeJS installed on your machine to be able to run it.

Installing the Runtime Library and further dependencies

Add this to your own project where the generated code will run:

npm install  @ddd-components/runtime ts-results-es zod

Usage

MCP Server

The MCP server provides tools for generating DDD components. It can be integrated with MCP clients like Claude Desktop.

Configure your MCP client to use the server:

{
    "mcpServers": {
        "ddd-scaffolder": {
            "command": "/bin/sh",
            "args": [
                "-c",
                "node ~/bin/mcp4ddd.js"
            ],
            "env": {
                "BASIC_TYPES_FROM": "@ddd-components/runtime",
                "BASIC_ERROR_TYPES_FROM": "@ddd-components/runtime",
                "DYNAMODB_CONFIG_FROM": "@ddd-components/runtime",
                "BOUNDED_CONTEXTS_PARENT_FOLDER": "packages/domainlogic"
            }
        }
    }
}

The AI assistant that you use with this MCP server will "see" that it can generate entities, value objects, services, and repositories. You can use the following environment variables to influence its behavior:

• The generated code will be written to subdirectories of BOUNDED_CONTEXTS_PARENT_FOLDER.
• The basic types that the generated code needs at runtime will be imported from BASIC_TYPES_FROM.
• The basic error types will be imported from BASIC_ERROR_TYPES_FROM.
• You can override these module names to fit your project environment.

Runtime Library

The runtime library @ddd-components/runtime provides utilities for the generated DDD components:

import type { Branded, SingleError, TechError, ValidationError } from '@ddd-components/runtime';

import { beginWith, singleError, techError, validationError } from '@ddd-components/runtime';

// Use in generated and in hand-written code

API Reference

MCP Tools

• generateEntity: Creates DDD entities with optional aggregate root
• generateValueObject: Generates immutable value objects
• generateRepository: Creates repository interfaces
• generateDomainService: Generates domain services with dependency injection and optional transaction-aware repository support
• generateDynamoDBRepository: Generates DynamoDB repository implementations using ElectroDB
• generatePostgreSQLRepository: Generates PostgreSQL repository implementations using Objection.js

Runtime Exports

• BasicErrorTypes: Error type definitions
• BasicModelTypes: Basic model utilities
• WorkflowStart: Workflow utilities

Environment Variables

The MCP server supports several environment variables to customize its behavior:

Contributing

We welcome contributions! Please see for details.

License

MIT - see for details.

Target Users

Developers implementing Domain-Driven Design in TypeScript projects who want to quickly scaffold DDD components with consistent patterns.