mpalpha · December 5, 2025 22:21
diff --git a/README.md b/README.md
diff --git a/config.behavioral.json b/config.behavioral.json
 {
  "enforced_rules": {
    "require_protocol_steps": [
      {
        "name": "sequential_thinking",
        "hook": "user_prompt_submit"
      },
      {
        "name": "analyze_behavior",
        "hook": "user_prompt_submit"
      },
      {
        "name": "apply_chores_fixes",
        "hook": "pre_tool_use"
      }
    ],
    "require_checklist_confirmation": true,
    "minimum_checklist_items": 5
  },
  "checklist_items": [
    {
      "text": "Sequential thinking completed FIRST",
      "hook": "user_prompt_submit"
    },
    {
      "text": "Behavioral patterns analyzed systematically",
      "hook": "user_prompt_submit"
    },
    {
      "text": "Constraint issues addressed (structure/format adherence)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Hallucination issues addressed (no false information)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Overconfidence issues addressed (uncertainty expressed when appropriate)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Reasoning issues addressed (logical consistency verified)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Technical precision maintained (state 'I don't know' when uncertain)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Zero deflection policy (attempt tools before claiming unavailable)",
      "hook": "pre_tool_use"
    },
    {
      "text": "No 'likely' explanations without verification",
      "hook": "pre_tool_use"
    },
    {
      "text": "Ethical/Safety issues addressed (harmful content prevented)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Sycophancy issues addressed (truthfulness over false agreement)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Professional objectivity maintained (facts over validation)",
      "hook": "post_tool_use"
    }
  ]
 }
diff --git a/config.development.json b/config.development.json
 {
  "enforced_rules": {
    "require_protocol_steps": [
      {
        "name": "sequential_thinking",
        "hook": "user_prompt_submit"
      },
      {
        "name": "task_initiation",
        "hook": "user_prompt_submit"
      },
      {
        "name": "pre_planning_analysis",
        "hook": "pre_tool_use",
        "applies_to": ["Write", "Edit"]
      },
      {
        "name": "plan_generation",
        "hook": "pre_tool_use",
        "applies_to": ["Write", "Edit"]
      }
    ],
    "require_checklist_confirmation": true,
    "minimum_checklist_items": 5
  },
  "checklist_items": [
    {
      "text": "Pre-response compliance audit completed",
      "hook": "user_prompt_submit"
    },
    {
      "text": "Sequential thinking completed FIRST (mcp__clear-thought__sequentialthinking)",
      "hook": "user_prompt_submit"
    },
    {
      "text": "User request restated with ALL ambiguities clarified",
      "hook": "user_prompt_submit"
    },
    {
      "text": "Requirements gathered (tickets, designs, data sources)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Existing patterns analyzed for reuse (components, hooks, utils)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Dependencies identified (files to modify/create, reusable code)",
      "hook": "pre_tool_use"
    },
    {
      "text": "PLAN comprehensive (objective, files, dependencies, tools, confidence, risks)",
      "hook": "pre_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "PLAN confirmed by user BEFORE executing code",
      "hook": "pre_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "Technical precision maintained (no 'likely' explanations)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Pattern matching verified (file structure, naming, code style)",
      "hook": "pre_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "Reuse verified (searched before creating)",
      "hook": "pre_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "TypeScript strict mode (no 'any' without justification)",
      "hook": "pre_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "Linting passed",
      "hook": "post_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "Type check passed",
      "hook": "post_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "No console.log() statements",
      "hook": "post_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "Import order correct",
      "hook": "post_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "Acceptance criteria verified",
      "hook": "post_tool_use"
    },
    {
      "text": "Completion summarized with deviations justified",
      "hook": "post_tool_use"
    }
  ]
 }
diff --git a/config.minimal.json b/config.minimal.json
 {
  "enforced_rules": {
    "require_protocol_steps": [
      {
        "name": "sequential_thinking",
        "hook": "user_prompt_submit"
      },
      {
        "name": "planning",
        "hook": "pre_tool_use",
        "applies_to": ["Write", "Edit"]
      },
      {
        "name": "execution",
        "hook": "pre_tool_use",
        "applies_to": ["Write", "Edit"]
      }
    ],
    "require_checklist_confirmation": true,
    "minimum_checklist_items": 3
  },
  "checklist_items": [
    {
      "text": "Sequential thinking completed FIRST",
      "hook": "user_prompt_submit"
    },
    {
      "text": "Task requirements clarified with user",
      "hook": "pre_tool_use"
    },
    {
      "text": "Plan created and confirmed before execution",
      "hook": "pre_tool_use",
      "applies_to": ["Write", "Edit"]
    },
    {
      "text": "Technical precision maintained (state 'I don't know' when uncertain)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Zero deflection policy (attempt available tools before claiming unavailable)",
      "hook": "pre_tool_use"
    },
    {
      "text": "Completion verified against stated objectives",
      "hook": "post_tool_use",
      "applies_to": ["Write", "Edit"]
    }
  ]
 }
