Skip to content

MCP Zen of Languages

Write code the way the language intended.

Run MCP-native workflows for code review, remediation, and onboarding across multi-language codebases.

Quickstart MCP Integration CLI Reference

Zen-inspired abstract hero artwork

MCP Zen of Languages

Every programming language has a philosophy — a sense of what "good code" looks like. Python has PEP 20. Rust has ownership semantics. Go has proverbs. TypeScript has the type system. MCP Zen of Languages encodes these philosophies into automated analysis across programming languages, workflow automation, and config formats — exposed as both a CLI and an MCP server.

  • Start fast

    Install, initialize, and run your first analysis in under two minutes.

    Quickstart

  • Use the CLI

    Run zen for local checks, exports, and CI automation with JSON/Markdown outputs.

    CLI Reference

  • Integrate via MCP

    Connect to VS Code, Codex, Copilot, and other MCP-compatible clients for AI-assisted analysis.

    MCP Integration

  • Explore language coverage

    From Python's PEP 20 to Rust's ownership idioms — each language has its own zen.

    Languages

  • Solution workflow

    Analyze code, generate remediation prompts, and turn findings into actionable fixes.

    Project Analysis

Why zen?

Most linters focus on formatting. Zen analysis goes deeper — it detects architectural and idiomatic issues: god classes, circular dependencies, callback hell, unsafe blocks, monkey-patching. The goal isn't nitpicking commas; it's surfacing the structural problems that slow teams down.

New: GitLab CI workflow analysis

GitLab CI (.gitlab-ci.yml and gitlab-ci/**/*.yml) is now supported with dedicated zen rules for security, maintainability, and idiomatic pipeline practices.

Why MCP

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.

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.

The 10 Dogmas of Zen — code quality principles visualised as zen garden stones

Quickstart

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

# Run without installing (recommended)
uvx --from mcp-zen-of-languages mcp-zen-of-languages-cli init
uvx --from mcp-zen-of-languages mcp-zen-of-languages-cli reports path/to/project

# Or install globally
pip install mcp-zen-of-languages
mcp-zen-of-languages-cli init
mcp-zen-of-languages-cli reports path/to/project

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

What You Get

  • 348 zen principles across programming, markup, workflow, and config domains
  • 367 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

Maturity Tiers

  • Full Analysis

    AST parsing, cyclomatic complexity, dependency graphs, maintainability index. The deepest analysis available.

    Python

  • Rule-Driven

    Dedicated detectors with regex-based pattern matching. Each rule has its own detector class with configurable thresholds.

    TypeScript · Rust · Go · JavaScript · CSS · Bash · PowerShell · Ruby · SQL · C++ · C# · Docker Compose · Dockerfile

  • Documentation & Markup

    Markup-focused detectors for docs and technical writing quality, structure, and maintainability.

    Markdown / MDX · LaTeX

  • Workflow Automation

    CI/CD-specific security and maintainability checks for pipeline files and reusable workflow patterns.

    GitHub Actions

  • Config Validation

    Schema and structure-focused detectors for data formats. Checks consistency, naming conventions, and format-specific best practices.

    JSON · TOML · XML · YAML

MCP Tools at a Glance

MCP tools workflow illustration

The MCP server exposes 15 tools (including versioned v1/v2 variants) across five families, plus 3 resources and 1 prompt.

  • Analysis (4 tools)

    analyze_zen_violations (v1, v2) · analyze_repository · check_architectural_patterns

  • Reporting (4 tools)

    generate_prompts (v1, v2) · generate_agent_tasks · generate_report

  • Configuration (3 tools)

    get_config · set_config_override · clear_config_overrides

  • Metadata (3 tools)

    detect_languages · get_supported_languages · export_rule_detector_mapping

  • Onboarding (1 tool)

    onboard_project — initialise zen-config.yaml for any repository

Full MCP Tools Reference

Choose Your Path

Next Steps