MCP Tools Reference¶

MCP tools illustration

Auto-generated from server.py. Do not edit manually.

Regenerate with: uv run python scripts/generate_mcp_tools_docs.py

The MCP server exposes tools, resources, and prompts that AI agents and IDE integrations can invoke via the Model Context Protocol.

Surface Summary¶

Capability	Count
Tools	13
Resources	3
Prompts	1

Quick Reference¶

Tool	Family	Description	Access
`analyze_zen_violations`	Analysis	Analyze a code snippet against zen rules and return analysis results.	Read-only
`analyze_repository`	Analysis	Analyze a repository path and return per-file analysis results.	Read-only
`check_architectural_patterns`	Analysis	Return detected architectural patterns for a code snippet.	Read-only
`generate_prompts`	Reporting	Generate remediation prompts from zen analysis results.	Read-only
`generate_agent_tasks`	Reporting	Convert zen violations into structured agent task lists for automated remediation.	Read-only
`generate_report`	Reporting	Generate a markdown/json report with gap analysis and prompts.	Read-only
`get_config`	Configuration	Return the current server configuration including any runtime overrides.	Read-only
`set_config_override`	Configuration	Override configuration values for a specific language at runtime. Overrides persist for the session.	Mutating
`clear_config_overrides`	Configuration	Clear all runtime configuration overrides, reverting to zen-config.yaml defaults.	Mutating
`detect_languages`	Metadata	Return supported language list for analysis.	Read-only
`export_rule_detector_mapping`	Metadata	Generate rule-detector mapping JSON from the live registry.	Read-only
`get_supported_languages`	Metadata	Return list of all languages with zen rules and their detector coverage.	Read-only
`onboard_project`	Onboarding	Get interactive onboarding guidance for setting up zen analysis on a project. Returns recommended configuration based on project characteristics.	Read-only

Analysis Tools¶

`analyze_zen_violations`¶

Read-only analysis snippet zen

Analyze a code snippet against zen rules and return analysis results.

Run the full zen analysis pipeline on a single code snippet.

Parameters:

Parameter	Description
`code`	Raw source code to analyse — typically the full contents of a single file read by the MCP client.
`language`	Target language identifier such as `"python"` or `"tsx"`. Aliases like `"ts"` and `"rs"` are accepted.
`severity_threshold`	Floor severity that downstream consumers (reports, task generators) should honour. Falls back to `CONFIG.severity_threshold` when omitted.
`perspective`	Public result view to apply: `all`, `zen`, `dogma`, `testing`, or `projection`. `dogma` keeps universal dogma analysis and filters to dogma-relevant violations.
`project_as`	Projection-family target used when `perspective` is `projection`.

Returns: AnalysisResult carrying metrics, a scored violation list, and the computed overall_score (0–100 scale, higher is better).

testing requires a real file path to resolve the test-family overlay, so snippet requests should generally use all, zen, or projection.

`analyze_repository`¶

Read-only analysis repository

Analyze a repository path and return per-file analysis results.

Analyse every eligible file in a repository and return per-file results.

Parameters:

Parameter	Description
`repo_path`	Absolute path to the repository root. The MCP client typically resolves this from the active workspace.
`languages`	Restrict analysis to specific language identifiers. Defaults to `["python"]` internally.
`max_files`	Per-language cap on the number of files to analyse, protecting against excessive runtime on monorepos.
`ctx`	Optional FastMCP context for progress and log updates during repository analysis.

Returns: List of RepositoryAnalysis entries, each pairing a file path and language with its AnalysisResult.

`check_architectural_patterns`¶

Read-only analysis patterns

Return detected architectural patterns for a code snippet.

Scan a code snippet for recognised architectural patterns.

Parameters:

Parameter	Description
`code`	Source fragment to inspect for structural patterns.
`language`	Language identifier guiding which pattern recognisers to apply (e.g. `"python"`, `"go"`).

Reporting Tools¶

`generate_prompts`¶

Read-only prompts remediation

Generate remediation prompts from zen analysis results.

Analyse code and synthesise remediation prompts for each detected violation.

Parameters:

Parameter	Description
`code`	Source code whose violations will drive prompt generation — should match the snippet passed to analysis.
`language`	Language identifier used to select the correct analyzer and prompt templates (e.g. `"python"`).
`perspective`	Public result view to apply before prompts are generated: `all`, `zen`, `dogma`, `testing`, or `projection`. `dogma` keeps universal dogma analysis and filters to dogma-relevant violations.
`project_as`	Projection-family target used when `perspective` is `projection`.

Returns: PromptBundle holding file_prompts with per-violation remediation text and generic_prompts for broader guidance.

`generate_agent_tasks`¶

Read-only agent automation tasks

Convert zen violations into structured agent task lists for automated remediation.

Convert repository-level violations into prioritised remediation tasks.

Parameters:

Parameter	Description
`repo_path`	Absolute path to the repository to scan. All eligible source files are discovered recursively.
`languages`	Restrict scanning to these languages. Omit to analyse only Python files by default.
`min_severity`	Severity floor (1–10 scale). Violations below this threshold are excluded from the task list.

