Skip to content

Quickstart

Two minutes to your first analysis — whether you're working through an AI assistant or the CLI.

Command naming cheat sheet

  • Package for install/uvx: mcp-zen-of-languages
  • Preferred CLI command: mcp-zen-of-languages-cli
  • Preferred server command: mcp-zen-of-languages-server
  • Compatibility aliases: mcp-zen-of-languages, zen, zen-mcp-server
  • MCP config server key: zen-of-languages

MCP path (editor + AI agent)

The fastest way to use Zen of Languages is through an MCP-compatible client like VS Code with Copilot, Codex, Claude Desktop, or Cursor. Once the server is configured (see Installation), ask your agent to analyze code directly.

Example conversation

You: Run zen analysis on src/auth/login.py

Agent: (calls analyze_zen_violations) Found 3 violations:

  • Severity 8 — Cyclomatic complexity of 14 exceeds threshold of 10 in authenticate()
  • Severity 6 — Function authenticate() is 85 lines (max 50)
  • Severity 5 — Nesting depth of 4 exceeds threshold of 3

You: Fix the highest-severity violation

Agent: (calls generate_prompts, then applies changes) Extracted the credential-validation logic into a _validate_credentials() helper, reducing authenticate() complexity from 14 to 7.

No CLI needed — the agent handles analysis and remediation in a single editor session.

MCP quick-start steps

  1. Add the server to your client config (see Installation or MCP Integration).
  2. Open a project and ask your agent: "Run zen analysis on this file."
  3. Review violations and ask: "Generate remediation for the top finding."
  4. Re-run analysis to confirm the score improves.

CLI path — first code anamnesis

The CLI is the ideal tool for first code anamnesis: an initial diagnostic sweep that reveals the overall health of a codebase before you dive into individual files. Run a single command and get a severity-ranked map of every architectural smell, idiomatic violation, and remediation opportunity across all supported languages.

1. Initialize configuration

mcp-zen-of-languages-cli init

mcp-zen-of-languages-cli init (alias: zen init) creates zen-config.yaml, bootstraps .zen-of-languages.ignore, and can also generate MCP client config files when you opt into them interactively or pass --mcp-target.

If you opt into MCP setup during mcp-zen-of-languages-cli init, or run mcp-zen-of-languages-cli init --mcp-target vscode, the command writes .vscode/mcp.json for the zen-of-languages server automatically.

Codex does not use a workspace .json MCP file. Run mcp-zen-of-languages-cli init --mcp-target codex to append the server entry to ~/.codex/config.toml, or add it manually:

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

mcp-zen-of-languages-cli init also supports GitHub Copilot-compatible JSON configs:

  • mcp-zen-of-languages-cli init --mcp-target copilot-local writes .github/mcp.json
  • mcp-zen-of-languages-cli init --mcp-target copilot-global writes ~/.copilot/mcp-config.json

This creates a zen-config.yaml in your project root. It enables all languages and sets default thresholds — you can tune these later.

Repository scans honor both .gitignore and .zen-of-languages.ignore.

2. Run a report

mcp-zen-of-languages-cli reports path/to/project --out report.md  # (1)!
1. Scans all supported files, groups violations by language and severity, and outputs a human-readable report.

mcp-zen-of-languages-cli reports path/to/project --export-json out/report.json
Structured output for CI artifacts, dashboards, or downstream automation.

The report tells you what's wrong, how severe it is (1–10), and which zen principle was violated.

3. Generate remediation prompts

mcp-zen-of-languages-cli prompts path/to/project --mode both \
  --export-prompts out/prompts.md \
  --export-agent out/prompts.json

This produces two outputs:

  • Markdown prompts — Human-readable remediation guidance you can paste into any AI chat
  • JSON agent tasks — Structured instructions for MCP-connected AI agents to fix violations automatically
CI integration

Export JSON in CI and attach it as a build artifact. Developers can feed the prompts to Copilot or GPT to resolve violations in context.

Path strategy

Point commands at the repository root so import analysis and dependency detection can see the full project.

What you'll see

A typical report surfaces violations like:

  • Severity 8: Cyclomatic complexity exceeding threshold (Python)
  • Severity 7: Bare unwrap() calls without error context (Rust)
  • Severity 6: Missing error return checks (Go)
  • Severity 5: Implicit any types (TypeScript)

Each violation links to a specific zen principle — not a generic lint rule, but a language-community standard for what "good code" means.

Next steps

  • MCP Integration — Full setup guide for VS Code, Codex, Claude Desktop, Cursor, and more
  • Configuration — Tune thresholds for your codebase
  • Languages — See every principle and detector by language