clenzer

MCP server that hunts dead code and complexity — then cleanses it.
Add it to any CLI agent and your codebase stays lean on every session.

---

What it does

clenzer is a Model Context Protocol (MCP) server that plugs into any MCP-compatible CLI agent (Claude Code, Antigravity, Cursor, etc.) and gives it five new tools:

Tool	Description
register_rules	Writes hygiene rules into AGENTS.md / CLAUDE.md so the agent re-enforces them every session
scan_dead_code	Finds unused imports, unused variables, and exported functions with no cross-file references
scan_complexity	Flags long functions, deep nesting, large files, and duplicate code blocks
cleanse	Safely auto-removes dead imports and side-effect-free variables; flags riskier items for manual review
report	Token-efficient summary of all findings with prioritised action items

Design principles

• Token-efficient — compact output, no JSON blobs, grouped by file
• Safe — cleanse never removes code with potential side effects; it skips functions and anything with call expressions in initialisers
• Non-destructive — dry-run mode available; skipped items are always explained
• Zero config — works on any TS/JS project with or without tsconfig.json

---

Installation

Via npx (no install needed)

npx clenzer

Global install

npm install -g clenzer

Local project install

npm install --save-dev clenzer

---

Adding to your CLI agent

Claude Code / Antigravity CLI

Add to your mcp_config.json (usually ~/.gemini/antigravity/mcp_config.json or ~/.claude/mcp_config.json):

{
  "mcpServers": {
    "clenzer": {
      "command": "npx",
      "args": ["-y", "clenzer"],
      "env": {}
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "clenzer": {
      "command": "clenzer",
      "args": [],
      "env": {}
    }
  }
}

Cursor / other MCP hosts

Add the same block to your MCP host's server config. Refer to your host's documentation for the exact file location.

---

Usage

Once clenzer is connected to your agent, use natural language or call the tools directly.

Recommended workflow

1. register_rules   — run once per project to lock in hygiene rules
2. scan_dead_code   — before any significant editing session
3. scan_complexity  — identify hotspots
4. report           — get a prioritised action list
5. cleanse          — auto-remove safe dead code

Tool reference

register_rules

project_root: string   # absolute path to project root

Appends clenzer's hygiene rules to AGENTS.md (or CLAUDE.md if it exists). The agent will re-read this file every session, ensuring the rules are always active.

scan_dead_code

project_root: string       # required
include?: string[]         # glob patterns, default: all TS/JS files
exclude?: string[]         # glob patterns, default: node_modules, dist, tests

Reports unused imports, unused variables, and exported functions with no cross-file references. Results are stored in session state for use by cleanse.

scan_complexity

project_root: string       # required
include?: string[]
exclude?: string[]

Thresholds (all configurable via future config file):

• Function length > 60 lines → long-function
• Nesting depth > 4 → deep-nesting
• File size > 600 lines → large-file
• Duplicate block ≥ 6 lines → duplicate-block

cleanse

project_root: string    # required
dry_run?: boolean       # default: false

Auto-removes items safe to delete (unused imports, variables with no side effects). Skips functions, exports, and anything with call expressions in the initialiser — those are flagged for manual review.

report

project_root: string    # required
top_n?: number          # default: 5 — how many issues to surface per category

Returns a compact markdown summary with dead code counts by kind, high-severity complexity hotspots, and recommended next steps.

---

Hygiene rules enforced

When you run register_rules, the following are appended to your AGENTS.md:

1. No unused imports — every import must be referenced in the file body
2. No unused variables — variables must be read, not just declared
3. Max function length: 60 lines — extract helpers if exceeded
4. Max nesting depth: 4 — flatten with early returns
5. Max file size: 600 lines — split large files into modules
6. No duplicate code blocks — extract shared logic into utilities
7. Prefix intentionally unused variables with _ — clenzer skips them

---

Development

git clone https://github.com/Parth3930/clenzer.git
cd clenzer
npm install
npm run build     # compile TypeScript → dist/
npm run dev       # run with tsx (no compile step)

Project structure

src/
├── index.ts      # MCP server, all 5 tools
├── scanner.ts    # AST-based dead code + complexity analysis (ts-morph)
├── cleanser.ts   # Safe removal engine
├── rules.ts      # AGENTS.md / CLAUDE.md rule injection
└── types.ts      # Shared interfaces

---

Tech stack

• @modelcontextprotocol/sdk — MCP server transport and tool registration
• ts-morph — TypeScript AST analysis and safe code modification
• zod — Runtime schema validation for tool inputs

---

Keywords

mcp, mcp-server, dead-code, unused-imports, code-cleanup, refactor, typescript, javascript, code-quality, static-analysis, ast, ts-morph, claude-code, cursor, antigravity, model-context-protocol, linter, cleaner, unused-variables, complexity

---

License

ISC © Parth3930