ddd-domain-mcp

stdio MCP server that searches a DDD domain model in one tool call.

It does not index source code and it does not run DDD.
codebase-memory indexes repos. The ddd-platform-modeling skillset then writes docs/domain-model/*.json. This server queries those JSON files.

Use it so an agent can answer “find 10 use cases of cart” without opening contexts/*/use-cases.json one file at a time.

How the graph and search work

The DDD skill still writes the usual shard files (contexts/*/aggregates.json, use-cases.json, the context map, and so on). Those files stay the source of truth.

Creating domain-graph.json. compile reads those shards and turns each domain thing into a node (a context, aggregate, command, event, use case, …). A link is added only when a field already points at another thing, for example a use case’s commands_invoked or an event’s emitted_by_aggregate. The id is {context}/{type}/{name}, so uc-001 in two contexts does not collide. A name that does not match any node is listed under unresolved and is not turned into a fake edge. Search does this same build in memory when the file is missing or older than the shards. It does not write the file.

How a search walks. The question is split into words. Filler words are dropped. Each node is scored by its name: an exact name ranks far above a name that only contains the word. The top matches become seeds, and a rare word still gets its own seed so one exact hit cannot hide the rest. From each seed the walk goes two hops. Each hop follows edges that leave the node and edges that point into it. Nodes it never touches are left out. If two seeds never meet, the result is two separate clusters, not a made-up bridge.

Prerequisite

A domain model on disk, usually:

docs/domain-model/
  platform-manifest.json
  context-map.json
  process-map.json
  ubiquitous-language.json
  contexts/{slug}/use-cases.json
  contexts/{slug}/aggregates.json
  ...

If that folder is missing, the MCP process still starts. Tool calls return an error that tells the user to install ddd-platform-modeling and run the DDD skill.

Install the skillset in the project that owns the model:

cd /path/to/your-project
npx git+ssh://[email protected]/awesome-cursor-skills-v2/awesome-cursor-skills-v2.git install ddd-platform-modeling

Then run the DDD skill so JSON exists under docs/domain-model.

Install

npm:

npx -y ddd-domain-mcp
# or
npm install -g ddd-domain-mcp

From git:

git clone https://git.rolustech.com/ddd-domain-mcp/ddd-domain-mcp.git
cd ddd-domain-mcp
npm install
npm run build

Requires Node.js 20+ (Node 24 LTS recommended).

Cursor (stdio)

Project .cursor/mcp.json in the repo that contains docs/domain-model:

{
  "mcpServers": {
    "ddd-domain": {
      "command": "npx",
      "args": ["-y", "ddd-domain-mcp"],
      "env": {
        "DOMAIN_MODEL_ROOT": "docs/domain-model"
      }
    }
  }
}

DOMAIN_MODEL_ROOT is resolved from the workspace cwd. Absolute paths also work.

Restart MCP (or Cursor) after changing mcp.json.

Tools

Always search_domain first. It returns a subgraph (nodes and edges). Call get_neighbors or shortest_path to expand, and get_entities only if you need the full record.

Each search_domain call rebuilds the graph in memory when domain-graph.json is missing or older than the shard JSON. It does not write that file, and it does not write the HTML page.

To see the picture, generate the files yourself:

npx ddd-domain-mcp compile

That writes domain-graph.json, views/html/graph.html, and views/html/search-demo.html. Open the HTML files in a browser. Run compile again after the shards change if you want the pages to match. Search stays current either way.

search-demo.html plays that walk on the full map. Presets are a coupon (one cluster), SEO catalog refresh (one connected region), add-to-cart (three areas), and SEO versus payments (both found, no edge between them). Hover a dot to see its name.

Do not write scripts or Read/grep docs/domain-model JSON — that is what these tools are for.

search_domain

| Argument | Required | Notes | |---|---|---| | query | yes | Text to match. * lists up to 3 seeds and does not walk. | | types | no | use_case, gap, aggregate, command, query, event, integration, context, process, term, relationship | | context_slug | no | Only this bounded context | | kind | no | e.g. use-case command | query | reactive | | min_confidence | no | low | medium | high | | mode | no | bfs (default) or dfs | | depth | no | Default 2, max 4. * uses 0. | | budget | no | Approximate token cap. Default 2000. | | format | no | json (default) includes nodes, edges, and text. Other names return the walk text. |

JSON includes seeds, nodes, edges, and text (NODE / EDGE lines). Edges point both directions from the seed.

get_neighbors

| Argument | Required | Notes | |---|---|---| | id | yes | Global id or label | | relation | no | Filter, e.g. invokes |

--> is outbound, <-- is inbound.

shortest_path

| Argument | Required | Notes | |---|---|---| | from | yes | Label or global id | | to | yes | Label or global id |

uc-001 is per context. Prefer a global id: cart-quote/use_case/uc-001.

get_entities

| Argument | Required | Notes | |---|---|---| | ids | yes | [{ type, id, context_slug? }, …] or a global id in id | | fields | no | Columns. One id defaults to all fields; several ids default to a compact row. * or all = everything | | format | no | Same as search_domain | | limit / offset | no | Page over ids (default 50, cap 500) |

context_slug is required when the same id exists in two contexts.

Agent usage

Using the ddd-domain MCP, find 10 use cases related to cart.

One search_domain call. get_entities only for extra fields on chosen hits.

Publish to npm

npm login
npm publish --access public

prepublishOnly runs tests and build. The published tarball contains dist/, README.md, LICENSE, and CHANGELOG.md (bin: ddd-domain-mcp).

Source: https://git.rolustech.com/ddd-domain-mcp/ddd-domain-mcp

Development

npm install
npm test
npm run build

Tests use the fixture under test/fixtures/domain-model.

Do not write to stdout except MCP JSON-RPC. Logs go to stderr.

License

MIT