ContextualAgentRulesHub

ContextualAgentRulesHub

概要

ContextualAgentRulesHub は MCP（Model Context Protocol）サーバーで、AI エージェントがコンテキストに応じたガイドラインに従うために利用できるエージェントルールを柔軟に保存・取得するシステムを提供します。MCP サーバーは効率的なルールの検索とコンテンツ取得を行うツールを公開し、AI エージェントが現在のタスクに関連するルールだけにアクセスできるようにします。

動機

エージェントルールを効果的に管理するのは容易ではありません。異なるエージェントやプロジェクト間でルールを共有すると、一貫性が失われたり、ルールセットの一元管理が難しくなったりすることがよくあります。さらに、AI エージェントのコンテキストウィンドウには制限があることがよくあります。整理されていない大量のルールを送信すると、貴重なコンテキスト領域を消費してしまいます。AgentRulesHub は、次の方法でこれらの問題に対処します。

• ルールを整理してアクセスするための構造化された方法を提供します。
• エージェントが現在のタスクに関連するルールだけを取得できるようにすることで、コンテキストの長さを最小限に抑え、効率を高めます。
• プロジェクト固有のガイドラインに対応する、コンテキストに基づいたルールの整理をサポートします。

主な機能

• コンテキストベースのルール整理：ルールを特定のコンテキスト（プロジェクト名など）に関連付けることで、一般的なガイドラインとコンテキスト固有のガイドラインの両方を扱えます
• 複数ソースのサポート：ファイル、データベース、Git リポジトリ、API のソースに対応する拡張可能なアーキテクチャ
• YAML ベースのストレージ：メタデータとコンテンツを分離して保存できる、人が読みやすい形式
• 効率的なインデックス作成：言語、タグ、コンテキスト、コンテンツ検索による高速な検索
• 遅延読み込み：パフォーマンスを最適化するため、ルールのコンテンツは必要な場合にのみ読み込まれます
• 柔軟なクエリ：言語、タグ、コンテキスト、テキスト検索を組み合わせた複雑なクエリをサポートします
• タグベースの整理：AND／OR ロジックに対応した柔軟な分類システム
• コアルール：必須ルールを識別する is_core フラグをサポートし、そのコンテンツを取得する専用の MCP ツール（GetCoreRulesContent）を提供します。

タスクの流れ

このセクションでは、AI エージェントが AgentRulesHub MCP サーバーとやり取りし、特定のタスクに必要なルールを取得して利用する一般的な流れについて説明します。

1. タスクの開始：エージェント（Cline など）が、任意のコンテキスト（特定のプロジェクトを示す「TheProject」など）を指定して新しいタスクを開始します。
2. コアルールのコンテンツを取得：エージェントは GetCoreRulesContent ツールにクエリを送信します。コアルールが存在する場合は、そのコンテンツを取得し、タスクの基本ガイドラインとして適用します。
3. 利用可能なコンテキストを取得（任意）：エージェントは GetAllContexts ツールにクエリを送信し、より具体的なルールに対応する利用可能なコンテキストを確認できます。
4. ルールのインデックスを取得：エージェントは、任意でコンテキストフィルターを指定し、GetAllRulesMetadata ツールを使用して rules-hub MCP サーバーにクエリを送信します。これにより、ID、説明、言語、タグ、コンテキストを含む、すべての非コアルールのインデックスが取得されます。
5. 関連する非コアルールを特定：エージェントは、現在のタスクのコンテキスト（プログラミング言語、キーワード、目的など）と取得したメタデータに基づいてルールのインデックスを分析し、関連する非コアルールを特定します。
6. 非コアルールのコンテンツを取得：関連する非コアルールが特定された場合、エージェントはルール ID ごとに GetRuleContentById ツールを使用し、それぞれのコンテンツを取得します。
7. ルールを利用：エージェントは、取得したすべてのルール（コアと非コア）のコンテンツを取り入れ、動作の指針として活用したり、出力を改善したり、現在のタスクに固有のガイドラインへの準拠を確保したりします。

