Workflow Generator

workflow-generator

Scan any project and generate WORKFLOW.html — a dark-mode visual system diagram showing every component, how they talk to each other, and where your throughput ceiling actually is.

Works with Python, Node.js, Go, Java, Rust, Ruby, and mixed projects. No external dependencies for the core scanner. Vendored and generated directories (node_modules, venv, site-packages, dist, …) are never scanned, and capacity figures are clearly labeled as static-analysis estimates.

Live demo → — generated from fastapi/full-stack-fastapi-template, unmodified.

(real CLI output, unscripted — static screenshot if you'd rather not autoplay)

What it produces

Every generated page contains:

Codebase dependency graph

Every source file (Python, JS/TS, Go, Java, Rust, Ruby) becomes a node; every real import becomes an edge — resolved with a language-appropriate parser (Python's ast module, regex for JS/TS/Go/ Java/Rust/Ruby), not guessed. Files that match an already-detected component (an LLM call, a database client, a queue) get an edge to that component too, so you can see exactly which files talk to Redis, OpenAI, etc. Large repos (350+ files) are automatically aggregated into directory-level nodes so the graph stays readable; override with --graph-detail files or --graph-detail dirs.

Test files (tests/, test_*.py, conftest.py, *.spec.ts, *_test.go, …) get their own Test Graph section below the main one, showing which modules and services each test reaches. Fixtures and test doubles name every service they exercise, so keeping them in the main graph buries the real dependency structure under service edges.

Both sections have a Flow | Graph toggle over the same nodes and edges. Flow (the default up to 80 nodes) is a left-to-right layered diagram: columns are dependency depth from the sources (HTTP entry and files nothing imports), every detected service is its own node in the last column, and import cycles are drawn dashed. Graph is the force-directed view. Moving dots show data going both ways: a filled dot is the call/request, a hollow dot the return/response. On graphs with more than 60 edges, only the paths of the clicked or hovered node animate. Search, "hide isolated" and the selected node are shared between the two views.

The older layered Full System Architecture diagram is collapsed by default, since the Architecture Map covers the same ground.

By default the graph only shows what the code says (import direction, static "this file calls Redis"), which is honest but not the same as real traffic. Pass --access-log /path/to/access.log (any combined/common log format) to overlay real observed request counts onto the HTTP-entry edges — and the generated report includes a ready-to-run k6 load-test script covering up to 5 detected routes, so the "Practical throughput" number can be checked against a real measurement instead of only a static-analysis estimate.

What it detects

Install

pip (CLI + MCP server)

pip install workflow-generator-mcp

workflow-generator . WORKFLOW.html       # CLI: scan and write the report
workflow-generator-mcp                    # stdio MCP server

With pip installed, any MCP host config reduces to:

{
  "mcpServers": {
    "workflow-generator": { "command": "workflow-generator-mcp" }
  }
}

Claude Code (skill)

mkdir -p ~/.claude/skills
git clone https://github.com/askuma/workflow-generator.git ~/.claude/skills/workflow-generator

Then in any Claude Code session:

/workflow-generator
/workflow-generator /path/to/project

MCP server (Claude Desktop, VS Code, Cursor, Zed, Windsurf, Continue)

1. Install the dependency:

pip install mcp

2. Add to your MCP host config (replace ~ with your actual home path):

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (Mac)
%APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "workflow-generator": {
      "command": "python3",
      "args": ["~/.claude/skills/workflow-generator/mcp/server.py"]
    }
  }
}

VS Code

.vscode/mcp.json

{
  "servers": {
    "workflow-generator": {
      "type": "stdio",
      "command": "python3",
      "args": ["~/.claude/skills/workflow-generator/mcp/server.py"]
    }
  }
}

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "workflow-generator": {
      "command": "python3",
      "args": ["~/.claude/skills/workflow-generator/mcp/server.py"]
    }
  }
}

Zed

.zed/settings.json

{
  "context_servers": {
    "workflow-generator": {
      "command": {
        "path": "python3",
        "args": ["~/.claude/skills/workflow-generator/mcp/server.py"]
      }
    }
  }
}

Windsurf

~/.windsurf/mcp_config.json

{
  "mcpServers": {
    "workflow-generator": {
      "command": "python3",
      "args": ["~/.claude/skills/workflow-generator/mcp/server.py"]
    }
  }
}

3. Restart your tool, then ask:

generate a workflow diagram for this project
how many concurrent requests can this handle?
show me the system architecture

MCP tools exposed:

• generate_workflow — scans project, writes WORKFLOW.html, optionally opens in browser
• analyze_workflow — returns structured JSON summary (no file written)

Command line (standalone)

No install needed beyond Python 3.8+:

python3 ~/.claude/skills/workflow-generator/scripts/analyze.py . ~/WORKFLOW.html
# then open ~/WORKFLOW.html

Optional flags:

--access-log /path/to/access.log   # overlay real request counts onto the dependency graph
--graph-detail auto|files|dirs     # force file-level or directory-level graph nodes (default: auto)

Example output (terminal)

Written: /your/project/WORKFLOW.html
Framework: FastAPI · Workers: 8 · Concurrent I/O: ~800
Practical throughput: ~50–200 req/min
Bottleneck: OpenAI (LLM latency 3–30s per call)
Gateway: nginx · 2 rate limit zone(s)
LLM: OpenAI · eval: TruLens RAG Triad
Storage: Qdrant, Redis
External sources: Jira, Azure DevOps, Slack

Repo layout

workflow-generator/
├── SKILL.md                        ← Claude Code skill definition
├── INSTALL.md                      ← detailed per-platform install guide
├── workflow_generator_mcp/
│   ├── analyze.py                  ← core scanner + HTML renderer (stdlib only)
│   └── server.py                   ← MCP stdio server (package form)
├── scripts/
│   └── analyze.py                  ← thin compatibility shim -> workflow_generator_mcp/analyze.py
├── tests/                          ← pytest suite for the scanner
├── mcp/
│   ├── server.py                   ← MCP stdio server
│   └── requirements.txt            ← pip install mcp
└── copilot/
    ├── index.js                    ← GitHub Copilot Extension (Express)
    ├── package.json
    └── openai_function.json

License

MIT