Understand Anything MCP

Understand-Anything MCP 服务

一个 Model Context Protocol (MCP) 服务，可让你的 AI Agent 理解整个项目架构；同时也是一个无头 CI 网关，可在代码合并前强制执行架构规则。

快速开始

说明

前提条件： ua-mcp 是一个轻量级读取工具，可将你的 AI 助手连接到本地 Understand-Anything 知识图谱。它不会自行构建知识图谱。 你必须先从 Egonex-AI/Understand-Anything 安装核心扫描器，并在项目中运行 /understand，以生成 .ua/knowledge-graph.json 文件。继续之前，请将此文件提交到你的代码仓库。

只需 60 秒，即可为你的 AI 助手接入架构上下文。ua_find_callers、ua_impact_analysis 和 ua_precheck 无需许可证密钥即可立即免费使用！

Claude Desktop

将以下内容添加到你的 claude_desktop_config.json：

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

Cursor

1. 前往 Settings > Features > MCP。
2. 点击 + Add new MCP server。
3. 名称：understand-anything
4. 类型：command
5. 命令：npx -y ua-mcp
6. 添加一个环境变量：UA_PROJECT_PATH = /absolute/path/to/your/project

UA-MCP 与 Understand-Anything 工具的比较

上游免费工具 Understand-Anything 负责生成本地知识图谱并执行手动本地分析。UA-MCP 基于此图谱提供自动化的治理层和代码库的安全网。免费工具是一个诊断扫描器，而 UA-MCP 会通过其 CI/分支保护闸门（ua-ci）主动阻止有风险的合并，并强制执行自定义 .ua-rules.json 架构边界。

隐私政策

重要

隐私政策链接

数据处理详情：

• 许可证密钥和电子邮件地址会安全存储，以用于计费。
• 完全本地运行，不进行网络调用： ua_status、ua_scan、ua_graph_summary、ua_explain、ua_onboarding_doc。
• 向后端发送图谱数据： ua_precheck（Free 和 Pro）以及所有仅限 Pro 的工具（ua_rules、ua_ci_check、ua_find_callers、ua_impact_analysis、ua_validate_graph）。使用这些工具时，完整的本地图谱对象会发送到我们的后端，用于 CI 风险分析、规则评估和配额验证。所有 Pro 级计算均在远程处理。
• 不会传输源代码内容，只会传输图谱元数据（文件路径和导入关系）。所有后端图谱处理都仅在每次请求期间于内存中完成，绝不会持久化。

安全注意事项

• UA_API_URL 默认指向官方后端（https://ua-mcp-backend.onrender.com）。如果将其更改为自定义端点，请务必谨慎，因为第三方后端将收到完整的知识图谱和源文件路径。
• 自托管： 如果你自托管后端，请注意，生产环境需要 PostgreSQL DATABASE_URL。生产部署不支持 SQLite。

🚀 功能

• 分支保护 / CI 门禁： 根据代码库图谱自动阻止高风险 PR。
• 架构规则： 定义自定义 .ua-rules.json 以强制执行边界。
• 影响范围分析： 准确检测修改某个模块后哪些下游文件会损坏。
• 按需知识图谱： 让 Claude 即时查询大型代码库中的依赖关系，而不会占满其上下文窗口。

提示

建议使用系统指令： 为获得最佳体验，请将以下内容添加到 AI 助手的系统提示词或自定义指令中： “在修改此项目中的任何文件之前，始终先调用 ua_precheck。”

工作原理

1. AI Agent 判断需要修改一个关键文件（例如 src/auth.ts）。
2. Agent（遵循其系统指令）会在编辑前触发 ua_precheck，运行架构安全检查器。
3. 服务会分析图谱以确定“影响范围”，并根据你的规则进行检查。
4. 如果影响范围过大或违反规则，安全检查点（征询提示）会中断 Agent，并要求你明确确认后才能继续。

