MCP Constraint Monitor

MCP约束监视器

Claude Code的实时约束执行系统，可在策略违规发生之前防止其发生。

概述

MCP约束监视器提供：

• 实时验证：在执行工具之前检查约束
• 灵活的规则：带有可选语义验证的正则表达式模式
• 低延迟：正则表达式检查1-5ms，语义验证50-200ms
• 仪表盘：用于监控违规和合规性的Web UI
• 文件路径与内容检查：控制约束是否检查路径或内容

快速开始

安装

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

基本用法

1. 定义约束 在 .constraint-monitor.yaml:

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

1. 启动监视器:

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

1. 查看仪表板: http://localhost:3030

文档

核心文件

• 约束配置指南 ⭐ 从这里开始

- 基本约束结构 - 所有约束属性(applies_to, severity, flags等等） - 图案匹配技巧 - 真实世界的例子 - 最佳实践和故障排除

高级功能

• 语义约束检测

- 基于人工智能的验证，以减少误报 - LLM整合（Groq、Anthropic、Gemini） - 性能基准测试和缓存

• 语义检测设计

- 架构和设计决策 - 系统图表 - 实现细节

整合

• Claude代码挂钩格式

- Hook数据结构 - 工具调用拦截 - 集成模式

• 状态行集成

- 实时状态显示 - 配置选项

主要特点

文件路径与内容检查

新：使用 applies_to: file_path 要检查文件路径而不是内容，请执行以下操作：

- 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"

这可以防止文件内容提到受保护的路径时出现误报。

语义验证

通过人工智能验证减少误报：

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

例外和白名单

从约束检查中排除特定文件：

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

建筑

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

配置文件

• .constraint-monitor.yaml：项目特定限制（主要）
• constraints.yaml：全球限制（整个存储库）
• config/enforcement.json：强制设置
• .env.ports：端口配置

仪表盘

访问web仪表板http://localhost:3030致：

• 查看实时约束违规
• 监控合规性得分
• 分析违规趋势
• 测试约束模式
• 管理执行设置

发展

运行测试

npm test

调试

启用调试日志记录：

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

添加新约束

1. 编辑 .constraint-monitor.yaml
2. 重新启动显示器： pkill -f global-service-coordinator && node scripts/global-service-coordinator.js --daemon
3. 使用实际文件操作进行测试
4. 监控仪表板上的违规行为

故障排除

约束不射击

1. 检查 enabled: true 在配置中
2. 验证模式正则表达式是否正确
3. 对于 applies_to: file_path，确保模式匹配路径而非内容
4. 重新启动约束监视器

假阳性

1. 添加 applies_to: file_path 如果检查路径
2. 启用 semantic_validation: true
3. 为特定文件添加例外
4. 优化正则表达式模式

请参阅 约束配置指南 了解详细的故障排除。

演出

• 正则表达式检查：每个约束1-5ms
• 语义验证：50-200ms，带缓存
• 仪表盘：通过WebSocket实时更新
• 记忆：~50MB基础+缓存开销

贡献

添加功能时：

1. 更新相关文件
2. 添加新功能的测试
3. 更新配置示例
4. 使用真实场景进行测试

许可证

编码基础设施项目的一部分。

支持

• 文档：参见 docs/ 目录
• 问题：在主存储库中创建问题
• 仪表盘: http://localhost:3030用于监控