Skip to main content
Glama
noit-mcp-server
by Yuki-az-23

NOit Documenting Data Flow

STAR diagram pieces → interactive viewer + overview
By NOit — Architecture documentation that stays in sync.

PyPI License: MIT Python

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 mermaid fences get pan/zoom automatically

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.html

MCP 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 8765

HTTP 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_diagram_piece

Create a new STAR diagram piece from template

update_diagram_piece

Update an existing piece

list_diagram_pieces

List all pieces with metadata

build_viewer

Generate the interactive HTML viewer

get_diagram_piece

Read a piece's content

audit_diagrams

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 updated

Check

Finding

Meaning

Source exists

missing_source

Hub references a file that is gone

Freshness

stale

Source committed after the piece was last touched

Registration

unregistered

Piece on disk but missing from the manifest

Manifest integrity

missing_file

Manifest lists a piece that doesn't exist

Hub format

no_source_ref

Hub label has no <br/>src/path.py line

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

  1. L1 — report: run noit-diagram-rollup audit locally; --json for scripts.

  2. 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 80
  3. L3 — agent loop: agents call the audit_diagrams MCP 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 agents

Configuration (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.md

The 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:2px

Rules:

  • One function = one hub = one piece (.md file)

  • Use <br/> for line breaks (never \n)

  • Use edge vocab: --> direct, ==> pipeline, -.-> async/optional, <--> bidirectional

  • Register in .pages (nav order) and rollup.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_format

CLI 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 && pytest

See 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 tools
build_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

    B3.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers