protocol-enforcer mcp - "Set up protocol enforcement using https://gist.github.com/jasonlusk/eb0f0acd737c1ab6390e699a3a950271"

.protocol-enforcer.example.json

{
  "enforced_rules": {
    "require_protocol_steps": [
      "sequential_thinking",
      "memory_bank_query",
      "checklist_review"
    ],
    "require_checklist_confirmation": true,
    "minimum_checklist_items": 3
  },
  "checklist_items": [
    "No unnecessary CSS comments",
    "Component props inline (NOT separate .types.ts)",
    "No React.FC type annotations",
    "Match existing file structure and naming conventions",
    "Reuse existing components before creating new ones",
    "Run graphql:codegen after GraphQL operation changes",
    "Run lint:all before committing",
    "Follow CSS module camelCase naming for class names",
    "Use existing SCSS variables from _variables.scss",
    "Check package.json for existing dependencies before adding new ones"
  ]
}

README.md

Protocol Enforcer MCP Server

A Model Context Protocol (MCP) server that enforces custom workflow protocols before allowing AI agents to perform file operations.

Author: Jason Lusk [email protected] License: MIT

What This Does

This MCP server acts as a gatekeeper that ensures AI coding assistants follow your project's mandatory protocols:

• ✅ Enforces custom protocol steps before planning/coding
• ✅ Tracks required checklist items specific to your project
• ✅ Records compliance violations over time
• ✅ Fully configurable - adapt to any workflow or toolchain
• ✅ Tool-agnostic - works with any MCP servers or development process

Installation

Quick Install (from gist)

Add to your .mcp.json (project-level) or ~/.claude.json (user-level):

{
  "mcpServers": {
    "protocol-enforcer": {
      "command": "npx",
      "args": ["-y", "https://gist.github.com/YOUR_USERNAME/YOUR_GIST_ID"]
    }
  }
}

Replace YOUR_USERNAME/YOUR_GIST_ID with your actual gist URL.

Manual Install

1. Create a directory: mkdir -p ~/mcp-servers/protocol-enforcer && cd ~/mcp-servers/protocol-enforcer
2. Save package.json and index.js from this gist
3. Add to .mcp.json:

{
  "mcpServers": {
    "protocol-enforcer": {
      "command": "node",
      "args": ["/full/path/to/index.js"]
    }
  }
}

Verify Installation

After adding to .mcp.json:

1. Reload your IDE (Cursor: Cmd+Shift+P → "Developer: Reload Window")
2. Check MCP status (in terminal):

   ~/.cursor/extensions/anthropic.claude-code-*/resources/native-binary/claude mcp list

3. You should see protocol-enforcer in the list

Configuration

Creating a Configuration File

The server supports two configuration scopes:

• Project scope: .protocol-enforcer.json in your project root
• User scope: ~/.protocol-enforcer.json in your home directory

Project scope takes precedence if both exist.

Initialize Configuration

Ask your AI assistant:

Use the initialize_protocol_config tool to create a project-level configuration file.

Or manually create .protocol-enforcer.json:

{
  "enforced_rules": {
    "require_protocol_steps": ["step1", "step2"],
    "require_checklist_confirmation": true,
    "minimum_checklist_items": 2
  },
  "checklist_items": [
    "Follow project coding standards",
    "Check for reusable components",
    "Run linting before commit"
  ]
}

Configuration Options

Option	Type	Description
require_protocol_steps	string[]	List of required protocol step names (e.g., ["planning", "analysis", "review"])
require_checklist_confirmation	boolean	Require checking project-specific checklist items
minimum_checklist_items	number	Minimum number of checklist items that must be verified
checklist_items	string[]	List of project-specific patterns/rules to enforce

Usage

For AI Agents

Before making any file changes, you must call the verification tool:

// Complete your required protocol steps first
// (The specific steps depend on YOUR project configuration)

