Guardrail MCP Validator

A Model Context Protocol (MCP) server designed to act as a strict syntax gatekeeper for AI agents.

When LLMs generate configuration files (like docker-compose.yml or JSON), they often make subtle syntax errors or use deprecated schemas. This MCP server provides a validate_and_format_code tool that allows the AI to test its output against local, native engines (like the Docker CLI or V8) before returning the final result to the user.

If the validation fails, the MCP server returns an error state (isError: true), which forces autonomous agents into a self-correction loop until the code actually compiles.

Features

• Data-Driven Architecture: Easily add support for new languages and CLI tools by simply modifying validators.json. No TypeScript required!

• Docker Compose Validation: Uses the native docker compose config engine to verify syntax.

• JSON Validation: Validates JSON payloads using native parsing.

• Python Validation: Syntax checks Python scripts using python3 -m py_compile.

• Bash Validation: Syntax checks shell scripts using bash -n.

• Agentic Looping: Intentionally returns structured error prompts designed to trigger self-correction in models like Claude or local Hermes variants.

• Configurable Tooling: Developers can opt-in/out of specific validation engines via environment variables, ensuring you don't need Docker or Python installed if you don't want to use them.

Related MCP server: gwaya

Adding Custom Validators

Because this MCP server is data-driven, you can add support for any language that has a CLI linter/compiler just by editing validators.json.

For example, to add yaml validation using yq, you would simply add this to the validators.json object:

  "yaml": {
    "extension": "yml",
    "command": "yq eval '.' {{FILE}}"
  }

The server will automatically load this, add "yaml" to the LLM's schema, and execute your command!

Getting Started

Prerequisites

• Node.js (v18+)

• (Optional) Docker (For Compose validation)

• (Optional) Python 3 (For Python validation)

• (Optional) Bash (For shell script validation)

Installation

Clone the repository and install dependencies:

git clone https://github.com/your-username/guardrail-mcp-validator.git
cd guardrail-mcp-validator
npm install

Running the Server

You can run the server in development mode using tsx:

npm run dev

Or build and run the compiled output:

npm run build
node dist/index.js

Client Configuration

Because MCP is a standardized protocol, you can use this server with any compatible client. Below are configuration examples for a few popular clients.

Using with Hermes

You can integrate this server into a Hermes agent. By running hermes config edit, you can set the path and the tool name for the agent in your configuration.

You can use the env block to define ENABLED_VALIDATORS. This accepts a comma-separated list of the tools you want to expose to the LLM (e.g. json,python,bash). If omitted, all supported validators will be enabled by default.

mcp_servers:
  guardrail-validator:
    command: node
    args:
      - /absolute/path/to/guardrail-mcp-validator/dist/index.js
    env:
      ENABLED_VALIDATORS: "json,python"

Using with Claude Desktop (Example)

To use this with an MCP-compatible client like Claude Desktop, add it to your configuration file (usually claude_desktop_config.json):

{
  "mcpServers": {
    "guardrail-validator": {
      "command": "node",
      "args": ["/absolute/path/to/guardrail-mcp-validator/dist/index.js"],
      "env": {
        "ENABLED_VALIDATORS": "json,bash,docker-compose"
      }
    }
  }
}

Tool Details

validate_and_format_code

Input Schema:

• language (string): The target language/schema ("docker-compose", "json", "python", or "bash").

• code (string): The raw configuration text block to validate.

License

This project is licensed under the MIT License - see the LICENSE file for details.