convez.ai
MCP ServerDesenvolvimento WebAvançado
abp2204

Roze - Motor de Análise Arquitetural

abp2204/roze

Análise arquitetural estática para mapeamento de DNA técnico em projetos

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que mapeia a estrutura e comportamento de codebases complexas usando análise estática pura com Tree-Sitter. Identifica componentes críticos, traça cadeias de chamadas e gera dossiês arquiteturais sem chamadas LLM, funcionando diretamente dentro do seu agente de codificação.

Instalação

$npx convez-ai abp2204/roze

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Onboarding em codebases complexas e legadas
  • Identificação de componentes críticos e dependências de alto impacto
  • Documentação automática de padrões arquiteturais e fluxos de chamadas
  • Análise de complexidade cognitiva para refatoração estratégica

Veredito

Ferramenta sólida para engenheiros que trabalham com codebases grandes, especialmente em TypeScript/Next.js. A análise estática sem dependência de LLM é valiosa, mas o escopo atual é restrito a JavaScript/TypeScript e requer entendimento técnico profundo para extrair máximo valor.

README

A tradução para o português deste README ainda está na fila.


roze is a high-fidelity static analysis engine and MCP server. It uses Tree-Sitter to extract the structural and behavioral patterns of a codebase—identifying high-gravity components, mapping semantic actions, and tracing call-chains between entrypoints and side effects.

While roze is built on a language-agnostic foundation, the current toolset is highly optimized for TypeScript and JavaScript (especially Next.js, Prisma, and tRPC environments).

Zero LLM calls. Zero API keys. Pure static analysis.

Your coding agent does all the thinking — roze just gives it the right data.

Install

npx roze install

That's it. This patches your coding agent's MCP config so it can call roze's tools. Restart your agent.

Running the Analysis

You don't need to write a complex prompt. roze provides a built-in MCP Prompt called build_dossier that automatically tells your agent exactly what to do.

In Claude Code / Gemini CLI: Type /prompt build_dossier and press enter.

In Cursor / Windsurf: Open the MCP panel or agent chat, select the build_dossier prompt from the roze server, and run it.

Your agent will loop through the high-gravity files, analyze each one, and build an Architectural Dossier — a structured set of Decision Cards explaining the technical rationale of the code.

Supported Agents

AgentConfig File
Claude Code~/.claude/claude_desktop_config.json
Gemini CLI~/.gemini/settings.json
Cursor~/.cursor/mcp.json
Windsurf~/.codeium/windsurf/mcp_config.json

How It Works

┌─────────────────────────────────────────────────────────┐
│  Your Coding Agent (Claude / Gemini / Cursor)           │
│                                                         │
│  "Scan this project" ──► scan_project ──► get_file_ctx  │
│                             │                  │        │
│  Agent synthesizes  ◄──────┘   ◄──────────────┘        │
│  narratives + diagrams                                  │
│       │                                                 │
│       ▼                                                 │
│  write_decision_card ──► .roze/dossier.json    │
│                               │                         │
│                               ▼                         │
│                    file:// Dossier UI                    │
└─────────────────────────────────────────────────────────┘

Three Levels of Analysis

  1. Level 0 — Semantic Classification: Maps files to architectural "pillars" (Auth, Payments, Database, etc.) using import-path heuristics and library signatures.

  2. Level 1 — Cognitive Complexity: Tree-Sitter AST analysis computes a complexity score per file based on link density, nesting depth, and mutation counts. Files scoring ≥ 15 are identified as High-Gravity.

  3. Level 2 — Behavioral Traceability: Tree-Sitter powered call-graph analysis. It maps function-level dependencies and identifies Critical Functions (entrypoints, semantic actions, or high-outbound callers) so your agent can trace the exact ripple effect of a code change.

MCP Tools

roze exposes 8 tools over MCP stdio:

ToolPurpose
scan_projectCall first. Scans the codebase, returns high-gravity files grouped by pillar. Starts file watcher.
get_file_contextReturns full source + import graph neighbors for a specific file.
write_decision_cardPersists a Decision Card (narrative + evidence + optional Mermaid diagram).
get_strategic_overviewReturns dossier state without evidence snippets (saves tokens).
inspect_pillarReturns all Decision Cards for a pillar with full evidence.
get_wild_discoveriesReturns the most complex files that don't fit standard patterns.
mark_staleMarks cards as stale when you modify files during a session.