// Then verify compliance
mcp__protocol-enforcer__verify_protocol_compliance({
  protocol_steps_completed: ["planning", "analysis"],
  checklist_items_checked: [
    "Follow project coding standards",
    "Check for reusable components"
  ]
});

// Only if verification passes, proceed with file operations

Available Tools

1. initialize_protocol_config

Create a new configuration file.

Parameters:

• scope (required): "project" or "user"

Example:

mcp__protocol-enforcer__initialize_protocol_config({
  scope: "project"
});

2. verify_protocol_compliance

Verify that mandatory protocol steps have been completed.

Parameters:

• protocol_steps_completed (required): string[] - List of protocol step names completed
• checklist_items_checked (required): string[] - List of checklist items verified

Returns:

{
  "compliant": true,
  "message": "Protocol compliance verified. You may proceed with file operations."
}

Or if violations exist:

{
  "compliant": false,
  "violations": [
    "VIOLATION: Required protocol step not completed: planning",
    "VIOLATION: Only 1 checklist items checked, minimum 2 required"
  ],
  "message": "Protocol compliance check FAILED. Fix violations before proceeding."
}

3. get_compliance_status

Get current compliance statistics and recent violations.

Parameters: None

Returns:

{
  "total_checks": 47,
  "recent_checks": 10,
  "passed": 8,
  "failed": 2,
  "recent_violations": [
    {
      "timestamp": "2025-12-04T10:30:00.000Z",
      "violations": ["VIOLATION: Required protocol step not completed: analysis"]
    }
  ]
}

4. get_protocol_config

Get the current protocol enforcer configuration.

Parameters: None

Returns:

{
  "config_path": "/Users/username/project/.protocol-enforcer.json",
  "config": {
    "enforced_rules": {
      "require_protocol_steps": ["planning", "analysis"],
      "require_checklist_confirmation": true,
      "minimum_checklist_items": 2
    },
    "checklist_items": [...]
  }
}

Example Configurations

Example 1: TDD Workflow

{
  "enforced_rules": {
    "require_protocol_steps": ["write_tests", "implement", "refactor"],
    "require_checklist_confirmation": true,
    "minimum_checklist_items": 2
  },
  "checklist_items": [
    "Tests written before implementation",
    "All tests passing",
    "Code coverage maintained"
  ]
}

Example 2: Design-First Workflow

{
  "enforced_rules": {
    "require_protocol_steps": ["design_review", "component_mapping"],
    "require_checklist_confirmation": true,
    "minimum_checklist_items": 3
  },
  "checklist_items": [
    "Design tokens mapped to variables",
    "Figma specs reviewed",
    "Accessibility requirements checked",
    "Responsive breakpoints defined"
  ]
}

Example 3: Minimal Workflow

{
  "enforced_rules": {
    "require_protocol_steps": ["plan"],
    "require_checklist_confirmation": true,
    "minimum_checklist_items": 1
  },
  "checklist_items": [
    "Reviewed existing code patterns"
  ]
}

Integration with Your Workflow

This server is tool-agnostic and works with any workflow. Configure it to match YOUR process:

If you use reasoning tools:

{
  "require_protocol_steps": ["reasoning", "planning"],
  "checklist_items": ["Analyzed edge cases", "Considered alternatives"]
}

If you use documentation tools:

{
  "require_protocol_steps": ["query_docs", "review_patterns"],
  "checklist_items": ["Checked project guidelines", "Followed naming conventions"]
}

If you use design tools:

{
  "require_protocol_steps": ["fetch_design", "map_tokens"],
  "checklist_items": ["Design reviewed", "Tokens mapped", "Responsive checked"]
}

Custom workflow:

{
  "require_protocol_steps": ["your_step_1", "your_step_2"],
  "checklist_items": ["Your requirement 1", "Your requirement 2"]
}

Integration with AI Supervisor Protocols

Update your AI supervisor protocol to enforce verification before file operations:

## Protocol Enforcer Integration

