rules-mcp-server

MCP (Model Context Protocol) server providing development prompts with embedded rules for microfrontend and microservice applications.

Overview

This MCP server provides interactive prompts for designing and reviewing microfrontend and microservice architectures. All prompts have direct access to development rules and best practices.

Architecture: This server implements the standard three-step MCP server pattern:

1. Create a Server instance and register prompts
2. Create a transport (stdio for local, HTTP for remote)
3. Connect the server to the transport

Content Management: All prompts and rules are defined in markdown files with YAML frontmatter metadata in the content/ directory:

• content/prompts/ - Interactive prompt templates
• content/rules/ - Development rules organized by system

This approach makes it easy to add, edit, and organize content without modifying code. See content/README.md for details on the markdown format and how to add new content.

Features

Prompts

The server provides interactive prompts that guide you through:

• design-microfrontend: Design a new microfrontend application with architectural guidance
• design-microservice: Design a new microservice with best practices
• review-architecture: Review existing architecture against established patterns

Each prompt has access to the complete rule set and provides contextual guidance based on your specific needs

Example queries:

// Get TypeScript-specific microfrontend architecture rules
{
  "name": "get-microfrontend-rules",
  "arguments": {
    "category": "architecture",
    "language": "typescript",
    "codeType": "source"
  }
}

// Get all microservice testing rules
{
  "name": "get-microservice-rules",
  "arguments": {
    "category": "testing",
    "codeType": "test"
  }
}

Rules

The server has access to comprehensive development rules organized by:

Systems:

• Microfrontend architecture
• Microservice architecture

Categories:

• Architecture patterns and decisions
• Performance optimization
• Security best practices
• Testing strategies

Languages:

• TypeScript, JavaScript, Python, Java, Go, Rust

Rules are embedded in prompt responses and provided contextually based on your design needs.

Installation

Prerequisites

• Node.js v24.x or later (latest version recommended)
• npm v11.x or later

From GitHub Packages

This package is published to GitHub Packages. To install it, you need to configure npm to use GitHub Packages for the @yurykabernik scope.

Setup authentication (one-time):

1. Create a GitHub Personal Access Token with read:packages scope
2. Add to your ~/.npmrc (replace <YOUR_GITHUB_TOKEN> with your actual token):

@yurykabernik:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=<YOUR_GITHUB_TOKEN>

Global installation:

npm install -g @yurykabernik/rules-mcp-server
rules-mcp-server

Use with npx (no installation):

npx @yurykabernik/rules-mcp-server

As NPM Package (Public Registry)

If published to npm public registry:

Global installation:

npm install -g rules-mcp-server
rules-mcp-server

Use with npx (no installation):

npx -y rules-mcp-server

From Source

1. Clone the repository:

git clone https://github.com/YuryKabernik/rules-mcp-server.git
cd rules-mcp-server

2. Install dependencies and build:

npm install
npm run build

Using Dev Container (Recommended for Development)

This project includes a VS Code Dev Container configuration for a consistent development environment:

1. Install Docker and VS Code
2. Install the Dev Containers extension
3. Clone the repository and open in VS Code
4. Click "Reopen in Container" when prompted (or use F1 → "Dev Containers: Reopen in Container")
5. The environment will be automatically set up with all dependencies

See .devcontainer/README.md for more details.

Usage

Running the Server

Development Mode (with auto-reload)

npm run dev

Production Mode

npm start

Watch Mode (auto-rebuild on changes)

npm run watch

Using with MCP Clients

The server uses stdio transport and can be integrated with any MCP-compatible client.

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "rules-mcp-server": {
      "command": "npx",
      "args": ["@yurykabernik/rules-mcp-server"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "rules-mcp-server": {
      "command": "rules-mcp-server"
    }
  }
}

Or from source:

{
  "mcpServers": {
    "rules-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/rules-mcp-server/build/index.js"]
    }
  }
}

See mcp-config.example.json for reference.

Development

Project Structure

rules-mcp-server/
├── content/                     # 📝 All MCP content (markdown files)
│   ├── rules/                  # Development rules by system
│   │   ├── microfrontend/
│   │   └── microservice/
│   ├── tools/                  # Tool definitions
│   ├── prompts/                # Prompt templates
│   └── resources/              # Documentation resources
├── build/                       # Compiled JavaScript (generated)
├── package.json                 # Project metadata and dependencies
├── tsconfig.json                # TypeScript configuration
└── README.md                   # This file

Content Management: All server content is in the content/ directory as markdown files with frontmatter metadata. See content/README.md for details on how to add or modify content.

Available Scripts

Development:

• npm run build - Compile TypeScript to JavaScript
• npm run watch - Watch mode for development (auto-rebuild)
• npm run dev - Run server in development mode with tsx
• npm start - Run the compiled server
• npm run prepare - Automatically builds before npm publish

Testing:

