# codesmell

> codesmell detects code smells in source code with deterministic heuristics — no API key, no LLM, no upload.

codesmell is a code smell detector for AI agents and humans: a browser playground, a REST endpoint, and a remote MCP server, all running the same pure TypeScript engine. 13 rules, 11 languages, deterministic output, zero runtime dependencies.

## Use it when

- An agent needs a fast, repeatable smell scan of a file before rewriting it.
- A reviewer wants the boring checks automated: long functions, deep nesting, duplicated blocks, magic numbers, silent catches.
- A CI job needs a stable exit signal — the same input always yields the same findings.

## The 13 rules

Severity and default thresholds. All thresholds are tunable per request, and a `profile` of `strict`, `default` or `lenient` sets a coherent set of budgets at once (explicit thresholds win over it). Every rule also ships with a `remedy` (the refactoring that fixes it) in the MCP `rules` tool output.

- `god-file` (error, 400 lines / 20 functions): too large or too many functions — split it by domain.
- `empty-catch` (error): a catch/except block swallows the error silently.
- `long-function` (warning, 50 lines): extract cohesive blocks into named helpers.
- `long-parameter-list` (warning, 4 params): prefer an options object.
- `deep-nesting` (warning, 4 levels): use early returns and guard clauses.
- `duplicated-code` (warning, 4-line block): extract the shared logic.
- `nested-ternary` (warning): a ternary nested inside another ternary.
- `high-complexity` (warning, 20 decision points): too many branches in one function — split it.
- `long-line` (info, 120 chars): hurts readability in reviews and diffs.
- `magic-number` (info): an unexplained numeric literal — name it as a constant.
- `console-statement` (info): a debug print left in the code.
- `todo-comment` (info): TODO/FIXME/HACK/XXX — track it in an issue instead.
- `commented-out-code` (info): dead weight — version control remembers.

## Try it live

- [Playground](https://codesmell.net/#playground) — paste code, analyze in the browser. Two modes: the local engine (offline, instant) or the live MCP server (the code is sent to `/api/mcp` as a real `tools/call detect`).
- [Examples gallery](https://codesmell.net/#examples) — 15 snippets across 11 languages, each tied to the rules it demonstrates, with the findings computed live.

## MCP server

Endpoint: `https://codesmell.net/api/mcp` — Streamable HTTP, stateless, no auth, no API key.

Tools:

- `detect` — input `{ code, filename?, language?, thresholds? }` → `{ summary, language, smells[], stats, score, grade }`. The `summary` line is a human-readable routing hint.
- `rules` — no input → the rule catalog and the default thresholds.
- `examples` — optional `{ language?, id?, includeCode? }` → the sample catalogue: canonical snippets in 11 languages, each with the findings it must produce. Use it to show what a rule looks like, or to self-check a client.

Client config:

```json
{
  "mcpServers": {
    "codesmell": {
      "url": "https://codesmell.net/api/mcp"
    }
  }
}
```

## REST API

`POST https://codesmell.net/api/analyze` with `{ code, filename?, language?, thresholds? }` → `{ language, smells[], stats, score, grade }`.

`GET https://codesmell.net/api/health` → uptime JSON (never rate-limited).

60 requests/minute per IP on analyze and MCP; `x-ratelimit-limit` and `x-ratelimit-remaining` on every response.

Both endpoints send permissive CORS headers, so a browser can call them from any origin.

## Scoring

`score = clamp(round(100 − penalty × 100 / max(codeLines, 100)), 0, 100)` with penalty weights 6 (error), 3 (warning), 1 (info). Grades: A+ ≥ 97, A ≥ 90, B ≥ 80, C ≥ 65, D ≥ 50, else F.

## Links

- [Full specification](https://codesmell.net/llms-full.txt): complete rule catalog, request/response shapes, scoring, limits, examples.
- [Rule catalog](https://codesmell.net/#rules): the same catalog on the site.
- [FAQ](https://codesmell.net/#faq): plain-language answers to the common questions.
- [Playground](https://codesmell.net/#playground): paste code, analyze in the browser.
- [MCP setup](https://codesmell.net/#mcp): client configs and example calls.