Skip to main content
Glama
Sign In
noit-mcp-server

noit-mcp-server

by Yuki-az-23
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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 Authorization: Bearer $NOIT_MCP_TOKEN; without the variable 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

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

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"}]
  }
}

Groups: infra (badge: infra), ops (badge: ops), seq (badge: seq)

Configuration

Create noit-diagram-rollup.yaml in project root:

diagrams_dir: "docs/architecture/diagrams"
manifest: "rollup.manifest.yml"
title: "My Project Architecture Diagrams"
subtitle: "Generated from STAR pieces"
groups:
  - id: "infra"
    label: "Infrastructure"
    badge: "infra"
  - id: "ops"
    label: "Operations"
    badge: "ops"
  - id: "seq"
    label: "Sequences"
    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

This server cannot be deployed

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Maintenance

ActivitySlowing
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers