Understand Anything MCP

Understand-Anything MCP サーバー

AI エージェントがプロジェクト全体のアーキテクチャを理解できるようにする Model Context Protocol（MCP）サーバーであり、コードがマージされる前にアーキテクチャルールを適用するヘッドレス 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. 設定 > 機能 > MCP に移動します。
2. + 新しい MCP サーバーを追加 をクリックします。
3. 名前：understand-anything
4. 種類：command
5. コマンド：npx -y ua-mcp
6. 環境変数を追加します：UA_PROJECT_PATH = /absolute/path/to/your/project

UA-MCP と Understand-Anything Tool の比較

上流の無料ツールである 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 エージェントが、重要なファイル（例：src/auth.ts）を変更する必要があると判断します。
2. エージェントは（システム指示に従い）、編集を行う前に ua_precheck を実行して、アーキテクチャ安全性リンターを起動します。
3. サーバーがグラフを分析して「影響範囲」を特定し、ルールと照合します。
4. 影響範囲が大きすぎる場合やルールに違反する場合は、安全性チェックポイント（確認プロンプト）がエージェントを中断し、続行する前に明示的な確認を求めます。

設定ルール（.ua-rules.json）

ワークスペースのルートにある .ua-rules.json ファイルで、LLM が変更できる範囲を指定する境界を定義できます。

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

GitHub Actions または GitLab CI でローカル実行する補助 CLI です。PR の差分を解析し、ローカルのグラフと比較します。

• 無料プラン： 影響範囲を評価し、リスクレベルを記録します。
• Pro プラン： リスクが HIGH の場合、またはアーキテクチャルールに違反する場合に、自動的にマージをブロックします。

重要

真の強制手段となる最後の砦： ローカルのエージェントは ua_precheck を実行するためにシステム指示に依存しますが、ua-ci コマンドは回避できない安全策として設計されています。 GitHub Actions で ua-ci を実行し、GitHub ブランチ保護でステータスチェックを必須にすることで、明示的な承認なしに不正な編集が本番環境にマージされることを防げます。

無料プランに関する注意： 有効な Pro ライセンスキーが環境変数内に見つからない場合、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

🛡️ 使用方法：ローカルガバナンス（エージェント）

Claude Desktop または MCP クライアントに接続すると、以下のツールをエージェントが利用できるようになります。

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：アーキテクチャ上のリスクを事前チェックします（1 日 10 回、デフォルトのクリティカルパスルールのみ）。
• ua_status：MCP のヘルスステータスを返します。
• ua_scan：ワークスペースを強制的に再スキャンします。
• ua_graph_summary：ノードとエッジの集計統計を返します。
• ua_architecture_report：ファイルをトップレベルのモジュールごとに分類します。
• ua_dependency_report：受信依存関係（ファンイン）が最も多いファイルを特定します。
• ua_explain：特定のファイルの 1 ホップの依存関係を取得します。
• ua_onboarding_doc：オンボーディング用のコンテキストを生成します。

プレミアムツール（Pro プラン）

Pro プラン — アーキテクチャの適用と CI の安全性

チームでの利用： Pro ライセンスキー 1 つを、チーム全体の CI パイプラインと MCP 設定で共有できます。ユーザーごとの料金はかかりません。

• ua_rules と ua_rules_check：カスタムの .ua-rules.json 境界ルールを適用します。制約を評価し、直近の変更によって違反が発生していないことを確認します。
• ua_ci_check と ua-ci：GitHub Actions で、リスクの高い PR が本番環境に到達する前にブロックします。Git の PR 差分を分析し、アーキテクチャへの影響を確認します。
• ua_precheck：設定可能なクリティカルパスと .ua-rules.json の適用による、無制限の事前チェックを行います。
• ua_validate_graph：ナレッジグラフのスキーマに破損がないか確認します。

料金

プラン	価格	機能
無料	永久に $0	基本的なグラフ操作、ローカルストレージ。
Pro	月額 $10 または一括 $50	ノード数無制限、高度なグラフ分析、ルールの適用、優先サポート。（買い切りライセンスは数量限定）

ライセンスキーの取得：

• Pro - 月額（$10）
• Pro - 買い切り（$50）

トラブルシューティング

• サーバーが起動しない場合：Node.js v18 以降がインストールされていることを確認してください。
• ライセンスキーのエラー：.env ファイルまたは Claude の設定にあるキーが、ダッシュボードに表示されているキーと一致することを確認してください。
• パスが見つからない場合：UA_PROJECT_PATH が絶対パスであるか、サーバーの実行場所からの相対パスとして正しく解決されることを確認してください。

ライセンス

MIT ライセンス