mirdan 1.12.0

AI Code Quality Orchestrator - Automatically transforms developer prompts into high-quality, structured requests

Mirdan

AI Code Quality Orchestrator — prevent AI slop before it reaches your codebase.

uv tool install mirdan      # Install globally
mirdan init --claude-code   # or --cursor, or --all
# Done. Quality enforcement is now automatic.

---

Why Mirdan?

AI coding assistants generate code fast, but without guardrails they produce slop: hardcoded secrets, SQL injection, placeholder functions, hallucinated imports, bare except blocks, and code that looks right but fails in production.

Mirdan fixes this by intercepting your AI workflow at two points:

1. Before coding — enhance_prompt enriches your task with quality requirements, security constraints, and framework-specific standards so the AI produces better code from the start
2. After coding — validate_code_quality catches what slipped through: 64 rules covering security vulnerabilities, AI-specific antipatterns, and language best practices

Once installed, it runs invisibly through IDE hooks. You just code normally.

What It Catches

Here's what mirdan flags on a single function of typical AI-generated code:

API_KEY = "sk-proj-abc123456789"           # SEC001: hardcoded API key
def get_users(user_id):
    query = f"SELECT * FROM users WHERE id={user_id}"  # SEC005 + AI008: SQL injection
    result = eval(user_input)              # PY001: code injection via eval()
    data = requests.get(url, verify=False) # SEC007: SSL verification disabled
    try:
        process(data)
    except:                                # PY003: bare except
        pass

Result: Score 0.0/1.0, 6 errors, 3 warnings. With auto-fix, mirdan resolves 5 of these automatically.

What It Adds to Your Prompts

When you ask an AI assistant to "Create a user auth endpoint in FastAPI with JWT tokens", mirdan's enhance_prompt detects this touches security and injects:

• Framework standards: "Use Depends() with Annotated for type-safe dependency injection"
• Security constraints: "Check that no secrets or credentials are hardcoded"
• Quality requirements: "Use Pydantic models for all request bodies and response schemas"
• Verification steps: "Ensure error handling covers all async operations"

The AI gets structured guidance instead of a bare prompt, producing better code on the first try.

---

Quick Start

Install

uv tool install mirdan           # Core (installs globally in isolated environment)
uv tool install 'mirdan[ast]'   # + tree-sitter for TS/JS AST analysis

# Upgrade to latest version
uv tool upgrade mirdan

Set Up Your IDE

mirdan init --claude-code    # Claude Code: hooks, rules, skills, agents
mirdan init --cursor         # Cursor: hooks, rules, AGENTS.md, BUGBOT.md
mirdan init --all            # Both IDEs

This generates everything — MCP server config, quality hooks, rules files, and agent definitions. After init, your IDE automatically:

1. Enriches prompts with quality requirements before coding tasks
2. Validates code against security and quality rules after every edit
3. Runs a final quality gate before task completion

Use From the Command Line

mirdan validate --file src/auth.py     # Validate a file
mirdan validate --staged               # Validate git staged changes
mirdan fix --file src/auth.py          # Auto-fix violations
mirdan gate                            # CI/CD quality gate (exit 0 or 1)
mirdan scan --dependencies             # Check deps for known CVEs
mirdan scan --directory src/           # Discover codebase conventions

---

How It Works

Mirdan is an MCP server — it connects to AI coding assistants (Claude Code, Cursor, Claude Desktop, or any MCP client) and provides quality enforcement tools.

┌──────────────────────────────────────────────────┐
│  Your AI Assistant (Claude Code / Cursor / etc)  │
│                                                  │
│  1. You type a coding task                       │
│  2. Hook calls enhance_prompt ──────────┐        │
│  3. AI generates code with guidance     │        │
│  4. Hook calls validate_code_quality ◄──┘        │
│  5. AI fixes violations automatically            │
│  6. Quality gate passes → task complete          │
└──────────────────────────────────────────────────┘
         │                        ▲
         ▼                        │
┌──────────────────────────────────────────────────┐
│  Mirdan MCP Server                               │
│                                                  │
│  enhance_prompt         → Quality requirements   │
│  validate_code_quality  → 64 rules, scoring      │
│  validate_quick         → Fast security checks   │
│  get_quality_standards  → Language/framework ref  │
│  get_quality_trends     → Historical analysis    │
│  scan_dependencies      → CVE detection (OSV)    │
│  scan_conventions       → Convention discovery   │
└──────────────────────────────────────────────────┘

---

Validation Rules

Mirdan ships with 64 rules across 10 categories. No external services required — all rules run locally.

AI Quality (AI001–AI008)

Rules that catch patterns unique to AI-generated code:

Rule	What It Catches
AI001	Placeholder code — raise NotImplementedError, pass with TODO (skips @abstractmethod)
AI002	Hallucinated imports — packages not in stdlib or project dependencies
AI003	Over-engineering — unnecessary abstractions for simple operations
AI004	Duplicate code blocks
AI005	Inconsistent error handling patterns
AI006	Unnecessary heavy imports where lighter alternatives exist
AI007	Security theater — patterns that look secure but provide no protection
AI008	Injection via f-strings — SQL, eval, exec, os.system with interpolation

Security (SEC001–SEC014)

Rule	What It Catches
SEC001–003	Hardcoded secrets — API keys, passwords, AWS keys
SEC004–006	SQL injection — string concat, f-strings, template literals
SEC007	SSL/TLS verification disabled
SEC008–009	Shell command injection via string formatting
SEC010	JWT verification disabled
SEC011–013	Graph database injection — Neo4j Cypher, Gremlin
SEC014	Vulnerable dependencies — packages with known CVEs

Language-Specific

Language	Rules	Key Checks
Python	PY001–PY015	eval/exec, bare except, mutable defaults, deprecated typing, unsafe pickle/yaml, subprocess shell, dead imports, unreachable code
JavaScript	JS001–JS005	var, eval, document.write, innerHTML, child_process.exec
TypeScript	TS001–TS005	eval, Function constructor, @ts-ignore, as any, innerHTML
Go	GO001–GO003	Ignored errors, panic(), SQL via fmt.Sprintf
Java	JV001–JV007	String ==, generic Exception, System.exit, Runtime.exec, unsafe deserialization
Rust	RS001–RS002	.unwrap(), empty .expect()

Plus ARCH001–003 / TSARCH001–004 (function length, file length, nesting depth, missing return types), RAG001–002 (chunk overlap, deprecated loaders).

Python rules PY001–PY004 use AST-based validation — eliminating false positives from strings and comments. When mirdan[ast] is installed, TypeScript/JavaScript architecture checks use tree-sitter for accurate function length, nesting depth, and return type analysis.

32 rules support automatic fixes via mirdan fix.

---

Language and Framework Support

Languages: Python, TypeScript, JavaScript, Go, Java, Rust

33 framework standards — mirdan knows the idioms, best practices, and common pitfalls for each:

React, React Native, Next.js, Nuxt, Vue, SvelteKit, Astro, Flutter, Tailwind, FastAPI, Django, Express, NestJS, Echo, Gin, Spring Boot, Micronaut, Quarkus, Drizzle, Neo4j, Supabase, Convex, Pinecone, Qdrant, Milvus, Weaviate, ChromaDB, FAISS, LangChain, LangGraph, CrewAI, DSPy, tRPC

When enhance_prompt detects a framework, it injects framework-specific quality requirements (e.g., "Use Depends() with Annotated" for FastAPI, "Prefer server components" for Next.js).

---

Quality Profiles

Profiles tune enforcement levels across 8 dimensions. Choose one that matches your project:

Profile	Security	Architecture	Testing	AI Slop	Dep Security	Best For
default	0.7	0.5	0.7	0.7	0.7	General-purpose projects
startup	0.7	0.3	0.5	0.8	0.5	Moving fast with safety nets
enterprise	1.0	0.9	0.9	1.0	1.0	Production enterprise code
fintech	1.0	0.8	1.0	1.0	1.0	Financial-grade correctness
library	0.8	0.9	0.9	0.8	0.8	Public APIs and packages
data-science	0.7	0.3	0.5	0.6	0.5	Exploration with data safety
prototype	0.5	0.2	0.2	0.5	0.3	Rapid prototyping

Scale: 0.0–0.3 permissive | 0.3–0.7 moderate | 0.7–1.0 strict

mirdan init --quality-profile enterprise
mirdan profile apply fintech          # Change later
mirdan profile suggest                # Let mirdan recommend one

---

IDE Integration

Claude Code

mirdan init --claude-code

Generates .mcp.json, hooks, rules, 7 skills (/code, /debug, /review, /plan, /quality, /scan, /gate), and 5 agents (quality-gate, security-audit, test-quality, convention-check, architecture-reviewer).

Hook stringency levels control how aggressively mirdan intervenes:

Level	Hooks	Best For
MINIMAL	2 (PostToolUse, Stop)	Low-friction onboarding
STANDARD	5 (+ UserPromptSubmit, PreToolUse, SubagentStart)	Daily development
COMPREHENSIVE	15 (full lifecycle including compaction, worktrees)	Teams and production

Cursor

mirdan init --cursor

Generates a complete Cursor 2.x integration:

• Rules — .cursor/rules/*.mdc (always-on, security, planning, debug, agent, language-specific)
• Hooks — .cursor/hooks.json with prompt-type + command-type hooks, .cursor/hooks/*.sh scripts
• Subagents — .cursor/agents/*.md (quality-validator, security-scanner, test-auditor, slop-detector, architecture-reviewer)
• Skills — .cursor/skills/*/SKILL.md following the Agent Skills Standard (code, debug, review, plan, quality, scan, gate)
• Commands — .cursor/commands/*.md slash commands (/code, /debug, /review, /plan, /quality, /scan, /gate)
• Environment — .cursor/environment.json for Cloud Agent environments
• Config — .cursor/mcp.json, AGENTS.md, BUGBOT.md

Cursor has tool slot limits. Set MIRDAN_TOOL_BUDGET to control which tools are exposed (2 = validation only, 5+ = all tools).

Claude Desktop / Any MCP Client

Add to your MCP configuration:

{
  "mcpServers": {
    "mirdan": {
      "command": "uvx",
      "args": ["mirdan"]
    }
  }
}

Enterprise Deployment

For organization-wide enforcement via managed configuration:

macOS: /Library/Application Support/ClaudeCode/managed-mcp.json Linux: /etc/claude-code/managed-mcp.json

{
  "mcpServers": {
    "mirdan": {
      "command": "uvx",
      "args": ["mirdan"]
    }
  }
}

---

CI/CD Integration

GitHub Actions

Add this workflow to .github/workflows/mirdan.yml:

name: Mirdan Quality Gate
on: [pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v4
      - run: uv tool install mirdan
      - run: mirdan gate

SARIF Export for GitHub Code Scanning

- run: mirdan export --format sarif > results.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: mirdan
        name: mirdan quality gate
        entry: mirdan validate --staged --quick
        language: system
        types: [python]

Quality Badges

mirdan export --format badge > .mirdan/badge.json

---

Configuration

mirdan init generates .mirdan/config.yaml. Key sections:

version: "1.0"

project:
  name: "MyApp"
  primary_language: "python"
  frameworks: ["fastapi", "react"]

# Quality enforcement levels
quality:
  security: "strict"           # strict|moderate|permissive
  architecture: "moderate"
  documentation: "moderate"
  testing: "strict"

# Or use a named profile (overrides quality section)
quality_profile: "default"

# Semantic validation and dependency scanning
semantic:
  enabled: true
  analysis_protocol: "security"  # none|security|comprehensive

dependencies:
  enabled: true
  osv_cache_ttl: 86400           # 24 hours
  scan_on_gate: true
  fail_on_severity: "high"       # critical|high|medium|low|none

# Score thresholds
thresholds:
  severity_error_weight: 0.25
  severity_warning_weight: 0.08
  arch_max_function_length: 30
  arch_max_file_length: 300
  # Per-file threshold overrides (glob patterns)
  file_overrides:
    - pattern: "tests/**"
      arch_max_function_length: 60
    - pattern: "scripts/**"
      arch_max_file_length: 500

# Hook behavior
hooks:
  enabled_events: ["PreToolUse", "PostToolUse", "Stop"]
  quick_validate_timeout: 5000
  auto_fix_suggestions: true

See the full configuration reference in docs/configuration.md or run mirdan init to generate a commented config file.

---

Advanced Features

AST-Based Validation

Python rules PY001–PY004 are verified via the ast module, eliminating false positives from eval/exec in strings, bare except in comments, etc. Two additional AST rules ship in 1.4.0:

• PY014 (dead-import) — detects unused imports, respecting TYPE_CHECKING blocks, __all__, and aliased imports
• PY015 (unreachable-code) — detects code after return/raise/break/continue, skipping finally blocks

For TypeScript/JavaScript, install the optional ast extra to enable tree-sitter parsing:

uv tool install 'mirdan[ast]'

This gives accurate function length, nesting depth, and missing return type detection instead of regex approximation. Falls back gracefully to regex when tree-sitter is not installed.

Full-File Diff Validation

When validating diffs (via hooks or validate_code_quality with input_type="diff"), mirdan reads the full file from disk when available. This enables architecture checks (function length, nesting depth) that require full-file context. Violations are filtered to changed lines only, and file-scope rules (file-too-long) are excluded from diff results.

Adaptive File-Path Thresholds

Override thresholds for specific file patterns using file_overrides in your config:

thresholds:
  arch_max_function_length: 30
  file_overrides:
    - pattern: "tests/**"
      arch_max_function_length: 60    # Tests can be longer
    - pattern: "migrations/**"
      arch_max_file_length: 1000      # Migration files are naturally long

Patterns use glob syntax and are matched against file paths. Overrides only replace the fields they specify — all other thresholds inherit from the base config.

Convention Discovery

Scan your codebase to discover implicit patterns and generate custom rules:

mirdan init --learn              # During init
mirdan scan --directory src/     # Standalone

Discovers naming patterns, import styles, docstring conventions, and recurring patterns. Generates .mirdan/rules/conventions.yaml with project-specific rules.

Dependency Vulnerability Scanning

Check dependencies against the OSV database (free, no API key required):

mirdan scan --dependencies                # Standalone scan
mirdan gate --include-dependencies        # Quality gate + vuln check

Supports PyPI, npm, crates.io, Go, and Maven. Results are cached for 24 hours. Vulnerabilities in imported packages trigger SEC014 violations during code validation.

Semantic Validation

validate_code_quality returns semantic_checks — targeted review questions generated from code patterns (SQL queries, auth logic, crypto operations, file I/O). These guide the AI to investigate specific concerns rather than doing shallow pattern matching. For security-critical code, an analysis_protocol provides structured deep-analysis steps.

Quality Forecasting

get_quality_trends analyzes validation history to track scores over time, forecast trajectory, detect regressions between sessions, and calculate pass rates.

Session Tracking and Feedback Loop

Each enhance_prompt call returns a session_id. Pass it to validate_code_quality to track quality across the full task lifecycle. Pass it back to enhance_prompt on the next call to close the feedback loop:

enhance_prompt(task)                   → session_id, enhanced_prompt
  ↓ implement code
validate_code_quality(code, session_id) → violations, session_context
  ↓ fix issues, iterate
enhance_prompt(task, session_id=...)   → persistent violations injected
                                          as priority quality requirements

When a violation recurs across two or more consecutive validations, mirdan surfaces it as a priority quality_requirement in the next enhanced prompt — ensuring the AI addresses the root cause rather than adding new code on top of broken foundations.

Multi-Agent Coordination

Hook configurations provide guardrails for autonomous agents (Cursor Background Agents, Claude Code subagents), ensuring quality enforcement without human oversight.

Cross-Project Intelligence

When combined with enyal (persistent knowledge graph MCP), mirdan stores project conventions as knowledge entries and recalls patterns across projects.

Upgrading

uv tool upgrade mirdan     # Upgrade to latest version
mirdan init --upgrade      # Regenerate IDE integration files

uv tool upgrade updates the package. mirdan init --upgrade merges new configuration fields into existing .mirdan/config.yaml, regenerates integration files, and preserves your customizations.

---

MCP Tools Reference

enhance_prompt

Entry point for coding tasks. Enriches a prompt with quality requirements, security constraints, and tool recommendations.

Parameters:
  prompt (required)     — The coding task description
  task_type             — generation|refactor|debug|review|test|planning|auto
  context_level         — minimal|auto|comprehensive
  max_tokens            — Token budget (0=unlimited)
  model_tier            — auto|opus|sonnet|haiku
  session_id            — Resume an existing session to thread validation
                          feedback into this prompt. Persistent violations
                          from prior validate_code_quality calls are injected
                          as priority quality requirements.

Returns:
  enhanced_prompt       — Enriched prompt with quality guidance
  detected_language     — Primary language detected
  detected_frameworks   — Frameworks to query docs for
  task_type             — Primary detected task type
  task_types            — All detected task types (compound detection). A
                          prompt like "add tests for the new feature" returns
                          ["test", "generation"] and unions verification steps
                          from both types.
  touches_security      — Whether task involves security-sensitive code
  quality_requirements  — Constraints to follow during implementation
  verification_steps    — Checklist before marking complete. Compressed to a
                          single re-validation step when a prior session passed,
                          reducing context waste on iterative work.
  tool_recommendations  — Which MCPs to call for context. Session-aware:
                          targets enyal recall to failure patterns on re-calls
                          with errors; suppresses redundant recalls after a pass.

validate_code_quality

Exit gate — validates code against quality standards. Returns score, violations, and semantic review questions.

Parameters:
  code (required)       — Code to validate
  language              — python|typescript|javascript|rust|go|java|auto
  check_security        — Enable security rules (default: true)
  check_architecture    — Enable architecture rules (default: true)
  check_style           — Enable style rules (default: true)
  severity_threshold    — error|warning|info
  input_type            — code|diff|compare
  session_id            — Session ID from enhance_prompt

Returns:
  passed                — Whether validation passed
  score                 — Quality score (0.0–1.0)
  violations            — List of rule violations with details. Each violation
                          includes verifiable: false when the check is
                          pattern-based (AI001–AI008) rather than AST-verified,
                          so the AI knows to confirm semantically before fixing.
  semantic_checks       — Targeted review questions from code patterns
  summary               — Human-readable summary

validate_quick

Fast security-only validation (<500ms) for hook integration. Runs SEC001–SEC014, AI001, and AI008.

get_quality_standards

Look up quality standards for a language/framework combination.

get_quality_trends

Quality score trends and forecasting from validation history.

scan_dependencies

Scan project dependencies for known vulnerabilities via the OSV database.

scan_conventions

Discover implicit codebase conventions and generate custom rules.

---

CLI Reference

Command	Purpose
mirdan serve	Start the MCP server (default)
mirdan init	Initialize project — generates config, hooks, rules, IDE integrations
mirdan validate	Validate code quality (--file, --staged, --stdin, --diff, --quick)
mirdan gate	Quality gate for CI/CD (--include-dependencies for vuln check)
mirdan fix	Auto-fix violations (--dry-run, --auto, --staged)
mirdan scan	Discover conventions (--directory) or scan deps (--dependencies)
mirdan profile	Manage quality profiles (list, suggest, apply)
mirdan export	Export results (--format sarif|badge|json)
mirdan report	Quality reports (--session, --compact-state, --format)
mirdan standards	View quality standards for a language
mirdan checklist	View verification checklists for a task type
mirdan plugin	Plugin export for standalone distribution

---

Troubleshooting

Server Not Connecting

1. Check uvx is available: uvx --version
2. Test server manually: uvx mirdan (should start without errors)
3. Check status in Claude Code: /mcp

Debug Logging

{
  "mcpServers": {
    "mirdan": {
      "command": "uvx",
      "args": ["mirdan"],
      "env": { "FASTMCP_DEBUG": "true" }
    }
  }
}

Common Issues

Issue	Solution
command not found: uvx	Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
Server starts but no tools appear	Restart your IDE after config changes
Python version error	Ensure Python 3.11+ is installed
Hook not firing	Check hook stringency level — MINIMAL only fires on 2 events
Tool budget limiting tools	Set MIRDAN_TOOL_BUDGET=5 or remove the env var

---

Development

git clone https://github.com/S-Corkum/mirdan.git
cd mirdan
uv sync --all-extras         # Includes tree-sitter for TS/JS AST
uv run pytest                # 2132 tests
uv run mirdan                # Run server locally

---

License

MIT