Returns: AgentTaskList containing prioritised tasks ready for automated remediation, sorted from highest to lowest severity.

`generate_report`¶

Read-only analysis reporting

Generate a markdown/json report with gap analysis and prompts.

Produce a structured markdown report combining analysis, gaps, and prompts.

Parameters:

Parameter	Description
`target_path`	Path to a single file or a directory. When a directory is given, all eligible files inside are analysed.
`language`	Explicit language override. When omitted, the language is inferred from file extensions.
`perspective`	Public report view to apply: `all`, `zen`, `dogma`, `testing`, or `projection`. `dogma` keeps universal dogma analysis and filters to dogma-relevant violations.
`project_as`	Projection-family target used when `perspective` is `projection`.
`include_prompts`	Append remediation prompt sections derived from `build_prompt_bundle`.
`include_analysis`	Include the violation-analysis body showing per-rule findings.
`include_gaps`	Include quality-gap and coverage-gap summaries highlighting areas that need attention.
`ctx`	Optional FastMCP context used to emit progress and log updates for analyzed targets.

Returns: ReportOutput with markdown (rendered report text) and data (structured dict) ready for MCP client consumption.

Configuration Tools¶

`get_config`¶

Read-only config metadata

Return the current server configuration including any runtime overrides.

Return a snapshot of the running server's configuration.

Returns: ConfigStatus describing active languages, severity threshold, resolved config file path, and a per-language map of overrides.

`set_config_override`¶

Mutating config settings

Override configuration values for a specific language at runtime. Overrides persist for the session.

Apply session-scoped threshold overrides for a specific language.

Parameters:

Parameter	Description
`language`	Language whose thresholds should be adjusted (e.g. `"python"`).
`max_cyclomatic_complexity`	Override the per-function cyclomatic-complexity ceiling.
`max_nesting_depth`	Override the maximum allowed nesting depth for control-flow blocks.
`max_function_length`	Override the maximum lines permitted in a single function body.
`max_class_length`	Override the maximum lines permitted in a single class definition.
`max_line_length`	Override the maximum character width for a single source line.
`severity_threshold`	Override the minimum severity at which violations are surfaced in results.

Returns: ConfigStatus reflecting all overrides after this mutation, confirming the change took effect.

`clear_config_overrides`¶

Mutating config settings

Clear all runtime configuration overrides, reverting to zen-config.yaml defaults.

Remove every session-scoped override, reverting to zen-config.yaml defaults.

Returns: ConfigStatus after all override entries have been cleared.

Metadata Tools¶

`detect_languages`¶

Read-only languages metadata

Return supported language list for analysis.

Return the language identifiers listed in the active zen-config.yaml.

Parameters:

Parameter	Description
`repo_path`	Workspace root passed by the MCP client — reserved for future per-repo config resolution but currently unused.

Returns: LanguagesResult wrapping the list of language strings declared in zen-config.yaml (e.g. ["python", "typescript", "go"]).

`export_rule_detector_mapping`¶

Read-only mapping metadata

Generate rule-detector mapping JSON from the live registry.

Export the live rule-to-detector wiring from the detector registry.

Parameters:

Parameter	Description
`languages`	Restrict the export to these language identifiers. When omitted, mappings for every registered language are returned.

Returns: Nested dictionary keyed by language, then by rule ID, with detector metadata (class name, config schema) as values.

`get_supported_languages`¶

Read-only languages metadata

Return list of all languages with zen rules and their detector coverage.

List every language that has zen rules alongside its registered detector IDs.

Returns: Dictionary mapping each language identifier (e.g. "python") to the list of detector IDs wired up for that language.

Onboarding Tools¶

`onboard_project`¶

Read-only onboarding setup

Get interactive onboarding guidance for setting up zen analysis on a project. Returns recommended configuration based on project characteristics.

Generate a step-by-step onboarding guide tailored to a project's profile.

Parameters:

Parameter	Description
`project_path`	Absolute path to the project root, used to derive the project name and populate example commands.
`primary_language`	Language used for example snippets and default pipeline selection (e.g. `"python"`).
`team_size`	Descriptive team-size hint (`"small"`, `"medium"`, `"large"`), reserved for future adaptive threshold scaling.
`strictness`	Preset name controlling all numeric thresholds (`"relaxed"`, `"moderate"`, or `"strict"`).

Returns: OnboardingGuide with ordered steps, each carrying an action key and example, plus a recommended_config dict ready to write into zen-config.yaml.

Resources¶

MCP resources are read-only data endpoints that clients can subscribe to.

URI	Name	Description
`zen://config`	zen_config_resource	Read-only resource exposing current configuration and active overrides.
`zen://languages`	zen_languages_resource	Read-only resource listing language principle and detector coverage counts.
`zen://rules/{language}`	zen_rules_resource	Read-only resource exposing canonical zen principles for a language.

`zen://config`¶

Read-only resource exposing current configuration and active overrides.

Return current configuration status as a read-only MCP resource.

