{
  "markdown": "# workflow-generator\n\n<!-- mcp-name: io.github.askuma/workflow-generator -->\n\nScan 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.\n\nWorks with Python, Node.js, Go, Java, Rust, Ruby, and mixed projects. No external dependencies for the core scanner.\nVendored and generated directories (`node_modules`, `venv`, `site-packages`, `dist`, …) are never scanned,\nand capacity figures are clearly labeled as static-analysis estimates.\n\n**[Live demo →](https://askuma.github.io/workflow-generator/)** — generated from\n[fastapi/full-stack-fastapi-template](https://github.com/fastapi/full-stack-fastapi-template), unmodified.\n\n![Running workflow-generator against fastapi/full-stack-fastapi-template, from pip install to the generated diagram](https://raw.githubusercontent.com/askuma/workflow-generator/main/docs/demo.gif)\n\n*(real CLI output, unscripted — [static screenshot](https://raw.githubusercontent.com/askuma/workflow-generator/main/docs/preview.png) if you'd rather not autoplay)*\n\n## What it produces\n\nEvery generated page contains:\n\n| Section | What you get |\n|---|---|\n| **Stat row** | Workers · Concurrent I/O ceiling · Semaphore limit · Rate limit · Practical throughput |\n| **Architecture diagram** | Layered flow: external sources → gateway → API → queues → AI → storage |\n| **Data flow cards** | Write path, read/query path, background jobs — inferred from what's detected |\n| **Concurrency table** | Every layer: model · ceiling · limiting factor |\n| **Bottleneck analysis** | Ranked CRITICAL → LOW with mitigation notes |\n| **Codebase dependency graph** | Force-directed module/import graph — click a node to isolate its neighbors, hover for file details. Import-direction edges are clearly distinguished from real observed traffic (see below) |\n| **Guided tour** | Spotlight walkthrough of every section, shown automatically the first time a report is opened; replay anytime with the `?` button |\n\n### Codebase dependency graph\n\nEvery source file (Python, JS/TS, Go, Java, Rust, Ruby) becomes a node; every real import becomes\nan edge — resolved with a language-appropriate parser (Python's `ast` module, regex for JS/TS/Go/\nJava/Rust/Ruby), not guessed. Files that match an already-detected component (an LLM call, a\ndatabase client, a queue) get an edge to that component too, so you can see exactly which files\ntalk to Redis, OpenAI, etc. Large repos (350+ files) are automatically aggregated into\ndirectory-level nodes so the graph stays readable; override with `--graph-detail files` or\n`--graph-detail dirs`.\n\nBy default the graph only shows what the *code* says (import direction, static \"this file calls\nRedis\"), which is honest but not the same as real traffic. Pass `--access-log /path/to/access.log`\n(any combined/common log format) to overlay real observed request counts onto the HTTP-entry\nedges — and the generated report includes a ready-to-run [k6](https://k6.io) load-test script\ncovering up to 5 detected routes, so the \"Practical throughput\" number can be checked against a\nreal measurement instead of only a static-analysis estimate.\n\n## What it detects\n\n| Category | Examples |\n|---|---|\n| API frameworks | FastAPI, Flask, Django, Express, Nest.js, Gin |\n| Gateways | nginx, Caddy, Traefik (with rate limits + worker_connections) |\n| LLM providers | OpenAI, Anthropic Claude, Cohere, AWS Bedrock |\n| Vector stores | Qdrant, Pinecone, Weaviate, ChromaDB, pgvector, FAISS, Milvus |\n| Databases | PostgreSQL, MySQL, MongoDB, SQLite, Redis |\n| Queues | Celery, BullMQ, Kafka, RabbitMQ, RQ, AWS SQS |\n| Async primitives | `asyncio.Semaphore`, `run_in_executor`, `asyncio.gather`, `asyncio.Lock` |\n| Workers | `--workers N` (uvicorn/gunicorn), `replicas:` (docker-compose), PM2 instances |\n| External sources | Jira, Azure DevOps, Slack, GitHub, Stripe, Salesforce, Twilio |\n| Evaluation | TruLens, RAGAS, LangSmith |\n\n---\n\n## Install\n\n### pip (CLI + MCP server)\n\n```bash\npip install workflow-generator-mcp\n\nworkflow-generator . WORKFLOW.html       # CLI: scan and write the report\nworkflow-generator-mcp                    # stdio MCP server\n```\n\nWith pip installed, any MCP host config reduces to:\n\n```json\n{\n  \"mcpServers\": {\n    \"workflow-generator\": { \"command\": \"workflow-generator-mcp\" }\n  }\n}\n```\n\n### Claude Code (skill)\n\n```bash\nmkdir -p ~/.claude/skills\ngit clone https://github.com/askuma/workflow-generator.git ~/.claude/skills/workflow-generator\n```\n\nThen in any Claude Code session:\n\n```\n/workflow-generator\n/workflow-generator /path/to/project\n```\n\n### MCP server (Claude Desktop, VS Code, Cursor, Zed, Windsurf, Continue)\n\n**1. Install the dependency:**\n```bash\npip install mcp\n```\n\n**2. Add to your MCP host config** (replace `~` with your actual home path):\n\n<details>\n<summary>Claude Desktop</summary>\n\n`~/Library/Application Support/Claude/claude_desktop_config.json` (Mac)  \n`%APPDATA%\\Claude\\claude_desktop_config.json` (Windows)\n\n```json\n{\n  \"mcpServers\": {\n    \"workflow-generator\": {\n      \"command\": \"python3\",\n      \"args\": [\"~/.claude/skills/workflow-generator/mcp/server.py\"]\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary>VS Code</summary>\n\n`.vscode/mcp.json`\n\n```json\n{\n  \"servers\": {\n    \"workflow-generator\": {\n      \"type\": \"stdio\",\n      \"command\": \"python3\",\n      \"args\": [\"~/.claude/skills/workflow-generator/mcp/server.py\"]\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary>Cursor</summary>\n\n`~/.cursor/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"workflow-generator\": {\n      \"command\": \"python3\",\n      \"args\": [\"~/.claude/skills/workflow-generator/mcp/server.py\"]\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary>Zed</summary>\n\n`.zed/settings.json`\n\n```json\n{\n  \"context_servers\": {\n    \"workflow-generator\": {\n      \"command\": {\n        \"path\": \"python3\",\n        \"args\": [\"~/.claude/skills/workflow-generator/mcp/server.py\"]\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary>Windsurf</summary>\n\n`~/.windsurf/mcp_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"workflow-generator\": {\n      \"command\": \"python3\",\n      \"args\": [\"~/.claude/skills/workflow-generator/mcp/server.py\"]\n    }\n  }\n}\n```\n</details>\n\n**3. Restart your tool, then ask:**\n```\ngenerate a workflow diagram for this project\nhow many concurrent requests can this handle?\nshow me the system architecture\n```\n\n**MCP tools exposed:**\n- `generate_workflow` — scans project, writes `WORKFLOW.html`, optionally opens in browser\n- `analyze_workflow` — returns structured JSON summary (no file written)\n\n### Command line (standalone)\n\nNo install needed beyond Python 3.8+:\n\n```bash\npython3 ~/.claude/skills/workflow-generator/scripts/analyze.py . ~/WORKFLOW.html\n# then open ~/WORKFLOW.html\n```\n\n**Optional flags:**\n\n```bash\n--access-log /path/to/access.log   # overlay real request counts onto the dependency graph\n--graph-detail auto|files|dirs     # force file-level or directory-level graph nodes (default: auto)\n```\n\n---\n\n## Example output (terminal)\n\n```\nWritten: /your/project/WORKFLOW.html\nFramework: FastAPI · Workers: 8 · Concurrent I/O: ~800\nPractical throughput: ~50–200 req/min\nBottleneck: OpenAI (LLM latency 3–30s per call)\nGateway: nginx · 2 rate limit zone(s)\nLLM: OpenAI · eval: TruLens RAG Triad\nStorage: Qdrant, Redis\nExternal sources: Jira, Azure DevOps, Slack\n```\n\n---\n\n## Repo layout\n\n```\nworkflow-generator/\n├── SKILL.md                        ← Claude Code skill definition\n├── INSTALL.md                      ← detailed per-platform install guide\n├── workflow_generator_mcp/\n│   ├── analyze.py                  ← core scanner + HTML renderer (stdlib only)\n│   └── server.py                   ← MCP stdio server (package form)\n├── scripts/\n│   └── analyze.py                  ← thin compatibility shim -> workflow_generator_mcp/analyze.py\n├── tests/                          ← pytest suite for the scanner\n├── mcp/\n│   ├── server.py                   ← MCP stdio server\n│   └── requirements.txt            ← pip install mcp\n└── copilot/\n    ├── index.js                    ← GitHub Copilot Extension (Express)\n    ├── package.json\n    └── openai_function.json\n```\n\n---\n\n## License\n\nMIT\n",
  "bytes": 8172,
  "sha": "46e0246f35dddc175c0b30fe62675534fa86eb73f9cba321ec78b2e3eb2e94db",
  "repo_slug": "askuma/workflow-generator",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_askuma_workflow_generator_fed83f38/readme"
}