arch-viewer

MCP-native architecture viewer with AI-powered codebase analysis

Point arch-viewer at any codebase and get a living, AI-curated map of how it actually fits together. It scans your project, runs structured analysis through pydantic-ai, persists the result into a Neo4j knowledge graph, exposes 17 MCP tools to any MCP client (Claude Code, Cursor, your own agent), and serves a vanilla-JS dashboard with an interactive SVG architecture diagram you can hand to anyone. No SaaS, no telemetry, all local.

Why arch-viewer?

• vs. Mermaid / PlantUML — those are static diagrams you hand-write and forget. arch-viewer regenerates the picture every time your code changes, then asks an LLM to caption what it sees.

• vs. Structurizr / C4 tooling — Structurizr makes you author DSL by hand. arch-viewer derives components, data flows, and tech stack directly from AST analysis and lets you correct it; corrections persist into a memory store and shape future runs.

• vs. Sourcegraph / CodeSee — those are hosted, paid, and need to ingest your code in their cloud. arch-viewer is MIT-licensed, runs entirely on localhost (Neo4j + Qdrant in Docker, LLM call to the provider of your choice), and is free.

Demo

Screenshots live in docs/screenshots/ — drop your own in to replace the placeholders below.

Live dashboard at http://localhost:3777 — file tree, architecture score, AST analysis, AI summary, editor.

Standalone HTML diagram produced by the generate_interactive_diagram MCP tool — pan, zoom, click a node to see its files and routes.

Quick start

git clone https://github.com/axumquant/arch-viewer
cd arch-viewer
pip install -e .
python -m arch_viewer --web /path/to/your/project

Open http://localhost:3777. On first launch you'll be prompted for an LLM API key (OpenAI, Anthropic, Groq, or Ollama Cloud).

Docker Desktop must be running. arch-viewer auto-starts a local Neo4j and Qdrant container the first time it boots and waits for them to be healthy before serving requests.

Features

• Multi-language scanner — Python, JavaScript, TypeScript, Go, Rust, Java, and more. Discovers components, dependency files, API routes, and entry points.

• AI architecture analysis via pydantic-ai — structured ArchitectureSummary output from OpenAI, Anthropic, Groq, or Ollama Cloud.

• 17 MCP tools — drop into Claude Code, Cursor, or any MCP client and ask the model about your codebase directly.

• Neo4j knowledge graph — every component, dependency, and data flow is upserted per project. Browse it at http://localhost:7474.

• Mem0 semantic memory — corrections and patterns you teach the AI persist into Qdrant, scoped per project, and are re-injected before each analysis.

• Standalone interactive HTML diagrams — single self-contained file, pure SVG, no framework. Open it in any browser, ship it to a stakeholder, embed it in docs.

• Live file watching — WebSocket-pushed updates to the dashboard whenever a file changes.

• Built-in code editor with CodeMirror 6 syntax highlighting for Python, JS/TS, Go, Rust, JSON, YAML, Markdown.

• Architecture health score (0–100) across Modularity, Code Quality, Maintainability, and Structure, with anti-pattern detection (circular imports, god files, orphaned modules, etc.).

Prerequisites

• Python 3.11+

• Docker Desktop (running) — for the Neo4j + Qdrant stack, auto-bootstrapped on first launch

• At least one LLM API key — OpenAI, Anthropic, Groq, or Ollama Cloud

Installation

Option A — Quick (Docker stack + local Python)

git clone https://github.com/axumquant/arch-viewer
cd arch-viewer
docker compose up -d neo4j qdrant
pip install -e .
python -m arch_viewer --web

Option B — Development

git clone https://github.com/axumquant/arch-viewer
cd arch-viewer
pip install -e ".[dev]"
docker compose up -d neo4j qdrant
pytest
python -m arch_viewer --web

Option C — MCP integration with Claude Code

Add to .claude/settings.json (or ~/.claude/settings.json for a global server):

{
  "mcpServers": {
    "arch-viewer": {
      "command": "python",
      "args": ["-m", "arch_viewer"],
      "env": {
        "ARCH_VIEWER_ROOT": ".",
        "ARCH_VIEWER_PROVIDER": "anthropic"
      }
    }
  }
}

Restart Claude Code. The 17 arch-viewer tools will appear under the MCP servers list.

