claw-code/.guardrails/docs/MCP_TOOLS_REFERENCE.md

MCP Tools Reference

Complete reference for Guardrails MCP validation tools.

---

Quick Reference Table

Tool	Purpose	Input	Categories Validated
guardrail_validate_bash	Validate bash commands	Command string	bash
guardrail_validate_git_operation	Validate git operations	Operation + args	git
guardrail_validate_file_edit	Validate file edits	Path + content	file_edit, content, edit, security

---

guardrail_validate_bash

Validates bash commands against dangerous patterns.

Description

Analyzes bash commands for potentially destructive or dangerous operations like rm -rf /, fork bombs, and data destruction patterns.

Input Parameters

Parameter	Type	Required	Description
command	string	Yes	The bash command to validate

Return Value

{
  "violations": [
    {
      "rule_id": "BASH-001",
      "severity": "critical",
      "message": "Dangerous bash command detected",
      "category": "bash"
    }
  ]
}

Example Usage

Request:

{
  "tool": "guardrail_validate_bash",
  "arguments": {
    "command": "rm -rf /"
  }
}

Response:

{
  "violations": [
    {
      "rule_id": "BASH-001",
      "severity": "critical",
      "message": "Dangerous bash command detected",
      "category": "bash"
    }
  ]
}

Valid Command (no violations):

{
  "tool": "guardrail_validate_bash",
  "arguments": {
    "command": "ls -la /home/user"
  }
}

Response:

{
  "violations": []
}

Validated Rule Categories

Category	Rules	Severity
bash	BASH-001	critical

---

guardrail_validate_git_operation

Validates git operations for safety and compliance.

Description

Checks git commands against rules preventing force pushes, branch deletions, and history rewrites.

Input Parameters

Parameter	Type	Required	Description
operation	string	Yes	Git operation (push, commit, rebase, etc.)
args	array[string]	Yes	Command arguments

Return Value

{
  "violations": [
    {
      "rule_id": "GIT-001",
      "severity": "error",
      "message": "Force push to main/master is blocked",
      "category": "git"
    }
  ]
}

Example Usage

Request (Force Push Blocked):

{
  "tool": "guardrail_validate_git_operation",
  "arguments": {
    "operation": "push",
    "args": ["--force", "origin", "main"]
  }
}

Response:

{
  "violations": [
    {
      "rule_id": "GIT-001",
      "severity": "error",
      "message": "Force push to main/master is blocked",
      "category": "git"
    }
  ]
}

Request (Safe Operation):

{
  "tool": "guardrail_validate_git_operation",
  "arguments": {
    "operation": "push",
    "args": ["origin", "feature-branch"]
  }
}

Response:

{
  "violations": []
}

Validated Rule Categories

Category	Rules	Severity Range
git	GIT-001 to GIT-006	error, warning

---

guardrail_validate_file_edit

Validates file edits for security and safety compliance.

Description

Multi-purpose validation tool checking file paths, content changes, and security patterns in edits.

Input Parameters

Parameter	Type	Required	Description
path	string	Yes	File path being edited
content	string	Yes	New file content
original_content	string	No	Previous content (for diff analysis)

Return Value

{
  "violations": [
    {
      "rule_id": "API-001",
      "severity": "critical",
      "message": "API key exposure detected",
      "category": "security"
    }
  ]
}

Example Usage

Request (Secret Detection):

{
  "tool": "guardrail_validate_file_edit",
  "arguments": {
    "path": "config.js",
    "content": "const apiKey = 'sk_live_abc123xyz789secretkey';"
  }
}

Response:

{
  "violations": [
    {
      "rule_id": "API-001",
      "severity": "critical",
      "message": "API key exposure",
      "category": "security"
    }
  ]
}

Request (Protected File):

{
  "tool": "guardrail_validate_file_edit",
  "arguments": {
    "path": ".claude/config.json",
    "content": "{}",
    "original_content": "{\"key\": \"value\"}"
  }
}

Response:

{
  "violations": [
    {
      "rule_id": "GENERAL-001",
      "severity": "error",
      "message": "Cannot modify protected files (.claude/, docs/, .md files)",
      "category": "general"
    }
  ]
}

Validated Rule Categories

Category	Rules	Purpose
file_edit	GENERAL-001	Protected path patterns
content	CODE-xxx	Code security patterns
edit	GIT-xxx	Git-related content
security	API-xxx, DB-xxx, CONT-xxx, CFG-xxx	Security credentials

---

Validation Engine Features

Caching

• TTL: 30 seconds
• Scope: Rule patterns cached to reduce database load
• Invalidation: Automatic after TTL expires

Severity Levels

Level	Color	Action
critical	Red	Blocks operation
error	Orange	Blocks operation
warning	Yellow	Warns, allows with confirmation
info	Blue	Informational only

Pattern Matching

• Engine: Go regexp package
• Flags: Case-insensitive (?i) by default
• Validation: Pre-compiled for performance

---

Tool Selection Guide

Use guardrail_validate_bash when:

• Executing shell commands via Bash tool
• Running system commands
• Processing user-provided command strings

Use guardrail_validate_git_operation when:

• Performing git push operations
• Executing git commands with arguments
• Automating git workflows

Use guardrail_validate_file_edit when:

• Writing to files
• Modifying configuration files
• Processing file uploads
• Checking code for secrets before commit

---

Related Documentation

Document	Purpose
RULES_INDEX_MAP.md	Complete rule reference
RULE_PATTERNS_GUIDE.md	Writing custom patterns
AGENT_GUARDRAILS.md	Main guardrails guide