• npm test - Run all unit tests (fast, ~1 second)
• npm run test:watch - Run tests in watch mode
• npm run test:ui - Open visual test UI
• npm run test:coverage - Generate coverage report

Code Quality:

• npm run lint - Run ESLint to check code quality
• npm run lint:fix - Auto-fix ESLint issues
• npm run format - Format code with Prettier
• npm run format:check - Check code formatting

Code Quality Tools

This project uses ESLint and Prettier for consistent code styling:

• ESLint: Enforces code quality rules and catches common errors
• Prettier: Ensures consistent code formatting
• EditorConfig: Maintains consistent coding styles across different editors

IDE Integration:

• VS Code settings are pre-configured in .vscode/settings.json
• Install recommended extensions from .vscode/extensions.json
• Code is auto-formatted on save

Adding Content

Rules are now stored as markdown files with frontmatter metadata in the rules/ directory. This makes it easy to add and edit content without modifying TypeScript code.

1. Adding Rules

Quick Start:

1. Create a new markdown file in the appropriate directory:

   • rules/microfrontend/ for microfrontend rules
   • rules/microservice/ for microservice rules

2. Add frontmatter metadata at the top:

---
id: mfe-arch-002
title: Your Rule Title
description: Brief description
category: architecture
system: microfrontend
language: typescript  # optional
codeType: source     # optional
tags:
  - tag1
  - tag2
---

# Your Rule Content

Write your rule content in markdown...

3. Build and test:

npm run build
npm start

Detailed Guide: See content/rules/README.md for complete documentation on:

• Markdown format and frontmatter fields
• Naming conventions
• Adding examples and code snippets
• Best practices for writing rules

Adding a new project system:

To add support for a new system (e.g., "monolith"):

1. Create a new directory: content/rules/monolith/
2. Add markdown rule files in that directory following the frontmatter format
3. Create a new tool definition in content/tools/get-monolith-rules.md
4. Restart the server - new content is automatically loaded

See content/README.md for detailed instructions.

2. Adding Resources

Resources provide documentation and guides. Add new markdown files in content/resources/ with proper frontmatter:

---
uri: rules://monolith/architecture
name: Monolith Architecture Guide
description: Guide for building monolithic applications
mimeType: text/markdown
---

# Your resource content here...

3. Adding Prompts

Prompts provide interactive templates. Add new markdown files in content/prompts/ with proper frontmatter:

---
name: design-monolith
description: Help design a monolithic application
arguments:
  - name: app_name
    description: Name of the application
    required: true
---

# Your prompt template here with {{variables}}...

Technical Details

Built With

• Runtime: Node.js v24.x (ESM modules)
• Language: TypeScript 5.x
• SDK: @modelcontextprotocol/sdk v1.26.0 (latest stable)
  • 📝 v2 Migration Guide - v2 planned for Q1 2026, architecture ready for smooth migration
• Build Tool: TypeScript compiler (tsc)
• Dev Runner: tsx (TypeScript execute)

MCP Capabilities

This server implements the following MCP capabilities:

• ✅ Tools (for rules and best practices)
• ✅ Resources (for documentation)
• ✅ Prompts (for interactive guidance)

Transport

Uses stdio transport for communication with MCP clients. The server follows the standard MCP three-step architecture pattern:

1. Create Server: Instantiate MCP Server and register handlers
2. Create Transport: Set up stdio transport for local integrations
3. Connect: Wire the server to the transport

For detailed architecture documentation, see docs/ARCHITECTURE.md.

Continuous Integration

This project uses GitHub Actions for automated testing and quality checks:

• CI Workflow: Runs on every push to every branch and all pull requests
  • Build verification (TypeScript compilation)
  • Unit tests (Vitest)
  • Build artifact upload

See CI_WORKFLOW.md for detailed documentation.

Contributing

This is a proof-of-concept project for aggregating rules across multiple similar projects. Contributions for rules, resources, and prompts are welcome!

License

ISC

Troubleshooting

Server Not Starting

1. Ensure Node.js v24.x or later is installed:

   node --version
   

2. Rebuild the project:

   npm run build
   

3. Check for errors in the console output

MCP Client Not Connecting

1. Verify the path to the build/index.js file is correct
2. Ensure the build directory exists and contains compiled files
3. Check MCP client logs for connection errors

Build Errors

1. Clean and reinstall dependencies:

   rm -rf node_modules package-lock.json
   npm install
   

2. Verify TypeScript version:

   npx tsc --version
   

Future Enhancements

• [ ] Add comprehensive microfrontend rules (Module Federation, routing, state management, etc.)
• [ ] Add comprehensive microservice rules (API design, service mesh, resilience patterns, etc.)
• [ ] Add detailed architectural guides
• [ ] Include code examples and templates
• [ ] Add validation rules and linting recommendations
• [ ] Include testing strategies and examples
• [ ] Add CI/CD pipeline recommendations

Links

• Model Context Protocol Documentation
• MCP SDK on GitHub
• Repository Issues