Skip to main content
Glama
mcp-zen-of-languages

mcp-zen-of-languages


An MCP server for AI assistants that brings multi-language idiomatic code analysis into your editor. Zen of Languages codifies best practices ("zen principles") into machine-readable rules across programming languages, CI automation, and configuration formats — so AI agents and developers get actionable, language-aware feedback in every review. Connect it to Codex, Claude Desktop, VS Code, Cursor, or any MCP-compatible client and start analyzing code in seconds.

  • 350 zen principles across programming, markup, workflow, and config domains

  • 369 detector/check coverage points with severity scoring

  • MCP server for IDE and agent workflows (13 tools, 3 resources, 1 prompt)

  • CLI reports with remediation prompts and JSON / Markdown export

  • Rule-driven pipelines configurable per language and project

Why MCP for Zen Analysis

MCP turns zen analysis from a standalone report into an interactive engineering loop. Instead of copying output between tools, your editor/agent can call zen tools directly, inspect violations in context, generate remediation prompts, and apply fixes in one flow.

  • Less context switching: analyze, explain, and remediate without leaving your coding session.

  • Higher-fidelity fixes: prompts are generated from structured violations, not ad-hoc lint text.

  • Team consistency: MCP workflows make review behavior repeatable across IDEs and agents.

Related MCP server: CodeBase Optimizer

Zen Philosophy

Zen of Languages treats idioms as engineering constraints, not style preferences. Every language guide encodes the practices that make code maintainable in that ecosystem, then scores violations by risk so teams can fix what matters first.

  • Language-native quality over one-size-fits-all linting.

  • Architectural feedback beyond formatting checks.

  • Actionable prioritization through severity-guided remediation.

The project is guided by the 10 Dogmas of Zen — a set of language-agnostic principles that drive every detector and architectural decision. Read the full philosophy document for anti-patterns, rationale, and detector mappings.

Quickstart

# MCP server (IDE/agent workflows)
uvx --from mcp-zen-of-languages mcp-zen-of-languages-server

# CLI without installing (recommended)
uvx --from mcp-zen-of-languages mcp-zen-of-languages-cli --help

# Or install globally
pip install mcp-zen-of-languages

# Analyze a file (CLI)
mcp-zen-of-languages-cli report path/to/file.py

# Analyze a project with remediation prompts (CLI)
mcp-zen-of-languages-cli report path/to/project --include-prompts

Legacy aliases remain available after install: zen for the CLI and zen-mcp-server for the MCP server.

Ignore files during analysis

Directory scans in both CLI and MCP repository analysis honor:

  • .gitignore

  • .zen-of-languages.ignore

zen init now bootstraps a starter .zen-of-languages.ignore file when one is missing.

Naming Guide

Keep these names distinct to avoid setup confusion:

  • Package name: mcp-zen-of-languages (for pip install and uvx --from)

  • Preferred CLI command: mcp-zen-of-languages-cli

  • Preferred server command: mcp-zen-of-languages-server

  • Compatibility aliases: mcp-zen-of-languages, zen, and zen-mcp-server

  • MCP client server key: zen-of-languages (JSON config label in VS Code/Claude/Cursor; use the same label as a quoted TOML table name in Codex)

Installation

MCP Integration

Add the server to your MCP client configuration. For the full setup guide, see MCP Integration.

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "zen-of-languages": {
      "command": "uvx",
      "args": ["--from", "mcp-zen-of-languages", "mcp-zen-of-languages-server"]
    }
  }
}

VS Code — add to .vscode/mcp.json:

{
  "servers": {
    "zen-of-languages": {
      "command": "uvx",
      "args": ["--from", "mcp-zen-of-languages", "mcp-zen-of-languages-server"]
    }
  }
}

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "zen-of-languages": {
      "command": "uvx",
      "args": ["--from", "mcp-zen-of-languages", "mcp-zen-of-languages-server"]
    }
  }
}

Codex — add to ~/.codex/config.toml:

[mcp_servers."zen-of-languages"]
command = "uvx"
args = ["--from", "mcp-zen-of-languages", "mcp-zen-of-languages-server"]
enabled = true

Codex loads MCP servers from the global ~/.codex/config.toml file rather than a repo-local workspace config.

One-Click (VS Code)

Method

VS Code

VS Code Insiders

UVX (native)

Install

Install

Docker (isolated)

Install

Install

Docker

# MCP server via Docker
docker run --rm -i ghcr.io/anselmoo/mcp-zen-of-languages:latest

