{
  "markdown": "# Archiet X-Ray\n\nmcp-name: io.github.Anioko/archiet-xray\n\n**See what your AI sees.** Your codebase is too big for any AI agent's context\nwindow. The agent reads 40 files out of 4,000, makes a change, and you have no\nway to know whether it respected the architecture — or quietly violated it.\n\nX-Ray extracts the *actual* architecture of any repo — deterministically, no\nLLM, code never leaves your machine — and gives it to both **you** (an\ninteractive map) and **your AI agent** (an MCP server + context pack).\n\n```\n$ python xray.py .\n\nArchiet X-Ray v0.2.0 — your-repo\n  visibility score : 78/100\n  prod readiness   : 71/100 (near production-ready)\n  code files       : 3,412 (1,907 read, 1,584 with elements)\n  routes           : 214\n  entities         : 87\n  async tasks      : 31\n  findings         : 6\n  wrote            : .archiet/ARCHITECTURE.md\n                     .archiet/AGENT_CONTEXT.md\n                     .archiet/architecture.json\n                     .archiet/diagrams/diagrams.html (+3 .mmd)\n```\n\n## What you get\n\n| File | What it is |\n|---|---|\n| `ARCHITECTURE.md` | Human-readable map: module dependency graph (Mermaid), domain model, every route with auth status, dependency hotspots, risk findings, production-readiness scorecard |\n| `AGENT_CONTEXT.md` | Drop into your CLAUDE.md / rules file — makes Claude Code, Cursor, and Windsurf respect your architecture *today* |\n| `architecture.json` | The machine-readable model (the \"repo genome\") |\n| `diagrams/` | Architecture diagrams as Mermaid sources + a self-contained HTML viewer — module dependency graph, ER / domain-model diagram, HTTP route map |\n\n## Production-readiness score (new in 0.2)\n\nA deterministic **0–100 production-readiness score** over 8 dimensions:\nroute auth coverage, secrets hygiene, client token storage, data-layer\ndiscipline, test footprint, migration discipline, ops readiness\n(Docker/CI/.env contract), and docs/API contract. Same repo always scores\nthe same — so the score is comparable across commits, branches, and repos,\nand you can put it in CI.\n\nEach dimension reports its evidence (\"142/214 statically-guarded routes\ncarry an auth guard\") and the report ends with the **top fixes ranked by\npoints lost**. Dimensions that don't apply (a CLI tool has no routes) take\nhalf credit and say so — honesty over flattery.\n\nUseful when: reviewing AI-generated code before shipping it, auditing an\ninherited codebase, or tracking whether your repo is drifting away from\nproduction readiness over time.\n\n## Architecture diagrams from code (new in 0.2)\n\n`generate_diagrams` turns any repo into **Mermaid architecture diagrams**,\ndeterministically extracted from the code itself:\n\n- **Module dependency graph** — the real import structure, not the wiki's\n- **ER / domain-model diagram** — entities and relations from SQLAlchemy,\n  Django, and Prisma models\n- **HTTP route map** — the API surface grouped by prefix\n\nYou get the raw `.mmd` sources (paste into any README, wiki, GitHub, GitLab,\nNotion, Obsidian, or VS Code — they all render Mermaid natively) plus a\nself-contained `diagrams.html` viewer.\n\n## Give it to your agent (MCP)\n\n[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=archiet-xray&config=eyJjb21tYW5kIjogInV2eCIsICJhcmdzIjogWyJhcmNoaWV0LXhyYXkiLCAibWNwIl19)\n\n```bash\n# Claude Code (from PyPI — pip install archiet-xray)\nclaude mcp add archiet-xray -- archiet-xray mcp /path/to/repo\n\n# or from a checkout\nclaude mcp add archiet-xray -- python /path/to/mcp_server.py /path/to/repo\n```\n\n**Claude Desktop** — download `archiet-xray-<version>.mcpb` from the\n[latest release](https://github.com/Anioko/archiet-xray/releases/latest),\nthen double-click it (or Settings → Extensions → Install Extension). It\nprompts for the repository to analyze; one-click after that.\n\n**Official MCP Registry** — listed as `io.github.Anioko/archiet-xray`,\nso registry-aware clients can install it by name.\n\nYour agent can now ask — *before* it edits:\n\n- **`blast_radius`** — \"who depends on this file? what breaks if I touch it?\"\n- **`arch_summary`** — \"where do routes/entities/services actually live?\"\n- **`boundary_findings`** — \"hardcoded secrets, raw SQL, tokens in localStorage, unauthenticated routes\"\n- **`production_readiness`** — \"score this repo 0–100 for production readiness, with evidence and top fixes\"\n- **`generate_diagrams`** — \"draw the module graph / ER diagram / route map as Mermaid\"\n- **`xray_scan`** — re-scan after structural changes\n\n## Principles\n\n1. **Deterministic.** Same repo in, same map out. Every fact traces to a file\n   and line. No LLM guesses anywhere in the pipeline.\n2. **Honest.** What can't be extracted with confidence is labelled *unmapped*\n   — never invented. A wrong map is worse than no map.\n3. **Local-first.** Stdlib only, zero network calls, zero telemetry. Your code\n   never leaves your machine.\n\n## What it extracts today\n\n- **Python**: Flask / FastAPI routes (+ auth-guard detection), SQLAlchemy &\n  Django models with relations, Celery tasks, import graph — via `ast`, not regex\n- **JS/TS**: Next.js app & pages router (pages + API routes), Express routes,\n  Prisma models, import graph\n- **Findings**: hardcoded secrets, raw SQL bypassing the ORM, auth tokens in\n  localStorage/AsyncStorage, routes without auth guards\n- **Graph**: module dependency edges, fan-in/fan-out, blast-radius hotspots\n\nMore stacks (Go, Java, Rails, .NET) welcome — the extractor pattern is one\nclass per language. PRs invited.\n\n## Real examples\n\n[`examples/`](examples/) holds unedited X-Ray output for repos you know —\nmicroblog (Flask), the official FastAPI full-stack template, and\nvercel/commerce (Next.js). GitHub renders the Mermaid maps inline. On the\nFastAPI template, X-Ray correctly detects `CurrentUser` dependency auth on 18\nroutes and flags a real auth-token-in-localStorage write in `useAuth.ts`.\n\n## FAQ\n\n**How is this different from a dependency-graph MCP server (Codegraph, dependency-mcp)?**\nThose show call/import edges. X-Ray extracts *web-architecture semantics* on top\nof the graph: which routes exist, which carry auth guards, where the domain\nentities live, and where security boundaries leak (hardcoded secrets, raw SQL,\ntokens in localStorage). No graph tool tells you \"510 of your routes have no\ndetectable auth guard.\"\n\n**How is this different from a CLAUDE.md generator?**\nCLAUDE.md generators write *instructions and conventions* — usually with an\nLLM. X-Ray extracts *facts*: every claim in its output traces to a file and\nline, and what it can't extract it labels unknown. Use both: your conventions\nplus X-Ray's ground truth.\n\n**What does auth status `?` mean?**\n\"Not detectable from per-function analysis.\" FastAPI routers often attach auth\nat `include_router(dependencies=...)` level, which is invisible when analyzing\nthe route function. X-Ray reports unknown rather than guessing a confident\n\"no auth\" — a wrong map is worse than no map.\n\n**Is the production-readiness score a security audit?**\nNo. It is a deterministic static-signal score — it measures whether the repo\n*carries the marks* of production discipline (auth guards on routes, no\nhardcoded secrets, tests, migrations, ops + docs contracts). The payload says\nso explicitly. It is a fast, repeatable triage number, not a substitute for\ncode review, load testing, or a security audit.\n\n**Why Mermaid for the diagrams instead of images?**\nMermaid sources are diffable, render natively on GitHub/GitLab/Notion/VS\nCode/Obsidian, and stay in sync with the repo because you can regenerate them\nin one command. The bundled `diagrams.html` gives you a browser view without\ninstalling anything.\n\n**Does it phone home?**\nNo. Stdlib-only, zero network calls, zero telemetry. The only outbound anything\nis a link in the generated footer.\n\n## Sibling server: archiet-audit\n\nX-Ray never touches the network. If you want the *hosted* counterpart — a\nprocurement-grade architecture audit (traceability %, severity-ranked gaps,\n30/60/90-day roadmap) generated from your architecture documents — the\n[`archiet-audit` MCP server](../audit-mcp/) bridges your agent to\n[archiet.com/audit-my-architecture](https://archiet.com/audit-my-architecture).\nIt is a separate server precisely so X-Ray's \"your code never leaves your\nmachine\" guarantee stays absolute.\n\n## Privacy Policy\n\nX-Ray is local-only by design. Specifically:\n\n- **Data collection: none.** X-Ray collects no telemetry, no analytics, no\n  usage data, and no personal information of any kind.\n- **Data usage: local analysis only.** Your code is read from disk solely to\n  build the architecture model, in-process, on your machine.\n- **Data storage: your disk, your control.** The only artifacts produced are\n  the files written to `.archiet/` inside the repository you scan\n  (ARCHITECTURE.md, AGENT_CONTEXT.md, architecture.json, diagrams/). Delete\n  them at any time; nothing else is stored anywhere.\n- **Third-party sharing: none.** X-Ray makes zero network calls (stdlib-only,\n  no HTTP client is even imported). Your code never leaves your machine.\n- **Data retention: not applicable.** No data reaches us, so there is nothing\n  for us to retain or delete.\n- **Contact:** aniekan.okono@archiet.dev — or open an issue on this repo.\n\nThe company-wide policy at [archiet.com/privacy](https://archiet.com/privacy)\ncovers Archiet's hosted products; it applies to X-Ray only in the trivial\nsense that X-Ray sends us nothing.\n\n## Part of Archiet\n\nX-Ray is the free, open companion to [Archiet](https://archiet.com) — the\narchitecture-to-code platform. The map X-Ray extracts is the same formal model\nArchiet uses to *enforce* architecture on every PR (boundary gates, drift\nscoring, consulting-grade architecture reports) and to regenerate\nproduction-ready applications from it.\n\nMIT licensed.\n",
  "bytes": 9814,
  "sha": "1d62279b1a9825235bff40f8783896301acbfe0ed88417d8d2286f9cffcc56d1",
  "repo_slug": "anioko/archiet-xray",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_anioko_archiet_xray_80fdd621/readme"
}