ua-mcp

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:

{
  "mcpServers": {
    "understand-anything": {
      "command": "npx",
      "args": ["-y", "ua-mcp"],
      "env": {
        "UA_PROJECT_PATH": "/absolute/path/to/your/project"
      }
    }
  }
}

Cursor

• Go to Settings > Features > MCP.
• Click + Add new MCP server.
• Name: understand-anything
• Type: command
• Command: npx -y ua-mcp
• 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

• Your AI agent decides it wants to modify a critical file (e.g., src/auth.ts).
• The agent (following its system instructions) triggers ua_precheck before making the edit to run an Architectural Safety Linter.
• The server analyzes the graph to determine the "blast radius" and checks it against your rules.
• 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.

{
  // 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.

# .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):

{
  "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:

"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)
• 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 .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