vibecheck-mcp-server 2.0.1

package/README.md

@@ -0,0 +1,191 @@
+# Guardrail MCP Server
+
+Professional Model Context Protocol server for Guardrail AI.
+
+> "Stop shipping pretend features."
+
+## Installation
+
+```bash
+npm install -g guardrail-mcp-server
+```
+
+## Configuration
+
+See [MCP-INSTALLATION-GUIDE.md](../docs/MCP-INSTALLATION-GUIDE.md) for editor-specific setup.
+
+## Development
+
+```bash
+cd mcp-server
+npm install
+npm start
+```
+
+## Premium Command Palette Tools
+
+These tools provide a top-notch, zero-friction UX:
+
+### Ship Check Commands
+- `run_ship` - Guardrail: Ship Check (GO/NO-GO)
+- `run_reality` - Guardrail: Run Reality Mode
+- `run_mockproof` - Guardrail: Run MockProof Gate
+- `run_airlock` - Guardrail: Run Airlock (SupplyChain)
+
+### Report & Artifact Commands
+- `get_last_run` - Guardrail: Open Last Run Report
+- `open_artifact` - Open Report/Replay/Trace/SARIF/Badge
+- `rerun_last_check` - Guardrail: Re-run Last Check
+- `export_sarif` - Export findings as SARIF
+
+### Setup & Policy Commands
+- `run_doctor` - Guardrail: Doctor (Fix my setup)
+- `edit_policies` - Guardrail: Policies (Quick Edit)
+- `get_status` - Get server status and workspace info
+- `policy_patch` - Apply atomic policy changes
+
+### Fix Mode Commands
+- `enter_fix_mode` - Enter Fix Mode for blocker resolution
+- `fix_mode_status` - Get Fix Mode checklist status
+- `mark_fix_complete` - Mark blocker as fixed
+- `exit_fix_mode` - Exit and re-run ship check
+
+### Evidence & Diagnostics
+- `explain_finding` - Get detailed finding explanation
+
+## AI Guardrail Tools (Prompt Firewall + Output Verification)
+
+These tools provide AI safety and verification capabilities:
+
+| Tool | Description |
+|------|-------------|
+| `guardrail.verify` | 🛡️ Verify AI agent output before applying - checks secrets, dangerous commands, path traversal |
+| `guardrail.quality` | 📊 Code quality analysis - complexity, maintainability, technical debt metrics |
+| `guardrail.smells` | 👃 Code smell detection - anti-patterns, naming issues, structural problems |
+| `guardrail.hallucination` | 🔍 Hallucination check - verify claims against actual source code |
+| `guardrail.breaking` | ⚠️ Breaking change detection - API changes, removed methods, type changes |
+| `guardrail.mdc` | 📝 MDC Generator - source-anchored documentation generation |
+| `guardrail.coverage` | 🧪 Test coverage mapping - identify untested components |
+
+### Example Usage
+
+```json
+// Verify AI-generated code before applying
+{
+  "tool": "guardrail.verify",
+  "arguments": {
+    "input": "{\"format\":\"guardrail-v1\",\"diff\":\"...\",\"commands\":[]}",
+    "mode": "build"
+  }
+}
+
+// Check code quality
+{
+  "tool": "guardrail.quality",
+  "arguments": {
+    "projectPath": ".",
+    "threshold": 70
+  }
+}
+
+// Detect code smells
+{
+  "tool": "guardrail.smells",
+  "arguments": {
+    "projectPath": ".",
+    "severity": "high"
+  }
+}
+```
+
+## Agent Checkpoint Tools
+
+Pre-write validation that blocks AI agents until issues are fixed:
+
+| Tool | Description |
+|------|-------------|
+| `guardrail_checkpoint` | 🛡️ Validate code before writing - blocks on TODOs, mocks, console.log, etc. |
+| `guardrail_set_strictness` | ⚙️ Set checkpoint strictness: chill, standard, strict, paranoid |
+| `guardrail_checkpoint_status` | 📊 Get current checkpoint status and blocking violations |
+
+## Architect Tools
+
+AI agents consult the Architect before writing code:
+
+| Tool | Description |
+|------|-------------|
+| `guardrail_architect_review` | 🏛️ Review code against architecture patterns |
+| `guardrail_architect_suggest` | 💡 Get architectural guidance before writing code |
+| `guardrail_architect_patterns` | 📋 List all active architecture patterns |
+| `guardrail_architect_set_strictness` | ⚙️ Set architect strictness level |
+
+## Codebase Architect Tools
+
+Deep codebase knowledge for AI agents:
+
+| Tool | Description |
+|------|-------------|
+| `guardrail_architect_context` | 🧠 Load full codebase context (tech stack, conventions, patterns) |
+| `guardrail_architect_guide` | 🏛️ Get guidance for creating/modifying code |
+| `guardrail_architect_validate` | ✅ Validate code against codebase patterns |
+| `guardrail_architect_dependencies` | 🔗 Understand file relationships and impact |
+
+## Guardrail 2.0 Tools (Consolidated)
+
+Six core tools for the complete workflow:
+
+| Tool | Description |
+|------|-------------|
+| `checkpoint` | 🛡️ Block AI agents until issues are fixed (pre/post write) |
+| `check` | 🔍 Verify code is real, wired, honest |
+| `ship` | 🚀 Go/No-Go decision (GO / WARN / NO-GO) |
+| `fix` | 🔧 Fix blocking issues safely |
+| `status` | 📊 Health + version info |
+| `set_strictness` | ⚙️ Set checkpoint strictness level |
+
+## Intent Drift Guard Tools
+
+Capture intent before writing code, monitor for drift:
+
+| Tool | Description |
+|------|-------------|
+| `guardrail_intent_start` | 🎯 Start a new step with explicit intent |
+| `guardrail_intent_check` | ✅ Check if code changes align with stated intent |
+| `guardrail_intent_validate_prompt` | 🔒 Validate new prompts against locked intent |
+| `guardrail_intent_status` | 📊 Get current Intent Drift Guard status |
+| `guardrail_intent_complete` | ✅ Complete step and generate proof artifact |
+| `guardrail_intent_lock` | 🔒 Lock intent to prevent scope expansion |
+| `guardrail_intent_unlock` | 🔓 Unlock intent, allow scope changes |
+
+## Core Analysis Tools
+
+- `validate_project` - Validate project structure and API endpoints
+- `check_design_system` - Validate design system consistency
+- `check_project_drift` - Check for architecture drift
+- `setup_design_system` - Set up and lock design system
+- `register_api_endpoint` - Register API endpoint
+- `get_project_health` - Get project health score
+- `get_guardrails_rules` - Get guardrails rules
+- `architect_analyze` - Intelligent project analysis
+- `build_knowledge_base` - Build codebase knowledge
+- `semantic_search` - Search code by meaning
+- `security_scan` - Full security scan
+- `ship_check` - Ship readiness check
+- `get_deploy_verdict` - Get deploy GO/NO-GO decision
+
+## Resources
+
+- `guardrails://rules` - Guardrails rules document
+- `guardrails://templates` - Available templates
+- `guardrails://design-tokens` - Design system tokens
+
+## Documentation
+
+See [MCP-PREMIUM-TOOLS.md](../docs/MCP-PREMIUM-TOOLS.md) for detailed tool documentation.
+
+## Privacy & Trust
+
+- Runs locally
+- Artifacts saved to `.Guardrail/`
+- No upload unless you export/share
+

