teitasan/rules-mcp-server

Rules MCP Server

A Model Context Protocol (MCP) server for detecting rules.md violations and providing AI-powered inline suggestions. Designed to work seamlessly with Cursor and other AI development tools.

Features

• 🔍 Real-time Rule Checking: Analyze code and text against your custom rules.md style guide
• 🤖 AI-Powered Suggestions: Get intelligent violation fixes and improvement suggestions
• 📝 Comprehensive Logging: Detailed logging with categorization and context
• ⚡ High Performance: 100KB input limit with sub-2-second response times
• 🔒 Local-First: All processing happens locally - no external API dependencies

Requirements

• Node.js 20.0.0 or higher
• A rules.md file in your project root

Installation

Global Installation

npm install -g rules-mcp-server

Local Installation

npm install rules-mcp-server

Using npx (Recommended for testing)

npx rules-mcp-server

Usage

Automated Installation (Recommended)

Rules MCP Server includes automated installation scripts for seamless Cursor integration:

# Install to current project (creates/updates .cursor/mcp.json)
npm run install:cursor

# Install globally (updates ~/.cursor/mcp.json)  
npm run install:cursor:global

# Check installation status
npm run mcp:status

# Remove from project
npm run uninstall:cursor

Manual Installation

For manual setup or custom configurations:

1. Add to your .cursor/mcp.json configuration:

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

2. Create a rules.md file in your project root with your coding standards
3. Restart Cursor and start using the AI tools - violations will be automatically detected!

Available Tools

• fix-rules: Analyze text for rule violations and get fix suggestions
• rules-status: Check the status of your rules.md file loading

Direct Execution

# Run the server directly
npx rules-mcp-server

# Or if installed globally
rules-mcp-server

Configuration

rules.md File

Create a rules.md file in your project root. Example:

# Project Rules

## Code Style
- Use camelCase for variables
- Add comments for complex logic

## Testing
- All functions must have tests
- Use descriptive test names

Environment Variables

• LOG_LEVEL: Set logging level (debug, info, warn, error)

Testing

# Run all tests
npm test

# Run specific test suites
npm run test:rules    # Test rules loading
npm run test:mcp      # Test MCP server functionality  
npm run test:logging  # Test error handling and logging

Development

Project Structure

rules-mcp-server/
├── index.js              # Main MCP server
├── lib/
│   ├── logger.js         # Enhanced logging system
│   └── rules-analyzer.js # Rule violation analysis
├── test/                 # Test suites
├── assets/              # Templates and examples
└── package.json

Building and Testing Package

# Test package creation
npm run pack:test

# Create actual package
npm pack

Integration Examples

Cursor AI

1. Install the package globally or use npx
2. Configure in .cursor/mcp.json
3. The AI will automatically check your code against rules.md

Command Line Usage

# Check if rules are loaded properly
echo '{"method": "tools/list"}' | npx rules-mcp-server

# Analyze code for violations
echo '{"method": "tools/call", "params": {"name": "fix-rules", "arguments": {"text": "var badVariable = true;"}}}' | npx rules-mcp-server

Performance

• Input Limit: 100KB per request
• Response Time: < 2 seconds for typical analysis
• Memory Usage: Optimized for low memory footprint
• File Size: Warns on rules.md files > 1MB

Error Handling

The server provides comprehensive error handling with helpful suggestions:

• Missing rules.md file → Suggests creating one
• Permission errors → Suggests checking file permissions
• Large files → Performance warnings
• Invalid Markdown → Syntax validation

API Documentation

For complete API specifications and integration details:

• : Complete MCP tool specifications
• : Detailed Cursor integration guide

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - see file for details.

Support

• GitHub Issues: Report bugs and request features
• Documentation: This README and inline code comments
• Examples: Check the assets/ directory for templates

Note: This server is designed to work locally and does not send any code or data to external services.