# CLI via Docker
docker run --rm ghcr.io/anselmoo/mcp-zen-of-languages:latest mcp-zen-of-languages-cli --help

CLI — First Code Anamnesis

The CLI is a powerful tool for first code anamnesis — an initial diagnostic sweep of any codebase. Before wiring up MCP or choosing which files to focus on, run a single command to get a full-project health picture with severity-ranked violations, architectural smells, and remediation guidance.

# Install globally
pip install mcp-zen-of-languages

# Full-project diagnostic in one command
mcp-zen-of-languages-cli report path/to/project --include-prompts

# Export structured results for CI or dashboards
mcp-zen-of-languages-cli report path/to/project --export-json report.json --export-markdown report.md

From source:

git clone https://github.com/Anselmoo/mcp-zen-of-languages.git
cd mcp-zen-of-languages
uv sync --group dev --all-extras

# Start the MCP server
mcp-zen-of-languages-server

# Run a CLI report
mcp-zen-of-languages-cli report path/to/file.py

MCP Tools

The server exposes 13 tools, 3 resources, and 1 prompt for AI-assisted code analysis.

Family

Tools

Purpose

Analysis

analyze_zen_violations, analyze_repository, check_architectural_patterns

Idiomatic and structural analysis

Reporting

generate_prompts, generate_agent_tasks, generate_report

Remediation guidance, task lists, gap reports

Configuration

get_config, set_config_override, clear_config_overrides

Read and tune thresholds at runtime

Metadata

detect_languages, get_supported_languages, export_rule_detector_mapping

Discover languages, rules, detector coverage

Onboarding

onboard_project

Initialize zen-config.yaml for a project

See the full MCP Tools Reference for parameters, return types, and workflow diagrams.

Use Cases

  1. AI Code Review — Call analyze_zen_violations on a file, then generate_prompts for remediation instructions in a single editor round-trip.

  2. Project-Wide Gap Analysis — analyze_repository scans a codebase, generate_report produces a Markdown/JSON report, and generate_agent_tasks creates a prioritised fix list.

  3. One-Click Onboarding — onboard_project detects languages and writes a tuned zen-config.yaml, making analysis immediately project-aware.

Supported Languages

Tier

Languages

Notes

Stable

Python

Full parser + richest detector coverage

Beta

Pydantic, FastAPI, Django, SQLAlchemy, TypeScript, React, Angular, Next.js, Go, Rust, JavaScript, Vue

Rule-driven pipelines and framework-aware heuristics

Experimental

Bash, PowerShell, Ruby, C++, C#

Heuristic detectors

Data/Config

YAML, TOML, JSON/JSON5, XML, GitHub Actions

Structure, schema, and workflow checks

Configuration

Analysis pipelines are derived from language zen rules and merged with project overrides in zen-config.yaml. See the Configuration Guide for the full reference.

# Generate reports in multiple formats
zen report path/to/project --export-json report.json --export-markdown report.md

Documentation

Full documentation is available at anselmoo.github.io/mcp-zen-of-languages.

Contributing

See Adding a Language and Development Guide to get started.

License

MIT


Available Tools

16 tools
analyze_batchAnalyze repository (batch / LLM-safe)A
Read-onlyIdempotent

Analyse a repository path and return token-budgeted, paginated violations designed for LLM context windows. Highest-severity violations appear first. Pass the returned cursor to resume from the next page.

Inputs: path (required), language (required), cursor, max_files, +3 more. Returns: Paginated result returned by a single ``analyze_batch`` call. Each invocation o…

analyze_batch_autoAnalyze repository (auto-routing)A
Read-onlyIdempotent

Smart entry point for LLM agents: automatically decides between returning all violations at once (small repos) or paginating (large repos). Pass the returned cursor back to continue pagination if has_more is true. Prefer this over manually choosing between analyze_repository and analyze_batch.

Inputs: path (required), language (required), cursor, max_files, +3 more. Returns: Paginated result returned by a single ``analyze_batch`` call. Each invocation o…

analyze_batch_summaryAnalyze repository — batch summaryA
Read-onlyIdempotent

Return a compact project health score and top-5 hotspot files from a repository scan. Always fits within a single LLM context window. Use this before analyze_batch to decide whether full pagination is needed.

Inputs: path (required), language (required), max_files, enable_external_tools, +1 more. Returns: One-shot health overview for the ``analyze_batch_summary`` tool. Unlike the pag…

analyze_repositoryAnalyze repositoryB
Read-onlyIdempotent

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

Inputs: repo_path (required), languages, max_files, enable_external_tools, +1 more. Returns: result

analyze_zen_violationsAnalyze zen violations (v2)C
Read-onlyIdempotent

Analyze a code snippet against zen rules with stricter request-quality guardrails and richer telemetry metadata.

Inputs: code (required), language (required), project_as, perspective, +3 more. Returns: Primary output produced by every language analyser. A call to ``BaseAnalyzer.an…

check_architectural_patternsCheck architectural patternsA
Read-onlyIdempotent

Return detected architectural patterns for a code snippet.

Inputs: code (required), language (required). Returns: Bundled response from the architectural-pattern detection pass. The ``analyze_z…

clear_config_overridesClear configuration overridesA
Destructive

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

Inputs: no named parameters. Returns: Read-only snapshot of the server's current configuration state. Returned by ``g…

detect_languagesDetect languagesB
Read-onlyIdempotent

Return supported language list for analysis.

Inputs: repo_path (required). Returns: Enumeration of every language the server can currently analyse. The ``list_zen_…

export_rule_detector_mappingExport rule detector mappingA
Read-onlyIdempotent

Generate rule-detector mapping JSON from the live registry.

Inputs: languages. Returns: object

generate_agent_tasksGenerate agent tasksA
Read-onlyIdempotent

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

Inputs: repo_path (required), languages, min_severity, enable_external_tools, +1 more. Returns: Top-level container for all agent tasks generated from an analysis batch. This…

generate_promptsGenerate remediation prompts (v2)B
Read-onlyIdempotent

Generate remediation prompts with MCP-first guidance metadata and v2 versioned prompt semantics.

Inputs: code (required), language (required), project_as, perspective, +2 more. Returns: Bundle of all remediation prompts produced for a single reporting run. Combines…

generate_reportGenerate reportA
Read-onlyIdempotent

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

Inputs: target_path (required), language, project_as, perspective, +3 more. Returns: Final output of the reporting pipeline. Carries both a human-readable Markdown…

get_configGet current configurationA
Read-onlyIdempotent

Return the current server configuration including any runtime overrides.

Inputs: no named parameters. Returns: Read-only snapshot of the server's current configuration state. Returned by ``g…

get_supported_languagesGet supported languagesA
Read-onlyIdempotent

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

Inputs: no named parameters. Returns: object

onboard_projectOnboard a new projectA
Read-onlyIdempotent

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

Inputs: project_path (required), team_size, strictness, primary_language. Returns: Complete onboarding payload returned by ``onboard_project``. Bundles an ordered…

set_config_overrideSet configuration overrideA
Destructive

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

Inputs: language (required), max_line_length, max_class_length, max_nesting_depth, +3 more. Returns: Read-only snapshot of the server's current configuration state. Returned by ``g…

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 16 tools

    Disambiguation2/5

    The repository analysis tools form a confusing cluster: analyze_repository, analyze_batch, analyze_batch_summary, and analyze_batch_auto all analyze a repository but differ in output format, pagination, and token budget. Additionally, detect_languages and get_supported_languages both return language lists with only subtle differences. This overlap creates real ambiguity for an agent despite the descriptive text.

    Naming Consistency5/5

    All tool names consistently use a verb_noun structure with snake_case, such as analyze_repository, set_config_override, and onboard_project. The pattern is predictable and easy to navigate.

    Tool Count4/5

    At 16 tools, the server is slightly over the ideal 3-15 range, but the tools cover distinct aspects of the analysis workflow: snippet analysis, repository analysis, batch processing, reporting, configuration, and onboarding. The count feels justified rather than bloated.

    Completeness4/5

    The tool set covers the core workflow of language detection, code and repository analysis, paginated scanning, summarization, remediation prompt generation, agent task creation, and configuration management. Minor gaps exist, such as no explicit rule-listing tool, but the export_rule_detector_mapping and get_supported_languages partially compensate.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables comprehensive code analysis including quality assessment, security vulnerability detection, refactoring suggestions, complexity calculations, and automatic documentation generation for multiple programming languages.
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides comprehensive codebase analysis including project structure evaluation, cross-language duplicate detection, microservices validation, and configuration optimization with AI-powered pattern learning that generates actionable improvement reports.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables local code inspection and analysis for clean code practices, best practices, and actionable recommendations without external API calls or modifying the code.
      51 npm
      1
      MIT