DocHub Architect Tool

English · Русский

An MCP server that helps transfer C4 diagrams from DrawIO and PlantUML into a DocHub architecture repository.

Code does the deterministic work: parsing diagrams, assembling the repository manifest, finding components to reuse, checking referential integrity, rendering, writing YAML, publishing. The meaning — which business function an element represents, which subdomain owns it, how scenarios split into contexts — comes from the agent working together with a person, because a diagram alone does not carry it.

What it gives you

• Parsing that works on real files. C4 attributes live on <object> wrappers, nesting is expressed by geometry rather than a parent attribute, and pages are often stored compressed. All of that is handled.
• Rejection of logical diagrams. A sequence or activity diagram describes behaviour, not composition; the server says so instead of guessing.
• Rendering by DocHub's own metamodel, taken from its plugin, so a context looks exactly as DocHub will draw it.
• A split-screen preview: the original diagram on the left, the generated one on the right, refreshed as the YAML changes.
• Ownership rules. A queue, a foreign API method or a stored procedure belongs in the file of the subdomain that owns it; your own file only references it.
• Research before questions. The brief reads the diagram, the domain model, the repository and the accumulated rules, and only what none of them answers is asked — with the source quoted.
• The repository is checked before the work, not after. Reachable, current, a work branch created — instead of discovering a divergence at push time.
• Accumulated knowledge. Decisions confirmed by the user are stored and reused, so the same conventions need not be explained again.

Requirements

What	Why	Without it
Python 3.10+	the server itself	required
Java 11+	rendering PlantUML	preview and context rendering unavailable
lib/plantuml.jar	rendering	fetched by setup_assets.py
vendor/dochub/	DocHub metamodel	ships with the project
vendor/viewer-static.min.js	drawing the original DrawIO	left preview pane stays empty
lib/elk/	ELK layout	falls back to smetana, wider diagrams
GITLAB_TOKEN	creating a merge request	the branch is pushed, the MR is made by hand

Install

Nothing installed on the machine? Build a portable archive — python tools/build_release.py packs a self-contained Windows x64 build with its own Python, Java and git, so the recipient installs nothing.

From source:

pip install -r requirements.txt
python setup_assets.py
cp .env.example .env

The second command downloads PlantUML and the drawio viewer. They are tens of megabytes and are not kept in git; after this everything runs offline. python setup_assets.py --check reports what is in place.

Configure

.env is the whole configuration; .env.example is the annotated template. The paths are the part you must fill in — the repository, the domain schema — the rest has working defaults:

DOCHUB_REPO_ROOT=C:/repos/architectural-repository
DOCHUB_DDD_PATH=C:/repos/architectural-repository/ddd.drawio
GITLAB_TOKEN=                       # only to create a merge request
DOCHUB_REMOTE_PROTOCOL=https        # or ssh — what your origin expects
DOCHUB_TARGET_BRANCH=main
DOCHUB_COMMIT_TEMPLATE=Добавление схемы {schema}
DOCHUB_MR_ASSIGNEE=                 # who owns the merge request
DOCHUB_AUTOMODE=false               # the agent goes to the MR on its own

An environment variable of the same name wins over the file, so a client can override one value without editing anything. dochub_workspace shows the result and says where each value came from. Full table: docs/USAGE.md.

automode is for people who do not work with architecture repositories: the agent answers the brief from defaults and accumulated rules, builds the schema, shows the preview and goes all the way to the merge request without asking for confirmation. Merging is never automatic — that stays a human decision.

Register in an MCP client

The server speaks MCP over stdio. Clients usually keep servers in an mcpServers object:

{
  "mcpServers": {
    "dochub": {
      "command": "python",
      "args": ["-m", "app.mcp_server"],
      "cwd": "<path to the project>"
    }
  }
}

A helper prints or writes this fragment without touching servers already registered:

python skills/dochub-architect/tools/install_mcp.py --print

Quick check

python -m app.mcp_server

The server writes a startup line to stderr and waits for input — stdout carries the protocol, so nothing else may go there. Stop with Ctrl+C.

python -m pytest

Documentation

• ARCHITECTURE.md — components, technologies, diagrams
• ROADMAP.md — status and boundaries
• docs/USAGE.md — the tools and how they work together
• skills/dochub-architect/ — the skill that teaches an agent the working order; it ships with the project
• workflows/ — the research phase as a parallel run for Claude Code, optional
• SECURITY.md — threat model and how to report a vulnerability

Support author

<p align="center"> <img src="donate-qr.png" alt="Donate QR" width="200"/> </p>

BTC: bc1q3frrup5neh7nhfg944etu2agd4j9u0vg3jyee6

ETH(Arbitrum): 0x43B349d8Cea83215D707EBa3bc35e9917f746b0a

TRX: THSzvy49KNeqRjXsGkurh2A5G4avV4RgN4

XRP: rLWZjS3DMupC4ZdXCX3BVYn4dEtC3iNhgy

SOL: 3xwfybxJ6Tz5t6pjBBkL5yYQCZo6wfbv932UNA4ThdP8

ADA: addr1q926ys75jp5wn2pv32a3t8r8pdhr7w02v0t9j4a8pmg0ruww5rlkctu4lnz2hfcwa5qfn3zhsd0s23r22uqwzx9gu6cq5c4e76

TON: UQC4qlAOD9Nly4K_66GJ_yCsSM3x2sB0vZ2GrBQbc--gZUui

DOGE: DTjNYmbtymzcjUiV4MsZY8MP4dM7MJ6qLC

XMR: 44qRqM6YtnxXUhkgCFqDDrKMPjWriu69FLBoop8Kwp7e1VQsBUJoVQ8JYQjfMV5C6uidTUgSSyoJ65mq8aYG2esZ1rrqfwt

Licence

MIT, see LICENSE. Everything this project redistributes and under what licence: THIRD-PARTY-NOTICES.md.