{
  "markdown": "# Understand-Anything MCP Server\n\n[![npm version](https://img.shields.io/npm/v/ua-mcp)](https://www.npmjs.com/package/ua-mcp)\n[![license](https://img.shields.io/npm/l/ua-mcp)](https://github.com/uamcp/Understand-Anything-MCP/blob/main/LICENSE)\n[![GitHub stars](https://img.shields.io/github/stars/uamcp/Understand-Anything-MCP)](https://github.com/uamcp/Understand-Anything-MCP/stargazers)\n\n\nA 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.\n\n## Quick Start\n\n> [!NOTE]\n> **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.\n> 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.\n\nGet 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!\n\n### Claude Desktop\nAdd this to your `claude_desktop_config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"understand-anything\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"ua-mcp\"],\n      \"env\": {\n        \"UA_PROJECT_PATH\": \"/absolute/path/to/your/project\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n1. Go to **Settings > Features > MCP**.\n2. Click **+ Add new MCP server**.\n3. Name: `understand-anything`\n4. Type: `command`\n5. Command: `npx -y ua-mcp`\n6. Add an environment variable: `UA_PROJECT_PATH = /absolute/path/to/your/project`\n\n## How UA-MCP compares to Understand-Anything Tool\n\nThe 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.\n\n\n## Privacy Policy\n> [!IMPORTANT]\n> **[Link to Privacy Policy](https://uamcp.github.io/Understand-Anything-MCP/)**\n> \n> **Data Processing Details:**\n> - License keys and email addresses are securely stored for billing purposes.\n> - **Purely local, no network calls:** `ua_status`, `ua_scan`, `ua_graph_summary`, `ua_explain`, `ua_onboarding_doc`.\n> - **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.\n> - **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.\n> \n> ### Security Considerations\n> - `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.\n> - **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.\n\n## 🚀 Features\n\n- **Branch Protection / CI Gate:** Automatically block high-risk PRs based on the codebase graph.\n- **Architectural Rules:** Define custom `.ua-rules.json` to enforce boundaries.\n- **Blast Radius Analysis:** Detect exactly which downstream files will break if a module is modified.\n- **On-Demand Knowledge Graph:** Let Claude instantly query dependencies across massive codebases without filling its context window.\n\n> [!TIP]\n> **System Instruction Recommended:** For the best experience, add the following to your AI assistant's system prompt or custom instructions:\n> *\"Always call `ua_precheck` before modifying any file in this project.\"*\n\n## How it works\n1. Your AI agent decides it wants to modify a critical file (e.g., `src/auth.ts`).\n2. The agent (following its system instructions) triggers `ua_precheck` before making the edit to run an **Architectural Safety Linter**.\n3. The server analyzes the graph to determine the \"blast radius\" and checks it against your rules.\n4. 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.\n\n## Configuration Rules (.ua-rules.json)\nYou 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.\n\n```json\n{\n  // Understand-Anything Architectural Rules\n  // Define constraints that agents and developers must respect.\n  \"rules\": [\n    {\n      \"id\": \"no-ui-db-import\",\n      \"description\": \"UI layer must never import database layer directly\",\n      \"from_pattern\": \"src/ui/**\",\n      \"to_pattern\": \"src/db/**\",\n      \"severity\": \"error\"\n    },\n    {\n      \"id\": \"auth-required-for-payments\",\n      \"description\": \"Payment modules must always be reachable from auth\",\n      \"requires_path_through\": \"src/auth/**\",\n      \"for_pattern\": \"src/payments/**\",\n      \"severity\": \"error\"\n    }\n  ]\n}\n```\n\n## 🔒 Usage: CI/CD Branch Protection (Enforcement)\n\n#### CI Gateway (`ua-ci`)\nA companion CLI that runs locally in your GitHub Actions or GitLab CI. It parses your PR diff and compares it to the local graph.\n- **Free Tier:** Evaluates blast-radius and logs the risk level.\n- **Pro Tier:** Automatically blocks the merge if the risk is `HIGH` or violates architectural rules.\n\n> [!IMPORTANT]\n> **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. \n> 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.\n>\n> **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.\n\n```yaml\n# .github/workflows/ua-ci.yml\nname: Understand-Anything CI Check\non:\n  pull_request:\n    branches: [ main ]\n\njobs:\n  ua-ci-check:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n        with:\n          fetch-depth: 0\n\n      - name: Generate PR Diff\n        run: git diff origin/main...HEAD > pr.diff\n\n      - name: Run UA Branch Protection\n        env:\n          UA_LICENSE_KEY: ${{ secrets.UA_LICENSE_KEY }}\n        run: npx ua-ci --pr-diff=pr.diff\n```\n\n## 🛡️ Usage: Local Governance (Agents)\n\nWhen connected to Claude Desktop or an MCP client, the following tools become available to the agent:\n\n### Claude Desktop (`claude_desktop_config.json`)\nAdd 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):\n\n```json\n{\n  \"mcpServers\": {\n    \"understand-anything\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"ua-mcp\"],\n      \"env\": {\n        \"UA_PROJECT_PATH\": \"/path/to/your/project\",\n        \"UA_LICENSE_KEY\": \"your_license_key_here\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n1. Go to **Settings > Features > MCP**.\n2. Click **+ Add new MCP server**.\n3. Name: `understand-anything`\n4. Type: `command`\n5. Command: `npx -y ua-mcp`\n\n### Continue\nAdd to your `config.json` under `mcpServers`:\n```json\n\"understand-anything\": {\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"ua-mcp\"]\n}\n```\n\n## Available Tools & Tiering\n\nThe Understand-Anything MCP Server operates on a tiered licensing model.\n\n### Core Tools (Free Tier)\nAvailable out of the box with no license required.\n- `ua_find_callers`: Retrieves reverse dependencies up to 2 hops (Now unlimited and free!).\n- `ua_impact_analysis`: Retrieves full transitive closure of reverse dependencies (Now unlimited and free!).\n- `ua_precheck`: Pre-flight architectural risk check (10 checks/day, default critical-path rules only)\n- `ua_status`: Returns MCP health status.\n- `ua_scan`: Forces a re-scan of the workspace.\n- `ua_graph_summary`: Returns aggregated node/edge statistics.\n- `ua_architecture_report`: Groups files by top-level modules.\n- `ua_dependency_report`: Identifies files with the most incoming dependencies (fan-in).\n- `ua_explain`: Retrieves 1-hop dependencies for a specific file.\n- `ua_onboarding_doc`: Generates onboarding context.\n\n### Premium Tools (Pro Tier)\n\n**Pro Tier — Architectural Enforcement & CI Safety**\n\n**Team Use:** One Pro license key can be shared across your entire team's CI pipelines and MCP configurations — no per-seat pricing.\n\n- `ua_rules` & `ua_rules_check`: Enforce custom `.ua-rules.json` boundaries. Evaluates constraints to ensure recent changes haven't introduced violations.\n- `ua_ci_check` & `ua-ci`: Block risky PRs in GitHub Actions before they reach production. Analyzes Git PR diffs for architectural impact.\n- `ua_precheck`: Unlimited pre-flight checks with configurable critical paths and .ua-rules.json enforcement\n- `ua_validate_graph`: Checks the knowledge graph schema for corruption.\n\n## Pricing\n\n| Tier | Price | Features |\n|---|---|---|\n| **Free** | $0 forever | Basic graph operations, local storage. |\n| **Pro** | $10/month OR $50 one-time | Unlimited nodes, advanced graph analytics, rule enforcement, priority support. (Lifetime access limited availability) |\n\n**Get your license key:**\n- [Pro - Monthly ($10)](https://buy.stripe.com/7sYeVdaQW95GbBmaqj7bW01)\n- [Pro - Lifetime ($50)](https://buy.stripe.com/dRmaEX8IO0zacFqfKD7bW00)\n\n## Troubleshooting\n\n- **Server fails to start**: Ensure you have Node.js v18 or later installed.\n- **License key error**: Verify your key in the `.env` file or Claude config matches the one on your dashboard.\n- **Path not found**: Ensure `UA_PROJECT_PATH` is absolute or resolves correctly relative to where the server runs.\n\n## License\nMIT License\n",
  "bytes": 10669,
  "sha": "e6ffce42de80605399baf4ab471d494a705692fe411cf3de5e4fd636ca996256",
  "repo_slug": "uamcp/understand-anything-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_uamcp_ua_mcp_444298c2/readme"
}