mcp-zen-of-languages 0.2.0

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

Zen of Languages

🖌️ Write code the way the language intended.

---

Multi-language architectural and idiomatic code analysis, exposed as an MCP server and a CLI. Zen of Languages codifies idiomatic best practices ("zen principles") for 14 languages into machine-readable rules, then detects violations automatically — so AI agents and developers get actionable, language-aware feedback in every review.

• 151 zen principles across 14 languages
• 163 focused detectors 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

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

One-Click (VS Code)

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

Docker

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

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

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, XML	Structure and schema 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

---