sequenceDiagram
    participant Agent
    participant RulesHubServer as "rules-hub MCP Server"

    Agent->>RulesHubServer: 1. Request: GetCoreRulesContent
    RulesHubServer-->>Agent: 2. Response: Core Rules Content (if any)
    Agent->>RulesHubServer: 3. Request: GetAllContexts (Optional)
    RulesHubServer-->>Agent: 4. Response: Available Contexts
    Agent->>RulesHubServer: 5. Request: GetAllRulesMetadata(contextFilter?)
    RulesHubServer-->>Agent: 6. Response: Non-Core Rules Index (Metadata)
    Agent->>Agent: 7. Analyze Task & Identify Relevant Non-Core Rules
    alt Relevant Non-Core Rules Found
        loop For Each Relevant Non-Core Rule
            Agent->>RulesHubServer: 8. Request: GetRuleContentById (ruleId)
            RulesHubServer-->>Agent: 9. Response: Rule Content
        end
    end
    Agent->>Agent: 10. Utilize All Retrieved Rule Content for Task

コンテキストベースのルールフィルタリング

コンテキスト機能を使うと、すべてに共通して適用される一般的なルールセットを維持しながら、特定のプロジェクトや分野向けのルールを整理できます。

コンテキストの動作

• コンテキストフィルターなし：コンテキストのないルール（一般ルール）のみを返します
• コンテキストフィルターあり：コンテキストのないルール、または指定されたコンテキストに一致するルールを返します

これにより、一般ルールは常に利用でき、コンテキスト固有のルールは明示的に要求された場合にのみ返されます。

使用例

1. 一般的な開発：コンテキストフィルターなし。一般的なコーディング標準をすべて取得します
2. プロジェクト固有の作業：コンテキストフィルター「TheProject」。一般ルールとTheProject固有のガイドラインを取得します
3. MCP サーバーの開発：コンテキストフィルター「mcp-server」。一般ルールとMCP固有の標準を取得します

インストール

1. リポジトリをクローンします：

   git clone <repository-url>
   cd ContextualAgentRulesHub
   

2. 依存関係をインストールします：

   pip install -r requirements.txt
   

MCP サーバーの設定

MCP で使用するためのインストール

1. Python の依存関係をインストールします：

   pip install -r mcp-server/requirements.txt
   

2. MCP クライアント（例：Claude Desktop、Cline）を設定します：

   MCP 設定ファイルに以下を追加します：

   Claude Desktop の場合（claude_desktop_config.json）：

   {
     "mcpServers": {
       "cotextual-agent-rules-hub": {
         "command": "python",
         "args": ["C:/path/to/ContextualAgentRulesHub/mcp-server/run_server.py"],
         "env": {
           "RulesLoaderOptions:0:SourceType": "YamlFile",
           "RulesLoaderOptions:0:Path": "C:/path/to/ContextualAgentRulesHub/rules"
         }
       }
     }
   }
   

   Cline VSCode 拡張機能の場合（settings.json）：

   {
     "cline.mcpServers": {
       "cotextual-agent-rules-hub": {
         "command": "python",
         "args": ["C:/path/to/ContextualAgentRulesHub/mcp-server/run_server.py"]
       }
     }
   }
   

MCP クライアント設定用のカスタム指示

MCP サーバーの設定の一環として、コンテキスト機能とコアルール機能を活用する、最適化された以下のカスタム指示ブロックを追加してください：

When starting a new task:
1. Always begin by using the cotextual-agent-rules-hub MCP server's GetCoreRulesContent tool to retrieve and apply any foundational core rules.
2. Next, use the GetAllContexts tool to discover available contexts for more specific guidelines.
3. Unless the task explicitly states which context to use, ask the user to select from the available contexts or indicate that none should be used for non-core rules.
4. Use GetAllRulesMetadata with the appropriate contextFilter if the user selected a specific context, or without a filter for general non-core tasks.
5. Review the non-core rules metadata and identify ALL rules relevant to your task based on language, tags, and descriptions.
6. Use GetRuleContentById to retrieve the content of ALL relevant non-core rules.
7. Apply all retrieved rules (core and non-core) throughout your work on the task.

This approach ensures you always have access to fundamental core guidelines, general best practices, and project-specific rules when explicitly requested.

環境設定

MCP サーバーは環境変数を使用して設定できます：

変数	説明	デフォルト
RulesLoaderOptions:0:SourceType	ルール読み込み元の種類	YamlFile
RulesLoaderOptions:0:Path	ルールディレクトリのパス	./rules
AGENT_RULES_VALIDATION	ルールの検証を有効にする	true
AGENT_RULES_LOG_LEVEL	ログレベル（DEBUG、INFO、WARNING、ERROR）	INFO

複数ソースの設定

