fwornle/mcp-constraint-monitor

MCP Constraint Monitor

🛡️ Universal MCP server for real-time coding constraint monitoring and live guardrails

Add intelligent code quality monitoring to any Claude Code project with zero configuration. The constraint monitor provides real-time violation detection, compliance scoring, and live guardrails that keep your coding on track.

🎯 Features

• 🛡️ Live Guardrails: Real-time constraint violation detection
• 📊 Compliance Scoring: Automated code quality assessment
• 🌐 Web Dashboard: Comprehensive constraint management interface
• 🔍 Pattern Detection: Configurable rules for code patterns
• ⚡ Ultra-Fast: Sub-10ms constraint checking
• 🧠 AI-Powered: Optional semantic analysis with Grok
• 📈 Enhanced Status Line: Rich tooltips with visual progress bars
• 🔧 Zero Config: Works out of the box with sensible defaults
• 🌐 Universal: Works with any Claude Code project

🚀 Quick Start

Installation Options

Option 1: Standalone Installation (Recommended for standalone use)

Clone and install with hooks configured automatically:

git clone https://github.com/fwornle/mcp-server-constraint-monitor.git
cd mcp-server-constraint-monitor
./install.sh

This will:

• ✅ Install all dependencies (main + dashboard with Redux)
• ✅ Configure Claude Code hooks automatically
• ✅ Set up .claude/settings.local.json with constraint enforcement

Option 2: Dependencies Only (For integration into larger projects)

./install.sh --skip-hooks

Use this when:

• You're integrating into a larger project (like coding repo)
• The parent project manages hook configuration
• You only need dependency installation

Option 3: NPM Global Install

# Via npm (for CLI usage)
npm install -g mcp-constraint-monitor

# Or use npx (no installation)
npx mcp-constraint-monitor

Add to Claude Code

Step 1: Add MCP Server

Add to your ~/.claude/mcp.json or project's .mcp.json:

{
  "mcpServers": {
    "constraint-monitor": {
      "command": "npx",
      "args": ["mcp-constraint-monitor"]
    }
  }
}

Step 2: Configure Real-Time Hooks

Add to your ~/.claude/settings.local.json for real-time constraint enforcement:

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "node /path/to/mcp-constraint-monitor/src/hooks/pre-prompt-hook-wrapper.js"
      }]
    }],
    "PreToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "node /path/to/mcp-constraint-monitor/src/hooks/pre-tool-hook-wrapper.js"
      }]
    }]
  }
}

Hook Types:

• UserPromptSubmit: Checks user prompts for constraint violations
• PreToolUse: Prevents tool execution that would violate constraints
• Prevention: Violations are blocked before execution, not detected after

Start Monitoring

# In your project directory
mcp-constraint-monitor

That's it! The constraint monitor will:

• ✅ Create default configuration
• ✅ Initialize local databases
• ✅ Start monitoring your code
• ✅ Display status in Claude Code

📋 MCP Tools

The server exposes these tools for Claude Code:

🛡️ Status Line & Dashboard Integration

Enhanced Status Line

The constraint monitor provides rich status line integration with enhanced tooltips:

🛡️ 8.5 🔍EX

Hover Tooltip:

🛡️ Constraint Monitor Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Compliance: 8.5/10.0
   █████████████░░ (Good)
✅ Status: No active violations
🔍 Activity: Exploring
🟢 Risk Level: Low
🔧 Interventions: 0
🟢 System: Operational

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🖱️  Click to open dashboard
🔄 Updates every 5 seconds

Status Elements:

• 🛡️ 8.5 - Compliance score (0-10)
• 🔍EX - Current trajectory (Exploring, On Track, Implementing, etc.)
• Click Action - Opens web dashboard

Status Colors:

• 🟢 Green: Excellent compliance (9.0+)
• 🔵 Cyan: Good compliance (7.0-8.9)
• 🟡 Yellow: Warning compliance (5.0-6.9)
• 🔴 Red: Critical violations or offline

Web Dashboard

Access the comprehensive web dashboard at http://localhost:3030/dashboard

Dashboard Features:

