mcp-zen-of-languages 0.4.0

Multi-language architectural and idiomatic code analysis via CLI and MCP server.

Zen of Languages

🖌️ Write code the way the language intended.

---

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 Claude Desktop, VS Code, Cursor, or any MCP-compatible client and start analyzing code in seconds.

• 224 zen principles across programming, markup, workflow, and config domains
• 236 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.

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 zen-mcp-server

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

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

# Analyze a file (CLI)
zen report path/to/file.py

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

Naming Guide

Keep these names distinct to avoid setup confusion:

• Package name: mcp-zen-of-languages (for pip install and uvx --from)
• CLI command: zen
• MCP server command: zen-mcp-server
• MCP client server key: zen-of-languages (JSON config label in VS Code/Claude/Cursor)

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", "zen-mcp-server"]
    }
  }
}

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

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

Cursor — add to .cursor/mcp.json:

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

One-Click (VS Code)

Method	VS Code	VS Code Insiders
UVX (native)
Docker (isolated)

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 zen --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
zen report path/to/project --include-prompts

# Export structured results for CI or dashboards
zen 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 --all-groups --all-extras

# Start the MCP server
zen-mcp-server

# Run a CLI report
zen 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	TypeScript, Go, Rust, JavaScript	Rule-driven pipelines, partial parsing
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

---