archy
Exposes 17 tools that let Claude and other MCP clients read Python architectural health in real time. You get module dependency graphs, import cycle detection, layer violation checks against archy.yaml rules, hotspot analysis that crosses cyclomatic complexity with git churn, and a single trended score per commit. Built on tree-sitter so it survives syntax errors. The check command gates CI, the mcp command wires into agents so they see their own structural impact before pushing code. Particularly useful when AI tools generate fast, correct code that quietly accumulates cycles and coupling debt. Requires Python 3.10 or newer and works best with a persistent parse cache at .archy/index.db for sub-second warm builds on large codebases.
- GitHub stars
- 8
- tools
- 12
- transport
- STDIO
- last updated
- Nov 12, 2026
Tools
12 toolsPublic tool metadata for what this MCP can expose to an agent.
archy_briefOne call before starting on an unfamiliar repository. Composes archy_conventions, the layer coverage of archy.yaml, and with contracts=True the transitive import-linter verdict. Advisory; mutates nothing.
One call before starting on an unfamiliar repository. Composes archy_conventions, the layer coverage of archy.yaml, and with contracts=True the transitive import-linter verdict. Advisory; mutates nothing.
No parameter schema in public metadata yet.
archy_scoreCompute the five-metric score (modularity, acyclicity, depth, equality, complexity, geometric mean); optional record=True and strict=True for the same regression-gate behaviour the CLI offers. view="history" returns the recent score history from .archy/history.jsonl.
Compute the five-metric score (modularity, acyclicity, depth, equality, complexity, geometric mean); optional record=True and strict=True for the same regression-gate behaviour the CLI offers. view="history" returns the recent score history from .archy/history.jsonl.
No parameter schema in public metadata yet.
archy_cyclesFind import cycles; exclude_type_checking leaves out if TYPE_CHECKING: edges.
Find import cycles; exclude_type_checking leaves out if TYPE_CHECKING: edges.
No parameter schema in public metadata yet.
archy_checkRun direct-edge layer rules from archy.yaml. Pass contracts=True to also run the transitive import-linter contracts. Always returns coverage: how many modules and import edges the rules actually reach.
Run direct-edge layer rules from archy.yaml. Pass contracts=True to also run the transitive import-linter contracts. Always returns coverage: how many modules and import edges the rules actually reach.
No parameter schema in public metadata yet.
archy_impactGiven changed file paths, return what they affect. mode="blast" (default) returns the modules that transitively import them (blast radius) with chains explaining why each is impacted. mode="affected" is the CI-shaped lookup returning impacted_tests and impacted_modules, depth-...
Given changed file paths, return what they affect. mode="blast" (default) returns the modules that transitively import them (blast radius) with chains explaining why each is impacted. mode="affected" is the CI-shaped lookup returning impacted_tests and impacted_modules, depth-...
No parameter schema in public metadata yet.
archy_snapshotCapture score, cycles, and violations to .archy/baseline.json. Call at session start. Also returns an invariant_brief to read before the first edit.
Capture score, cycles, and violations to .archy/baseline.json. Call at session start. Also returns an invariant_brief to read before the first edit.
No parameter schema in public metadata yet.
archy_diffCompare current state against the snapshot; returns added/resolved cycles and violations, per-component score deltas, and a risk-weighted summary. strict=True with baseline adds a strict verdict.
Compare current state against the snapshot; returns added/resolved cycles and violations, per-component score deltas, and a risk-weighted summary. strict=True with baseline adds a strict verdict.
No parameter schema in public metadata yet.
archy_simulateCounterfactual pre-edit check: given a proposed import-edge delta (add/remove of from/to pairs), return the would-be cycles, violations, per-axis score delta, and blast-radius change, with no file written.
Counterfactual pre-edit check: given a proposed import-edge delta (add/remove of from/to pairs), return the would-be cycles, violations, per-axis score delta, and blast-radius change, with no file written.
No parameter schema in public metadata yet.
archy_graphInspect the dependency graph. With no focus, response_format="summary" (default) returns the top-N overview; response_format="full" returns the complete node/edge dump. Pass focus=[...] for a bounded subgraph around one or more modules.
Inspect the dependency graph. With no focus, response_format="summary" (default) returns the top-N overview; response_format="full" returns the complete node/edge dump. Pass focus=[...] for a bounded subgraph around one or more modules.
No parameter schema in public metadata yet.
archy_what_to_refactor_nextRanked refactor-priority list. lens="fused" (default) sums the behavioral and structural lenses into a priority; lens="behavioral" ranks CC x churn hotspots; lens="structural" ranks the edit-risk composite.
Ranked refactor-priority list. lens="fused" (default) sums the behavioral and structural lenses into a priority; lens="behavioral" ranks CC x churn hotspots; lens="structural" ranks the edit-risk composite.
No parameter schema in public metadata yet.
archy_dsmDesign Structure Matrix view of the import graph. response_format="summary" (default) returns a compact overview; response_format="full" returns the positional matrix. When baseline_path is provided, returns a structured diff flagging newly introduced cycles.
Design Structure Matrix view of the import graph. response_format="summary" (default) returns a compact overview; response_format="full" returns the positional matrix. When baseline_path is provided, returns a structured diff flagging newly introduced cycles.
No parameter schema in public metadata yet.
archy_duplicatesCluster functions with identical normalized bodies.
Cluster functions with identical normalized bodies.
No parameter schema in public metadata yet.
Sponsors
Agent CaffeineSponsoredClose your lid, come back to finished work
SnugSponsoredThe clipboard manager for the AI eraPromote your product hereReach 125k+ visitors monthly
WaxSponsoredBlock anything with supervision, without erasing your iPhonePromote your product hereReach 125k+ visitors monthly
knobsSponsoredSee your site on any phone, any day, in any languageReadme
archy
Your folders show your architecture. Your imports decide it. archy turns a Python import graph into something an agent can use: blast radius before an edit, the tests that edit affects, the modules most at risk. And it fails when the graph disagrees with the layers you declared. Same graph either way, as a CLI and an MCP server, every session and in CI.
Details
- Repository
- github.com/hslee16/archy
- Website
- github.com/hslee16/archy
- Package
archy- Transport
- STDIO
- Registry
- MCP registry, active