Contextual Agent Rules Hub

情境代理规则中心

概述

ContextAgentRulesHub是一个MCP（模型上下文协议）服务器 该系统提供了一个灵活的存储和检索代理规则的系统，AI代理可以使用这些规则来遵循特定上下文的指导方针。MCP服务器公开了用于高效规则发现和内容检索的工具，使AI代理能够仅访问与其当前任务相关的规则。

动机

有效地管理代理规则可能具有挑战性。在不同的代理或项目之间共享规则通常会导致不一致和难以维护集中式规则集。此外，人工智能代理通常在有限的上下文窗口下运行。发送一组庞大的、无差别的规则可能会占用宝贵的上下文空间。AgentRulesHub旨在通过以下方式解决这些问题：

• 提供一种结构化的方式来组织和访问规则。
• 使代理能够仅检索与其当前任务相关的规则，从而最小化上下文长度并提高效率。
• 支持基于上下文的规则组织，用于项目特定的指导方针。

主要特点

• 基于上下文的规则组织：规则可以与特定背景（例如项目名称）相关联，允许制定一般和特定背景的指导方针
• 多源支持：支持文件、数据库、Git存储库和API源的可扩展体系结构
• 基于YAML的存储：具有元数据和内容分离功能的人类可读规则存储
• 高效索引：按语言、标签、上下文和内容搜索快速查找
• 延迟加载：仅在需要最佳性能时加载规则内容
• 灵活查询：支持结合语言、标签、上下文和文本搜索的复杂查询
• 基于标签的组织：灵活的分类系统，支持AND/OR逻辑
• 核心规则：支持 is_core 使用专用MCP工具标记基本规则(GetCoreRulesContent)以检索其内容。

任务流程

本节描述了AI代理与AgentRulesHub MCP服务器交互以检索和利用给定任务规则的典型流程。

1. 任务启动：代理（例如Cline）使用可选上下文（例如特定项目的“TheProject”）开始新任务。
2. 检索核心规则内容：代理查询 GetCoreRulesContent 工具。如果存在任何核心规则，则检索其内容并将其作为任务的基本指导方针。
3. 检索可用上下文 （可选）：代理可以查询 GetAllContexts 该工具用于发现更具体规则的可用上下文。
4. 检索规则索引：代理查询 rules-hub MCP服务器使用 GetAllRulesMetadata 工具，可选地提供上下文过滤器。这提供了所有内容的索引 *非核心的* 规则，包括它们的ID、描述、语言、标签和上下文。
5. 确定相关的非核心规则：根据当前任务的上下文（例如编程语言、关键字、目标）和收到的元数据，代理分析规则索引，以确定哪些非核心规则是相关的。
6. 检索非核心规则内容：如果确定了相关的非核心规则，代理人将使用 GetRuleContentById 该工具用于获取每个相关规则ID的特定内容。
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服务器”-获取一般规则和mcp特定标准

安装

1. 克隆存储库:

   git clone 
   cd ContextualAgentRulesHub

1. 安装依赖项:

   pip install -r requirements.txt

MCP服务器配置

MCP使用安装

1. 安装Python依赖项:

   pip install -r mcp-server/requirements.txt

1. 配置您的MCP客户端 （例如，克劳德桌面、克莱恩）：

将以下内容添加到MCP设置文件中：

适用于克劳德桌面 (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"
         }
       }
     }
   }

用于临床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: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 （string）：规则的唯一标识符。

• 退货：规则内容为markdown/text。
• 用法：从元数据中识别相关规则后，或者如果您知道核心规则的ID，则检索特定规则内容。

示例用法:

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

故障排除

• 服务器无法启动：检查Python路径和依赖关系
• 未加载规则：验证 RulesLoaderOptions:0:Path 指向您的规则目录
• 权限错误：确保Python进程具有对rules目录的读取权限
• 连接问题：检查MCP客户端配置和服务器日志
• 上下文筛选不起作用：确保规则具有 context 在YAML文件中正确设置字段

规则格式

规则内容文件(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

1. 在存储库中注册:

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

需求

• Python 3.8+
• Yaml 6.0+
• fastmcp（用于MCP服务器）

实施状态

✅ 已完成的功能：

• MCP服务器实现：功能齐全的FastMCP服务器，配备三个工具
• 基于上下文的过滤：支持项目特定的规则组织
• 代理规则体系：通过延迟加载完成规则管理
• YAML文件支持：从包含元数据的YAML文件中加载规则
• 引导系统：基于环境的配置和初始化
• 规则存储库：具有高效查询功能的内存存储
• 内容源：适用于不同源类型的可插拔架构
• 集成层：MCP服务器和规则系统之间的桥梁
• 测试脚本：自动化测试和验证
• 综合文档：设置、配置和使用指南

✅ 可用MCP工具：

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

管理自定义指令

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

• 集中管理：在一个地方更新说明，所有代理都会收到更新。
• 上下文特异性：根据项目、用户或任务类型提供不同的自定义说明集。
• 版本控制：如果使用Git支持的源代码（未来的增强），指令更改可以进行版本控制。
• 减少快速Bloat：代理只加载必要的指令，节省上下文窗口空间。

这将使规则中心成为您的AI代理的强大“指令库”。

🔄 未来的增强功能：

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

贡献

1. 遵循Python PEP8标准（详见所附规则）
2. 添加新功能的测试
3. 更新API变更文档
4. 使用描述性提交消息

许可证

\[待添加许可证信息\]