内容
# ContextualAgentRulesHub
## 概述
**ContextualAgentRulesHub 是一个 MCP (Model Context Protocol) 服务器**，提供一个灵活的系统用于存储和检索代理规则，这些规则可以被 AI 代理用来遵循特定上下文的指导方针。MCP 服务器提供高效的规则发现和内容检索工具，使 AI 代理能够仅访问与其当前任务相关的规则。
## 动机
有效管理代理规则可能是一个挑战。在不同代理或项目之间共享规则往往会导致不一致性，并且在维护集中规则集时会遇到困难。此外，AI 代理通常在有限的上下文窗口内操作。发送一大堆未分类的规则可能会消耗宝贵的上下文空间。AgentRulesHub 旨在通过以下方式解决这些问题：
- 提供一种结构化的方式来组织和访问规则。
- 使代理能够仅检索与其当前任务相关的规则，从而最小化上下文长度并提高效率。
## 任务流程
本节描述了 AI 代理与 AgentRulesHub MCP 服务器交互以检索和利用给定任务规则的典型流程。
1. **任务启动**：一个代理（例如，Cline）开始一个新任务。
2. **检索规则索引**：代理使用 `GetAllRulesMetadata` 工具查询 `rules-hub` MCP 服务器。这将提供所有可用规则的索引，包括它们的 ID、描述、语言和标签。
3. **识别相关规则**：根据当前任务的上下文（例如，编程语言、关键字、目标）和接收到的元数据，代理分析规则索引以识别哪些规则是相关的。
4. **检索规则内容**：如果识别出相关规则，代理使用 `GetRuleContentById` 工具针对每个相关规则 ID 获取其具体内容。
5. **利用规则**：代理将检索到的规则内容纳入其行动中，以指导其行为、改善输出或确保遵循特定的任务指导方针。
```mermaid
sequenceDiagram
participant Agent
participant RulesHubServer as "rules-hub MCP Server"
Agent->>RulesHubServer: 1. Request: GetAllRulesMetadata
RulesHubServer-->>Agent: 2. Response: Rules Index (Metadata)
Agent->>Agent: 3. Analyze Task & Identify Relevant Rules
alt Relevant Rules Found
loop For Each Relevant Rule
Agent->>RulesHubServer: 4. Request: GetRuleContentById (ruleId)
RulesHubServer-->>Agent: 5. Response: Rule Content
end
end
Agent->>Agent: 6. Utilize Rule Content for Task
```
## 特性
- **多源支持**：可扩展架构，支持文件、数据库、Git 仓库和 API 源
- **基于 YAML 的存储**：人类可读的规则存储，具有元数据和内容分离
- **高效索引**：按语言、标签和内容搜索进行快速查找
- **懒加载**：规则内容仅在需要时加载，以优化性能
- **灵活查询**：支持结合语言、标签和文本搜索的复杂查询
- **基于标签的组织**：灵活的分类系统，支持 AND/OR 逻辑
## 安装
1. **克隆仓库**：
```bash
git clone <repository-url>
cd ContextualAgentRulesHub
```
2. **安装依赖**：
```bash
pip install -r requirements.txt
```
## MCP 服务器配置
### MCP 使用的安装
1. **安装 Python 依赖**：
```bash
pip install -r mcp-server/requirements.txt
```
2. **配置你的 MCP 客户端**（例如，Claude Desktop，Cline）：
将以下内容添加到你的 MCP 设置文件中：
**对于 Claude Desktop** (`claude_desktop_config.json`)：
```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`)：
```json
{
"cline.mcpServers": {
"cotextual-agent-rules-hub": {
"command": "python",
"args": ["C:/path/to/ContextualAgentRulesHub/mcp-server/run_server.py"]
}
}
}
```
### MCP 客户端配置的自定义指令
作为 MCP 服务器配置的一部分，你应该添加以下自定义指令块：
**"对于每个任务，使用 cotextual-agent-rules-hub MCP 服务器获取所有规则元数据索引，如果有与任务相关的规则，则将它们全部读取到上下文中 - 这是必需的"**
### 环境配置
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:` 等添加额外源。
**多个源的示例**：
```bash
# 第一个源 - 本地 YAML 文件
RulesLoaderOptions:0:SourceType=YamlFile
RulesLoaderOptions:0:Path=C:/path/to/ContextualAgentRulesHub/rules
# 第二个源 - 额外的规则目录
RulesLoaderOptions:1:SourceType=YamlFile
RulesLoaderOptions:1:Path=C:/path/to/additional/rules
# 第三个源 - 团队共享规则
RulesLoaderOptions:2:SourceType=YamlFile
RulesLoaderOptions:2:Path=\\shared\network\path\team-rules
```
**在 MCP 客户端配置中**：
```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",
"RulesLoaderOptions:1:SourceType": "YamlFile",
"RulesLoaderOptions:1:Path": "C:/path/to/additional/rules"
}
}
}
}
```
### 可用的 MCP 工具
服务器提供两个主要工具：
#### `GetAllRulesMetadata`
- **目的**：检索所有可用规则的元数据
- **参数**：无
- **返回**：规则元数据对象的 JSON 数组
- **用法**：首先查询此工具以发现可用规则
**示例响应**：
```json
[
{
"ruleId": "csharp-standards-rule",
"description": "此规则检查是否遵循 C# 编码标准",
"language": "csharp",
"tags": ["coding-standards", "best-practices"],
"source": {
"sourceType": "File"
}
}
]
```
#### `GetRuleContentById`
- **目的**：获取特定规则的完整内容
- **参数**：
- `ruleId` (字符串)：规则的唯一标识符
- **返回**：规则内容，格式为 markdown/text
- **用法**：在识别相关规则后检索特定规则内容
**示例用法**：
```json
{
"ruleId": "csharp-standards-rule"
}
```
### 测试 MCP 服务器
#### 手动测试
1. **直接启动服务器**：
```bash
cd ContextualAgentRulesHub
python mcp-server/run_server.py
```
2. **使用包含的脚本进行测试**：
```bash
python test_mcp_server.py
```
#### 集成测试
1. **使用上述服务器设置配置你的 MCP 客户端**
2. **查询可用规则**：
- 使用 `GetAllRulesMetadata` 工具查看所有可用规则
- 验证规则是否从你的 `rules/` 目录加载
3. **检索规则内容**：
- 使用 `GetRuleContentById`，传入元数据响应中的规则 ID
- 验证是否返回完整的规则内容
#### 故障排除
- **服务器无法启动**：检查 Python 路径和依赖
- **没有加载规则**：验证 `RulesLoaderOptions:0:Path` 是否指向你的规则目录
- **权限错误**：确保 Python 进程对规则目录具有读取权限
- **连接问题**：检查 MCP 客户端配置和服务器日志
## 快速开始
### 运行演示
```bash
python simple_demo.py
```
这将演示：
- 从 YAML 文件加载规则
- 按语言和标签过滤
- 内容检索
- 元数据索引
### 基本用法（直接 API）
```python
from src.bootstrap.agent_rules_bootstrapper import AgentRulesBootstrapper
# 从环境配置引导规则系统
bootstrapper = AgentRulesBootstrapper.from_environment()
repository = bootstrapper.bootstrap()
# 查询规则
all_rules = repository.get_all_rules()
csharp_rules = repository.get_rules_by_language("csharp")
testing_rules = repository.get_rules_by_tag("testing")
# 获取规则内容
content = repository.get_rule_content("csharp-standards-rule")
print(content)
```
### MCP 使用（推荐）
使用此系统的推荐方式是通过 MCP 服务器，它提供 AI 代理可以使用的工具：
```python
# 配置你的 MCP 客户端以连接到服务器
# 然后通过你的 AI 代理使用工具：
# 1. 获取所有可用规则
metadata = use_mcp_tool("GetAllRulesMetadata")
# 2. 获取特定规则内容
content = use_mcp_tool("GetRuleContentById", {"ruleId": "csharp-standards-rule"})
```
## 规则格式
### 索引文件 (`rules/index.yaml`)
```yaml
rules:
- id: python-pep8-standards
description: "Python PEP8 编码标准和格式化指南"
language: python
tags: [coding-standards, pep8, formatting, best-practices]
content_file: python-pep8-standards.yaml
```
### 规则内容文件 (`rules/python-pep8-standards.yaml`)
```yaml
id: python-pep8-standards
description: "Python PEP8 编码标准和格式化指南"
language: python
tags:
- coding-standards
- pep8
- formatting
- best-practices
rule: |
# Python PEP8 标准指南
## 缩进
- 每个缩进级别使用 4 个空格
- 永远不要混合使用制表符和空格
## 行长度
- 限制所有行的最大长度为 79 个字符
[... 详细规则内容 ...]
```
## 核心组件
### 数据模型
- **规则**：包含元数据（ID、描述、语言、标签）和内容
- **源**：定义不同源类型的存储配置
- **规则索引**：提供高效的索引和查询能力
### 源类型
- **FileSource**：从 YAML 文件读取规则，具有基于索引的元数据
- **DatabaseSource**： （未来）基于数据库的规则存储
- **GitSource**： （未来）基于 Git 仓库的规则存储
- **APISource**： （未来）基于 API 的规则检索
### 仓库特性
- **多源聚合**：从多个源组合规则
- **懒加载**：仅在请求时加载内容
- **高效查询**：基于索引的快速查找
- **灵活过滤**：按语言、标签和基于文本的搜索
## API 参考
### RuleRepository
#### 查询方法
- `get_all_rules()` - 获取所有规则
- `get_rules_by_language(language)` - 按编程语言过滤
- `get_rules_by_tag(tag)` - 按单个标签过滤
- `get_rules_by_tags_any(tags)` - 按多个标签中的任何一个过滤（OR 逻辑）
- `get_rules_by_tags_all(tags)` - 按所有标签过滤（AND 逻辑）
- `search_rules(query)` - 在描述中进行文本搜索
- `get_rules_by_criteria()` - 复杂的多条件查询
#### 内容方法
- `get_rule(rule_id)` - 获取规则元数据
- `get_rule_content(rule_id)` - 获取规则内容，支持懒加载
#### 管理方法
- `discover_rules()` - 扫描并索引所有来自源的规则
- `add_source(source)` - 添加新的规则源
- `refresh()` - 从源重新加载所有规则
- `get_repository_stats()` - 获取关于仓库的统计信息
## 扩展系统
### 添加新源类型
1. **实现 RuleSource 接口**：
```python
from src.sources.base import RuleSource
class CustomSource(RuleSource):
def load_rules_metadata(self) -> List[Rule]:
# 实现
pass
def load_rule_content(self, rule_id: str) -> str:
# 实现
pass
def validate_source(self) -> bool:
# 实现
pass
```
2. **在仓库中注册**：
```python
custom_source = CustomSource(config)
repository.add_source(custom_source)
```
### 添加新规则类型
只需按照既定格式添加新的 YAML 文件：
1. 将元数据添加到 `rules/index.yaml`
2. 创建内容文件 `rules/your-rule-id.yaml`
3. 使用适当的语言和标签进行分类
## 包含的示例规则
1. **python-pep8-standards**：Python 编码标准和格式化
2. **python-testing-guide**：使用 pytest 的 Python 测试最佳实践
3. **git-workflow-guide**：Git 工作流和分支策略
## 需求
- Python 3.8+
- PyYAML 6.0+
## 实现状态
✅ **已完成特性：**
- **MCP 服务器实现**：功能齐全的 FastMCP 服务器，具有两个工具
- **代理规则系统**：完整的规则管理，支持懒加载
- **YAML 文件支持**：从 YAML 文件加载规则，带有元数据
- **引导系统**：基于环境的配置和初始化
- **规则仓库**：内存存储，支持高效查询
- **内容源**：可插拔架构，支持不同源类型
- **集成层**：MCP 服务器与规则系统之间的桥梁
- **测试脚本**：自动化测试和验证
- **全面文档**：设置、配置和使用指南
✅ **可用的 MCP 工具：**
- `GetAllRulesMetadata`：检索规则索引以进行发现
- `GetRuleContentById`：通过 ID 获取特定规则内容
🔄 **未来增强：**
- 数据库源实现
- Git 仓库源实现
- API 源实现
- 规则验证增强
- 大规则集的性能优化
- 高级查询能力
- 规则版本控制系统
## 贡献
1. 遵循 Python PEP8 标准（有关详细信息，请参见包含的规则）
2. 为新功能添加测试
3. 更新 API 更改的文档
4. 使用描述性的提交信息
## 许可证
[许可证信息待添加]
MCP 市场