diff --git a/index.js b/index.js
 #!/usr/bin/env node

 /**
 * Protocol Enforcer MCP Server
 * Enforces custom workflow protocol compliance before allowing file operations
 *
 * Author: Jason Lusk <[email protected]>
 * License: MIT
 */

 const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const readline = require('readline');

 // State tracking
 const state = {
  configPath: null,
  config: null,
  complianceChecks: [],
  operationTokens: new Map(), // Map<token, {expires: timestamp, used: boolean}>
  tokenTimeout: 60000 // 60 seconds
 };

 // Default configuration (MODEL Framework CHORES behavioral fixes)
 const DEFAULT_CONFIG = {
  enforced_rules: {
    require_protocol_steps: [
      {
        name: "analyze_behavior",
        hook: "user_prompt_submit"
      },
      {
        name: "apply_chores_fixes",
        hook: "pre_tool_use",
        applies_to: ["Write", "Edit"]
      }
    ],
    require_checklist_confirmation: true,
    minimum_checklist_items: 3
  },
  checklist_items: [
    {
      text: "Constraint issues addressed (structure/format adherence)",
      hook: "pre_tool_use"
    },
    {
      text: "Hallucination issues addressed (no false information)",
      hook: "pre_tool_use"
    },
    {
      text: "Overconfidence issues addressed (uncertainty expressed when appropriate)",
      hook: "pre_tool_use"
    },
    {
      text: "Reasoning issues addressed (logical consistency verified)",
      hook: "pre_tool_use"
    },
    {
      text: "Ethical/Safety issues addressed (harmful content prevented)",
      hook: "pre_tool_use"
    },
    {
      text: "Sycophancy issues addressed (truthfulness over false agreement)",
      hook: "pre_tool_use"
    }
  ]
 };

 // Find config file (project scope takes precedence)
 function findConfigFile() {
  const cwd = process.cwd();
  const projectConfig = path.join(cwd, '.protocol-enforcer.json');
  const homeConfig = path.join(process.env.HOME || process.env.USERPROFILE, '.protocol-enforcer.json');

  if (fs.existsSync(projectConfig)) {
    return projectConfig;
  }
  if (fs.existsSync(homeConfig)) {
    return homeConfig;
  }
  return null;
 }

 // Load configuration
 function loadConfig() {
  const configPath = findConfigFile();
  if (configPath) {
    state.configPath = configPath;
    const rawConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
    state.config = validateConfig(rawConfig);
    return state.config;
  }
  state.config = DEFAULT_CONFIG;
  return null;
 }

 // Tool: initialize_protocol_config
 async function initializeProtocolConfig(args) {
  const scope = args.scope || 'project';

  let configPath;
  if (scope === 'project') {
    configPath = path.join(process.cwd(), '.protocol-enforcer.json');
  } else if (scope === 'user') {
    configPath = path.join(process.env.HOME || process.env.USERPROFILE, '.protocol-enforcer.json');
  } else {
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ error: 'Invalid scope. Must be "project" or "user".' }, null, 2)
      }]
    };
  }

  if (fs.existsSync(configPath)) {
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          error: 'Configuration file already exists',
          path: configPath
        }, null, 2)
      }]
    };
  }

  fs.writeFileSync(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2), 'utf8');
  state.configPath = configPath;
  state.config = DEFAULT_CONFIG;

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        success: true,
        message: `Configuration file created at ${configPath}`,
        config: DEFAULT_CONFIG
      }, null, 2)
    }]
  };
 }

 // Validate config format
 function validateConfig(config) {
  const errors = [];

  // Validate protocol steps
  if (config.enforced_rules.require_protocol_steps) {
    config.enforced_rules.require_protocol_steps.forEach((step, idx) => {
      if (typeof step === 'string') {
        errors.push(`Protocol step at index ${idx} is a string. Must be an object with 'name' and 'hook' properties.`);
      } else if (!step.name || !step.hook) {
        errors.push(`Protocol step at index ${idx} missing required 'name' or 'hook' property.`);
      }
    });
  }

  // Validate checklist items
  if (config.checklist_items) {
    config.checklist_items.forEach((item, idx) => {
      if (typeof item === 'string') {
        errors.push(`Checklist item at index ${idx} is a string. Must be an object with 'text' and 'hook' properties.`);
      } else if (!item.text || !item.hook) {
        errors.push(`Checklist item at index ${idx} missing required 'text' or 'hook' property.`);
      }
    });
  }

  if (errors.length > 0) {
    throw new Error(`Invalid configuration format:\n${errors.join('\n')}\n\nSee README.md Configuration Reference section for correct format.`);
  }

  return config;
 }

 // Filter rules by hook and tool name
 function filterByHook(items, hook, toolName = null) {
  return items.filter(item => {
    // Check if hook matches
    if (item.hook !== hook) return false;

    // Check if tool-specific filtering applies
    if (item.applies_to && toolName) {
      return item.applies_to.includes(toolName);
    }

    return true;
  });
 }

 // Tool: verify_protocol_compliance
 async function verifyProtocolCompliance(args) {
  const rawConfig = state.config || loadConfig() || DEFAULT_CONFIG;

  // Validate config format (throws if invalid)
  const config = validateConfig(rawConfig);
  const violations = [];

  const hook = args.hook;
  const toolName = args.tool_name || null;

  if (!hook) {
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          error: 'Missing required parameter: hook. Must specify which hook is calling (e.g., "user_prompt_submit", "pre_tool_use", "post_tool_use").'
        }, null, 2)
      }]
    };
  }

  // Check required protocol steps (filtered by hook)
  if (config.enforced_rules.require_protocol_steps && Array.isArray(config.enforced_rules.require_protocol_steps)) {
    const allRequiredSteps = config.enforced_rules.require_protocol_steps;
    const hookFilteredSteps = filterByHook(allRequiredSteps, hook, toolName);
    const completedSteps = args.protocol_steps_completed || [];

    const missingSteps = hookFilteredSteps.filter(step => !completedSteps.includes(step.name));
    if (missingSteps.length > 0) {
      missingSteps.forEach(step => {
        violations.push(`VIOLATION: Required protocol step not completed: ${step.name} (hook: ${hook})`);
      });
    }
  }

  // Check checklist confirmation (filtered by hook)
  if (config.enforced_rules.require_checklist_confirmation) {
    const checkedItems = args.checklist_items_checked || [];
    const allRequiredItems = config.checklist_items || [];
    const hookFilteredItems = filterByHook(allRequiredItems, hook, toolName);
    const minItems = config.enforced_rules.minimum_checklist_items || 0;

    // Count only items applicable to this hook
    const applicableMinItems = Math.min(minItems, hookFilteredItems.length);

    if (checkedItems.length < applicableMinItems) {
      violations.push(`VIOLATION: Only ${checkedItems.length} checklist items checked, minimum ${applicableMinItems} required for hook '${hook}'`);
    }

    const uncheckedRequired = hookFilteredItems.filter(item => !checkedItems.includes(item.text));
    if (uncheckedRequired.length > 0) {
      violations.push(`VIOLATION: Required checklist items not confirmed for hook '${hook}': ${uncheckedRequired.map(i => i.text).join(', ')}`);
    }
  }

  // Record check
  state.complianceChecks.push({
    timestamp: new Date().toISOString(),
    passed: violations.length === 0,
    violations: violations,
    args: args
  });

  if (violations.length > 0) {
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          compliant: false,
          violations: violations,
          message: 'Protocol compliance check FAILED. Fix violations before proceeding.'
        }, null, 2)
      }]
    };
  }

  // Generate single-use operation token
  const crypto = require('crypto');
  const token = crypto.randomBytes(32).toString('hex');
  const expires = Date.now() + state.tokenTimeout;

  state.operationTokens.set(token, { expires, used: false });

  // Clean up expired tokens
  for (const [key, value] of state.operationTokens.entries()) {
    if (value.expires < Date.now() || value.used) {
      state.operationTokens.delete(key);
    }
  }

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        compliant: true,
        operation_token: token,
        token_expires_in_seconds: state.tokenTimeout / 1000,
        message: 'Protocol compliance verified. Use the operation_token with authorize_file_operation before proceeding.'
      }, null, 2)
    }]
  };
 }

 // Tool: get_compliance_status
 async function getComplianceStatus() {
  const recentChecks = state.complianceChecks.slice(-10);
  const passedCount = recentChecks.filter(c => c.passed).length;
  const failedCount = recentChecks.length - passedCount;

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        total_checks: state.complianceChecks.length,
        recent_checks: recentChecks.length,
        passed: passedCount,
        failed: failedCount,
        recent_violations: recentChecks
          .filter(c => !c.passed)
          .map(c => ({ timestamp: c.timestamp, violations: c.violations }))
      }, null, 2)
    }]
  };
 }

 // Tool: get_protocol_config
 async function getProtocolConfig() {
  const config = state.config || loadConfig() || DEFAULT_CONFIG;

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        config_path: state.configPath || 'Using default configuration',
        config: config
      }, null, 2)
    }]
  };
 }

 // Tool: authorize_file_operation
 async function authorizeFileOperation(args) {
  const token = args.operation_token;

  if (!token) {
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          authorized: false,
          error: 'No operation token provided. You must call verify_protocol_compliance first to obtain a token.'
        }, null, 2)
      }]
    };
  }

  const tokenData = state.operationTokens.get(token);

  if (!tokenData) {
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          authorized: false,
          error: 'Invalid or expired operation token. Call verify_protocol_compliance again to obtain a new token.'
        }, null, 2)
      }]
    };
  }

  if (tokenData.used) {
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          authorized: false,
          error: 'Operation token already used. Each token is single-use only. Call verify_protocol_compliance again.'
        }, null, 2)
      }]
    };
  }

  if (tokenData.expires < Date.now()) {
    state.operationTokens.delete(token);
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          authorized: false,
          error: 'Operation token expired. Call verify_protocol_compliance again to obtain a new token.'
        }, null, 2)
      }]
    };
  }

  // Mark token as used
  tokenData.used = true;

  // Write token file for PreToolUse hook verification
  const tokenFile = path.join(os.homedir(), '.protocol-enforcer-token');
  try {
    fs.writeFileSync(tokenFile, token, 'utf8');
  } catch (err) {
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          authorized: false,
          error: `Failed to write token file: ${err.message}`
        }, null, 2)
      }]
    };
  }

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        authorized: true,
        message: 'File operation authorized. Token file written for hook verification. You may now proceed with Write/Edit operations.'
      }, null, 2)
    }]
  };
 }

 // MCP Protocol Handler
 const tools = [
  {
    name: 'initialize_protocol_config',
    description: 'Create a new protocol enforcer configuration file at project or user scope',
    inputSchema: {
      type: 'object',
      properties: {
        scope: {
          type: 'string',
          enum: ['project', 'user'],
          description: 'Where to create the config file: "project" (.protocol-enforcer.json in current directory) or "user" (~/.protocol-enforcer.json)'
        }
      },
      required: ['scope']
    }
  },
  {
    name: 'verify_protocol_compliance',
    description: 'Verify that mandatory protocol steps have been completed before allowing file operations. This is a generic tool - protocol steps and checklist items are defined in your .protocol-enforcer.json configuration file. Supports hook-specific filtering.',
    inputSchema: {
      type: 'object',
      properties: {
        hook: {
          type: 'string',
          enum: ['user_prompt_submit', 'session_start', 'pre_tool_use', 'post_tool_use', 'stop'],
          description: 'REQUIRED: Which hook is calling this verification (e.g., "pre_tool_use", "user_prompt_submit"). Filters rules to only those applicable to this hook.'
        },
        tool_name: {
          type: 'string',
          description: 'Optional: name of the tool being called (e.g., "Write", "Edit"). Used for tool-specific filtering when combined with hook. Only applies when hook is "pre_tool_use" or "post_tool_use".'
        },
        protocol_steps_completed: {
          type: 'array',
          items: { type: 'string' },
          description: 'List of protocol step names that have been completed (e.g., ["planning", "analysis"]). Step names must match those defined in your .protocol-enforcer.json config.'
        },
        checklist_items_checked: {
          type: 'array',
          items: { type: 'string' },
          description: 'List of checklist items that were verified. Items should match those defined in your .protocol-enforcer.json config.'
        }
      },
      required: ['hook', 'protocol_steps_completed', 'checklist_items_checked']
    }
  },
  {
    name: 'get_compliance_status',
    description: 'Get current compliance check statistics and recent violations',
    inputSchema: {
      type: 'object',
      properties: {}
    }
  },
  {
    name: 'get_protocol_config',
    description: 'Get the current protocol enforcer configuration',
    inputSchema: {
      type: 'object',
      properties: {}
    }
  },
  {
    name: 'authorize_file_operation',
    description: 'MANDATORY before ANY file write/edit operation. Validates the operation token from verify_protocol_compliance. Single-use token that expires in 60 seconds.',
    inputSchema: {
      type: 'object',
      properties: {
        operation_token: {
          type: 'string',
          description: 'The operation token received from verify_protocol_compliance. Required for authorization.'
        }
      },
      required: ['operation_token']
    }
  }
 ];

 // Main MCP message handler
 async function handleMessage(message) {
  const { method, params, id } = message;

  switch (method) {
    case 'initialize':
      return {
        jsonrpc: '2.0',
        id,
        result: {
          protocolVersion: '2024-11-05',
          serverInfo: {
            name: 'protocol-enforcer',
            version: '1.0.0'
          },
          capabilities: {
            tools: {}
          }
        }
      };

    case 'tools/list':
      return {
        jsonrpc: '2.0',
        id,
        result: { tools }
      };

    case 'tools/call':
      const { name, arguments: args } = params;
      let result;
      switch (name) {
        case 'initialize_protocol_config':
          result = await initializeProtocolConfig(args || {});
          break;
        case 'verify_protocol_compliance':
          result = await verifyProtocolCompliance(args || {});
          break;
        case 'get_compliance_status':
          result = await getComplianceStatus();
          break;
        case 'get_protocol_config':
          result = await getProtocolConfig();
          break;
        case 'authorize_file_operation':
          result = await authorizeFileOperation(args || {});
          break;
        default:
          result = {
            content: [{
              type: 'text',
              text: JSON.stringify({ error: `Unknown tool: ${name}` })
            }],
            isError: true
          };
      }
      return {
        jsonrpc: '2.0',
        id,
        result
      };

    default:
      return {
        jsonrpc: '2.0',
        id,
        error: {
          code: -32601,
          message: `Method not found: ${method}`
        }
      };
  }
 }

 // Stdio transport
 async function main() {
  loadConfig();

  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
    terminal: false
  });

  rl.on('line', async (line) => {
    try {
      const message = JSON.parse(line);
      const response = await handleMessage(message);
      console.log(JSON.stringify(response));
    } catch (error) {
      console.error(JSON.stringify({
        error: error.message,
        stack: error.stack
      }));
    }
  });

  // Keep process alive indefinitely for MCP persistent connection
  // This interval ensures the event loop never exits
  setInterval(() => {
    // Keep-alive: This keeps the process running
    // MCP servers must maintain persistent stdio connection
  }, 2147483647); // Maximum safe timeout (~24.8 days)
 }

 main().catch(console.error);