• 📊 Real-time Metrics: Live compliance scoring and violation tracking
• 📋 Constraint Management: View and manage all constraint rules
• ⚡ Activity Feed: Real-time system activity and events
• 📱 Responsive Design: Works on desktop and mobile devices
• 🌙 Dark/Light Mode: Automatic theme detection
• 🔧 Health Monitoring: System status and performance metrics
• 📈 Violation Trends: Historical analysis with configurable time ranges
• ⚠️ Real-time Alerts: Live notification of constraint violations

Quick Access:

# Launch dashboard (development)
cd integrations/mcp-constraint-monitor
PORT=3030 npm run dashboard

# Launch API server (production)
PORT=3031 npm run api

# Health check
curl http://localhost:3031/api/health

API Endpoints:

• GET /api/health - System health and uptime
• GET /api/status - Current compliance metrics and hook status
• GET /api/constraints - All constraint rules and configuration
• GET /api/violations - Active violation history with filtering
• GET /api/activity - Real-time event feed and hook executions
• GET /api/projects - Multi-project constraint monitoring status

Health Monitoring: The dashboard includes comprehensive health monitoring for:

• Hook System Status: Real-time verification of Claude Code hook integration
• API Response Times: Sub-10ms constraint checking performance
• Constraint Engine Health: Pattern matching and violation detection status
• Database Connectivity: SQLite, Qdrant (optional), and Redis (optional) status
• Memory Usage: System resource utilization and performance metrics

⚙️ Configuration

Default Constraints

The monitor comes with sensible defaults:

constraints:
  - id: no-console-log
    pattern: "console\\.log"
    message: "Use Logger.log() instead of console.log"
    severity: warning
    
  - id: no-var-declarations  
    pattern: "\\bvar\\s+"
    message: "Use 'let' or 'const' instead of 'var'"
    severity: warning
    
  - id: no-hardcoded-secrets
    pattern: "(api[_-]?key|password|secret)\\s*[=:]\\s*['\"][^'\"]{8,}['\"]"
    message: "Potential hardcoded secret detected"
    severity: critical

Project-Specific Rules

Create constraints.yaml in your project:

constraints:
  # Your project-specific rules
  - id: react-hooks-deps
    pattern: "useEffect\\([^,]*,\\s*\\[\\]"
    message: "Verify useEffect dependencies"
    severity: info
    enabled: true

  # Framework-specific patterns
  - id: redux-direct-mutation
    pattern: "state\\.[\\w.]+\\s*="
    message: "Direct state mutation - use Redux patterns"
    severity: error

Environment Variables

Optional configuration via environment:

export XAI_API_KEY="your-key"           # Enable AI analysis
export QDRANT_HOST="localhost"          # Vector database
export ANALYTICS_DB_PATH="./data.db"    # Persistent analytics

🏗️ Architecture

Real-Time Guardrails Architecture

⚠️ Important: This system uses pre-tool hook prevention for real-time constraint enforcement, not post-hoc file monitoring.

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Claude Code   │◄──►│  Hook System     │◄──►│ Constraint      │
│                 │    │                  │    │ Engine          │
│ • PreToolUse    │ ━► │ • Pre-Tool Hook  │ ━► │ • Pattern Check │
│ • UserPrompt    │ ━► │ • Pre-Prompt     │ ━► │ • Violation     │
│ • Status Line   │    │ • Real-time      │    │ • Prevention    │
└─────────────────┘    │   Prevention     │    └─────────────────┘
                       └──────────────────┘              │
                                 │                       │
┌─────────────────┐    ┌──────────────────┐              │
│  Web Dashboard  │◄──►│   MCP Server     │◄─────────────┘
│                 │    │                  │
│ • Real-time UI  │    │ • Status API     │
│ • Health Monitor│    │ • Config Mgmt    │
│ • Violation Mgmt│    │ • History        │
└─────────────────┘    └──────────────────┘

Hook-Based Prevention Flow

1. Pre-Tool Hook: Intercepts tool calls before execution
2. Constraint Check: Real-time pattern matching (< 1ms)
3. Violation Prevention: Blocks violating actions immediately
4. Status Update: Real-time dashboard and status line updates

