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

Env var	Default	Description
`ARCH_VIEWER_ROOT`	`cwd`	Project root directory to scan
`ARCH_VIEWER_PROVIDER`	auto-detect	LLM provider: `openai`, `anthropic`, `groq`, `ollama`
`ARCH_VIEWER_MODEL`	provider default	Model name override
`ARCH_VIEWER_PORT`	`3777`	Web dashboard port
`ARCH_VIEWER_NO_AI`	unset	Set to `1` to disable AI analysis (static scan only)
`OPENAI_API_KEY`	—	OpenAI API key
`ANTHROPIC_API_KEY`	—	Anthropic API key
`GROQ_API_KEY`	—	Groq API key
`OLLAMA_API_KEY`	—	Ollama Cloud API key
`NEO4J_URI`	`bolt://localhost:7687`	Neo4j bolt endpoint
`NEO4J_USER`	`neo4j`	Neo4j username
`NEO4J_PASSWORD`	`archviewer123`	Neo4j password (override in production)
`QDRANT_URL`	`http://localhost:6333`	Qdrant REST endpoint
`MEM0_ENABLED`	`1`	Set to `0` to skip semantic memory

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.

Tool	Description
`get_architecture`	Complete architecture model — components, data flows, tech stack, stats, AI summary
`get_component`	Detailed info on a single component (files, routes, tech, description)
`get_data_flows`	How components connect — protocol and direction
`get_dependencies`	Project dependencies, filterable by category (`python`, `node-runtime`, `node-dev`)
`get_file_tree`	Nested file tree, optionally filtered by path prefix
`get_ai_summary`	AI-generated narrative of the architecture
`get_api_routes`	All detected HTTP/WS routes across components
`get_architecture_score`	0–100 score across Modularity, Code Quality, Maintainability, Structure
`get_dependency_graph`	Import / call / package / component graph with hotspot analysis
`get_anti_patterns`	Severity-ranked findings: circular imports, god files, orphaned modules, etc.
`analyze_file_ast`	Functions, classes, imports, exports, and complexity for a single file
`get_recent_changes`	Recent file changes from the live watcher
`refresh_architecture`	Force a full rescan and AI re-analysis
`get_memory`	All learned patterns, corrections, and analysis history
`add_memory_pattern`	Teach the AI a new project-specific pattern
`add_memory_correction`	Correct a past AI mistake — applied to future analyses
`generate_interactive_diagram`	Write a standalone interactive HTML diagram to disk

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

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

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.github		.github
arch_viewer		arch_viewer
docs		docs
public		public
src		src
web		web
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
config.example.yaml		config.example.yaml
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

arch-viewer

MCP-native architecture viewer with AI-powered codebase analysis

Why arch-viewer?

Demo

Quick start

Features

Prerequisites

Installation

Option A — Quick (Docker stack + local Python)

Option B — Development

Option C — MCP integration with Claude Code

Configuration

MCP tools

Usage examples

Scan from the CLI

Call an MCP tool from Claude Code

Generate a standalone diagram

Architecture

Tech stack

Roadmap

Contributing

License

Built by

Acknowledgements

About

Uh oh!

Releases

Sponsor this project

Uh oh!

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

arch-viewer

MCP-native architecture viewer with AI-powered codebase analysis

Why arch-viewer?

Demo

Quick start

Features

Prerequisites

Installation

Option A — Quick (Docker stack + local Python)

Option B — Development

Option C — MCP integration with Claude Code

Configuration

MCP tools

Usage examples

Scan from the CLI

Call an MCP tool from Claude Code

Generate a standalone diagram

Architecture

Tech stack

Roadmap

Contributing

License

Built by

Acknowledgements

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages