clarityaui-mcp

Give any MCP agent a map of your codebase — derived deterministically, on your machine, in seconds.

npx clarityaui-mcp /path/to/repo

This is a stdio MCP server. Register it in your client (blocks below) and the agent gains four read-only tools answered from a deterministic concept map of the repository — real structure from real imports, not folders, and not a model's guess:

| Tool | Answers | |---|---| | atlas_overview | The repo at a glance: file/module counts and the top-level concepts, each anchored on the file it formed around | | atlas_concept | One concept: what it contains, what it is made of, which concepts it touches and how hard | | atlas_connection | How two concepts or files are ACTUALLY connected — the import links and the symbols that cross them | | atlas_find | Locate a concept or file by name, and say where it sits in the hierarchy |

The point, in one comparison: asking an agent to "figure out the structure" burns tokens for minutes and yields a guess that varies run to run. These tools return in seconds, cost zero tokens to produce, and the same repo always yields the same answer. The agent spends its context reasoning about your code instead of rediscovering its shape.

Registration

The repository to index is, in order: the argument, $CLARITY_WORKSPACE, or the directory the client launched the server in.

Claude Code — spawns project servers in the project root, so inside a project the bare form indexes the right repo:

claude mcp add --transport stdio clarity-atlas -- npx -y clarityaui-mcp

Or shared with your team via .mcp.json in the project root (--scope project writes this):

{
  "mcpServers": {
    "clarity-atlas": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "clarityaui-mcp"]
    }
  }
}

Claude Desktop — claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\). Desktop launches servers from your home directory, so the path must be explicit and absolute:

{
  "mcpServers": {
    "clarity-atlas": {
      "command": "npx",
      "args": ["-y", "clarityaui-mcp", "/absolute/path/to/repo"]
    }
  }
}

Cursor — .cursor/mcp.json in the project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "clarity-atlas": {
      "command": "npx",
      "args": ["-y", "clarityaui-mcp", "/absolute/path/to/repo"]
    }
  }
}

On Windows, npx works directly in all three clients — no cmd /c wrapping.

What it does, honestly

• Zero network, zero key, verifiably. No LLM, no account, no telemetry. The package contains no network code at all — the publish gate greps every shipped bundle for network primitives (fetch, the node http / net / tls modules, sockets) and fails if one appears. Your code never leaves your machine, and nothing here writes to your repository.
• Deterministic clustering, natively fast. The concept map comes from the same clustering core as clarity-aui-atlas, running as a compiled WebAssembly module. A 3,000-file framework indexes end-to-end in a few seconds on an ordinary laptop.
• The same map the app shows. If the repository has been opened in Clarity AUI, the concepts wear the names the app cached in .clarity/concept-names.json — an agent and the person steering it are reading one map, not two. Without the cache, the deterministic names stand.
• One index per server session. The atlas is built on the first question and reused, so follow-up questions are instant. Restart the server (most clients have a reconnect) to pick up structural changes.
• Evidence over confidence. atlas_connection names the import links and crossing symbols, or says plainly there are none. Static analysis is approximate; where it is, the answer says so instead of pretending.

Part of Clarity AUI

This is the query door to the atlas inside Clarity AUI — a context-native visual IDE where the same map is the surface you watch and command agents on. These tools answer questions about the territory; commanding agents on it is the app.

Licence

Free for any use, including commercial use on proprietary code, by teams of any size — but proprietary software: no redistribution, no hosting as a service, no derivative or competing use. Your code and every answer the server produces from it remain yours. See LICENSE and THIRD-PARTY-NOTICES.md.

Requires Node ≥ 20.

Feedback and bugs: [email protected] · security reports: https://clarityaui.com/security/