package/agent-checkpoint.js

@@ -0,0 +1,364 @@
+/**
+ * Agent Guardrails - MCP Server Integration
+ *
+ * This MCP tool intercepts file writes from AI agents and validates
+ * them against checkpoint rules BEFORE the write happens.
+ *
+ * When an agent (Cursor, Windsurf, etc.) tries to write code,
+ * this tool validates it first and blocks if violations found.
+ */
+
+import fs from "fs";
+import path from "path";
+
+// Strictness level rules
+const STRICTNESS_LEVELS = ["chill", "standard", "strict", "paranoid"];
+
+// Built-in checkpoint rules
+const CHECKPOINT_RULES = {
+  chill: [
+    {
+      id: "no-todo",
+      pattern: /\/\/\s*TODO[:\s].*$/gim,
+      message: "TODO comment - complete before moving on",
+      block: true,
+    },
+    {
+      id: "no-fixme",
+      pattern: /\/\/\s*FIXME[:\s].*$/gim,
+      message: "FIXME comment - fix it now",
+      block: true,
+    },
+    {
+      id: "no-mock-data",
+      pattern:
+        /(?:const|let|var)\s+(?:mock|fake|dummy|sample)(?:Data|Users?|Items?)\s*=/gi,
+      message: "Mock data detected",
+      block: true,
+    },
+    {
+      id: "no-placeholder",
+      pattern: /['"`](?:TODO|PLACEHOLDER|REPLACE_ME|CHANGEME|XXX)['"`]/gi,
+      message: "Placeholder string",
+      block: true,
+    },
+    {
+      id: "no-lorem",
+      pattern: /lorem\s+ipsum/gi,
+      message: "Lorem ipsum placeholder",
+      block: true,
+    },
+  ],
+  standard: [
+    {
+      id: "no-console-log",
+      pattern: /console\.log\s*\(/g,
+      message: "console.log - remove or use proper logging",
+      block: true,
+    },
+    {
+      id: "no-debugger",
+      pattern: /\bdebugger\b/g,
+      message: "debugger statement",
+      block: true,
+    },
+    {
+      id: "no-localhost",
+      pattern: /['"`]https?:\/\/localhost[:\d]*[^'"`]*['"`]/g,
+      message: "Hardcoded localhost",
+      block: true,
+    },
+    {
+      id: "no-empty-catch",
+      pattern: /catch\s*\([^)]*\)\s*\{\s*\}/g,
+      message: "Empty catch block",
+      block: true,
+    },
+  ],
+  strict: [
+    {
+      id: "no-any",
+      pattern: /:\s*any\b/g,
+      message: "any type - use proper TypeScript type",
+      block: true,
+    },
+    {
+      id: "no-ts-ignore",
+      pattern: /@ts-ignore/g,
+      message: "@ts-ignore - fix the type error",
+      block: true,
+    },
+    {
+      id: "no-eslint-disable",
+      pattern: /eslint-disable/g,
+      message: "ESLint disabled - fix the lint error",
+      block: true,
+    },
+  ],
+  paranoid: [
+    {
+      id: "no-nested-ternary",
+      pattern: /\?[^:]+\?[^:]+:/g,
+      message: "Nested ternary - use if/else",
+      block: true,
+    },
+    {
+      id: "no-inline-styles",
+      pattern: /style\s*=\s*\{\s*\{/g,
+      message: "Inline styles - use CSS",
+      block: false,
+    },
+  ],
+};
+
+// Current state
+let currentStrictness = "standard";
+let blockedFiles = new Map();
+let stats = { checked: 0, blocked: 0, passed: 0 };
+
+/**
+ * Get all rules for a strictness level (includes all lower levels)
+ */
+function getRulesForLevel(level) {
+  const levelIndex = STRICTNESS_LEVELS.indexOf(level);
+  let rules = [];
+
+  for (let i = 0; i <= levelIndex; i++) {
+    const levelRules = CHECKPOINT_RULES[STRICTNESS_LEVELS[i]] || [];
+    rules = [...rules, ...levelRules];
+  }
+
+  return rules;
+}
+
+/**
+ * Validate content against checkpoint rules
+ */
+function validateContent(filePath, content) {
+  const rules = getRulesForLevel(currentStrictness);
+  const violations = [];
+  const lines = content.split("\n");
+
+  for (const rule of rules) {
+    rule.pattern.lastIndex = 0;
+    let match;
+
+    while ((match = rule.pattern.exec(content)) !== null) {
+      const beforeMatch = content.substring(0, match.index);
+      const lineNumber = beforeMatch.split("\n").length;
+      const line = lines[lineNumber - 1] || "";
+
+      // Check for ignore directive
+      if (line.includes("@guardrail-ignore")) continue;
+
+      violations.push({
+        rule: rule.id,
+        message: rule.message,
+        line: lineNumber,
+        code: line.trim(),
+        block: rule.block,
+      });
+
+      if (match[0].length === 0) break;
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Format violations for output
+ */
+function formatViolations(filePath, violations) {
+  const blockers = violations.filter((v) => v.block);
+
+  if (blockers.length === 0) {
+    return { blocked: false, message: "✅ Checkpoint passed" };
+  }
+
+  let output = "\n🛑 CHECKPOINT BLOCKED\n";
+  output += "═".repeat(50) + "\n";
+  output += `File: ${filePath}\n\n`;
+
+  for (const v of blockers) {
+    output += `  ❌ Line ${v.line}: ${v.message}\n`;
+    output += `     ${v.code}\n\n`;
+  }
+
+  output += "═".repeat(50) + "\n";
+  output += "Fix these issues before proceeding.\n";
+
+  return { blocked: true, message: output };
+}
+
+/**
+ * MCP Tool Definitions for Agent Guardrails
+ */
+const AGENT_CHECKPOINT_TOOLS = [
+  {
+    name: "guardrail_checkpoint",
+    description: `🛡️ AGENT CHECKPOINT - Validates code before writing. 
+    
+IMPORTANT: Call this tool BEFORE writing any code to check for:
+- TODOs, FIXMEs that must be completed
+- Mock/placeholder data that must be replaced  
+- console.log/debugger statements
+- Type errors (any, @ts-ignore)
+
+If this returns blocked=true, you MUST fix the issues before proceeding.
+Do NOT skip this checkpoint.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        file_path: {
+          type: "string",
+          description: "Path to the file being written",
+        },
+        content: {
+          type: "string",
+          description: "The content to validate",
+        },
+        strictness: {
+          type: "string",
+          enum: ["chill", "standard", "strict", "paranoid"],
+          description: "Validation strictness level (default: standard)",
+        },
+      },
+      required: ["file_path", "content"],
+    },
+  },
+  {
+    name: "guardrail_set_strictness",
+    description: `Set the checkpoint strictness level:
+- chill: TODOs, FIXMEs, mock data, placeholders
+- standard: + console.log, debugger, localhost URLs
+- strict: + any types, @ts-ignore, eslint-disable  
+- paranoid: + nested ternaries, inline styles`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        level: {
+          type: "string",
+          enum: ["chill", "standard", "strict", "paranoid"],
+          description: "The strictness level",
+        },
+      },
+      required: ["level"],
+    },
+  },
+  {
+    name: "guardrail_checkpoint_status",
+    description: "Get current checkpoint status and any blocking violations",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+];
+
+/**
+ * Handle MCP tool calls
+ */
+async function handleCheckpointTool(name, args) {
+  switch (name) {
+    case "guardrail_checkpoint": {
+      const { file_path, content, strictness } = args;
+
+      if (strictness) {
+        currentStrictness = strictness;
+      }
+
+      stats.checked++;
+      const violations = validateContent(file_path, content);
+      const result = formatViolations(file_path, violations);
+
+      if (result.blocked) {
+        stats.blocked++;
+        blockedFiles.set(file_path, violations);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: result.message,
+            },
+          ],
+          isError: true, // Signal to agent this is a blocker
+        };
+      }
+
+      stats.passed++;
+      blockedFiles.delete(file_path);
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `✅ Checkpoint PASSED for ${file_path}\n\nYou may proceed with writing this file.`,
+          },
+        ],
+      };
+    }
+
+    case "guardrail_set_strictness": {
+      const { level } = args;
+      currentStrictness = level;
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `🛡️ Checkpoint strictness set to: ${level.toUpperCase()}\n\nActive rules:\n${getRulesForLevel(
+              level,
+            )
+              .map((r) => `- ${r.id}: ${r.message}`)
+              .join("\n")}`,
+          },
+        ],
+      };
+    }
+
+    case "guardrail_checkpoint_status": {
+      const blockedList = Array.from(blockedFiles.entries());
+
+      let status = `🛡️ Agent Guardrails Status\n`;
+      status += `═══════════════════════════\n`;
+      status += `Strictness: ${currentStrictness.toUpperCase()}\n`;
+      status += `Files checked: ${stats.checked}\n`;
+      status += `Passed: ${stats.passed}\n`;
+      status += `Blocked: ${stats.blocked}\n\n`;
+
+      if (blockedList.length > 0) {
+        status += `⚠️ Currently blocked files:\n`;
+        for (const [file, violations] of blockedList) {
+          status += `\n📄 ${file}\n`;
+          for (const v of violations.filter((v) => v.block)) {
+            status += `   Line ${v.line}: ${v.message}\n`;
+          }
+        }
+      } else {
+        status += `✅ No blocked files - all clear!\n`;
+      }
+
+      return {
+        content: [{ type: "text", text: status }],
+      };
+    }
+
+    default:
+      return {
+        content: [{ type: "text", text: `Unknown tool: ${name}` }],
+        isError: true,
+      };
+  }
+}
+
+export {
+  AGENT_CHECKPOINT_TOOLS,
+  handleCheckpointTool,
+  validateContent,
+  formatViolations,
+  getRulesForLevel,
+  CHECKPOINT_RULES,
+  STRICTNESS_LEVELS,
+};