Logging Architecture Status

Performance Targets

System Status

• Pre-Tool Hooks: ✅ Real-time tool interception working
• Pre-Prompt Hooks: ✅ User prompt constraint checking active
• Constraint Engine: ✅ Sub-5ms violation prevention achieved
• Dashboard Health: ✅ Real-time monitoring and API endpoints operational
• Claude Integration: ✅ Hook system integrated with settings.local.json

🔧 Development

Local Setup

git clone https://github.com/fwornle/mcp-constraint-monitor
cd mcp-constraint-monitor
npm install
npm run setup

Testing

npm test                    # Run tests
npm run start              # Start server
npm run dev                # Development mode
./bin/demo                 # Complete system demo

Custom Engines

Add custom analysis engines:

import { ConstraintEngine } from 'mcp-constraint-monitor';

class CustomEngine extends ConstraintEngine {
  async checkCustomPattern(code) {
    // Your custom logic
  }
}

📚 Examples

React Project

constraints:
  - id: react-memo
    pattern: "export default function\\s+\\w+.*\\{[^}]*useState"
    message: "Consider React.memo for components with complex state"
    severity: info

Node.js API

constraints:
  - id: async-error-handling
    pattern: "app\\.(get|post|put|delete).*async.*\\{(?![^}]*catch)"
    message: "Async routes should have error handling"
    severity: error

Security-Focused

constraints:
  - id: sql-injection
    pattern: "\\$\\{[^}]*\\}.*SELECT|INSERT.*\\$\\{[^}]*\\}"
    message: "Potential SQL injection - use parameterized queries"
    severity: critical

🔒 Advanced Features

Real-Time Semantic Analysis

• Sub-50ms Analysis: Groq's mixtral-8x7b model delivers 1000+ tokens/sec
• Trajectory Thinking: Evaluates accumulated intent vs individual actions
• Context Persistence: Maintains constraint state across conversation auto-compaction
• Multi-Step Workflow Recognition: Distinguishes exploration from violation

Predictive Risk Assessment

The system learns from violation patterns to predict and prevent issues:

// Risk assessment before action execution
{
  "riskScore": 0.85,
  "reason": "Similar pattern led to violations in 3 recent sessions", 
  "alternatives": [
    "Read configuration files first",
    "Check user constraints in previous messages"
  ]
}

Database Options

Basic Mode (SQLite only):

• Fast constraint checking
• Violation history
• Local analytics

Enhanced Mode (with Docker):

• Vector similarity search (Qdrant)
• Advanced analytics (Redis)
• Semantic analysis
• Pattern learning

📊 API Reference

MCP Tools

// Check constraint status
mcp__constraint_monitor__get_constraint_status()

// Check specific code
mcp__constraint_monitor__check_action_constraints({
  action: { type: "code", content: "console.log('test')" }
})

// Add custom constraint
mcp__constraint_monitor__add_constraint_rule({
  id: "custom-rule",
  type: "pattern", 
  matcher: "TODO:",
  message: "No TODO comments in production code"
})

// Get violation history
mcp__constraint_monitor__get_violation_history({ limit: 10 })

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature-name
3. Add tests for new functionality
4. Submit pull request

Development Workflow

# Install dependencies
npm install

# Run tests
npm test

# Start development server
npm run dev

# Build for production
npm run build

📄 License

MIT License - see for details.

🆘 Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions

Built for the Claude Code ecosystem - Add intelligence to your coding workflow 🚀

Why Use MCP Constraint Monitor?

For Individual Developers:

• Catch coding mistakes before they become bugs
• Learn better coding patterns through real-time feedback
• Maintain consistent code quality across projects

For Teams:

• Enforce shared coding standards automatically
• Reduce code review time with automated checks
• Share constraint configurations across team members

For Projects:

• Zero-configuration setup works immediately
• Scales from simple scripts to complex applications
• Integrates with existing development workflows

Get started in under 30 seconds - just add the MCP server to your configuration and start coding with intelligent guardrails!