Configuration

Per-project API keys are persisted at <project>/.arch_viewer/keys.json (gitignored).

MCP tools

All 17 tools are registered in arch_viewer/mcp_server.py.

Usage examples

Scan from the CLI

# Live dashboard + MCP server (default)
python -m arch_viewer /path/to/project

# Dashboard only, custom port, no AI
python -m arch_viewer --web --port 4000 --no-ai /path/to/project

# One-shot JSON dump
python -m arch_viewer --scan /path/to/project > architecture.json

Call an MCP tool from Claude Code

Once arch-viewer is registered in settings.json, in Claude Code:

Use arch-viewer to show me the architecture score for this repo and list any anti-patterns ranked by severity.

Claude will invoke get_architecture_score and get_anti_patterns and explain the result.

Generate a standalone diagram

# Inside an MCP-enabled session, or via the REST API
POST /api/refresh
# then ask the agent:
# "Use generate_interactive_diagram with output_path=docs/architecture.html"

The output is a single .html file with embedded SVG, JS, and CSS — share it via email, embed it in a wiki, commit it to your docs folder.

Architecture

flowchart LR
    CLI["python -m arch_viewer"] --> Stack[stack.py<br/>bootstrap Docker]
    Stack --> Neo4j[(Neo4j)]
    Stack --> Qdrant[(Qdrant)]
    CLI --> Scanner[scanner.py<br/>multi-lang]
    Scanner --> Models[models.py<br/>Architecture]
    Models --> Agent[agent.py<br/>pydantic-ai]
    Agent --> Memory[memory.py]
    Memory --> Neo4j
    Memory --> Mem0[mem_store.py<br/>Mem0]
    Mem0 --> Qdrant
    Models --> MCP[mcp_server.py<br/>17 tools]
    Models --> Web[web_server.py<br/>aiohttp]
    Web --> Dashboard[web/<br/>SVG dashboard]
    MCP -.stdio.-> Client[Claude Code / Cursor]
    Web -.WebSocket.-> Watcher[watcher.py]

• Scanner does AST + regex extraction across supported languages.

• Agent wraps pydantic-ai with structured ArchitectureSummary output.

• Memory is a three-tier write: flat JSON → Neo4j graph → Mem0 semantic store.

• MCP server exposes the same model surface as the web dashboard, both backed by a single Architecture instance.

Tech stack

• Python 3.11+

• mcp ≥ 1.0 (Model Context Protocol SDK)

• pydantic-ai ≥ 0.0.30

• pydantic ≥ 2.9

• aiohttp ≥ 3.10 (web server + WebSockets)

• watchdog ≥ 4.0 (file change detection)

• neo4j ≥ 5.20 (knowledge graph)

• mem0ai ≥ 0.1.50 (semantic memory)

• qdrant-client ≥ 1.9 (vector store)

• openai ≥ 1.50 (provider SDK)

• Vanilla JS + SVG + CodeMirror 6 in the dashboard — no React, no build step

Roadmap

These are planned, not built. Open an issue if you want to drive one.

• In-browser graph editing — edit Neo4j nodes/edges from the dashboard

• Additional LLM providers — Gemini, Mistral, xAI Grok, AWS Bedrock

• Cytoscape.js alternate renderer for very large graphs (10k+ nodes)

• GitHub Action that auto-generates docs/architecture.html on every PR

• VS Code extension that surfaces the dashboard in a side panel

• Multi-repo aggregation — one dashboard across a monorepo or org

• arch-viewer diff — semantic diff between two revisions of an architecture

Contributing

PRs, issues, and discussions are very welcome. See CONTRIBUTING.md for setup, code style, and PR conventions. By participating you agree to abide by the Code of Conduct.

• Bug reports → Issues

• Questions / ideas → Discussions

• Security → see SECURITY.md

License

MIT © AxumQuant

Built by

AxumQuant — a small open-source lab building developer tools around MCP, knowledge graphs, and agentic workflows. Contact via GitHub issues.

Acknowledgements

• Anthropic for the Model Context Protocol spec and SDK

• Neo4j for the community-edition graph database

• Mem0 for the semantic memory layer

• pydantic-ai for typed LLM agents

• Qdrant for the vector store

• CodeMirror for the in-browser editor