Guardian MCP v0.1.4

Stop AI from hallucinating code. Give it memory and discipline.

AI coding tools like Claude Code, Cursor, and Windsurf have a problem: they hallucinate functions that already exist, break working code with unpredictable edits, and forget everything between sessions.

Guardian fixes this by giving AI persistent memory, preventing code duplication, and enforcing a disciplined workflow.

⚠️ IMPORTANT: Guardian doesn't work automatically. You must explicitly tell your AI to use it:
"Use Guardian to implement this feature"
"Use Guardian gates to build authentication"
"Check with Guardian if this function exists"
Without this prompt, AI won't invoke Guardian's MCP tools.

Quick Start

1. Get Your API Key

Visit guardianmcp.dev and get your free API key.

2. Install Guardian

Option A: NPX (Recommended - Zero Installation)

Add to your MCP client config (e.g., ~/.config/claude/claude_desktop_config.json or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{ "mcpServers": { "guardian": { "command": "npx", "args": ["-y", "@skyastrall/mcp-guardian"], "env": { "GUARDIAN_API_KEY": "gd_your_api_key_here" } } } }

Replace gd_your_api_key_here with your actual API key from guardianmcp.dev.

Option B: Direct Install

macOS/Linux

curl -fsSL https://pub-1058b19511694bca989b12b21540e908.r2.dev/install.sh | bash

Windows (PowerShell)

iwr -useb https://pub-1058b19511694bca989b12b21540e908.r2.dev/install.ps1 | iex

Verify installation

mcp-guardian --version

Add to your MCP config:

{ "mcpServers": { "guardian": { "command": "mcp-guardian", "env": { "GUARDIAN_API_KEY": "gd_your_api_key_here" } } } }

3. Restart Your AI Tool

Restart Claude Code, Cursor, or your MCP-compatible tool.

4. Start Using Guardian

CRITICAL: You must explicitly tell your AI to use Guardian. It won't activate automatically.

Open your project and say:

"Use Guardian to scan this project"

Then for any feature:

"Use Guardian gates to implement user authentication"
"Use Guardian to check if handlePayment function exists"
"Use Guardian to find all database-related code"

Guardian will index your codebase and start protecting against code duplication only when you tell AI to use it.

What Guardian Does

Prevents Code Hallucination

Blocks duplicate functions: AI can't rewrite handleAuth if it already exists in src/auth.rs:42
Forces code reuse: AI must extend existing code instead of reinventing auth, caching, or rate limiting
Persistent memory: Remembers what you built across sessions

Engineering Gates Workflow

A 3-gate system that forces AI to think before coding:

Analysis Gate: AI must find and document ALL existing types, models, API endpoints, and dependencies
Planning Gate: Guardian reviews the plan and rejects it if AI tries to recreate existing code
Execution Gate: Step-by-step implementation with progress tracking
Completion: Verifies all steps done, nothing forgotten

Persistent Memory

Ground truth storage: Confirmed config values, ports, package versions
API contracts: Locks endpoint behavior with curl commands (prevents breaking changes)
Working set: Tracks relevant files you're currently working on
Design decisions: Records why something is complex (prevents premature optimization)

Project Isolation

Works with multiple huge codebases
Scopes all queries to current project
No cross-contamination between projects

Usage Guide

💡 Remember: You must tell your AI to use Guardian in every conversation. MCP tools only activate when explicitly requested.

Recommended: Engineering Gates Workflow

For any new feature, tell your AI to use the gated workflow:

You: "Use Guardian gates to implement user profile export"

What happens:

AI starts engineering process

AI calls: start_engineering(feature="user-profile-export", scope=["backend", "frontend"])

Analysis Gate - AI finds existing code

AI searches for: similar functions, existing models, API patterns  
AI documents: ALL types, models, endpoints, dependencies  
AI submits: submit_analysis(...)

Planning Gate - Guardian reviews

Guardian checks: Is AI reinventing existing code?  
Guardian validates: Security, error handling, existing code reuse  
Guardian scores: GARBAGE / POOR / GOOD / EXCELLENT  
Guardian rejects if: "Auth already exists in src/auth.rs, extend it instead"

You approve the plan

Guardian presents plan file for review  
You approve: "Approve the plan"  
AI calls: approve_plan(feature_id="...")

Execution Gate - Step-by-step implementation

AI gets: get_next_step() → "Step 1: Add export types"  
AI implements step  
AI reports: report_progress(step_completed="Add export types", files_modified=["types.ts"])  
AI gets: get_next_step() → "Step 2: Add API endpoint"  
... continues until complete

Benefits:

AI can't skip analysis or planning
Guardian catches code duplication before it happens
Progress tracked, resumable after interruptions
Forces security and error handling

Manual Tools (Advanced Usage)

Search Your Codebase

You: "Use Guardian to find all caching-related functions"
AI: [calls search_functions(query="cache", fuzzy=true)]
Guardian: ✓ Found 3 matches: initCache (src/cache.rs:15), clearCache (src/cache.rs:42), getCacheStats (src/cache.rs:78)

Get Function Context

You: "Use Guardian to show me the create_subscription function with context"
AI: [calls get_context(function="create_subscription", lines=30)]
Guardian: [Returns function code + 30 lines before/after + imports + dependencies + impact analysis]

Store Verified Configuration

You: "Use Guardian to remember that server port is 3000"
AI: [calls confirm_ground_truth(key="server.port", value="3000", value_type="config")]
Guardian: ✓ Ground truth confirmed: server.port = 3000

Lock API Contracts

Tell Guardian to lock your API behavior:

You: "Use Guardian to lock the /api/vehicles endpoint"
AI: [calls set_api_contract(...)]
Guardian: ✓ API contract locked for GET /api/vehicles

Track Design Decisions

You: "Record why we use Razorpay"
AI: record_decision(
  component="payment_handler",
  reason="Using Razorpay for better async support and webhook handling"
)

Later...
AI: get_decision(component="payment_handler")
Guardian: Decision found: Using Razorpay for better async support...

Find All References

You: "Where is AppError used?"
AI: find_references(name="AppError", limit=50)
Guardian: Found 151 references across 23 files [shows file:line:snippet]

Map Relationships

You: "What does create_subscription call and what calls it?"
AI: map_relationships(function="create_subscription")
Guardian:
  Calls: [get_plan_limit, razorpay_service::create_subscription]
  Called by: [update_subscription, webhook_handler]

Common Workflows

Starting a New Feature

Always tell AI to use Guardian:

You: "Use Guardian gates to implement password reset feature"

What happens:

AI scans for existing auth code
Guardian reviews plan and blocks duplicates
You approve the plan
AI implements step-by-step with Guardian tracking progress

Exploring Unfamiliar Codebase

You: "Use Guardian to find all authentication-related code"
AI: [calls search_functions, get_context, find_references...]
Guardian: [Returns comprehensive auth code map]
AI: "I found 12 auth-related functions. Here's the structure..."

Preventing Breaking Changes

You: "Use Guardian to lock the /api/users endpoint contract"
AI: [calls set_api_contract(...)]
Guardian: ✓ API contract locked

Later, when AI tries to modify the endpoint, Guardian will warn about breaking changes.

Resuming After Interruption

You: "Use Guardian to resume the payment export feature"
AI: [calls list_active_features, resume_feature]
Guardian: [Returns full context: gate, progress %, next step, files modified]
AI: "You were at step 3/10. Next: Add export endpoint to router."

Best Practices

🚨 #1 RULE: Always start your prompt with "Use Guardian" or Guardian won't activate!

DO:

✅ Say "Use Guardian" at the start of every task
✅ Use engineering gates for any non-trivial feature
✅ Let Guardian reject plans (it's catching duplicates)
✅ Store ground truth when AI confirms critical values
✅ Set API contracts for important endpoints
✅ Scan project first thing when starting work

DON'T:

❌ Forget to say "Use Guardian" (AI won't invoke tools otherwise)
❌ Skip the analysis gate
❌ Override "function already exists" warnings without checking
❌ Work on multiple projects without setting context
❌ Ignore Guardian's plan rejections

Available Tools Reference

Engineering Gates (Gated Workflow)

Tool	Purpose
start_engineering	Begin gated workflow for a feature
submit_analysis	Submit all types, models, endpoints, dependencies
submit_plan	Submit implementation plan (auto-reviewed)
approve_plan	User approves plan to begin execution
get_next_step	Get next implementation step
report_progress	Mark step complete, track progress
resume_feature	Resume after context loss or interruption
list_active_features	Show all in-progress features

Function Management

Tool	Purpose
scan_project	Index entire codebase (run first)
search_functions	Fuzzy search for functions (use this to check if code exists)
get_context	Get function code + surrounding context
find_references	Find all usages of a function/variable
map_relationships	Show what calls what (dependency graph)

Memory & Persistent State

Tool	Purpose
confirm_ground_truth	Store verified config/package/env value
get_ground_truth	Retrieve stored verified value
update_ground_truth	Update stored value
delete_ground_truth	Remove stored ground truth entry
set_api_contract	Lock API behavior with curl command
get_api_contract	Get stored API contract
record_decision	Store design decision with rationale
get_decision	Retrieve stored design decision
why_is_this_complex	Legacy alias for get_decision

Project Management

Tool	Purpose
set_project_context	Switch between projects
remember_files	Add files to working set
get_working_set	Show currently tracked files

Troubleshooting

API Key Issues

Error: "Missing API key"

Add GUARDIAN_API_KEY to your MCP config:

Get your API key at guardianmcp.dev

Guardian Not Responding

Restart your AI tool (Claude Code, Cursor, etc.)
Check MCP config syntax is valid JSON
Verify API key starts with gd_

"Function Already Exists" Warning

This is Guardian working correctly! It found duplicate code. Options:

Use the existing function (recommended)
Extend the existing function
If you really need a new function, use a different name

Plan Rejected During Gates

Guardian is preventing code duplication. Review the rejection reason:

"Auth already exists" → Extend existing auth code
"Missing security section" → Add security considerations
"No error handling" → Document error cases

Support

Website: guardianmcp.dev
API Key: Get yours at guardianmcp.dev
Issues: Found a bug? Open an issue on GitHub

License

Proprietary - Closed Source SaaS Product

Guardian MCP