noit-mcp-server
This MCP server lets AI agents manage NOit STAR architecture diagram pieces and generate the interactive documentation viewer.
Create new STAR diagram pieces with slug, title, source function path, group, inputs, dependencies, and outputs.
Update existing diagram pieces, including metadata or rebuilding the diagram spokes from supplied lists.
List all diagram pieces with metadata such as file, slug, title, function path, group, path, and existence.
Read a diagram piece's content by filename.
Build the interactive HTML viewer and overview, either as a dry-run to a temp directory or written next to the live files.
The README also documents an
audit_diagramstool for drift checks and Docs Sync Score, but it is not present in the provided server schema.
Manages Markdown-based architecture documentation pieces, allowing agents to create, read, list, and update diagram source files while keeping Markdown as the source of truth.
Creates and updates STAR-style Mermaid diagram pieces and generates an interactive HTML viewer with pan, zoom, and fullscreen support for every Mermaid diagram.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@noit-mcp-server create a new diagram piece for the payment service"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
NOit Documenting Data Flow
STAR diagram pieces → interactive viewer + overview
By NOit — Architecture documentation that stays in sync.
What It Does
┌─────────────────────────────────────────────────────────────────┐
│ YOU WRITE THIS (once per function) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ docs/architecture/diagrams/01-api-gateway.md │ │
│ │ ```mermaid │ │
│ │ graph LR │ │
│ │ hub["⚙️ handle_request()"]:::hub │ │
│ │ in1["📥 HTTP Request"]:::input │ │
│ │ dep1["🤖 Auth Service"]:::dep │ │
│ │ out1["💾 Response + Logs"]:::output │ │
│ │ in1 --> hub --> dep1 ==> out1 │ │
│ │ ``` │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ GENERATOR CREATES THIS (automatically) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ docs/architecture_diagrams.html ← Interactive viewer │ │
│ │ docs/architecture/OVERVIEW.md ← High-level index │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘Source of truth = Markdown pieces. Never hand-edit the HTML.
Related MCP server: Principal Architect Service
Features
Feature | Description |
🎯 STAR Pattern | Hub-and-spoke: function = center, inputs/deps/outputs = spokes |
🌙 Dark Theme | Consistent palette across MkDocs + generated viewer |
🔍 Interactive | Pan, zoom, fullscreen, fit-to-screen on every diagram |
📱 Responsive | Works on mobile, tablets, desktop |
🏷️ Grouped Nav | Filter by Infra / Ops / Sequences (configurable) |
🤖 MCP Server | AI agents can create/update diagrams via tools |
💻 VS Code Extension | Sidebar tree to browse and toggle active pieces for the current chat |
📦 Zero Config | Drop into any MkDocs Material project |
🎨 Every Mermaid Interactive | All |
Quick Start
# Install
pip install noit-documenting-data-flow
# Or with MkDocs for full docs stack
pip install "noit-documenting-data-flow[docs]"
# Initialize in your project
noit-diagram-rollup init
# Add your first diagram piece
cp docs/architecture/diagrams/00-template.md docs/architecture/diagrams/01-my-api.md
# Edit 01-my-api.md with your function's data flow, then register it:
# add the file to .pages and to rollup.manifest.yml (file + group)
# Preview (dry-run to a temp dir), then write the live viewer
noit-diagram-rollup build
noit-diagram-rollup build --write --out-html docs/architecture_diagrams.html
# Serve docs
mkdocs serve
# Open http://127.0.0.1:8000/architecture_diagrams.htmlMCP Server (for AI Agents)
Run the MCP server to let AI agents manage your diagrams:
# Stdio transport (for Claude Code, etc.)
noit-mcp-server
# Or HTTP transport (streamable HTTP at /mcp; requires a bearer token)
export NOIT_MCP_TOKEN="$(openssl rand -hex 32)"
noit-mcp-server --transport http --port 8765HTTP clients must send a bearer token in the Authorization header; without
NOIT_MCP_TOKEN set, the server refuses to start.
Available Tools:
Tool | Description |
| Create a new STAR diagram piece from template |
| Update an existing piece |
| List all pieces with metadata |
| Generate the interactive HTML viewer |
| Read a piece's content |
| Drift check vs source code — findings + Docs Sync Score (JSON) |
Keep Docs in Sync — Audit & Docs Sync Score
Inspired by loop engineering: docs stay
alive only if a loop keeps checking them. audit measures drift between your diagram pieces
and the code they document, and reports a Docs Sync Score (10–100):
noit-diagram-rollup audit
Docs Sync Score: 85/100 [IN SYNC]
Pieces audited: 6
[FINDINGS]
[STALE] 03-generator.md: src/generator.py changed after this piece was last updatedCheck | Finding | Meaning |
Source exists |
| Hub references a file that is gone |
Freshness |
| Source committed after the piece was last touched |
Registration |
| Piece on disk but missing from the manifest |
Manifest integrity |
| Manifest lists a piece that doesn't exist |
Hub format |
| Hub label has no |
Score bands: 80+ in sync · 50–79 drifting · <50 out of sync.
Freshness uses git commit times (mtime fallback outside a repo). The hub label's second line
(hub["⚙️ name<br/>src/path.py"]) is what ties a piece to its source — keep it accurate.
Rollout, loop-engineering style
L1 — report: run
noit-diagram-rollup auditlocally;--jsonfor scripts.L2 — gate: enforce in CI once the score stabilizes:
# .github/workflows/docs-sync.yml (step) - run: pip install noit-documenting-data-flow - run: noit-diagram-rollup audit --fail-under 80L3 — agent loop: agents call the
audit_diagramsMCP tool post-merge, update stale pieces, and rebuild the viewer — the docs never rot.
VS Code Extension
A companion extension lives in vscode-extension/ and gives the editor a sidebar tree of all your STAR pieces, grouped by infra / ops / seq. Each piece has a checkbox; toggling it writes the path to .claude/diagrams-active.md, a hand-editable Markdown sidecar. A single command — NOit: Inject Active Diagrams into Chat — pastes @path lines for the active set into the prompt, so the agent sees exactly the pieces you marked.
The sidecar is the source of truth, not the tree: the agent can @-reference .claude/diagrams-active.md directly even if the extension isn't running. See vscode-extension/README.md for setup, configuration, and the file layout.
Project Structure (after init)
your-project/
├── mkdocs.yml # Add: extra_javascript/css for interactive mermaid
├── docs/
│ ├── architecture_diagrams.html # GENERATED - interactive viewer
│ ├── architecture/
│ │ ├── diagrams/
│ │ │ ├── .pages # Nav order (awesome-pages)
│ │ │ ├── rollup.manifest.yml # Groups + badges
│ │ │ ├── 00-template.md # STAR template (copy this)
│ │ │ ├── 01-your-function.md # Your pieces go here
│ │ │ └── mermaid-style.md # Dark palette reference
│ │ └── OVERVIEW.md # GENERATED - high-level index
│ ├── javascripts/
│ │ └── mermaid-interactive.js # Makes ALL mermaid fences interactive
│ └── stylesheets/
│ └── mermaid-interactive.css # Dark theme for interactive diagrams
├── vscode-extension/ # Optional: sidebar tree for active pieces
└── .claude/
├── diagrams-active.md # Active set (managed by extension, hand-editable)
└── skills/
└── documenting-data-flow/
└── SKILL.md # Skill definition for agentsConfiguration (noit.yml)
Optional, at the project root. Every key is optional and defaults to the paths shown:
diagrams_dir: docs/architecture/diagrams
out_html: docs/architecture_diagrams.generated.html
out_overview: docs/architecture/diagrams/OVERVIEW.generated.mdThe CLI and the MCP server (and so the VS Code extension) all read it; CLI flags still win.
STAR Diagram Template
graph LR
%% ── STAR hub: the ONE function this piece documents ──
hub["⚙️ FUNCTION_NAME<br/>src/path/to/module.py"]:::hub
%% ── Spoke: inputs (data the function reads) ──
subgraph In["📥 Inputs"]
in1["INPUT_SOURCE_1<br/>where it comes from"]:::input
in2["INPUT_SOURCE_2"]:::input
end
%% ── Spoke: dependencies (services / models it calls) ──
subgraph Deps["🤖 Dependencies"]
dep1["LLM / API / Cache"]:::dep
svc1["EXTERNAL_SERVICE"]:::extSvc
end
%% ── Spoke: outputs (data it writes / emits) ──
subgraph Out["💾 Outputs"]
out1["OUTPUT_SINK<br/>store / snapshot / preview"]:::output
end
%% ── Streaming edges: in → hub → out ──
in1 -->|"what flows"| hub
in2 --> hub
hub <-->|"read / write"| dep1
hub -->|"query"| svc1
hub ==>|"result"| out1
classDef hub fill:#4A148C,stroke:#CE93D8,color:#F3E5F9,stroke-width:3px
classDef input fill:#37474F,stroke:#78909C,color:#CFD8DC,stroke-width:1px
classDef dep fill:#0D47A1,stroke:#42A5F5,color:#BBDEFB,stroke-width:1px
classDef extSvc fill:#E65100,stroke:#FFB74D,color:#FFF3E0,stroke-width:2px
classDef output fill:#1B5E20,stroke:#66BB6A,color:#C8E6C9,stroke-width:2pxRules:
One function = one hub = one piece (
.mdfile)Use
<br/>for line breaks (never\n)Use edge vocab:
-->direct,==>pipeline,-.->async/optional,<-->bidirectionalRegister in
.pages(nav order) androllup.manifest.yml(group + badge)
MkDocs Integration
Add to your mkdocs.yml:
extra_javascript:
- javascripts/mermaid-interactive.js
extra_css:
- stylesheets/mermaid-interactive.css
plugins:
- awesome-pages # enables .pages nav
- roamlinks # enables [[wikilinks]]
markdown_extensions:
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_formatCLI Reference
noit-diagram-rollup --help
Commands:
init Initialize diagram structure in current project
build Build viewer + overview (dry-run by default)
validate Validate all pieces have valid mermaid + required fields
audit Audit pieces for drift vs source code (Docs Sync Score)
Options:
--diagrams-dir PATH Diagrams folder (default: docs/architecture/diagrams)
--manifest PATH Manifest file (default: <diagrams-dir>/rollup.manifest.yml)
--out-html PATH Output HTML (default: docs/architecture_diagrams.generated.html)
--out-overview PATH Output overview (default: docs/architecture/diagrams/OVERVIEW.generated.md)
--write Write to real paths (default: dry-run to temp dir)
--template PATH Viewer template (default: built-in dark template)MCP Tools Reference
{
"create_diagram_piece": {
"slug": "my-api-handler",
"title": "API Request Handler",
"function_path": "src/api/handler.py",
"group": "ops",
"inputs": [{"id": "req", "label": "HTTP Request", "description": "JSON + headers"}],
"dependencies": [{"id": "auth", "label": "Auth Service", "type": "extSvc"}],
"outputs": [{"id": "resp", "label": "HTTP Response", "description": "JSON + status"}]
}
}Manifest Groups
Use these conventional group IDs in rollup.manifest.yml:
infra(badge:infra)ops(badge:ops)seq(badge:seq)
Contributing
git clone https://github.com/Yuki-az-23/noit-VP-MCP
cd noit-VP-MCP
pip install -e ".[dev]"
ruff check . && ruff format --check . && mypy src && pytestSee docs/CONTRIBUTING.md and docs/SECURITY.md.
License
MIT — © 2024 NOit
Built by NOit — Making architecture documentation effortless since 2024.
🌐 noit2.com | 📧 az@zagent.live
Available Tools
5 toolsbuild_viewerC
Generate the interactive HTML viewer + overview
Inputs: write.
create_diagram_pieceC
Create a new STAR diagram piece from template
Inputs: slug (required), title (required), function_path (required), group, +3 more.
get_diagram_pieceC
Read a diagram piece's content
Inputs: file (required).
list_diagram_piecesA
List all diagram pieces as a JSON array of {file, slug, title, function_path, group, file_path, exists}
Inputs: no named parameters.
update_diagram_pieceA
Update an existing diagram piece. title/function_path/group are changed in place. If any of inputs/dependencies/outputs is given, the diagram is rebuilt from the given lists, so pass all spokes the piece should keep.
Inputs: file (required), group, title, inputs, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool maps to a distinct operation in the diagram-piece lifecycle: create, list, get, update, and a separate build_viewer for HTML generation. The only mild overlap is that update_diagram_piece does both field edits and full rebuilds, but the description flags this clearly.
Four tools follow a clean verb_noun pattern with a consistent 'diagram_piece(s)' object (create/list/get/update_diagram_piece). build_viewer slightly breaks the pattern by omitting the domain noun, but remains a readable verb_noun name.
Five tools is lean but appropriate for a small domain of managing diagram pieces plus rendering a viewer. Nothing is redundant, though the surface is on the thin side and could use one more lifecycle operation.
Create, read (single and list), update, and viewer generation are covered, but there is no delete_diagram_piece, leaving a dead end for removing pieces. This is a notable CRUD gap an agent cannot work around with the existing tools.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to programmatically create and manage flowcharts, ERDs, and swimlane diagrams. It provides tools for manipulating diagram structures, performing auto-layouts, and exporting to Mermaid or Markdown formats.MIT
- AlicenseNot gradedqualityDmaintenanceA comprehensive MCP server for managing product initiatives, architecture decisions, requirements, and releases, enabling AI tools to interact with architectural documentation and planning.MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that enables AI assistants to programmatically create and manage use case diagrams (actors, use cases, subjects, relationships) in StarUML via a REST API.1MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that allows AI agents to manage BuildBase resources (users, workspaces, subscriptions, projects) via 48 tools, with built-in agent authentication and discovery.MIT