Etude Agent Rules MCP Server

Etude Agent Rules is an IDE-agnostic Model Context Protocol (MCP) server that exposes your project rules and workflows as MCP resources. It gives AI coding tools a consistent, discoverable view of development guidelines, so agents always get the right context at the right time.

This repo contains the reference .NET 9 implementation.

Features

Clean Architecture
- Core domain models and ports (Rule, RuleMetadata, RuleSource, IRuleRepository, IFrontmatterParser).
- Application configuration (AgentRulesOptions).
- Infrastructure for YAML frontmatter, file system rules, and MCP protocol.
YAML frontmatter parsing
- Supports frontmatter at the top of markdown files:
```
---
description: Example rule
tags:
  - example
applyTo: "**/*.cs"
category: testing
---
```
- Parsed into RuleMetadata and stripped from the body before serving to clients.
File system rule repository
- Recursively scans configured directories for rule files.
- Canonicalizes paths and enforces directory whitelisting.
- Skips files larger than 1MB (configurable in future versions).
MCP JSON-RPC protocol
- Implements MCP methods over stdio:
  - initialize
  - initialized (notification)
  - resources/list
  - resources/read
- Follows JSON-RPC 2.0 error semantics with MCP-specific -32002 (resource not found).
MCP tools (v0.2.0)
- Exposes query and discovery tools via tools/list and tools/call:
  - query_rules — filter rules by tags, categories, and applyTo globs.
  - list_categories — list available rule categories with rule counts.
  - list_tags — list available tags with rule counts.
- Example tools/call request for query_rules:
```
{
  "jsonrpc": "2.0",
  "id": 21,
  "method": "tools/call",
  "params": {
    "name": "query_rules",
    "arguments": {
      "tags": ["architecture"],
      "categories": ["development"],
      "applyToGlobs": ["**/*.cs"],
      "limit": 10
    }
  }
}
```
Host & logging
- Generic host with Microsoft.Extensions.Hosting.
- Serilog logging to stderr only (stdout reserved for MCP protocol).
- Stdio transport (McpTransport) reading/writing newline-delimited JSON.

Requirements

.NET 9 SDK

Quickstart

Clone and build the project:

git clone https://github.com/Etude-Labs/etude-agent-rules-mcp.git
cd etude-agent-rules-mcp

dotnet build

Run the MCP server (debug configuration):

dotnet run --project src/EtudeLabs.AgentRules.Host -- --config config.yaml

The server communicates over stdio. MCP-compatible clients (IDEs, agents) should start this executable and speak JSON-RPC 2.0 with MCP resources.

Configuration

Configuration is bound into AgentRulesOptions from an agentrules section. A minimal YAML config:

agentrules:
  rules:
    directories:
      - ~/.agentrules/rules
      - ./.windsurf/rules

  logging:
    level: Information

  server:
    name: Etude Agent Rules
    version: 1.0.0

See docs/configuration-and-integration.md for details on prompts, hierarchical rules with hot-reload, caching, telemetry, HTTP endpoints, and the reload_rules tool.

Environment variables can override key settings (see SPEC for full list), e.g.:

AGENTRULES_RULES_DIRECTORIES – colon-separated list of rule directories.
AGENTRULES_LOGGING_LEVEL – logging level (Debug, Information, etc.).

Project Layout (high level)

src/
  EtudeLabs.AgentRules.Host/           # Host (entry point, DI, logging)
  EtudeLabs.AgentRules.Core/           # Domain models and ports
  EtudeLabs.AgentRules.Application/    # Application layer (services, options)
  EtudeLabs.AgentRules.Infrastructure/
    FileSystem/                        # FileSystemRuleRepository
    Yaml/                              # YamlFrontmatterParser
    Mcp/                               # McpServer, McpTransport, hosted service

tests/
  EtudeLabs.AgentRules.Tests.Unit/
  EtudeLabs.AgentRules.Tests.Integration/

See specs/versions/v1.0/sprints/sprint-1/SPEC.md for detailed design.

Development

Common commands:

dotnet build           # Build all projects
dotnet test            # Run all unit + integration tests
dotnet format          # Apply code style/formatting

CI runs the same dotnet build and dotnet test steps on GitHub Actions.

License

This project is licensed under the MIT License. See LICENSE for details.

MCP Servers