Recommended Agent Workflow

1. scan_project → get high-gravity files
2. For each file: get_file_context → read source + neighbors
3. Synthesize: "WHY does this code exist?"
5. write_decision_card → persist the narrative
6. Share the file:// UI link with the user

How It Works

Deep Analysis Pipeline

Unlike simple regex scanners, roze runs a deterministic 13-stage pipeline—from AST inventory and alias resolution to semantic classification and function-level scoring—to ensure every Decision Card is grounded in actual code paths.

Semantic Rulesets

roze uses specialized rulesets to understand framework-specific semantics. Current optimizations include:

  • Next.js: Server Actions, cookies(), headers(), and App Router conventions.
  • Database: Prisma model mutations and raw query patterns.
  • API: tRPC procedure calls (mutate/query) and standard fetch/axios patterns.
  • Auth: Clerk, NextAuth, and custom rate-limiting/validation logic.

Dossier UI

After your agent writes Decision Cards, open the generated file in your browser:

file:///path/to/your/project/.roze/ui/index.html

The UI features:

  • Dark theme with glassmorphism and subtle grid texture
  • Pillar tabs for navigating architectural areas
  • Decision Cards with fresh/stale status badges
  • Mermaid diagrams rendered inline as SVG
  • Evidence sidebar with Shiki syntax highlighting (tokyo-night)
  • Wild Discoveries tab for the most complex outlier files
  • Works entirely offline via file:// — no server needed

Architecture

packages/
├── brain/           # @roze/brain — analysis engine
│   └── src/
│       ├── scanner.ts    # Tree-Sitter AST analysis (L0 + L1 + L2)
│       ├── dossier.ts    # Atomic persistence + UI regeneration
│       ├── graph.ts      # Import graph read/write
│       └── watcher.ts    # Chokidar file watcher
├── cli/             # roze — MCP server + CLI
│   └── src/
│       ├── index.ts          # #!/usr/bin/env node entry
│       ├── commands/
│       │   ├── install.ts    # Agent config patcher
│       │   └── serve.ts      # MCP server launcher
│       └── mcp/
│           ├── server.ts     # @modelcontextprotocol/sdk setup
│           └── tools/        # 7 tool handlers
└── ui/              # @roze/ui — React dossier viewer
    └── src/
        ├── App.tsx               # Main app (reads window.__ROZE_DOSSIER__)
        ├── components/           # Header, PillarTabs, DecisionCard, etc.
        └── index.css             # Design system

Key Design Decisions

  • No LLM calls: roze is a pure static analysis tool. The coding agent provides all synthesis.
  • async-mutex: All dossier writes are guarded by a mutex with atomic tmp+rename.
  • startOnLoad: false: Mermaid is initialized manually — never auto-scans the DOM.
  • base: './': Vite builds with relative paths so the UI works from file:// URLs.
  • console.log banned: Brain and CLI use only console.error to avoid corrupting MCP stdio.
  • Tree-Sitter WASM: Loaded from the tree-sitter-wasms npm package — no network calls.

Development

Prerequisites

  • Node.js ≥ 18
  • npm ≥ 9 (for workspaces)

Setup

git clone https://github.com/abp2204/roze.git
cd roze
npm install

Build

npm run build

This runs in sequence: brain → cli → ui → bundle-ui (copies UI dist into CLI dist).

Dev UI

npm run dev:ui

Starts the Vite dev server for the UI package at http://localhost:5173.

Test Install Locally

node packages/cli/dist/index.js install

Test MCP Server

node packages/cli/dist/index.js serve

Then send JSON-RPC messages over stdin (see MCP specification).

Publish

npm run release

Builds everything and publishes the roze CLI package to npm.

How the Dossier Stays Fresh

When scan_project runs, it starts a Chokidar file watcher. When source files change:

  1. The watcher detects the change
  2. Matching Decision Cards are marked stale (amber badge in UI)
  3. The stalePaths array in the dossier tracks which files need re-analysis
  4. Your agent can call get_strategic_overview to see what's stale, then re-scan

You can also manually mark files stale with mark_stale if you modify code during a session.

License

MIT

Ver o original no GitHub

Bom para

Relacionados