Understand-Anything MCP Server
A Model Context Protocol (MCP) server that empowers your AI agents to understand your entire project architecture, and a headless CI gateway to enforce architectural rules before code is merged.
Quick Start
> [!NOTE]
> Prerequisite:
ua-mcp is a lightweight reader that connects your AI assistant to your local Understand-Anything knowledge graph. It does not build the graph itself.
> You must install the core scanner from Egonex-AI/Understand-Anything and run /understand in your project to produce the .ua/knowledge-graph.json file. Commit this file to your repository before proceeding.
Get your AI assistant hooked up with architectural context in 60 seconds. ua_find_callers, ua_impact_analysis, and ua_precheck work immediately for free with no license key required!
Claude Desktop
Add this to your claude_desktop_config.json:```json
{
"mcpServers": {
"understand-anything": {
"command": "npx",
"args": ["-y", "ua-mcp"],
"env": {
"UA_PROJECT_PATH": "/absolute/path/to/your/project"
}
}
}
}
### Cursor
1. Go to **Settings > Features > MCP**.
2. Click **+ Add new MCP server**.
3. Name: `understand-anything`
4. Type: `command`
5. Command: `npx -y ua-mcp`
6. Add an environment variable: `UA_PROJECT_PATH = /absolute/path/to/your/project`
## How UA-MCP compares to Understand-Anything Tool
The free upstream Understand-Anything tool is responsible for generating the local knowledge graph and performing manual local analysis. **UA-MCP** sits on top of this graph to provide an automated **governance layer** and **safety net** for your codebase. While the free tool is a diagnostic scanner, UA-MCP actively blocks risky merges via its CI/branch-protection gate (`ua-ci`) and enforces your custom `.ua-rules.json` architectural boundaries.
## Privacy Policy
> [!IMPORTANT]
> **Link to Privacy Policy**
>
> **Data Processing Details:**
> - License keys and email addresses are securely stored for billing purposes.
> - **Purely local, no network calls:** `ua_status`, `ua_scan`, `ua_graph_summary`, `ua_explain`, `ua_onboarding_doc`.
> - **Sends graph data to the backend:** `ua_precheck` (Free and Pro), and all Pro-only tools (`ua_rules`, `ua_ci_check`, `ua_find_callers`, `ua_impact_analysis`, `ua_validate_graph`). When these tools are used, the full local graph object is sent to our backend for CI risk analysis, rule evaluation, and quota validation. All Pro-tier computation is handled remotely.
> - **No source code contents are transmitted**, only graph metadata (file paths and import relationships). All backend graph processing is done purely in-memory per-request and is never persisted.
>
> ### Security Considerations
> - `UA_API_URL` defaults to the official backend (`https://ua-mcp-backend.onrender.com`). Be extremely cautious if you change this to a custom endpoint, as the third-party backend will receive your full knowledge graph and source file paths.
> - **Self-Hosting:** If you are self-hosting the backend, note that a PostgreSQL `DATABASE_URL` is required in production. SQLite is not supported for production deployments.
## 🚀 Features
- **Branch Protection / CI Gate:** Automatically block high-risk PRs based on the codebase graph.
- **Architectural Rules:** Define custom `.ua-rules.json` to enforce boundaries.
- **Blast Radius Analysis:** Detect exactly which downstream files will break if a module is modified.
- **On-Demand Knowledge Graph:** Let Claude instantly query dependencies across massive codebases without filling its context window.
> [!TIP]
> **System Instruction Recommended:** For the best experience, add the following to your AI assistant's system prompt or custom instructions:
> *"Always call `ua_precheck` before modifying any file in this project."*
## How it works
1. Your AI agent decides it wants to modify a critical file (e.g., `src/auth.ts`).
2. The agent (following its system instructions) triggers `ua_precheck` before making the edit to run an **Architectural Safety Linter**.
3. The server analyzes the graph to determine the "blast radius" and checks it against your rules.
4. If the blast radius is too large or violates a rule, a **Safety Checkpoint** (Elicitation Prompt) interrupts the agent, asking for your explicit confirmation before proceeding.
## Configuration Rules (.ua-rules.json)
You can define specific boundaries in a `.ua-rules.json` file in the root of your workspace to dictate what the LLM is allowed to touch.```json
{
// Understand-Anything Architectural Rules
// Define constraints that agents and developers must respect.
"rules": [
{
"id": "no-ui-db-import",
"description": "UI layer must never import database layer directly",
"from_pattern": "src/ui/**",
"to_pattern": "src/db/**",
"severity": "error"
},
{
"id": "auth-required-for-payments",
"description": "Payment modules must always be reachable from auth",
"requires_path_through": "src/auth/**",
"for_pattern": "src/payments/**",
"severity": "error"
}
]
}
🔒 Usage: CI/CD Branch Protection (Enforcement)
CI Gateway (ua-ci)
A companion CLI that runs locally in your GitHub Actions or GitLab CI. It parses your PR diff and compares it to the local graph.
- Free Tier: Evaluates blast-radius and logs the risk level.
- Pro Tier: Automatically blocks the merge if the risk is HIGH or violates architectural rules.
> [!IMPORTANT]
> The True Enforcement Backstop: While local agents rely on system instructions to run ua_precheck, the ua-ci command is designed to be your unbypassable safety net.
> By running ua-ci in your GitHub Actions and requiring it as a status check in GitHub Branch Protection, you ensure that no rogue edits can ever be merged into production without explicit approval.
>
> Note on Free Tier: If a valid Pro license key is not detected in the environment variables, the CI check will log a warning and silently pass (exit 0) so it does not block builds for non-paying users.```yaml
.github/workflows/ua-ci.yml
name: Understand-Anything CI Check
on:
pull_request:
branches: [ main ]
jobs:
ua-ci-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Generate PR Diff
run: git diff origin/main...HEAD > pr.diff
- name: Run UA Branch Protection
env:
UA_LICENSE_KEY: ${{ secrets.UA_LICENSE_KEY }}
run: npx ua-ci --pr-diff=pr.diff
## 🛡️ Usage: Local Governance (Agents)
When connected to Claude Desktop or an MCP client, the following tools become available to the agent:
### Claude Desktop (`claude_desktop_config.json`)
Add the following to your Claude Desktop config file (usually `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):```json
{
"mcpServers": {
"understand-anything": {
"command": "npx",
"args": ["-y", "ua-mcp"],
"env": {
"UA_PROJECT_PATH": "/path/to/your/project",
"UA_LICENSE_KEY": "your_license_key_here"
}
}
}
}
Cursor
- Go to Settings > Features > MCP.
- Click + Add new MCP server.
- Name:
understand-anything - Type:
command - Command:
npx -y ua-mcp
Continue
Add to your config.json under mcpServers:json
"understand-anything": {
"command": "npx",
"args": ["-y", "ua-mcp"]
}
Available Tools & Tiering
The Understand-Anything MCP Server operates on a tiered licensing model.
Core Tools (Free Tier)
Available out of the box with no license required.
- ua_find_callers: Retrieves reverse dependencies up to 2 hops (Now unlimited and free!).
- ua_impact_analysis: Retrieves full transitive closure of reverse dependencies (Now unlimited and free!).
- ua_precheck: Pre-flight architectural risk check (10 checks/day, default critical-path rules only)
- ua_status: Returns MCP health status.
- ua_scan: Forces a re-scan of the workspace.
- ua_graph_summary: Returns aggregated node/edge statistics.
- ua_architecture_report: Groups files by top-level modules.
- ua_dependency_report: Identifies files with the most incoming dependencies (fan-in).
- ua_explain: Retrieves 1-hop dependencies for a specific file.
- ua_onboarding_doc: Generates onboarding context.
Premium Tools (Pro Tier)
Pro Tier — Architectural Enforcement & CI Safety
Team Use: One Pro license key can be shared across your entire team's CI pipelines and MCP configurations — no per-seat pricing.
ua_rules&ua_rules_check: Enforce custom.ua-rules.jsonboundaries. Evaluates constraints to ensure recent changes haven't introduced violations.ua_ci_check&ua-ci: Block risky PRs in GitHub Actions before they reach production. Analyzes Git PR diffs for architectural impact.ua_precheck: Unlimited pre-flight checks with configurable critical paths and .ua-rules.json enforcementua_validate_graph: Checks the knowledge graph schema for corruption.
Pricing
| Tier | Price | Features |
|---|---|---|
| Free | $0 forever | Basic graph operations, local storage. |
| Pro | $10/month OR $50 one-time | Unlimited nodes, advanced graph analytics, rule enforcement, priority support. (Lifetime access limited availability) |
Get your license key:
- Pro - Monthly ($10)
- Pro - Lifetime ($50)
Troubleshooting
- Server fails to start: Ensure you have Node.js v18 or later installed.
- License key error: Verify your key in the
.envfile or Claude config matches the one on your dashboard. - Path not found: Ensure
UA_PROJECT_PATHis absolute or resolves correctly relative to where the server runs.
License
MIT License