Before ANY file write, edit, or create operation:
1. Complete all required protocol steps defined in your `.protocol-enforcer.json`
2. Call `mcp__protocol-enforcer__verify_protocol_compliance` with:
   - `protocol_steps_completed`: array of completed step names
   - `checklist_items_checked`: array of verified checklist items
3. If `compliant: false`, fix violations and retry verification
4. Only proceed with file operations if `compliant: true`

**This is a hard requirement - no exceptions.**

Troubleshooting

Server Not Appearing in MCP List

1. Check .mcp.json syntax - must be valid JSON
2. Reload IDE - Cmd+Shift+P → "Developer: Reload Window"
3. Verify gist URL - ensure it's publicly accessible
4. Check logs - look for MCP server startup errors

Configuration Not Loading

1. Check file name - must be exactly .protocol-enforcer.json
2. Verify JSON syntax - use a JSON validator
3. Check file location - project root or home directory
4. Call get_protocol_config - see what's actually loaded

Agent Still Violating Protocols

This server provides verification tools - it doesn't automatically prevent violations. You must:

1. Update your supervisor protocol to require calling verify_protocol_compliance before file operations
2. Configure your specific steps in .protocol-enforcer.json
3. Review compliance status - use get_compliance_status to track violations

Why This Exists

AI coding assistants are powerful but can bypass project-specific protocols when under pressure or context limits. This server:

• Enforces consistency - same rules for every task
• Provides traceability - tracks when protocols are followed/violated
• Enables accountability - compliance status shows protocol effectiveness
• Reduces technical debt - prevents shortcuts that violate project standards
• Works with ANY workflow - not tied to specific tools or processes

Contributing

This is a minimal implementation. Suggestions for improvement:

1. File operation hooks - intercept file writes directly (requires IDE integration)
2. Git pre-commit integration - block commits with compliance violations
3. Custom rule plugins - extend with project-specific validation logic
4. Dashboard UI - visualize compliance trends over time

Issues/PRs welcome on the gist discussion.

License

MIT License - see gist files for details.

---

Questions? Open a discussion on this gist or contact [email protected]

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 readline = require('readline');

// State tracking
const state = {
  configPath: null,
  config: null,
  complianceChecks: []
};

// Default configuration
const DEFAULT_CONFIG = {
  enforced_rules: {
    require_protocol_steps: ["plan", "review"],
    require_checklist_confirmation: true,
    minimum_checklist_items: 1
  },
  checklist_items: [
    "Follow project coding standards",
    "Check for reusable components"
  ]
};

// 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;
    state.config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
    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)
    }]
  };
}

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

  // Check required protocol steps
  if (config.enforced_rules.require_protocol_steps && Array.isArray(config.enforced_rules.require_protocol_steps)) {
    const requiredSteps = config.enforced_rules.require_protocol_steps;
    const completedSteps = args.protocol_steps_completed || [];

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

  // Check checklist confirmation
  if (config.enforced_rules.require_checklist_confirmation) {
    const checkedItems = args.checklist_items_checked || [];
    const requiredItems = config.checklist_items || [];
    const minItems = config.enforced_rules.minimum_checklist_items || 0;

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

    const uncheckedRequired = requiredItems.filter(item => !checkedItems.includes(item));
    if (uncheckedRequired.length > 0) {
      violations.push(`VIOLATION: Required checklist items not confirmed: ${uncheckedRequired.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)
      }]
    };
  }

  return {
    content: [{
      type: 'text',
      text: JSON.stringify({
        compliant: true,
        message: 'Protocol compliance verified. You may proceed with file operations.'
      }, 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)
    }]
  };
}

// 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.',
    inputSchema: {
      type: 'object',
      properties: {
        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: ['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: {}
    }
  }
];

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

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

    case 'tools/list':
      return { tools };

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

    default:
      return { error: `Unknown method: ${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
      }));
    }
  });
}

main().catch(console.error);

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