`zen://languages`¶

Read-only resource listing language principle and detector coverage counts.

Return supported languages with principle and detector counts.

`zen://rules/{language}`¶

Read-only resource exposing canonical zen principles for a language.

Return canonical zen principles for the requested language key.

Prompts¶

MCP prompts are pre-built templates that clients can render for user interaction.

`zen_remediation_prompt`¶

Generate a remediation prompt scaffold for violations in a language.

Build a typed remediation prompt template for MCP clients.

:material-workflow: MCP Use-Case Workflows¶

Tools reference illustration

AI Code Review in Editor¶

The most common use case: an AI agent inside VS Code, Cursor, or Claude Desktop invokes zen tools to review code as you write.

sequenceDiagram
    participant Dev as Developer
    participant IDE as VS Code / Cursor
    participant MCP as Zen MCP Server
    Dev->>IDE: "Review this file for zen violations"
    IDE->>MCP: analyze_zen_violations(code, language)
    MCP-->>IDE: AnalysisResult (violations, metrics, score)
    IDE->>Dev: Shows violations with severity and fix guidance
    Dev->>IDE: "Fix the highest-severity issue"
    IDE->>MCP: generate_prompts(code, language)
    MCP-->>IDE: PromptBundle (file + generic prompts)
    IDE->>Dev: Applies remediation

Automated Remediation Pipeline¶

For CI/CD or batch workflows, the agent tasks tool produces machine-readable work items that automation agents can process:

sequenceDiagram
    participant CI as CI Pipeline
    participant MCP as Zen MCP Server
    participant Agent as Remediation Agent
    CI->>MCP: analyze_repository(repo_path, languages)
    MCP-->>CI: list[RepositoryAnalysis]
    CI->>MCP: generate_agent_tasks(repo_path, min_severity=7)
    MCP-->>CI: AgentTaskList (prioritized tasks)
    CI->>Agent: Execute tasks sequentially
    Agent-->>CI: Applied fixes

Project Onboarding¶

New projects can use the onboarding tool to bootstrap configuration:

sequenceDiagram
    participant Dev as Developer
    participant MCP as Zen MCP Server
    Dev->>MCP: onboard_project(path, language, strictness)
    MCP-->>Dev: OnboardingGuide (steps + recommended_config)
    Dev->>MCP: set_config_override(language, thresholds…)
    MCP-->>Dev: ConfigStatus (confirmed)
    Dev->>MCP: analyze_repository(path)
    MCP-->>Dev: Baseline results

Multi-language Repository Analysis¶

Analyze polyglot projects by detecting configured languages, then scanning:

sequenceDiagram
    participant Agent as AI Agent
    participant MCP as Zen MCP Server
    Agent->>MCP: detect_languages(repo_path)
    MCP-->>Agent: LanguagesResult
    Agent->>MCP: analyze_repository(repo_path, languages)
    MCP-->>Agent: Per-file results
    Agent->>MCP: generate_report(repo_path, include_gaps=true)
    MCP-->>Agent: ReportOutput (markdown + data)

Runtime Configuration Tuning¶

Adjust thresholds mid-session without restarting the server:

sequenceDiagram
    participant Agent as AI Agent
    participant MCP as Zen MCP Server
    Agent->>MCP: get_config()
    MCP-->>Agent: ConfigStatus (current settings)
    Agent->>MCP: set_config_override("python", max_complexity=8)
    MCP-->>Agent: ConfigStatus (override applied)
    Agent->>MCP: analyze_zen_violations(code, "python")
    MCP-->>Agent: Results with stricter thresholds
    Agent->>MCP: clear_config_overrides()
    MCP-->>Agent: ConfigStatus (reset to defaults)

MCP Tools Reference¶

Surface Summary¶

Quick Reference¶

Analysis Tools¶

analyze_zen_violations¶

analyze_repository¶

check_architectural_patterns¶

Reporting Tools¶

generate_prompts¶

generate_agent_tasks¶

generate_report¶

Configuration Tools¶

get_config¶

set_config_override¶

clear_config_overrides¶

Metadata Tools¶

detect_languages¶

export_rule_detector_mapping¶

get_supported_languages¶

Onboarding Tools¶

onboard_project¶

Resources¶

zen://config¶

zen://languages¶

zen://rules/{language}¶

Prompts¶

zen_remediation_prompt¶

:material-workflow: MCP Use-Case Workflows¶

AI Code Review in Editor¶

Automated Remediation Pipeline¶

Project Onboarding¶

Multi-language Repository Analysis¶

Runtime Configuration Tuning¶

`analyze_zen_violations`¶

`analyze_repository`¶

`check_architectural_patterns`¶

`generate_prompts`¶

`generate_agent_tasks`¶

`generate_report`¶

`get_config`¶

`set_config_override`¶

`clear_config_overrides`¶

`detect_languages`¶

`export_rule_detector_mapping`¶

`get_supported_languages`¶

`onboard_project`¶

`zen://config`¶

`zen://languages`¶

`zen://rules/{language}`¶

`zen_remediation_prompt`¶