配置规则（.ua-rules.json）

你可以在工作区根目录的 .ua-rules.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"
    }
  ]
}

🔒 用法：CI/CD 分支保护（强制执行）

CI 网关（ua-ci）

一个配套的 CLI，可在 GitHub Actions 或 GitLab CI 中本地运行。它会解析 PR 差异，并将其与本地图谱进行比较。

• 免费版： 评估影响范围并记录风险等级。
• 专业版： 如果风险为 HIGH 或违反架构规则，则自动阻止合并。

重要

真正的强制执行保障： 本地 Agent 依靠系统指令运行 ua_precheck，而 ua-ci 命令则旨在充当无法绕过的安全网。 在 GitHub Actions 中运行 ua-ci，并在 GitHub 分支保护中将其设为必需状态检查，即可确保未经明确批准的违规修改绝不会合并到生产环境中。

关于免费版的说明： 如果未在环境变量中检测到有效的专业版许可证密钥，CI 检查会记录警告并静默通过（退出码为 0），因此不会阻止非付费用户的构建。

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

🛡️ 用法：本地治理（Agent）

连接到 Claude Desktop 或 MCP 客户端后，Agent 即可使用以下工具：

Claude Desktop（claude_desktop_config.json）

将以下内容添加到 Claude Desktop 配置文件中（macOS 上通常为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上通常为 %APPDATA%\Claude\claude_desktop_config.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. 前往 Settings > Features > MCP。
2. 点击 + Add new MCP server。
3. 名称：understand-anything
4. 类型：command
5. 命令：npx -y ua-mcp

Continue

在 config.json 的 mcpServers 下添加：

"understand-anything": {
  "command": "npx",
  "args": ["-y", "ua-mcp"]
}

可用工具与分级

Understand-Anything MCP 服务采用分级许可模式。

核心工具（免费版）

开箱即用，无需许可证。

• ua_find_callers：检索最多 2 跳的反向依赖（现在无限制且免费！）。
• ua_impact_analysis：检索反向依赖的完整传递闭包（现在无限制且免费！）。
• ua_precheck：架构风险预检（每天 10 次检查，仅使用默认关键路径规则）
• ua_status：返回 MCP 健康状态。
• ua_scan：强制重新扫描工作区。
• ua_graph_summary：返回聚合的节点／边统计信息。
• ua_architecture_report：按顶层模块对文件分组。
• ua_dependency_report：识别入向依赖最多的文件（扇入）。
• ua_explain：检索特定文件的 1 跳依赖。
• ua_onboarding_doc：生成入门背景信息。

高级工具（专业版）

专业版 — 架构约束与 CI 安全

团队使用： 一个专业版许可证密钥即可供整个团队的 CI 流水线和 MCP 配置共享，无需按席位付费。

• ua_rules 和 ua_rules_check：强制执行自定义 .ua-rules.json 边界。评估约束，确保近期更改未引入违规。
• ua_ci_check 和 ua-ci：在高风险 PR 进入生产环境之前，于 GitHub Actions 中拦截。分析 Git PR 差异对架构的影响。
• ua_precheck：无限次预检，支持配置关键路径并强制执行 .ua-rules.json
• ua_validate_graph：检查知识图谱架构是否损坏。

定价

版本	价格	功能
免费版	永久免费	基础图操作、本地存储。
专业版	$10/月或一次性支付 $50	节点数量不限、高级图分析、规则强制执行、优先支持。（终身访问名额有限）

获取许可证密钥：

• 专业版 - 月付（$10）
• 专业版 - 终身（$50）

故障排除

• 服务无法启动：确保已安装 Node.js v18 或更高版本。
• 许可证密钥错误：确认 .env 文件或 Claude 配置中的密钥与控制面板上的密钥一致。
• 找不到路径：确保 UA_PROJECT_PATH 是绝对路径，或相对于服务运行位置能够正确解析。

许可证

MIT 许可证