インデックス付き環境変数を使用すると、複数のルールソースを設定できます。RulesLoaderOptions:1:、RulesLoaderOptions:2: などを使用して、ソースを追加してください。

複数ソースの例：

# First source - Local YAML files
RulesLoaderOptions:0:SourceType=YamlFile
RulesLoaderOptions:0:Path=C:/path/to/ContextualAgentRulesHub/rules

# Second source - Additional rule directory
RulesLoaderOptions:1:SourceType=YamlFile
RulesLoaderOptions:1:Path=C:/path/to/additional/rules

# Third source - Team shared rules
RulesLoaderOptions:2:SourceType=YamlFile
RulesLoaderOptions:2:Path=\\shared\network\path\team-rules

MCP クライアントの設定例：

{
  "mcpServers": {
    "cotextual-agent-rules-hub": {
      "command": "python",
      "args": ["C:/path/to/ContextualAgentRulesHub/mcp-server/run_server.py"],
      "env": {
        "RulesLoaderOptions:0:SourceType": "YamlFile",
        "RulesLoaderOptions:0:Path": "C:/path/to/ContextualAgentRulesHub/rules",
        "RulesLoaderOptions:1:SourceType": "YamlFile",
        "RulesLoaderOptions:1:Path": "C:/path/to/additional/rules"
      }
    }
  }
}

利用可能な MCP ツール

サーバーでは、以下の主要なツールを公開しています：

GetCoreRulesContent

• 目的：is_core: true としてマークされたすべてのルールの内容を取得します。
• パラメーター：なし
• 戻り値：文字列の JSON 配列。各文字列はコアルールの内容です。
• 使用方法：タスクの開始時にこれを呼び出して、基礎となるガイドラインを取得します。

応答例：

[
  "Core Rule 1 Content...",
  "Core Rule 2 Content..."
]

GetAllContexts

• 目的：コア以外のルールでシステム内に利用可能なすべてのコンテキストを取得します。
• パラメーター：なし
• 戻り値：コンテキスト文字列の JSON 配列。
• 使用方法：これを呼び出して、コア以外のルールをフィルタリングする際に利用できるコンテキストを確認します。

応答例：

[
  "TheProject",
  "mcp-server",
  "frontend-app"
]

GetAllRulesMetadata

• 目的：利用可能なすべてのコア以外のルールのメタデータを取得します。
• パラメーター：
  • contextFilter（任意）：コンテキストでコア以外のルールをフィルタリングします。
• 戻り値：ルールメタデータオブジェクトの JSON 配列。
• 使用方法：利用可能なコア以外のルールを確認します。必要に応じてコンテキストでフィルタリングできます。コアルールは除外されます。

応答例：

[
  {
    "ruleId": "csharp-standards-rule",
    "description": "This rule checks for adherence to C# coding standards (non-core)",
    "language": "csharp",
    "tags": ["coding-standards", "best-practices"],
    "context": null,
    "source": {
      "sourceType": "File"
    }
  },
  {
    "ruleId": "theproject-python-guidelines",
    "description": "Python guidelines specific to TheProject (non-core)",
    "language": "python",
    "tags": ["python", "theproject"],
    "context": "TheProject",
    "source": {
      "sourceType": "File"
    }
  }
]

GetRuleContentById

• 目的：特定のルール（コアまたはコア以外）の完全な内容を取得します。
• パラメーター：
  • ruleId（文字列）：ルールの一意の識別子。
• 戻り値：Markdown／テキスト形式のルール内容。
• 使用方法：メタデータから関連するルールを特定した後、またはコアルールの ID がわかっている場合に、特定のルールの内容を取得します。

使用例：

{
  "ruleId": "csharp-standards-rule"
}

トラブルシューティング

• サーバーが起動しない：Python のパスと依存関係を確認してください
• ルールが読み込まれない：RulesLoaderOptions:0:Path がルールディレクトリを指していることを確認してください
• 権限エラー：Python プロセスにルールディレクトリへの読み取りアクセス権があることを確認してください
• 接続の問題：MCP クライアントの設定とサーバーログを確認してください
• コンテキストフィルタリングが機能しない：YAML ファイルでルールの context フィールドが正しく設定されていることを確認してください

ルール形式

ルールコンテンツファイル（rules/python-pep8-standards.yaml）

id: python-pep8-standards
description: "Python PEP8 coding standards and formatting guidelines"
language: python
context: null  # Optional: null for general rules, or specify a context like "TheProject"
is_core: false # Optional: true if this is a core rule, defaults to false.
               # 'coreRule' is also supported for backward compatibility.
