ContextualAgentRulesHub

ContextualAgentRulesHub

概述

ContextualAgentRulesHub 是一个 MCP（Model Context Protocol）服务，提供灵活的系统，用于存储和检索 AI Agent 可遵循的特定上下文指南。该 MCP 服务提供用于高效发现规则和检索内容的工具，使 AI Agent 只需访问与当前任务相关的规则。

动机

有效管理 Agent 规则可能颇具挑战。在不同 Agent 或项目之间共享规则，往往会导致不一致，也难以维护集中管理的规则集。此外，AI Agent 的上下文窗口通常有限。发送大量未经区分的规则会占用宝贵的上下文空间。AgentRulesHub 旨在解决这些问题：

• 提供一种有条理的规则组织和访问方式。
• 使 Agent 能够只检索与当前任务相关的规则，从而尽量缩短上下文并提高效率。
• 支持基于上下文组织规则，以便管理特定于项目的指南。

主要功能

• 基于上下文的规则组织：规则可以关联到特定上下文（例如项目名称），从而支持通用指南和特定上下文的指南
• 多数据源支持：可扩展的架构，支持文件、数据库、Git 仓库和 API 数据源
• 基于 YAML 的存储：以人类可读的形式存储规则，并将元数据与内容分离
• 高效索引：可按语言、标签、上下文和内容搜索快速查找
• 延迟加载：仅在需要时加载规则内容，以实现最佳性能
• 灵活查询：支持组合语言、标签、上下文和文本搜索的复杂查询
• 基于标签的组织：灵活的分类系统，支持 AND/OR 逻辑
• 核心规则：支持使用 is_core 标记识别重要规则，并提供专用 MCP 工具（GetCoreRulesContent）来检索其内容。

任务流程

本节介绍 AI Agent 与 AgentRulesHub MCP 服务交互，以检索并使用特定任务所需规则的典型流程。

1. 任务启动：Agent（例如 Cline）开始一项新任务，并可选择指定上下文（例如特定项目的 "TheProject"）。
2. 检索核心规则内容：Agent 查询 GetCoreRulesContent 工具。如果存在核心规则，就会检索其内容，并将其作为该任务的基础指南。
3. 检索可用上下文（可选）：Agent 可以查询 GetAllContexts 工具，以发现可用于更具体规则的上下文。
4. 检索规则索引：Agent 使用 GetAllRulesMetadata 工具查询 rules-hub MCP 服务，并可选择提供上下文筛选条件。该工具会提供所有非核心规则的索引，包括其 ID、描述、语言、标签和上下文。
5. 识别相关的非核心规则：Agent 根据当前任务的上下文（例如编程语言、关键词、目标）以及收到的元数据，分析规则索引，以确定哪些非核心规则与任务相关。
6. 检索非核心规则内容：如果找到了相关的非核心规则，Agent 就会针对每个相关规则 ID 使用 GetRuleContentById 工具来获取其具体内容。
7. 使用规则：Agent 将检索到的所有规则（核心和非核心）内容融入工作流程，以指导行动、改进输出，或确保遵循当前任务的特定指南。

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 服务实现：功能完备的 FastMCP 服务，包含三个工具
• 基于上下文的筛选：支持按项目组织规则
• Agent 规则系统：完整的规则管理，支持延迟加载
• YAML 文件支持：从 YAML 文件加载带元数据的规则
• 引导系统：基于环境的配置和初始化
• 规则仓库：支持高效查询的内存存储
• 内容来源：适用于不同来源类型的可插拔架构
• 集成层：连接 MCP 服务与规则系统
• 测试脚本：自动化测试和验证
• 完整文档：设置、配置和使用指南

✅ 可用的 MCP 工具：

• GetAllContexts：发现可用的上下文
• GetAllRulesMetadata：检索用于发现的规则索引，可选按上下文筛选（不包括核心规则）。
• GetRuleContentById：按 ID 获取特定规则的内容。
• GetCoreRulesContent：检索所有标记为 is_core: true 的规则内容。

管理自定义指令

ContextualAgentRulesHub 也可以作为一个集中式系统，用于管理和分发 AI Agent 的自定义指令。通过将自定义指令定义为规则（如果是基础指令，可以标记为 is_core: true），Agent 可以动态获取并应用与其任务或上下文相关的最新指令。这种方法有以下优势：

• 集中管理：在一处更新指令，所有 Agent 都能收到更新。
• 针对特定上下文：根据项目、用户或任务类型提供不同的自定义指令集。
• 版本控制：如果使用基于 Git 的来源（未来增强功能），可以对指令变更进行版本控制。
• 减少提示词冗余：Agent 只加载必要的指令，从而节省上下文窗口空间。

这使规则中心成为 AI Agent 的强大“指令库”。

🔄 未来增强功能：

• 数据库来源实现
• Git 仓库来源实现
• API 来源实现
• 增强规则验证
• 优化大型规则集的性能
• 高级查询功能
• 规则版本控制系统
• 规则继承与组合

贡献

1. 遵循 Python PEP8 标准（详情请参阅随附规则）
2. 为新功能添加测试
3. 更新 API 变更对应的文档
4. 使用描述性提交消息

许可证

[待添加许可证信息]