Etude-Labs/ruleforge-mcp-server

RuleForge MCP Server

RuleForge 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 (RuleForgeOptions).
  • 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/ruleforge-mcp-server.git
cd ruleforge-mcp-server

dotnet build

Run the MCP server (debug configuration):

dotnet run --project src/RuleForge.Mcp -- --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 RuleForgeOptions from a ruleforge section. A minimal YAML config:

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

  logging:
    level: Information

  server:
    name: RuleForge
    version: 0.1.0

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

• RULEFORGE_RULES_DIRECTORIES – colon-separated list of rule directories.
• RULEFORGE_LOGGING_LEVEL – logging level (Debug, Information, etc.).

Project Layout (high level)

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

tests/
  RuleForge.Mcp.Tests.Unit/
  RuleForge.Mcp.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.