ContextualAgentRulesHub

Overview

ContextualAgentRulesHub is an MCP (Model Context Protocol) server that provides a flexible system for storing and retrieving agent rules that can be used by AI agents to follow context-specific guidelines. The MCP server exposes tools for efficient rule discovery and content retrieval, enabling AI agents to access only the rules relevant to their current task.

Motivation

Managing agent rules effectively can be challenging. Sharing rules across different agents or projects often leads to inconsistencies and difficulties in maintaining a centralized rule set. Furthermore, AI agents often operate with limited context windows. Sending a large, undifferentiated set of rules can consume valuable context space. AgentRulesHub aims to address these issues by:

- Providing a structured way to organize and access rules.
- Enabling agents to retrieve only the rules relevant to their current task, thus minimizing context length and improving efficiency.
- Supporting context-based rule organization for project-specific guidelines.

Key Features

- Context-Based Rule Organization: Rules can be associated with specific contexts (e.g., project names), allowing for both general and context-specific guidelines
- Multi-Source Support: Extensible architecture supporting File, Database, Git Repository, and API sources
- YAML-Based Storage: Human-readable rule storage with metadata and content separation
- Efficient Indexing: Fast lookups by language, tags, context, and content search
- Lazy Loading: Rule content is loaded only when needed for optimal performance
- Flexible Querying: Support for complex queries combining language, tags, context, and text search
- Tag-Based Organization: Flexible categorization system with AND/OR logic support
- Core Rules: Support for is_core flag to identify essential rules, with a dedicated MCP tool (GetCoreRulesContent) to retrieve their content.

Task Flow

This section describes the typical flow of an AI agent interacting with the AgentRulesHub MCP server to retrieve and utilize rules for a given task.

1. Task Initiation: An agent (e.g., Cline) begins a new task with an optional context (e.g., "TheProject" for a specific project).
2. Retrieve Core Rules Content: The agent queries the GetCoreRulesContent tool. If any core rules exist, their content is retrieved and applied as foundational guidelines for the task.
3. Retrieve Available Contexts (Optional): The agent can query the GetAllContexts tool to discover available contexts for more specific rules.
4. Retrieve Rule Index: The agent queries the rules-hub MCP server using the GetAllRulesMetadata tool, optionally providing a context filter. This provides an index of all non-core rules, including their IDs, descriptions, languages, tags, and contexts.
5. Identify Relevant Non-Core Rules: Based on the current task's context (e.g., programming language, keywords, objectives) and the metadata received, the agent analyzes the rule index to identify which non-core rules are relevant.
6. Retrieve Non-Core Rule Content: If relevant non-core rules are identified, the agent uses the GetRuleContentById tool for each relevant rule ID to fetch its specific content.
7. Utilize Rules: The agent incorporates the content of all retrieved rules (core and non-core) to guide its actions, improve its output, or ensure adherence to specific guidelines for the task at hand.

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

Context-Based Rule Filtering

The context feature allows you to organize rules for specific projects or domains while maintaining a set of general rules that apply universally.

Context Behavior

- No context filter: Returns only rules without context (general rules)
- With context filter: Returns rules with no context OR rules matching the provided context

This ensures that general rules are always available, while context-specific rules are only returned when explicitly requested.

Example Use Cases

1. General Development: No context filter - get all general coding standards
2. Project-Specific Work: Context filter "TheProject" - get general rules plus TheProject-specific guidelines
3. MCP Server Development: Context filter "mcp-server" - get general rules plus MCP-specific standards

Installation

1. Clone the repository:

   git clone <repository-url>

   cd ContextualAgentRulesHub

   

2. Install dependencies:

   pip install -r requirements.txt

   

MCP Server Configuration

Installation for MCP Usage

1. Install Python dependencies:

   pip install -r mcp-server/requirements.txt

   

2. Configure your MCP client (e.g., Claude Desktop, Cline):

Add the following to your MCP settings file:

For 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.mcpServers": {

       "cotextual-agent-rules-hub": {

         "command": "python",

         "args": ["C:/path/to/ContextualAgentRulesHub/mcp-server/run_server.py"]

       }

     }

   }

   

Custom Instructions for MCP Client Configuration

As part of your MCP server configuration, you should add the following optimized custom instruction block that leverages the context and core rules features:

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.

Environment Configuration

The MCP server can be configured using environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| RulesLoaderOptions:0:SourceType | Source type for rules loading | YamlFile |
| RulesLoaderOptions:0:Path | Path to rules directory | ./rules |
| AGENT_RULES_VALIDATION | Enable rule validation | true |
| AGENT_RULES_LOG_LEVEL | Logging level (DEBUG, INFO, WARNING, ERROR) | INFO |

Multiple Sources Configuration

You can configure multiple rule sources by using indexed environment variables. Add additional sources using RulesLoaderOptions:1:, RulesLoaderOptions:2:, etc.

Example with multiple sources:
```bash