tags:
  - coding-standards
  - pep8
  - formatting
  - best-practices
rule: |
  # Python PEP8 Standards Guide
  
  ## Indentation
  - Use 4 spaces per indentation level
  - Never mix tabs and spaces
  
  ## Line Length
  - Limit all lines to a maximum of 79 characters
  
  [... detailed rule content ...]

コンテキスト固有のルールの例

id: theproject-api-guidelines
description: "API development guidelines specific to TheProject"
language: python
context: TheProject  # This rule only appears when context filter is "TheProject"
tags:
  - api
  - theproject
  - rest
  - guidelines
rule: |
  # TheProject API Development Guidelines
  
  ## API Versioning
  - All APIs must use semantic versioning
  - Version must be included in URL path: /api/v1/
  
  [... TheProject-specific guidelines ...]

システムの拡張

新しいソースタイプの追加

1. RuleSource インターフェースを実装します：

   from src.sources.base import RuleSource
   
   class CustomSource(RuleSource):
       def load_rules_metadata(self) -> List[Rule]:
           # Implementation
           pass
       
       def load_rule_content(self, rule_id: str) -> str:
           # Implementation
           pass
       
       def validate_source(self) -> bool:
           # Implementation
           pass
   

2. リポジトリに登録します：

   custom_source = CustomSource(config)
   repository.add_source(custom_source)
   

要件

• Python 3.8+
• PyYAML 6.0+
• fastmcp（MCP サーバー用）

実装状況

✅ 実装済みの機能：

• MCP サーバーの実装：3 つのツールを備えた完全に機能する FastMCP サーバー
• コンテキストベースのフィルタリング：プロジェクト固有のルール整理をサポート
• エージェントルールシステム：遅延読み込みを備えた完全なルール管理
• YAML ファイルのサポート：メタデータ付きの YAML ファイルからルールを読み込み
• ブートストラップシステム：環境ベースの設定と初期化
• ルールリポジトリ：効率的なクエリが可能なインメモリストレージ
• コンテンツソース：さまざまなソースタイプに対応したプラグイン可能なアーキテクチャ
• 統合レイヤー：MCP サーバーとルールシステムをつなぐブリッジ
• テストスクリプト：自動テストと検証
• 包括的なドキュメント：セットアップ、設定、使用方法のガイド

✅ 利用可能な MCP ツール：

• GetAllContexts：利用可能なコンテキストを確認
• GetAllRulesMetadata：検出用のルールインデックスを取得。コンテキストによるフィルタリングは任意で指定できます（コアルールを除外）。
• GetRuleContentById：ID を指定して特定のルールコンテンツを取得。
• GetCoreRulesContent：is_core: true とマークされたすべてのルールのコンテンツを取得。

カスタム指示の管理

ContextualAgentRulesHub は、AI エージェント向けのカスタム指示を一元管理し、配布するシステムとしても効果的に利用できます。カスタム指示をルールとして定義することで（基本的な指示には is_core: true とマークすることもできます）、エージェントはタスクやコンテキストに関連する最新の指示を動的に取得して適用できます。この方法には、次のような利点があります。

• 一元管理：指示を一か所で更新でき、すべてのエージェントに更新が反映されます。
• コンテキストへの対応：プロジェクト、ユーザー、タスクの種類に応じて、異なるカスタム指示を提供できます。
• バージョン管理：Git を利用するソースを使用する場合（将来の拡張）、指示の変更をバージョン管理できます。
• プロンプトの肥大化を抑制：エージェントは必要な指示だけを読み込むため、コンテキストウィンドウの領域を節約できます。

これにより、ルールハブは AI エージェント向けの強力な「指示バンク」になります。

🔄 今後の拡張：

• データベースソースの実装
• Git リポジトリソースの実装
• API ソースの実装
• ルール検証の強化
• 大規模なルールセットに対するパフォーマンスの最適化
• 高度なクエリ機能
• ルールのバージョン管理システム
• ルールの継承と合成

貢献

1. Python PEP8 標準に従ってください（詳細は同梱のルールを参照）
2. 新機能にはテストを追加してください
3. API の変更に合わせてドキュメントを更新してください
4. 内容が分かりやすいコミットメッセージを使用してください

ライセンス

[ライセンス情報は後日追加予定]