From 89f468478f60b96f56673a2132586c96bceeb81d Mon Sep 17 00:00:00 2001 From: Tomasz Zajac Date: Tue, 6 Oct 2026 14:04:22 +0200 Subject: [PATCH] docs(web): MCP server on the landing page and in the manual Landing page: a "Connect your agent" section with the build and `claude mcp add` commands, an MCP entry in "Also in the box", and the "Modelled by either" tile now points to MCP instead of editing the .radical file (the server works on Markdown folders only). Manual: a new "MCP server" section covering setup for Claude Code, Codex and Claude Desktop, working alongside Studio, the tool catalogue and its limits, plus links from the AI assistant, file formats and local install sections. Co-Authored-By: Claude Opus 5.5 --- apps/web/index.html | 29 +++++++++++++++++++- apps/web/landing.css | 2 ++ apps/web/manual.html | 65 +++++++++++++++++++++++++++++++++++++++++--- 3 files changed, 91 insertions(+), 5 deletions(-) diff --git a/apps/web/index.html b/apps/web/index.html index ee9f897d..500031d7 100644 --- a/apps/web/index.html +++ b/apps/web/index.html @@ -63,7 +63,7 @@

Architecture that lives here,
and holds whatever b
Modelled by either - Draw it in Studio, chat it with AI, or let an agent edit the .radical file. + Draw it in Studio, chat it with AI, or connect your agent over MCP.
@@ -114,6 +114,10 @@

Also in the box

AI that edits the model. Validated, undoable patches. Claude, OpenAI, Gemini or Ollama — your key, nothing proxied. +
  • + + MCP server. Claude Code, Claude Desktop or Codex read and edit a model folder with the same tools as Studio's assistant. +
  • Concept Hub. 120+ ready-made requirements, ADRs, patterns and blueprints. @@ -152,6 +156,29 @@

    Start from the Hub

    • + +
    +
    +

    Connect your agent

    +

    + A local MCP server gives Claude Code, Claude Desktop, Codex or any MCP client the model as tools: + read the summary and the metamodel rules, search, add and move elements, create views, sequences and slides, run Smart Layout. + Every write is checked against the metamodel, and Studio shows it on the open canvas. +

    +
    + Setup & tools → + Source → +
    +
    + 
    # Node.js ≥ 20, from the repository root
+npm run build -w @radical/mcp
+
+# point it at a Markdown model folder
+claude mcp add radical-folder -- node \
+  /path/to/radical.tools/apps/mcp/dist/index.js \
+  --folder /path/to/my-model
    +
    +
    diff --git a/apps/web/landing.css b/apps/web/landing.css index 1ef4c9a9..2432266b 100644 --- a/apps/web/landing.css +++ b/apps/web/landing.css @@ -224,6 +224,8 @@ main:not(.doc-main) > section { width: var(--w); margin: 0 auto; } .tile-n { margin-left: auto; font-family: var(--mono); font-size: 11px; color: var(--muted); } .tile-text { font-size: 12.5px; line-height: 1.5; color: var(--muted); } .tile-text b { color: var(--text-2); font-weight: 600; } +.tile-text a { color: var(--accent); } +.tile-text a:hover { text-decoration: underline; } /* ── Feature list ────────────────────────────────────────────────── */ .features { padding: 0 0 64px; } diff --git a/apps/web/manual.html b/apps/web/manual.html index ecf175c5..06572568 100644 --- a/apps/web/manual.html +++ b/apps/web/manual.html @@ -4,7 +4,7 @@ Docs — Radical.Tools - + @@ -80,6 +80,7 @@
  • Concept Hub
  • AI assistant
  • Radical Forge
    • +
  • MCP server
    • @@ -103,7 +104,7 @@

    Radical.Tools, explained

    One model of your architecture; every diagram, table and wiki page derived from it. This guide walks through modelling, the six view kinds, milestones, presentations, - files, the metamodel editor, the Concept Hub and the AI assistant. + files, the metamodel editor, the Concept Hub, the AI assistant and the MCP server that lets coding agents edit the model.

    Open Studio @@ -503,6 +504,7 @@

    AI assistant

  • Change the model — “add a Redis cache between the API gateway and the accounts service”. The answer is a patch (add / update / delete nodes and relations, add views) that is validated against the metamodel, applied atomically and undoable like any other edit.
  • Draft governance — turn a paragraph or a need into EARS requirements (linked back to the need) or an ADR with the right fields filled.
    • +

    The same tools are available outside Studio: the MCP server hands them to Claude Code, Claude Desktop, Codex or any other MCP client.

    @@ -517,6 +519,60 @@

    Radical Forge

    +
    +

    MCP server

    +

    + The MCP server lets a coding agent work on your model directly: Claude Code, Claude Desktop, Codex or any other client that speaks the Model Context Protocol. It runs locally over stdio, is bound to one Markdown folder, and offers the same tools as the AI assistant in Studio, so the agent can read the architecture, ADRs and requirements before it writes code and update the model when the design changes. Nothing leaves your machine except what your agent sends to its own provider. +

    +

    Set it up

    +

    Build it once with Node.js 20 or newer, from a clone of the repository (see local install):

    +
    npm install
