Understand Anything - MCP
A powerful MCP server for codebase architecture analysis and automated governance.
Open source Open in the app JSON README (API)
About
A powerful MCP server for codebase architecture analysis and automated governance.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- uamcp
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.2.16
- Last push
- 2026-07-19T18:23:53Z
- Repository state
- ativo
- Language
- HTML
- License
- MIT
- Added
- 2026-08-29 04:01:36
- Updated
- 2026-08-29 04:01:36
- Origin id
io.github.uamcp/ua-mcp
README
# Understand-Anything MCP Server
[](https://www.npmjs.com/package/ua-mcp)
[](https://github.com/uamcp/Understand-Anything-MCP/blob/main/LICENSE)
[](https://github.com/uamcp/Understand-Anything-MCP/stargazers)
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](https://github.com/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](https://github.com/Egonex-AI/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](https://uamcp.github.io/Understand-Anything-MCP/)**
>
> **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](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging), 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
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`
### 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.json` boundaries. 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 enforcement
- `ua_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)](https://buy.stripe.com/7sYeVdaQW95GbBmaqj7bW01)
- [Pro - Lifetime ($50)](https://buy.stripe.com/dRmaEX8IO0zacFqfKD7bW00)
## Troubleshooting
- **Server fails to start**: Ensure you have Node.js v18 or later installed.
- **License key error**: Verify your key in the `.env` file or Claude config matches the one on your dashboard.
- **Path not found**: Ensure `UA_PROJECT_PATH` is absolute or resolves correctly relative to where the server runs.
## License
MIT License