@cloud-arch/mcp-codeflow

MCP server that analyses TypeScript codebases via AST and visualises the call flow as an animated diagram on CloudArch. Built for the question "did the code my AI just generated actually do what I asked?" — point it at a project + entry method and you get a live URL where you can play through the flow and verify it matches your intent.

What it does

Given a TypeScript project (anything with a tsconfig.json) and an entry method/function, the analyser:

1. Walks every class and module-level function with ts-morph.
2. Builds a call graph by resolving this.x.method(), this.method(), and bare-identifier function calls (foo()) — including those reached via import.
3. Reachability-traces from your entry, dropping everything not actually called.
4. Lays groups out by architectural layer (controllers/services/repos/infra detected from file paths).
5. Renders one TopologyBuilder + FlowBuilder script and publishes it as an interactive CloudArch diagram.

Detects:

• Class methods + module-level functions (named functions, arrow functions assigned to const)
• Cross-class calls via constructor-injected dependencies (NestJS-flavour DI)
• Same-class private helpers
• Promise.all([...]) → rendered as a flow.parallel(...) step
• try/catch → calls inside the catch block render as showError('[CATCH] ...') (red)

Multiple entries → multiple scenarios on one diagram (player has scenario pills you flip between). Useful for "show me how every action on this controller works".

Tool

analyze_codeflow

| Param | Required | Description | |---|---|---| | projectPath | ✓ | Absolute path to the project root (the directory containing tsconfig.json). | | entry | ✓ | Entry point. Accepts: "ClassName.methodName", "ClassName.*" (all public methods as scenarios), "moduleName:funcName", "moduleName:*" (all functions of a module as scenarios). | | additionalEntries | optional | Extra entries (same syntax) rendered as additional scenarios on the same diagram. | | name / slug | optional | Display name / URL slug. Auto-generated from entry if omitted. | | isPublic | optional, default false | Whether the diagram is publicly visible. Defaults to private (your code is your business). |

Returns a URL like https://web.cloud-arch.ru/v/<slug> and stats: class/module group counts, methods, edges, flow steps, parallel blocks, catch edges, scenario count.

Usage

From Claude Code / any MCP client

Add to .mcp.json:

{
  "mcpServers": {
    "cloudarch-codeflow": {
      "command": "/abs/path/to/packages/mcp-codeflow/node_modules/.bin/tsx",
      "args": ["/abs/path/to/packages/mcp-codeflow/src/index.ts"],
      "env": { "CLOUDARCH_API_KEY": "ca_..." }
    }
  }
}

Get an API key at https://web.cloud-arch.ru/dashboard/api-keys.

Examples

Single entry:

analyze_codeflow(
  projectPath: "/abs/path/to/repo",
  entry: "OrderController.createOrder"
)

All actions of a controller as scenarios:

analyze_codeflow(
  projectPath: "/abs/path/to/repo",
  entry: "OrderController.*"
)

Compare two specific flows side by side:

analyze_codeflow(
  projectPath: "/abs/path/to/repo",
  entry: "OrderController.createOrder",
  additionalEntries: ["OrderController.cancelOrder"]
)

Function entry (for non-OOP code):

analyze_codeflow(
  projectPath: "/abs/path/to/repo",
  entry: "userHandlers:registerUser"
)

Sample projects

Two TypeScript samples live next to the analyser at tools/poc-codeflow/:

• sample-project/ — minimal 6-class createOrder flow (the original POC).
• sample-project-complex/ — 14-class controller + services + repos + infra, with Promise.all, try/catch, and multiple entry points (createOrder, cancelOrder). Use this to regression-test changes.

Run analysis through the MCP tool against either of these. Expected stats for sample-project-complex with OrderController.*:

14 class group(s) + 0 module group(s), 27 callables, 30 edges
2 scenarios (31 total flow steps), 1 parallel block(s), 1 catch edge(s)

Out of scope (current limits)

The analyser is intentionally conservative — better to miss an edge than draw a wrong one. Patterns it does NOT yet trace:

• if/else branch markers in animation (both branches' calls do appear as edges, just not labelled as branches)
• super.method() and inheritance — call resolves to the declared class, not the actual runtime override
• Decorator-based DI (NestJS @Inject, Angular providers) — only constructor-typed parameters are followed
• Callbacks where the callable is held in a variable and indirected through middleware
• Method calls where the receiver isn't this or a class member (e.g. store.method() where store is a hook return value) — these are skipped
• Languages other than TypeScript (Kotlin / Java / Python — own parsers needed; same DSL emission would work)

Architecture

packages/mcp-codeflow/
  src/
    analyzer.ts   # pure library: AST walk -> TopologyBuilder/FlowBuilder script string
    index.ts      # MCP server, calls analyzer + posts to CloudArch API
  tsconfig.json
  package.json

Library is independent of the MCP layer — analyzeCodeflow({ projectPath, entry }) returns either { ok: true, script, stats } or { ok: false, error, hint }. Easy to wire into a CLI or a CI check separately.

Spec

Original design and POC validation: docs/superpowers/specs/2026-05-04-code-flow-analyzer-poc-design.md.