约束监控系统

Constraint Monitor

Real-time constraint enforcement system for Claude Code that prevents policy violations before they happen.

Overview

The four MCP tools are retired. Their schemas cost ~1.5 KB in every context window for actions only ever taken deliberately. The agent-facing entry point is the constraints CLI (bin/constraints + the /constraints skill), which runs in-process against the same ConstraintEngine — so it keeps working when the container is down. Enforcement was never MCP anyway: it is the PreToolUse / UserPromptSubmit hooks, which are unchanged. src/server.js and src/sse-server.js still work for any external MCP client.

The Constraint Monitor provides:

• Real-time validation: Checks constraints before tool execution
• Flexible rules: Regex patterns with optional semantic validation
• Low latency: 1-5ms for regex checks, 50-200ms with semantic validation
• Dashboard: Web UI for monitoring violations and compliance
• File path vs content checking: Control whether constraints check paths or content

Quick Start

Installation

cd integrations/constraint-monitor
npm install
./install.sh

Basic Usage

1. Define constraints in .constraint-monitor.yaml:

constraints:
  - id: my-constraint
    pattern: "forbidden-pattern"
    message: "This pattern is not allowed"
    severity: error
    enabled: true

2. Start the monitor:

node scripts/global-service-coordinator.js --daemon

3. View dashboard: http://localhost:3030

Docker Deployment (HTTP/SSE Mode)

For containerized deployments, the MCP server supports HTTP/SSE transport:

# Start as SSE server (Docker mode)
npm run sse-server

# Or directly:
node src/sse-server.js

HTTP/SSE Endpoints:

• GET /health - Health check endpoint
• GET /sse - Server-Sent Events connection
• POST /messages - JSON-RPC message endpoint

Port Configuration:

• MCP SSE Server: 3849 (configurable via CONSTRAINT_MONITOR_SSE_PORT)
• Dashboard UI: 3030 (via CONSTRAINT_DASHBOARD_PORT)
• API Backend: 3031 (via CONSTRAINT_API_PORT)

Health Check:

curl http://localhost:3849/health

Claude Code Integration (Docker Mode):

In Docker mode, Claude connects via a lightweight stdio proxy:

{
  "constraint-monitor": {
    "command": "node",
    "args": ["path/to/src/stdio-proxy.js"],
    "env": {
      "CONSTRAINT_MONITOR_SSE_URL": "http://localhost:3849"
    }
  }
}

See the parent Docker Deployment Guide for full containerization setup.

Documentation

Core Documentation

• Constraint Configuration Guide ⭐ START HERE
  • Basic constraint structure
  • All constraint properties (applies_to, severity, flags, etc.)
  • Pattern matching tips
  • Real-world examples
  • Best practices and troubleshooting

Advanced Features

• Semantic Constraint Detection

  • AI-powered validation to reduce false positives
  • LLM integration (Groq, Anthropic, Gemini)
  • Performance benchmarks and caching

• Semantic Detection Design

  • Architecture and design decisions
  • System diagrams
  • Implementation details

Integration

• Claude Code Hook Format

  • Hook data structure
  • Tool call interception
  • Integration patterns

• Status Line Integration

  • Real-time status display
  • Configuration options

Key Features

File Path vs Content Checking

NEW: Use applies_to: file_path to check file paths instead of content:

- id: knowledge-base-protection
  pattern: "\\.data/knowledge-export/"
  applies_to: file_path  # Only blocks files IN this path
  message: "Use bin/ukb CLI to modify knowledge base"

This prevents false positives when file content mentions protected paths.

Semantic Validation

Reduce false positives with AI-powered validation:

- id: smart-constraint
  pattern: "console\\.log"
  semantic_validation: true  # LLM verifies if it's a real violation

Exceptions and Whitelists

Exclude specific files from constraint checking:

- id: my-constraint
  pattern: "strict-rule"
  exceptions:
    - path: "**/*.test.js"
      reason: "Tests are exempt"

Architecture

Claude Code Tool Call
        ↓
Pre-Tool Hook (Node.js)
        ↓
Constraint Engine
        ↓
[Regex Check] → [Semantic Validation (optional)]
        ↓
Block or Allow

Configuration Files

• .constraint-monitor.yaml: Project-specific constraints (primary)
• constraints.yaml: Global constraints (repository-wide)
• config/enforcement.json: Enforcement settings
• .env.ports: Port configuration

Dashboard

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

• View real-time constraint violations
• Monitor compliance scores
• Analyze violation trends
• Test constraint patterns
• Manage enforcement settings

Development

Running Tests

npm test

Debugging

Enable debug logging:

export LOG_LEVEL=debug
node src/dashboard-server.js

Adding New Constraints

1. Edit .constraint-monitor.yaml
2. Restart the monitor: pkill -f global-service-coordinator && node scripts/global-service-coordinator.js --daemon
3. Test with actual file operations
4. Monitor dashboard for violations

Troubleshooting

Constraint not firing

1. Check enabled: true in configuration
2. Verify pattern regex is correct
3. For applies_to: file_path, ensure pattern matches paths not content
4. Restart the constraint monitor

False positives

1. Add applies_to: file_path if checking paths
2. Enable semantic_validation: true
3. Add exceptions for specific files
4. Refine regex pattern

See the Constraint Configuration Guide for detailed troubleshooting.

Performance

• Regex checking: 1-5ms per constraint
• Semantic validation: 50-200ms with caching
• Dashboard: Real-time updates via WebSocket
• Memory: ~50MB base + caching overhead

Contributing

When adding features:

1. Update relevant documentation
2. Add tests for new functionality
3. Update configuration examples
4. Test with real-world scenarios

License

Part of the coding infrastructure project.

Support

• Documentation: See docs/ directory
• Issues: Create an issue in the main repository
• Dashboard: http://localhost:3030 for monitoring