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