+npm run build -w @radical/mcp
+node apps/mcp/dist/index.js --folder /absolute/path/to/my-model   # waits for MCP messages on stdin
    +

    Then register that command with your client, using absolute paths:

    +
    # Claude Code
+claude mcp add radical-folder -- node /path/to/radical.tools/apps/mcp/dist/index.js --folder /path/to/my-model
+
+# Codex
+codex mcp add radical-folder -- node /path/to/radical.tools/apps/mcp/dist/index.js --folder /path/to/my-model
    +

    For Claude Desktop, add it under mcpServers in ~/Library/Application Support/Claude/claude_desktop_config.json (on Windows %APPDATA%\Claude\claude_desktop_config.json) and restart the app. Give the full path to node, because the app does not see your shell's PATH:

    +
    {
+  "mcpServers": {
+    "radical-folder": {
+      "command": "/usr/local/bin/node",
+      "args": ["/path/to/radical.tools/apps/mcp/dist/index.js", "--folder", "/path/to/my-model"]
+    }
+  }
+}
    +

    Working alongside Studio

    +

    + Open the same folder in Studio: in the desktop app, or in a Chromium browser through Manage models… (the browser asks for folder access; a model kept only in browser storage cannot be reached by the server). Studio reloads the folder when the agent changes it, so new elements appear on the open canvas. Then ask the agent to call get_model_summary first; the server's instructions tell it to as well. +

    +
    + Tip: while the agent writes, keep Studio in Viewer. A change spans several files and the two processes share no lock: the server refuses to write over a file that changed since it read it, but editing the same folder from both sides at once can still race. +
    +

    Tools

    +
    + + + + + + + + + +
    GroupTools
    Readget_model_summary — counts, views, sequences, presentations and the metamodel rules (property keys and enum options, allowed parents, cardinality, allowed relation pairs) · search_model — the assistant's query language (LIST NODES WHERE …, GET NEIGHBORS, LIST SEQUENCES…)
    Elements & relationsadd_node, update_node, delete_node, move_node (change the parent) · add_relation, update_relation, delete_relation
    Viewscreate_view, update_view, set_view_nodes, delete_view · smart_layout for All elements or one view
    Sequences & slidescreate_sequence, update_sequence, delete_sequence · create_presentation, update_presentation, delete_presentation
    Metamodelupsert_node_type, delete_node_type, upsert_relation_type, delete_relation_type
    +
    +
      +
    • Validated like Studio. Writes go through the same schemas and metamodel rules as the editor; an invalid parent, type or relation pair is refused with a message the agent can act on. A tool reports success only after the files are written.
      • +
    • Placement. New elements land inside their parent and parents grow to fit; call smart_layout to tidy up. New elements show in All elements until a view lists them (create_view, set_view_nodes).
      • +
    • Metamodel edits. Changing a built-in metamodel saves it as a …-custom copy, like the Metamodel editor. The server then re-announces the element and relation tools with the new types.
      • +
    • Plain files. Unrelated files and the text of radical.md are left as they were, so the agent's changes show up as small Git diffs.
      • +
    +

    Single .radical files, milestones, canvas-only actions (switching or focusing the view in Studio) and remote HTTP connections are not supported.

    +
    +
    @@ -538,7 +594,7 @@

    Markdown folder

    ├─ metamodel.json · hubTemplates.json └─ _layout.json # positions & camera — the only noisy file

    - Each .md has YAML front-matter (id, type, label, then the element's properties, sorted) and the description as body. Hierarchy is the directory tree. Output is deterministic — sorted keys, stable file names — so Git diffs show what changed and nothing else. Edit the files by hand; the app picks them up. + Each .md has YAML front-matter (id, type, label, then the element's properties, sorted) and the description as body. Hierarchy is the directory tree. Output is deterministic — sorted keys, stable file names — so Git diffs show what changed and nothing else. Edit the files by hand, or let an agent edit them through the MCP server; the app picks them up.

    @@ -593,7 +649,8 @@

    Desktop app

    npm run dev # Electron, hot reload npm run build && npm start npm run dev:web # browser build of Studio -npm run dev:hub # Architecture Hub +npm run dev:hub # Architecture Hub +npm run build -w @radical/mcp # MCP server for coding agents

    The desktop app adds native file dialogs, Markdown folders without browser permissions and --file watching. Everything else is identical to the browser build.