Skip to content

About

No description, website, or topics provided.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

The art bin

The place to share your special snowflakes, pet peeves and other works of art. All so your LLM can learn what not to do and for you to have a good laugh.

this_is_true = False

if not this_is_true:
    print("You are such a special snowflake!")

What this is

A corpus of bad Python, Rust and TypeScript code, one smell per file, structured so a machine can find the ones your codebase resembles. An MCP server serves the corpus to an LLM reviewing real code, so instead of generic advice you get "line 42 is mutable-default-argument, here is why, here is what to write instead."

Linters already own the mechanically detectable defects — ruff and Semgrep will find bare excepts forever. What no linter ships is taste: the house style, the pet peeves, the patterns that run fine and that your team still refuses to accept. That knowledge normally lives in reviewers' heads and leaks out one PR comment at a time. This makes it addressable.

Layout

Path What it is
snippets/<language>/code/ The corpus, for python, rust and typescript (which covers plain JavaScript too). One smell per file, 15 lines or fewer.
snippets/<language>/architecture/ Smells that live between components, where 15 lines cannot show the problem. One entry per Gang of Four pattern, describing the code the pattern answers.
catalog.json Generated summary of every smell, small enough to read whole.
TAXONOMY.md The closed lists a smell is filed against.
TEMPLATE.md Skeleton for a new smell.
validate.py Schema and constraint checks. Runs in CI.
new_smell.py Scaffolds a smell file from the template, with the closed lists as menus.
install.sh Registers the server with an MCP client.
src/art_bin_server/ The MCP server.
tests/ Tests for the server, run against the real corpus.
CONTEXT.md The project glossary.
docs/ Design documents and architecture decision records.

Installing

Clone it and run the installer. There is nothing to build — the server launches with uv run, which resolves its own dependencies the first time a client starts it. You need uv and nothing else.

git clone https://github.com/ErnstRoell/the-art-bin
cd the-art-bin
./install.sh                            # Claude Code, user scope
./install.sh --client desktop           # Claude Desktop, this platform's config
./install.sh --config ~/.cursor/mcp.json  # anything else that speaks mcpServers

Install it as a tool, which puts art-bin-server on your PATH:

uv tool install .            # from a clone
uv tool install git+https://github.com/ErnstRoell/the-art-bin

The wheel bundles the corpus, so the installed server needs no checkout to read from:

{
  "mcpServers": {
    "the-art-bin": {
      "command": "art-bin-server"
    }
  }
}

An install is a snapshot of the corpus as of that build — uv tool upgrade art-bin-server to pick up new smells. To serve the corpus live from a clone instead, which is what you want while adding smells, register it against the checkout:

{
  "mcpServers": {
    "the-art-bin": {
      "command": "uv",
      "args": ["--directory", "/path/to/the-art-bin", "run", "art-bin-server"]
    }
  }
}

./install.sh --help lists the rest, and make install-mcp ARGS='...' is the same thing from the Makefile.

Using it

Ask your client to review some code. The server exposes three read-only tools and no analysis — nothing here accepts source code, scores anything, or decides what matches. The corpus goes to the model; the model does the judging (ADR 001).

Tool Returns
list_smells The whole catalog: id, signature, severity, category, topic, tags, keywords. Optional filters for severity, category, topic, language, python_version, rust_version and typescript_version.
get_smells Full records for specific ids: snippet, why it's bad, corrected version, distinguish, and sources (each claim linked to the passage that states it). Aliases resolve; unknown ids come back in unknown.
get_taxonomy The closed lists with corpus counts, for building valid filters.

Callers are expected to work in two phases — one list_smells to shortlist, one get_smells to confirm. The server's instructions field states that contract, and the full surface is specified in MCP API Overview.

The server finds the corpus in three steps, first match wins: ART_BIN_ROOT, then the first directory above its own location holding both catalog.json and snippets/, then the copy bundled into the wheel. A clone therefore beats the bundle, so a contributor always reads their own edits. Set ART_BIN_ROOT to override both — which is what a deployment that separates the server from the corpus would do.

Developing the server

uv sync
uv run pytest -q          # 41 tests, including 7 over a real stdio subprocess
uv run art-bin-server     # start on stdio

make help lists the targets, including make install-tool to put the binary on PATH and make build for the wheel. make catalog before either, if you have added smells — the wheel bundles the catalog as it stands at build time.

src/art_bin_server/corpus.py is the reading layer — catalog, record parsing, alias resolution, filters — and src/art_bin_server/server.py is the tool surface. Frontmatter parsing is deliberately duplicated between corpus.py and validate.py, so that contributors can validate a snippet without installing the server. The schema they agree on is Snippet Design.

Adding a smell

make new-smell                          # asks for the slug and the filing
make new-smell SLUG=my-new-smell        # asks only for the filing
# write it
make catalog                            # regenerate catalog.json
make check                              # what CI runs

The scaffolder fills in the frontmatter you would otherwise get wrong: it offers only the category and topic values TAXONOMY.md actually lists, refuses a slug that collides with an existing id or alias, and points out existing smells sharing a word with yours so near-duplicates surface before you write one. What it deliberately leaves at their template placeholders are signature, distinguish and keywords — the three fields that are the actual work. Answer architecture at the group prompt for a smell that needs 40 lines, and see uv run new_smell.py --help for the flags that skip the prompts entirely (make new-smell forwards them as ARGS='...').

Read CONTRIBUTING.md first — particularly the part about never pasting code from a real codebase, and the three fields that need actual thought.

Design

Licensing and disclaimer

The corpus under snippets/ is CC0 — public domain, no attribution required, ingest it however you like. The tooling is MIT.

Every snippet here is a minimal reconstruction written to illustrate a smell. Nothing in this repository is an excerpt of any real codebase, none of it is intended to be run, and all of it is provided without warranty of any kind. The opinions are opinions — severity: taste means exactly that.

About

No description, website, or topics provided.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages