de en es ja ko ru zh

Mirdan

Name: Mirdan
Author: S-Corkum

by S-Corkum

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Mirdan

AI Code Quality Orchestrator — saves 30-45% of your paid AI coding tokens by running a local intelligence layer that handles triage, linting, type checking, test running, and validation so expensive models like Claude Opus focus on writing code.

PyPI version Python 3.11+ License: MIT

uv tool install mirdan                  # Install mirdan
mirdan llm setup                        # Auto-installs backend, downloads model, configures
mirdan init --claude-code               # or --cursor
# Done. Quality enforcement + local intelligence is now automatic.

Works with Claude Code, Cursor IDE, and Cursor CLI. Runs on 16GB laptops. Everything stays local.

Brief-Driven Plan Pipeline (New in 2.1.0)

Mirdan 2.1.0 adds a brief-first plan workflow that shifts frontier-model token spend upstream (brief authoring) so the rest of the pipeline can run on cheaper models. One artifact, three layers, cross-IDE parity.

/brief <slug>                      → author structured brief in docs/briefs/
/plan --brief <path>               → three-layer plan (epic → stories → subtasks)
/plan-verify <plan-path>           → mechanical coverage check via local Gemma 4
/plan-review --stakes high <path>  → escape hatch: judgment review on shared rubric
/plan-execute <plan-path>          → dispatch subtasks to Haiku (CC) / local LLM (Cursor)

Worked example

# 1. Author a brief (required before /plan runs)
/brief add-passkey-auth "Add passkey authentication for web sign-in"
# → prompts for Outcome, Users & Scenarios, Business ACs, Constraints, Out of Scope
# → writes docs/briefs/add-passkey-auth.md
# → auto-stores to enyal with content_type="brief"

# 2. Generate the plan (brief constraints merge into quality_requirements)
/plan --brief docs/briefs/add-passkey-auth.md
# → writes docs/plans/add-passkey-auth.md with frontmatter brief: docs/briefs/add-passkey-auth.md

# 3. Verify coverage mechanically (local Gemma 4, ≤30s on mid-tier hardware)
/plan-verify docs/plans/add-passkey-auth.md
# → ## Verification report with unmapped_acs, missing_grounding, ...

# 4. Execute (Claude Code dispatches to Haiku subagents; Cursor A/B routing)
/plan-execute docs/plans/add-passkey-auth.md
# → runs /plan-verify as pre-flight, then walks subtasks in dependency order

MCP tool reference

Tool	Returns
`mcp__mirdan__validate_brief(brief_path)`	`{passed, score, gaps, missing_required, thin_recommended, would_pass_after_fixes}`
`mcp__mirdan__verify_plan_against_brief(plan_path, brief_path)`	`{verified, coverage_score, missing_grounding, out_of_scope_violations, invest_failures, phantom_files, dependency_errors, vague_cross_references, unmapped_acs, semantic_check_skipped, summary}`
`mcp__mirdan__propose_subtask_diff(subtask_yaml, file_context)`	`{diff, model_used, confidence, halted, halt_reason}`
`mcp__mirdan__mirdan_health()`	`{local_llm_available, model_in_use, vram_gb, recommended_mode, backend_kind}`
`mcp__mirdan__enhance_prompt(prompt, brief_path=...)`	existing output + `quality_requirements` prefixed with `[from brief]` + `out_of_scope` list

What `/plan-verify` actually catches (evidence-based)

Mechanical findings — reliable at any hardware tier, no LLM required:

phantom_files — subtask's **File:** points at a path that doesn't exist; for NEW: files, parent directory is missing
dependency_errors — **Depends on:** references a subtask ID that isn't in the plan; or a circular dependency graph
vague_cross_references — "as discussed", "like Step N", "from before" — phrases cheap executors can't resolve
missing_grounding — subtask missing any of the 6 required grounding fields
out_of_scope_violations — brief Out-of-Scope items appearing in plan body
invest_failures — stories missing INVEST structural fields

Evidence: tests/evidence/ — 100% detection on seeded defects, 0% false positives on clean plans, deterministic across 20 runs. Runtime: median 1.45 ms, max 11.87 ms across 18 historical plans.

Semantic findings — require BRAIN-tier (31B+) local model:

unmapped_acs — brief Business ACs not mapped to any story AC by an LLM judge with confidence ≥ 0.6

Semantic check is automatically skipped if no BRAIN-tier model is available. Gemma 4 E2B/E4B are FAST-tier and are not discriminative for this task — see docs/briefs/mirdan-brief-driven-pipeline.md "Semantic path hardware requirement" for the teeth-test data that established this.

Reference implementation

docs/briefs/mirdan-brief-driven-pipeline.md and docs/plans/mirdan-brief-driven-pipeline.md in the project root are the 2.1.0 release's own brief-and-plan pair — dogfooded during development.

Retired in 2.1.0

/debug, /review, /quality, /gate, /scan ship as deprecation stubs. See CHANGELOG.md 2.1.0 section for the migration table. Full deletion in 2.2.0.

Related MCP server: CloudZIR MCP Server

Local Intelligence Layer (New in 2.0)

Mirdan 2.0 offloads mundane work to a small local model (Gemma 4) running on your machine. The paid model focuses exclusively on complex reasoning and writing code.

Before you code:

Triage — classifies tasks. Trivial tasks (fix an import, format a file) never hit the paid model. Zero tokens spent.
Research — gathers codebase context, library docs, and project conventions locally (64GB+ only).

After you code:

Check Runner — runs ruff, mypy, pytest locally. LLM parses output, auto-fixes lint, reports only complex failures.
Smart Validation — 64 quality rules + LLM false-positive filtering, root cause grouping, and fix suggestions.
Auto-Fix — mirdan check --smart --fix applies LLM-generated search/replace fixes with verification.

Hardware	What Runs	Token Savings
16GB laptop	Gemma 4 E4B Q3 — triage, checks, validation, auto-fix	30-45%
32GB	Gemma 4 E4B Q3 — same features, more headroom	35-50%
64GB+ Apple Silicon	+ Gemma 4 31B for prompt optimization and research	50-70%

Quick Setup

mirdan llm setup              # Detects hardware, installs backend, downloads model, configures
mirdan init --claude-code     # or --cursor
mirdan llm status             # Verify it's working

Everything runs locally. No remote servers. No data leaves your machine.

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:

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
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                   # Install mirdan
mirdan llm setup                         # Auto-installs LLM backend + downloads model

# Optional extras:
uv tool install 'mirdan[ast]'            # + tree-sitter for TS/JS AST analysis
uv tool install 'mirdan[enterprise]'     # + truststore for corporate SSL inspection

# Upgrade:
uv tool upgrade mirdan

# Or with pip:
pip install 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. When LLM is enabled, hooks also configure local triage and check runner. After init, your IDE automatically:

Enriches prompts with quality requirements before coding tasks
Validates code against security and quality rules after every edit
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 (pattern-based)
mirdan check --smart                   # Run lint + typecheck + test with LLM analysis
mirdan check --smart --fix src/        # Run checks AND auto-fix with local LLM
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
mirdan llm setup                       # Configure local LLM
mirdan llm status                      # Show LLM health, model, hardware
mirdan llm metrics                     # Token savings dashboard

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 triages task via local LLM ────┐        │
│  3. AI generates code with guidance     │        │
│  4. Hook runs lint/typecheck/test ◄─────┘        │
│  5. AI fixes only complex issues                 │
│  6. Quality gate passes → task complete          │
└──────────────────────────────────────────────────┘
         │                        ▲
         ▼                        │
┌──────────────────────────────────────────────────┐
│  Mirdan MCP Server + Local Intelligence Layer    │
│                                                  │
│  MCP Tools (unchanged):                          │
│  enhance_prompt         → Quality requirements   │
│  validate_code_quality  → 64 rules + LLM enrich │
│  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   │
│                                                  │
│  Local LLM (Gemma 4, runs on your machine):      │
│  Triage          → Classify tasks, save tokens   │
│  Check Runner    → Run ruff/mypy/pytest locally  │
│  Smart Validator → FP filtering, root causes     │
│  Auto-Fix        → Search/replace code fixes     │
│  HTTP Sidecar    → <5ms hook integration         │
└──────────────────────────────────────────────────┘

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

Corporate networks (Netskope, Zscaler, Artifactory proxy): pass env vars for SSL and model downloads:

{
  "mcpServers": {
    "mirdan": {
      "command": "uvx",
      "args": ["mirdan"],
      "env": {
        "MIRDAN_HF_ENDPOINT": "https://artifactory.corp.com/hf",
        "MIRDAN_HF_TOKEN": "your-artifactory-token",
        "MIRDAN_SSL_CERT_FILE": "/path/to/corporate-ca-bundle.crt"
      }
    }
  }
}

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

LLM configuration goes in .mirdan.yaml (written by mirdan llm setup):

llm:
  enabled: true
  backend: llamacpp                # llamacpp (default) or ollama
  model_keep_alive: 5m             # Unload model after idle (saves RAM)

See the full LLM configuration reference or run mirdan llm setup to auto-configure.

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:

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 check`	Run lint + typecheck + test (`--smart` for LLM analysis, `--fix` for auto-fix)
`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
`mirdan llm setup`	Configure local LLM — installs backend, downloads model
`mirdan llm status`	Show LLM health, loaded model, hardware profile (`--json`)
`mirdan llm warmup`	Pre-load model into memory for faster first inference
`mirdan llm metrics`	Token savings dashboard (`--days N`, `--json`)
`mirdan triage`	Classify a task via local LLM (`--stdin`, used by hooks)
`mirdan fine-tune`	Training data management (`status`, `export`)

Troubleshooting

Server Not Connecting

Check uvx is available: uvx --version
Test server manually: uvx mirdan (should start without errors)
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`
`command not found: mirdan`	`uv tool install mirdan`
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
"LLM backend unavailable"	Run `mirdan llm setup` — it auto-installs the backend and model
"Model not found"	Run `mirdan llm setup` to download the recommended model
Slow LLM inference (<5 tok/s)	Verify Metal: `CMAKE_ARGS="-DGGML_METAL=ON" pip install --force-reinstall llama-cpp-python`
High memory usage	Set `model_keep_alive: 2m` in `.mirdan.yaml`. Model unloads after idle.
Hooks not calling local LLM	Run `mirdan init --claude-code` (or `--cursor`) to regenerate hooks
Corporate network download fails	Set `MIRDAN_HF_ENDPOINT` and `MIRDAN_HF_TOKEN` (see troubleshooting guide)

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                # 3050+ tests
uv run mirdan                # Run server locally

License

MIT

Available Tools

7 tools

analyze_intentB

Analyze a prompt without enhancement, returning the detected intent, entities, and recommended approach.

Args: prompt: The developer prompt to analyze

Returns: Structured intent analysis

ParametersJSON Schema

Name	Required	Description	Default
`prompt`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions the tool analyzes a prompt and returns structured intent analysis, but doesn't disclose behavioral traits such as whether it's read-only, requires authentication, has rate limits, or what happens with invalid inputs. This is a significant gap for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, with the core purpose stated first. The additional details about args and returns are useful but could be more integrated. There's no wasted text, though it could be slightly more polished for optimal clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (1 parameter, no annotations, but has an output schema), the description is minimally complete. It covers the purpose and basic I/O, but lacks details on behavior, error handling, or how it differs from siblings. The presence of an output schema reduces the need to explain return values, but more context is needed for full understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds minimal semantics beyond the input schema: it defines 'prompt' as 'The developer prompt to analyze'. With 0% schema description coverage and only 1 parameter, this provides some value, but it's basic and doesn't elaborate on format, constraints, or examples. The baseline is 3 since the schema covers the parameter structure adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Analyze a prompt without enhancement, returning the detected intent, entities, and recommended approach.' This specifies the verb (analyze), resource (prompt), and output (intent, entities, approach). However, it doesn't explicitly differentiate from sibling tools like 'enhance_prompt' or 'suggest_tools', which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by mentioning 'without enhancement' and listing output components, suggesting it's for raw analysis rather than enhancement. However, it lacks explicit guidance on when to use this tool versus alternatives like 'enhance_prompt' or 'suggest_tools', and doesn't specify prerequisites or exclusions, leaving some ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

enhance_promptA

Automatically enhance a coding prompt with quality requirements, codebase context, and tool recommendations.

Returns: Enhanced prompt with quality requirements and tool recommendations

ParametersJSON Schema

Name	Required	Default
`prompt`	Yes
`task_type`	No	auto
`context_level`	No	auto

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses the tool's behavior by describing what it adds ('quality requirements, codebase context, and tool recommendations') and mentions auto-detection and context levels. However, it lacks details on permissions, rate limits, or error handling, leaving gaps for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, starting with a clear purpose statement. The Args and Returns sections are structured efficiently, with each sentence adding value without redundancy. It avoids unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (3 parameters, no annotations, but with an output schema), the description is fairly complete. It covers the tool's purpose, parameters, and return value. The output schema reduces the need to explain returns in detail, but more behavioral context could be added for a tool with no annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must compensate. It adds meaning by explaining each parameter's purpose: 'prompt' as the original input, 'task_type' with enum values and override function, and 'context_level' with options. This goes beyond the bare schema, though it could provide more detail on enum semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('enhance a coding prompt') and resources ('quality requirements, codebase context, and tool recommendations'). It distinguishes from siblings like 'analyze_intent' or 'get_quality_standards' by focusing on prompt enhancement rather than analysis or standards retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage through the mention of 'auto-detection' and parameter defaults, but does not explicitly state when to use this tool versus alternatives like 'suggest_tools' or 'validate_code_quality'. It provides some context but lacks clear exclusions or named alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_quality_standardsC

Retrieve quality standards for a language/framework combination.

Args: language: Programming language (typescript, python, etc.) framework: Optional framework (react, fastapi, etc.) category: Filter to specific category (security|architecture|style|all)

Returns: Quality standards for the specified language/framework

ParametersJSON Schema

Name	Required	Default
`language`	Yes
`framework`	No
`category`	No	all

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions what the tool returns but doesn't describe important behavioral aspects like whether it's read-only, if it requires authentication, rate limits, error conditions, or pagination behavior. The description is minimal and lacks operational context needed for safe invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (purpose, Args, Returns) and uses minimal sentences. Each section earns its place by providing essential information without redundancy. However, the Args section could be more integrated with the main description rather than appearing as a separate block.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema (which handles return values) and moderate complexity with 3 parameters, the description is minimally adequate. It covers basic purpose and parameters but lacks important context about behavioral traits, usage guidelines, and detailed parameter semantics that would make it complete for safe and effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description lists parameters in the Args section with brief explanations, but with 0% schema description coverage, it doesn't fully compensate. It provides basic meaning for 'language', 'framework', and 'category' but lacks details on format constraints, valid values beyond examples, or how parameters interact. The schema shows defaults and requirements, but the description adds only marginal semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Retrieve') and resource ('quality standards for a language/framework combination'). It distinguishes from siblings like 'validate_code_quality' by focusing on retrieval rather than validation. However, it doesn't explicitly contrast with 'get_verification_checklist' which might have overlapping retrieval functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'get_verification_checklist' or 'validate_code_quality' that might serve similar purposes, nor does it specify prerequisites, constraints, or appropriate contexts for usage beyond the basic parameter requirements.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_verification_checklistB

Get a verification checklist for a specific task type.

Args: task_type: Type of task (generation|refactor|debug|review|test) touches_security: Whether the task involves security-sensitive code

Returns: Verification checklist appropriate for the task

ParametersJSON Schema

Name	Required	Description	Default
`task_type`	Yes
`touches_security`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'Returns: Verification checklist appropriate for the task,' which implies a read-only operation, but doesn't disclose critical traits like whether it's idempotent, has rate limits, requires authentication, or what format the checklist returns. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, starting with the core purpose. The 'Args' and 'Returns' sections add necessary details without redundancy. However, the structure could be slightly improved by integrating the parameter explanations more seamlessly, and the second sentence ('Args:...') feels slightly detached, but overall it's efficient with minimal waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (2 parameters, no annotations, but with an output schema), the description is reasonably complete. It explains the purpose, parameters, and return value, and the presence of an output schema means it doesn't need to detail return values further. However, it lacks behavioral context (e.g., error handling or usage scenarios), which slightly reduces completeness for a tool with no annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaningful semantics beyond the schema by explaining that 'task_type' includes specific values (generation|refactor|debug|review|test) and 'touches_security' indicates 'Whether the task involves security-sensitive code.' This clarifies parameter purposes and constraints, though it doesn't cover all possible nuances like default behavior for 'touches_security' (which the schema sets to false).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get a verification checklist for a specific task type.' It specifies the verb ('Get') and resource ('verification checklist'), and distinguishes it from sibling tools like 'get_quality_standards' or 'validate_code_quality' by focusing on task-specific checklists rather than general standards or validation. However, it doesn't explicitly differentiate from all siblings, such as 'suggest_tools', which might also relate to task guidance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context for selection, or exclusions, and fails to reference sibling tools like 'get_quality_standards' or 'validate_plan_quality' that might overlap in purpose. Usage is implied only by the tool's name and description, with no explicit when/when-not instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

suggest_toolsA

Suggest which MCP tools should be used for a given intent.

Args: intent_description: Description of what you're trying to do available_mcps: Comma-separated list of available MCPs (optional) discover_capabilities: If True, query actual MCP capabilities for recommended MCPs

Returns: Tool recommendations with priorities and reasons

ParametersJSON Schema

Name	Required	Description	Default
`intent_description`	Yes
`available_mcps`	No
`discover_capabilities`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the tool returns 'tool recommendations with priorities and reasons,' which adds some context about output behavior. However, it lacks details on permissions, rate limits, or error handling, leaving gaps for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a purpose statement, arg explanations, and return details, all in a compact format. Every sentence adds value, though the arg descriptions could be slightly more integrated into the flow rather than listed separately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, no annotations, and the presence of an output schema (which handles return values), the description is fairly complete. It covers purpose, parameters, and output behavior adequately, though it could benefit from more behavioral context like error cases or usage examples.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It provides clear semantics for all three parameters: intent_description explains its purpose, available_mcps notes it's optional and comma-separated, and discover_capabilities describes its boolean nature and effect. This adds significant value beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('suggest') and resource ('MCP tools'), and it distinguishes itself from siblings by focusing on tool recommendation rather than analysis, enhancement, or validation. The phrase 'for a given intent' establishes its unique role in the toolset.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when determining which tools to use for an intent, but it doesn't explicitly state when to use this tool versus alternatives like analyze_intent or get_quality_standards. No exclusions or clear alternatives are provided, leaving usage context somewhat vague.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_code_qualityB

Validate generated code against quality standards.

Args: code: The code to validate language: Programming language (python|typescript|javascript|rust|go|auto) check_security: Validate against security standards check_architecture: Validate against architecture standards check_style: Validate against language-specific style standards severity_threshold: Minimum severity to include in results (error|warning|info)

Returns: Validation results with pass/fail, score, violations, and summary

ParametersJSON Schema

Name	Required	Default
`code`	Yes
`language`	No	auto
`check_security`	No
`check_architecture`	No
`check_style`	No
`severity_threshold`	No	warning

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions validation against standards but doesn't describe what happens during validation (e.g., external calls, processing time), error handling, or output format details beyond the basic return statement. This leaves significant gaps for a tool with 6 parameters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized but not optimally structured. The initial sentence is clear, but the parameter and return sections are listed without integration into a cohesive narrative. While efficient, it could be more front-loaded with key usage context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, no annotations) and the presence of an output schema, the description is moderately complete. It covers parameter semantics well but lacks behavioral context and usage guidelines. The output schema likely details return values, reducing the need for that in the description, but overall gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds substantial meaning beyond the input schema, which has 0% description coverage. It explains each parameter's purpose (e.g., 'code: The code to validate,' 'check_security: Validate against security standards'), including enum values for 'language' and 'severity_threshold.' This compensates well for the schema's lack of documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as 'Validate generated code against quality standards,' which is a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'validate_plan_quality' or 'get_quality_standards,' leaving some ambiguity about when to choose this tool over alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus its siblings. It doesn't mention alternatives like 'validate_plan_quality' for non-code validation or 'get_quality_standards' for retrieving standards, nor does it specify prerequisites or contextual constraints for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_plan_qualityA

Validate a plan for implementation by a less capable model. Returns a quality score and list of issues that need fixing.

Args: plan: The plan text to validate target_model: Model that will implement (haiku|flash|cheap|capable) Cheaper models require stricter plan quality.

Returns: Quality scores, issues list, and ready_for_cheap_model flag

ParametersJSON Schema

Name	Required	Description	Default
`plan`	Yes
`target_model`	No		haiku

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: it returns a quality score, issues list, and a 'ready_for_cheap_model' flag, which adds context beyond basic validation. However, it lacks details on error handling, rate limits, or authentication needs, which are important for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, starting with the core purpose. The 'Args' and 'Returns' sections are structured clearly, but the note about 'cheaper models require stricter plan quality' could be integrated more smoothly. Overall, it's efficient with minimal waste, though minor improvements in flow could elevate it to a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (2 parameters, no annotations, but with an output schema), the description is fairly complete. It explains the purpose, parameters, and return values, and the output schema likely covers return details, so the description doesn't need to elaborate further. However, it could benefit from more context on how validation works or links to sibling tools, keeping it from a perfect score.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds significant meaning beyond the input schema, which has 0% description coverage. It explains that 'plan' is 'The plan text to validate' and 'target_model' specifies the model that will implement, with options like 'haiku|flash|cheap|capable' and the note that 'cheaper models require stricter plan quality.' This compensates well for the schema's lack of descriptions, though it doesn't detail all possible enum values or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Validate a plan for implementation by a less capable model.' It specifies the verb ('validate') and resource ('plan'), and distinguishes it from siblings like 'validate_code_quality' by focusing on plan validation rather than code. However, it doesn't explicitly differentiate from all siblings (e.g., 'get_verification_checklist'), so it falls short of a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by mentioning 'less capable model' and that 'cheaper models require stricter plan quality,' which suggests when to use it based on target model constraints. However, it doesn't explicitly state when to use this tool versus alternatives like 'get_quality_standards' or 'suggest_tools,' nor does it provide exclusions or prerequisites, leaving some ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

7 tool updatesv1.0.0Jan 11, 2026
- First observedanalyze_intent
- First observedenhance_prompt
- First observedget_quality_standards
- First observedget_verification_checklist
- First observedsuggest_tools
- First observedvalidate_code_quality
- First observedvalidate_plan_quality

Deploy Server

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A3.7/5.0

Scored 2026-04-18 07:00 across 7 tools

Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap. analyze_intent detects intent, enhance_prompt improves prompts, get_quality_standards retrieves standards, get_verification_checklist provides checklists, suggest_tools recommends tools, validate_code_quality validates code, and validate_plan_quality validates plans. The boundaries are well-defined and unambiguous.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with clear, descriptive names. The naming convention is uniform throughout: analyze_intent, enhance_prompt, get_quality_standards, get_verification_checklist, suggest_tools, validate_code_quality, and validate_plan_quality. There are no deviations or mixed styles.

Tool Count5/5

With 7 tools, the count is well-scoped for the server's purpose of prompt analysis, enhancement, and quality validation. Each tool earns its place by covering distinct aspects of the workflow, from intent analysis to code and plan validation, without being excessive or insufficient.

Completeness5/5

The tool surface provides complete coverage for the domain of developer prompt and code quality management. It includes analysis, enhancement, standards retrieval, verification, tool suggestion, and validation for both code and plans, ensuring no dead ends and supporting a full lifecycle from prompt to implementation.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Reddit Discussion

Related Servers

Related MCP Connectors

TokenmaxxingOAuth
io.github.Brock-Denton
Coordinate coding agents through MCP using existing AI plans, saved work, and independent checks.
Agent Orchestration Coding Agents Autonomous Agents
1
noteit-mcpOAuth
io.github.bahfahh
MCP server for AI agent profiles and smart notes. 60+ coding prompt packs with expert personas.
Note Taking Developer Tools Coding Agents
25
GodPrompt MCP Server A
io.github.AKzar1el
GodPrompt MCP + Agent Skill for coding agents with TDD, debugging, verification, and task routing.
Coding Agents Testing & QA Tools Developer Tools
711
OpenZeppelin Solidity Contracts A
com.openzeppelin.mcp
The OpenZeppelin Solidity Contracts MCP server integrates OpenZeppelin's security and style rules into AI-driven development workflows, enabling AI assistants to generate safe, correct, and production-ready smart contracts. It automatically validates generated code against OpenZeppelin standards (including imports, modifiers, naming conventions, and security checks) and supports various contract types including ERC-20, ERC-721, ERC-1155, Stablecoins, RWA, Governor, and Account contracts through prompt-driven workflows.
Developer Tools Blockchain Code Analysis
82

Related MCP Servers

Orchestrator MCP
RAG Systems Code Execution Agent Orchestration
Phoenixrr2113
F
license
A
quality
D
maintenance
An intelligent MCP server that orchestrates multiple MCP servers with AI-enhanced workflow automation and production-ready context engine capabilities for codebase analysis.
Updated a year ago (2025-11-09 10:00 UTC)
3
7
-
CloudZIR MCP Server
Developer Tools Autonomous Agents
SourireConcept
F
license
Not graded
quality
Not graded
maintenance
An enterprise-grade MCP server providing integrated system prompts and context management for consistent AI behavior across development and infrastructure tasks. It enables users to access specialized prompts for code quality standards and security-first deployment guidance.
Updated 9 months ago (2026-01-14 02:59 UTC)
-
Refine Prompt
Developer Tools Autonomous Agents
FelippeFarias
A
license
A
quality
D
maintenance
An MCP server that uses Claude 3.5 Sonnet to transform ordinary prompts into structured, professionally engineered instructions for any LLM. It enhances AI interactions by adding context, requirements, and structural clarity to raw user inputs.
Updated 2 years ago (2025-04-03 00:31 UTC)
1
3
MIT
prompt-plus-plus-mcp
AI & Machine Learning Developer Tools
bacoco
A
license
A
quality
D
maintenance
An advanced MCP server that intelligently enhances prompts using 44+ metaprompt strategies, with LLM-driven strategy selection and enterprise-grade features.
Updated a year ago (2025-06-13 07:11 UTC)
8
49 npm
9
MIT

Appeared in Searches

Powerful MCP servers with licensing, quality standards, and maintenance support

Mirdan

Brief-Driven Plan Pipeline (New in 2.1.0)

Worked example

MCP tool reference

What /plan-verify actually catches (evidence-based)

Reference implementation

Retired in 2.1.0

Local Intelligence Layer (New in 2.0)

Quick Setup

Why Mirdan?

What It Catches

What It Adds to Your Prompts

Quick Start

Install

Set Up Your IDE

Use From the Command Line

How It Works

Validation Rules

AI Quality (AI001–AI008)

Security (SEC001–SEC014)

Language-Specific

Language and Framework Support

Quality Profiles

IDE Integration

Claude Code

Cursor

Claude Desktop / Any MCP Client

Enterprise Deployment

CI/CD Integration

GitHub Actions

SARIF Export for GitHub Code Scanning

Pre-commit Hook

Quality Badges

Configuration

Advanced Features

AST-Based Validation

Full-File Diff Validation

Adaptive File-Path Thresholds

Convention Discovery

Dependency Vulnerability Scanning

Semantic Validation

Quality Forecasting

Session Tracking and Feedback Loop

Multi-Agent Coordination

Cross-Project Intelligence

Upgrading

MCP Tools Reference

enhance_prompt

validate_code_quality

validate_quick

get_quality_standards

get_quality_trends

scan_dependencies

scan_conventions

CLI Reference

Troubleshooting

Server Not Connecting

Debug Logging

Common Issues

Development

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches

What `/plan-verify` actually catches (evidence-based)