diff --git a/package.json b/package.json
 {
  "name": "protocol-enforcer-mcp",
  "version": "1.0.0",
  "description": "MCP server that enforces mandatory supervisor protocol compliance before allowing file operations",
  "author": "Jason Lusk <[email protected]>",
  "license": "MIT",
  "main": "index.js",
  "bin": {
    "protocol-enforcer": "./index.js"
  },
  "engines": {
    "node": ">=14.0.0"
  },
  "keywords": [
    "mcp",
    "model-context-protocol",
    "protocol-enforcer",
    "ai-assistant",
    "code-quality",
    "compliance"
  ]
 }
Platform	Config File	Hook Support	Enforcement
Claude Code	`.mcp.json` or `~/.claude.json`	✅ Full (all 5 hooks)	Automatic blocking
Cursor	`~/.cursor/mcp.json`	✅ Standard (PreToolUse)	Automatic blocking
Cline	`~/.cline/mcp.json`	⚠️ Limited (PostToolUse)	Audit only
Zed	`~/.config/zed/mcp.json`	❌ None	Voluntary
Continue	`~/.continue/mcp.json`	⚠️ Limited	Voluntary
Hook	When	Use Case
`user_prompt_submit`	Before processing user message	Pre-response checks, sequential thinking
`session_start`	At session initialization	Display requirements, initialize tracking
`pre_tool_use`	Before tool execution	Primary enforcement point for file operations
`post_tool_use`	After tool execution	Validation, linting, audit logging
`stop`	Before session termination	Compliance reporting, cleanup
Parameter	Type	Required	Description
`hook`	string	✅ Yes	Lifecycle point: `user_prompt_submit`, `session_start`, `pre_tool_use`, `post_tool_use`, `stop`
`tool_name`	string	No	Tool being called (`Write`, `Edit`) for tool-specific filtering
`protocol_steps_completed`	string[]	✅ Yes	Completed step names from config
`checklist_items_checked`	string[]	✅ Yes	Verified checklist items from config
Issue	Solution
Server not appearing	Check config file syntax, gist URL, file location, reload IDE
Configuration not loading	Verify `.protocol-enforcer.json` filename, check JSON syntax
Tools not working	Test with `get_protocol_config`, check tool names (must use full `mcp__protocol-enforcer__*`)
Hook not blocking	Verify platform support, check hook executable (`chmod +x`), verify absolute path, reload IDE
Token errors	Check `~/.protocol-enforcer-token` exists after `authorize_file_operation`
Platform	Recommended Hooks	Strategy
Claude Code	All 5 hooks	Maximum enforcement
Cursor	PreToolUse only	Standard enforcement (PostToolUse not reliably supported)
Cline	PostToolUse only	Audit logging
Zed/Continue	None	Voluntary compliance
Feature	Claude Code	Cursor	Cline	Zed/Continue
Hooks Available	All 5	PreToolUse + PostToolUse	PostToolUse	None
Automatic Blocking	✅ Yes	✅ Yes	❌ No	❌ No
Recommended Steps	5-7 steps	3-5 steps	2-3 steps	1-2 steps
Enforcement Level	Maximum	Standard	Audit	Voluntary
Best For	Production	Development	Code review	Minimal
	{
	"enforced_rules": {
	"require_protocol_steps": [
	{
	"name": "sequential_thinking",
	"hook": "user_prompt_submit"
	},
	{
	"name": "analyze_behavior",
	"hook": "user_prompt_submit"
	},
	{
	"name": "apply_chores_fixes",
	"hook": "pre_tool_use"
	}
	],
	"require_checklist_confirmation": true,
	"minimum_checklist_items": 5
	},
	"checklist_items": [
	{
	"text": "Sequential thinking completed FIRST",
	"hook": "user_prompt_submit"
	},
	{
	"text": "Behavioral patterns analyzed systematically",
	"hook": "user_prompt_submit"
	},
	{
	"text": "Constraint issues addressed (structure/format adherence)",
	"hook": "pre_tool_use"
	},
	{
	"text": "Hallucination issues addressed (no false information)",
	"hook": "pre_tool_use"
	},
	{
	"text": "Overconfidence issues addressed (uncertainty expressed when appropriate)",
	"hook": "pre_tool_use"
	},
	{
	"text": "Reasoning issues addressed (logical consistency verified)",
	"hook": "pre_tool_use"
	},
	{
	"text": "Technical precision maintained (state 'I don't know' when uncertain)",
	"hook": "pre_tool_use"
	},
	{
	"text": "Zero deflection policy (attempt tools before claiming unavailable)",
	"hook": "pre_tool_use"
	},
	{
	"text": "No 'likely' explanations without verification",
	"hook": "pre_tool_use"
	},
	{
	"text": "Ethical/Safety issues addressed (harmful content prevented)",
	"hook": "pre_tool_use"
	},
	{
	"text": "Sycophancy issues addressed (truthfulness over false agreement)",
	"hook": "pre_tool_use"
	},
	{
	"text": "Professional objectivity maintained (facts over validation)",
	"hook": "post_tool_use"
	}
	]
	}
	#!/usr/bin/env node

	/**
	* Protocol Enforcer MCP Server
	* Enforces custom workflow protocol compliance before allowing file operations
	*
	* Author: Jason Lusk <[email protected]>
	* License: MIT
	*/

	const fs = require('fs');
	const path = require('path');
	const os = require('os');
	const readline = require('readline');

	// State tracking
	const state = {
	configPath: null,
	config: null,
	complianceChecks: [],
	operationTokens: new Map(), // Map<token, {expires: timestamp, used: boolean}>
	tokenTimeout: 60000 // 60 seconds
	};

	// Default configuration (MODEL Framework CHORES behavioral fixes)
	const DEFAULT_CONFIG = {
	enforced_rules: {
	require_protocol_steps: [
	{
	name: "analyze_behavior",
	hook: "user_prompt_submit"
	},
	{
	name: "apply_chores_fixes",
	hook: "pre_tool_use",
	applies_to: ["Write", "Edit"]
	}
	],
	require_checklist_confirmation: true,
	minimum_checklist_items: 3
	},
	checklist_items: [
	{
	text: "Constraint issues addressed (structure/format adherence)",
	hook: "pre_tool_use"
	},
	{
	text: "Hallucination issues addressed (no false information)",
	hook: "pre_tool_use"
	},
	{
	text: "Overconfidence issues addressed (uncertainty expressed when appropriate)",
	hook: "pre_tool_use"
	},
	{
	text: "Reasoning issues addressed (logical consistency verified)",
	hook: "pre_tool_use"
	},
	{
	text: "Ethical/Safety issues addressed (harmful content prevented)",
	hook: "pre_tool_use"
	},
	{
	text: "Sycophancy issues addressed (truthfulness over false agreement)",
	hook: "pre_tool_use"
	}
	]
	};

	// Find config file (project scope takes precedence)
	function findConfigFile() {
	const cwd = process.cwd();
	const projectConfig = path.join(cwd, '.protocol-enforcer.json');
	const homeConfig = path.join(process.env.HOME \|\| process.env.USERPROFILE, '.protocol-enforcer.json');

	if (fs.existsSync(projectConfig)) {
	return projectConfig;
	}
	if (fs.existsSync(homeConfig)) {
	return homeConfig;
	}
	return null;
	}

	// Load configuration
	function loadConfig() {
	const configPath = findConfigFile();
	if (configPath) {
	state.configPath = configPath;
	const rawConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
	state.config = validateConfig(rawConfig);
	return state.config;
	}
	state.config = DEFAULT_CONFIG;
	return null;
	}

	// Tool: initialize_protocol_config
	async function initializeProtocolConfig(args) {
	const scope = args.scope \|\| 'project';

	let configPath;
	if (scope === 'project') {
	configPath = path.join(process.cwd(), '.protocol-enforcer.json');
	} else if (scope === 'user') {
	configPath = path.join(process.env.HOME \|\| process.env.USERPROFILE, '.protocol-enforcer.json');
	} else {
	return {
	content: [{
	type: 'text',
	text: JSON.stringify({ error: 'Invalid scope. Must be "project" or "user".' }, null, 2)
	}]
	};
	}

	if (fs.existsSync(configPath)) {
	return {
	content: [{
	type: 'text',
	text: JSON.stringify({
	error: 'Configuration file already exists',
	path: configPath
	}, null, 2)
	}]
	};
	}

	fs.writeFileSync(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2), 'utf8');
	state.configPath = configPath;
	state.config = DEFAULT_CONFIG;

	return {
	content: [{
	type: 'text',
	text: JSON.stringify({
	success: true,
	message: `Configuration file created at ${configPath}`,
	config: DEFAULT_CONFIG
	}, null, 2)
	}]
	};
	}

	// Validate config format
	function validateConfig(config) {
	const errors = [];

	// Validate protocol steps
	if (config.enforced_rules.require_protocol_steps) {
	config.enforced_rules.require_protocol_steps.forEach((step, idx) => {
	if (typeof step === 'string') {
	errors.push(`Protocol step at index ${idx} is a string. Must be an object with 'name' and 'hook' properties.`);
	} else if (!step.name \|\| !step.hook) {
	errors.push(`Protocol step at index ${idx} missing required 'name' or 'hook' property.`);
	}
	});
	}

	// Validate checklist items
	if (config.checklist_items) {
	config.checklist_items.forEach((item, idx) => {
	if (typeof item === 'string') {
	errors.push(`Checklist item at index ${idx} is a string. Must be an object with 'text' and 'hook' properties.`);
	} else if (!item.text \|\| !item.hook) {
	errors.push(`Checklist item at index ${idx} missing required 'text' or 'hook' property.`);
	}
	});
	}

	if (errors.length > 0) {
	throw new Error(`Invalid configuration format:\n${errors.join('\n')}\n\nSee README.md Configuration Reference section for correct format.`);
	}

	return config;
	}

	// Filter rules by hook and tool name
	function filterByHook(items, hook, toolName = null) {
	return items.filter(item => {
	// Check if hook matches
	if (item.hook !== hook) return false;

	// Check if tool-specific filtering applies
	if (item.applies_to && toolName) {
	return item.applies_to.includes(toolName);
	}

	return true;
	});
	}

	// Tool: verify_protocol_compliance
	async function verifyProtocolCompliance(args) {
	const rawConfig = state.config \|\| loadConfig() \|\| DEFAULT_CONFIG;

	// Validate config format (throws if invalid)
	const config = validateConfig(rawConfig);
	const violations = [];

	const hook = args.hook;
	const toolName = args.tool_name \|\| null;

	if (!hook) {
	return {
	content: [{
	type: 'text',
	text: JSON.stringify({
	error: 'Missing required parameter: hook. Must specify which hook is calling (e.g., "user_prompt_submit", "pre_tool_use", "post_tool_use").'
	}, null, 2)
	}]
	};
	}

	// Check required protocol steps (filtered by hook)
	if (config.enforced_rules.require_protocol_steps && Array.isArray(config.enforced_rules.require_protocol_steps)) {
	const allRequiredSteps = config.enforced_rules.require_protocol_steps;
	const hookFilteredSteps = filterByHook(allRequiredSteps, hook, toolName);
	const completedSteps = args.protocol_steps_completed \|\| [];

	const missingSteps = hookFilteredSteps.filter(step => !completedSteps.includes(step.name));
	if (missingSteps.length > 0) {
	missingSteps.forEach(step => {
	violations.push(`VIOLATION: Required protocol step not completed: ${step.name} (hook: ${hook})`);
	});
	}
	}

	// Check checklist confirmation (filtered by hook)
	if (config.enforced_rules.require_checklist_confirmation) {
	const checkedItems = args.checklist_items_checked \|\| [];
	const allRequiredItems = config.checklist_items \|\| [];
	const hookFilteredItems = filterByHook(allRequiredItems, hook, toolName);
	const minItems = config.enforced_rules.minimum_checklist_items \|\| 0;

	// Count only items applicable to this hook
	const applicableMinItems = Math.min(minItems, hookFilteredItems.length);

	if (checkedItems.length < applicableMinItems) {
	violations.push(`VIOLATION: Only ${checkedItems.length} checklist items checked, minimum ${applicableMinItems} required for hook '${hook}'`);
	}

	const uncheckedRequired = hookFilteredItems.filter(item => !checkedItems.includes(item.text));
	if (uncheckedRequired.length > 0) {
	violations.push(`VIOLATION: Required checklist items not confirmed for hook '${hook}': ${uncheckedRequired.map(i => i.text).join(', ')}`);
	}
	}

	// Record check
	state.complianceChecks.push({
	timestamp: new Date().toISOString(),
	passed: violations.length === 0,
	violations: violations,
	args: args
	});

	if (violations.length > 0) {
	return {
	content: [{
	type: 'text',
	text: JSON.stringify({
	compliant: false,
	violations: violations,
	message: 'Protocol compliance check FAILED. Fix violations before proceeding.'
	}, null, 2)
	}]
	};
	}

	// Generate single-use operation token
	const crypto = require('crypto');
	const token = crypto.randomBytes(32).toString('hex');
	const expires = Date.now() + state.tokenTimeout;

	state.operationTokens.set(token, { expires, used: false });

	// Clean up expired tokens
	for (const [key, value] of state.operationTokens.entries()) {
	if (value.expires < Date.now() \|\| value.used) {
	state.operationTokens.delete(key);
	}
	}

	return {
	content: [{
	type: 'text',
	text: JSON.stringify({
	compliant: true,
	operation_token: token,
	token_expires_in_seconds: state.tokenTimeout / 1000,
	message: 'Protocol compliance verified. Use the operation_token with authorize_file_operation before proceeding.'
	}, null, 2)
	}]
	};
	}

	// Tool: get_compliance_status
	async function getComplianceStatus() {
	const recentChecks = state.complianceChecks.slice(-10);
	const passedCount = recentChecks.filter(c => c.passed).length;
	const failedCount = recentChecks.length - passedCount;

	return {
	content: [{
	type: 'text',
	text: JSON.stringify({
	total_checks: state.complianceChecks.length,
	recent_checks: recentChecks.length,
	passed: passedCount,
	failed: failedCount,
	recent_violations: recentChecks
	.filter(c => !c.passed)
	.map(c => ({ timestamp: c.timestamp, violations: c.violations }))
	}, null, 2)
	}]
	};
	}

	// Tool: get_protocol_config
	async function getProtocolConfig() {
	const config = state.config \|\| loadConfig() \|\| DEFAULT_CONFIG;

	return {
	content: [{
	type: 'text',
	text: JSON.stringify({
	config_path: state.configPath \|\| 'Using default configuration',
	config: config
	}, null, 2)
	}]
	};
	}

	// Tool: authorize_file_operation
	async function authorizeFileOperation(args) {
	const token = args.operation_token;

	if (!token) {
	return {
	content: [{
	type: 'text',
	text: JSON.stringify({
	authorized: false,
	error: 'No operation token provided. You must call verify_protocol_compliance first to obtain a token.'
	}, null, 2)
	}]
	};
	}

	const tokenData = state.operationTokens.get(token);

	if (!tokenData) {
	return {
	content: [{
	type: 'text',
	text: JSON.stringify({
	authorized: false,
	error: 'Invalid or expired operation token. Call verify_protocol_compliance again to obtain a new token.'
	}, null, 2)
	}]
	};
	}

	if (tokenData.used) {
	return {
	content: [{
	type: 'text',
	text: JSON.stringify({
	authorized: false,
	error: 'Operation token already used. Each token is single-use only. Call verify_protocol_compliance again.'
	}, null, 2)
	}]
	};
	}

	if (tokenData.expires < Date.now()) {
	state.operationTokens.delete(token);
	return {
	content: [{
	type: 'text',
	text: JSON.stringify({
	authorized: false,
	error: 'Operation token expired. Call verify_protocol_compliance again to obtain a new token.'
	}, null, 2)
	}]
	};
	}

	// Mark token as used
	tokenData.used = true;

	// Write token file for PreToolUse hook verification
	const tokenFile = path.join(os.homedir(), '.protocol-enforcer-token');
	try {
	fs.writeFileSync(tokenFile, token, 'utf8');
	} catch (err) {
	return {
	content: [{
	type: 'text',
	text: JSON.stringify({
	authorized: false,
	error: `Failed to write token file: ${err.message}`
	}, null, 2)
	}]
	};
	}

	return {
	content: [{
	type: 'text',
	text: JSON.stringify({
	authorized: true,
	message: 'File operation authorized. Token file written for hook verification. You may now proceed with Write/Edit operations.'
	}, null, 2)
	}]
	};
	}

	// MCP Protocol Handler
	const tools = [
	{
	name: 'initialize_protocol_config',
	description: 'Create a new protocol enforcer configuration file at project or user scope',
	inputSchema: {
	type: 'object',
	properties: {
	scope: {
	type: 'string',
	enum: ['project', 'user'],
	description: 'Where to create the config file: "project" (.protocol-enforcer.json in current directory) or "user" (~/.protocol-enforcer.json)'
	}
	},
	required: ['scope']
	}
	},
	{
	name: 'verify_protocol_compliance',
	description: 'Verify that mandatory protocol steps have been completed before allowing file operations. This is a generic tool - protocol steps and checklist items are defined in your .protocol-enforcer.json configuration file. Supports hook-specific filtering.',
	inputSchema: {
	type: 'object',
	properties: {
	hook: {
	type: 'string',
	enum: ['user_prompt_submit', 'session_start', 'pre_tool_use', 'post_tool_use', 'stop'],
	description: 'REQUIRED: Which hook is calling this verification (e.g., "pre_tool_use", "user_prompt_submit"). Filters rules to only those applicable to this hook.'
	},
	tool_name: {
	type: 'string',
	description: 'Optional: name of the tool being called (e.g., "Write", "Edit"). Used for tool-specific filtering when combined with hook. Only applies when hook is "pre_tool_use" or "post_tool_use".'
	},
	protocol_steps_completed: {
	type: 'array',
	items: { type: 'string' },
	description: 'List of protocol step names that have been completed (e.g., ["planning", "analysis"]). Step names must match those defined in your .protocol-enforcer.json config.'
	},
	checklist_items_checked: {
	type: 'array',
	items: { type: 'string' },
	description: 'List of checklist items that were verified. Items should match those defined in your .protocol-enforcer.json config.'
	}
	},
	required: ['hook', 'protocol_steps_completed', 'checklist_items_checked']
	}
	},
	{
	name: 'get_compliance_status',
	description: 'Get current compliance check statistics and recent violations',
	inputSchema: {
	type: 'object',
	properties: {}
	}
	},
	{
	name: 'get_protocol_config',
	description: 'Get the current protocol enforcer configuration',
	inputSchema: {
	type: 'object',
	properties: {}
	}
	},
	{
	name: 'authorize_file_operation',
	description: 'MANDATORY before ANY file write/edit operation. Validates the operation token from verify_protocol_compliance. Single-use token that expires in 60 seconds.',
	inputSchema: {
	type: 'object',
	properties: {
	operation_token: {
	type: 'string',
	description: 'The operation token received from verify_protocol_compliance. Required for authorization.'
	}
	},
	required: ['operation_token']
	}
	}
	];

	// Main MCP message handler
	async function handleMessage(message) {
	const { method, params, id } = message;

	switch (method) {
	case 'initialize':
	return {
	jsonrpc: '2.0',
	id,
	result: {
	protocolVersion: '2024-11-05',
	serverInfo: {
	name: 'protocol-enforcer',
	version: '1.0.0'
	},
	capabilities: {
	tools: {}
	}
	}
	};

	case 'tools/list':
	return {
	jsonrpc: '2.0',
	id,
	result: { tools }
	};

	case 'tools/call':
	const { name, arguments: args } = params;
	let result;
	switch (name) {
	case 'initialize_protocol_config':
	result = await initializeProtocolConfig(args \|\| {});
	break;
	case 'verify_protocol_compliance':
	result = await verifyProtocolCompliance(args \|\| {});
	break;
	case 'get_compliance_status':
	result = await getComplianceStatus();
	break;
	case 'get_protocol_config':
	result = await getProtocolConfig();
	break;
	case 'authorize_file_operation':
	result = await authorizeFileOperation(args \|\| {});
	break;
	default:
	result = {
	content: [{
	type: 'text',
	text: JSON.stringify({ error: `Unknown tool: ${name}` })
	}],
	isError: true
	};
	}
	return {
	jsonrpc: '2.0',
	id,
	result
	};

	default:
	return {
	jsonrpc: '2.0',
	id,
	error: {
	code: -32601,
	message: `Method not found: ${method}`
	}
	};
	}
	}

	// Stdio transport
	async function main() {
	loadConfig();

	const rl = readline.createInterface({
	input: process.stdin,
	output: process.stdout,
	terminal: false
	});

	rl.on('line', async (line) => {
	try {
	const message = JSON.parse(line);
	const response = await handleMessage(message);
	console.log(JSON.stringify(response));
	} catch (error) {
	console.error(JSON.stringify({
	error: error.message,
	stack: error.stack
	}));
	}
	});

	// Keep process alive indefinitely for MCP persistent connection
	// This interval ensures the event loop never exits
	setInterval(() => {
	// Keep-alive: This keeps the process running
	// MCP servers must maintain persistent stdio connection
	}, 2147483647); // Maximum safe timeout (~24.8 days)
	}

	main().catch(console.error);
	{
	"name": "protocol-enforcer-mcp",
	"version": "1.0.0",
	"description": "MCP server that enforces mandatory supervisor protocol compliance before allowing file operations",
	"author": "Jason Lusk <[email protected]>",
	"license": "MIT",
	"main": "index.js",
	"bin": {
	"protocol-enforcer": "./index.js"
	},
	"engines": {
	"node": ">=14.0.0"
	},
	"keywords": [
	"mcp",
	"model-context-protocol",
	"protocol-enforcer",
	"ai-assistant",
	"code-quality",
	"compliance"
	]
	}