Skote Guardian MCP Tool

A Model Context Protocol (MCP) server that enforces Skote theme and Bootstrap design guidelines in your React/TypeScript codebase.

Installation

As an NPM Package

# Global installation
npm install -g skote-guardian-mcp

# Or as a dev dependency
npm install --save-dev skote-guardian-mcp

# Or use with npx (no installation required)
npx skote-guardian-mcp

Usage with Claude Desktop/Code

Option 1: Using NPX (Recommended)

Add to your Claude Desktop config file:

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

{
  "mcpServers": {
    "skote-guardian": {
      "command": "npx",
      "args": ["skote-guardian-mcp"]
    }
  }
}

Option 2: Global Installation

After installing globally with npm install -g skote-guardian-mcp:

{
  "mcpServers": {
    "skote-guardian": {
      "command": "skote-guardian"
    }
  }
}

Option 3: Local Project Installation

Install in your project and use the full path:

{
  "mcpServers": {
    "skote-guardian": {
      "command": "node",
      "args": ["/path/to/your/project/node_modules/skote-guardian-mcp/build/index.js"]
    }
  }
}

Available Tools

1. skote.audit - Audit Files

Scans TSX/JSX files for design violations.

// In Claude Desktop
skote.audit({ paths: ["src/pages/Dashboard.tsx", "src/components/"] })

2. skote.fix - Apply Fixes

Applies auto-fixes for detected issues (with dry-run mode).

// Dry run (preview changes)
skote.fix({ issues: auditResult.issues, write: false })

// Apply fixes
skote.fix({ issues: auditResult.issues, write: true })

3. skote.verify - Verify Runtime

Runtime verification of rendered pages.

skote.verify({ url: "http://localhost:3000/dashboard" })

What It Checks

Grid System ✅

• Proper .container → .row → .col-* hierarchy
• No nested .row inside .row
• Column count ≤ 12 per row
• Consistent gutter usage

Components ✅

• Cards use .card-body, .card-header, .card-footer
• Buttons have proper variant classes
• Images use .img-fluid or explicit dimensions

Design Tokens ✅

• No hardcoded hex colors
• Uses Bootstrap/Skote CSS variables
• Bootstrap spacing utilities (m-, p-)

Accessibility ✅

• Interactive elements have accessible names
• Proper ARIA attributes
• Focus management

Rules

| Rule | Severity | Auto-fixable | Description | |------|----------|--------------|-------------| | grid/invalid-nesting | error | ✅ | Row nested inside row | | grid/column-overflow | warning | ❌ | More than 12 columns in row | | card/invalid-structure | error | ✅ | Card content not in card-body | | tokens/hardcoded-color | warning | 🔧 | Hardcoded colors in styles | | tokens/hex-in-classname | warning | ❌ | Hex colors in className | | buttons/missing-variant | warning | 🔧 | Button without variant class | | images/missing-dimensions | warning | 🔧 | Image without size attributes | | spacing/inline-spacing | warning | 🔧 | Inline margin/padding styles | | a11y/missing-accessible-name | error | ❌ | Interactive element without label |

Output Format

Each issue includes:

{
  "file": "src/pages/Reports.tsx",
  "line": 42,
  "rule": "grid/invalid-nesting",
  "message": "`.row` should not be nested directly inside another `.row`",
  "fix": {
    "type": "wrap",
    "text": "<div className=\"col-12\">{children}</div>"
  },
  "severity": "error"
}

Development

Building from Source

# Clone the repository
git clone https://github.com/hiteshganjoo/skote-guardian-mcp.git
cd skote-guardian-mcp

# Install dependencies
npm install

# Build the package
npm run build

# Watch mode for development
npm run watch

# Test with MCP Inspector
npm run inspector

Testing Locally

1. Build the package: npm run build
2. Link globally: npm link
3. Test in Claude Desktop with the configuration above

Troubleshooting

Claude Desktop doesn't recognize the tool

1. Ensure the package is installed: npm list -g skote-guardian-mcp
2. Restart Claude Desktop after updating the config
3. Check the Claude Desktop logs for errors

Permission errors on macOS/Linux

If you get permission errors, ensure the built file is executable:

chmod +x /path/to/node_modules/skote-guardian-mcp/build/index.js

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Support

For issues and questions, please open an issue on GitHub.