Guardrails MCP Server

MCP server for enforcing project guardrails, code quality checks, and linting workflows.

Features

• ESLint Integration: Run ESLint checks on project files
• Prettier Integration: Validate code formatting with Prettier
• Guardrails Validation: Parse and enforce rules from docs/context/90-guardrails.md
• Patch Validation: Check code changes against project standards
• Auto-fix Support: Automatically fix linting and formatting issues

Installation

Via npx (Recommended)

npx @xenergyschool/guardrails-mcp --dir /path/to/project

Via npm

npm install -g @xenergyschool/guardrails-mcp
guardrails-mcp --dir /path/to/project

Usage

Command Line

Run the MCP server:

# Use current directory
guardrails-mcp

# Specify project directory
guardrails-mcp --dir /path/to/project

MCP Configuration

Add to your MCP settings (e.g., Claude Desktop config):

{
  "mcpServers": {
    "guardrails": {
      "command": "npx",
      "args": ["@xenergyschool/guardrails-mcp", "--dir", "/path/to/project"]
    }
  }
}

MCP Tools

1. guardrails.checkPatch

Check files for linting and guardrails violations.

Parameters:

• files (optional): Array of file paths to check
• runLint (optional, default: true): Run ESLint checks
• runFormat (optional, default: true): Run Prettier checks

Example:

{
  "files": ["src/index.ts", "src/utils.ts"],
  "runLint": true,
  "runFormat": true
}

Response:

{
  "ok": true,
  "projectDir": "/path/to/project",
  "filesChecked": 2,
  "results": {
    "lint": {
      "ok": true,
      "violations": [],
      "errorCount": 0,
      "warningCount": 0
    },
    "format": {
      "ok": true,
      "violations": []
    },
    "guardrails": {
      "ok": true,
      "rulesFound": 15,
      "checklistItems": 7,
      "rules": ["..."],
      "checklist": ["..."]
    }
  }
}

2. guardrails.validateRules

Validate project compliance with guardrails rules from docs/context/90-guardrails.md.

Parameters: None

Response:

{
  "ok": true,
  "projectDir": "/path/to/project",
  "guardrailsFile": "/path/to/project/docs/context/90-guardrails.md",
  "sections": ["Processing Rules", "Matching & Identification", "..."],
  "rulesCount": 15,
  "checklistCount": 7,
  "rules": ["Use ETLDatabase and async Supabase interactions", "..."],
  "checklist": [
    {
      "rule": "Job lifecycle updates only append/merge fields",
      "checked": false
    }
  ]
}

3. guardrails.runLint

Run linting tools (ESLint and/or Prettier) on specified files.

Parameters:

• pattern (optional, default: "."): Glob pattern for files to check
• fix (optional, default: false): Auto-fix issues if possible
• tool (optional, default: "both"): Which tool to run ("eslint", "prettier", or "both")

Example:

{
  "pattern": "src/**/*.ts",
  "fix": true,
  "tool": "eslint"
}

Response:

{
  "ok": true,
  "pattern": "src/**/*.ts",
  "fix": true,
  "results": {
    "eslint": {
      "ok": true,
      "output": "...",
      "fixed": true
    }
  }
}

Project Structure Requirements

The MCP server expects the following structure:

your-project/
├── docs/
│   └── context/
│       └── 90-guardrails.md    # Guardrails rules (optional)
├── .eslintrc.json              # ESLint config (optional)
├── .prettierrc                 # Prettier config (optional)
└── ...

Guardrails File Format

The 90-guardrails.md file should follow this format:

# Guardrails

## Section Name
- Rule description
- Another rule

## Compliance Checklist
- [ ] Checklist item 1
- [ ] Checklist item 2

Workflow Integration

With Factory.ai Droid

# Add to mcp_bootstrap.sh
droid <<EOF
/mcp add guardrails "npx @xenergyschool/guardrails-mcp --dir ."
EOF

Usage in Droid Workflow

1. Planning: Run guardrails.validateRules to check compliance
2. Before Commit: Run guardrails.checkPatch on changed files
3. CI/CD: Integrate in pipeline to block non-compliant changes

Development

# Clone repository
git clone https://github.com/xenergyschool/guardrails-mcp.git
cd guardrails-mcp

# Install dependencies
npm install

# Run locally
npm start -- --dir /path/to/project

License

MIT

Author

xenergyschool