# archy

> archy is an open-source MCP server for developer tools. Python import-graph analysis that shows blast radius, affected tests and layer violations. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Repository:** https://github.com/hslee16/archy
- **MCP Registry name:** io.github.hslee16/archy
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-18

## About

Archy parses a Python project's imports and calls once, caches the graph, and answers questions a folder tree cannot: what an edit reaches, which tests it affects, where cycles are, and whether the code still obeys the layers you declared. Layers and forbidden directions are written by hand in an archy.yaml file; archy only checks that the source agrees. The same graph is served as a CLI for CI and as an MCP server inside an agent session.

The README is unusually candid. Its author measured whether agents damage import graphs and found it rare: 0 percent in 25 agent runs and about 0.5 percent of human commits introduced cycles. What did show up was wrong-direction imports, such as entities reaching into data access, in 12 percent of 25 agents building to a specified architecture, and a checker in the loop brought that to zero.

The project publishes its null results in a WHAT_DIDNT_WORK document, and says new tools stay gated behind usage evidence. A sample failure is a single upward import that the check command flags as a forbidden layer edge, with a layer coverage figure beside it.

## Features

- **Blast radius:** Shows what a change reaches before an agent edits a file.
- **Affected tests:** Lists the tests that a given edit touches.
- **Layer rules:** Fails when imports break layers declared in archy.yaml.
- **Cycle detection:** Finds import cycles in the project graph.
- **CLI and MCP:** One cached graph serves both a CI command and an MCP server.
- **Coverage reporting:** Reports how many modules and edges fall inside declared layers.

## Good for

- Check an edit's blast radius before an agent changes a Python file
- Find which tests to run after touching a module
- Enforce layer direction in CI on a Python backend
- Spot import cycles introduced by a change
- See which modules are central and fragile

## Install

### Claude Code (Terminal)

```sh
claude mcp add archy -- uvx archy
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "archy": {
      "command": "uvx",
      "args": [
        "archy"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "archy": {
      "command": "uvx",
      "args": [
        "archy"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "archy": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "archy"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "archy": {
      "command": "uvx",
      "args": [
        "archy"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "archy": {
      "command": "uvx",
      "args": [
        "archy"
      ]
    }
  }
}
```

## FAQ

### Do I write the architecture rules myself?

Yes. Layers and forbidden directions go in archy.yaml; archy checks that the source still agrees.

### How is it run?

As a CLI, for example uvx archy check ., or as a stdio MCP server from PyPI.

### Does it prove agents damage architecture?

No. The author's own measurements found cycles and layer violations rare, and the README says so.

### Which languages are supported?

Python projects.

### Where are negative results published?

In docs/WHAT_DIDNT_WORK.md in the repository.

### Is archy free?

Yes. archy is open source, so you can use and self-host it for free.

### How do I add archy to Claude Code?

Run this command in your terminal: claude mcp add archy -- uvx archy

### What are the best alternatives to archy?

The closest alternatives to archy are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/archy
