dockerlint-mcp, The Hard Way

Build an MCP server that lets an AI lint Dockerfiles and compose files without Docker. Start from "what is a Dockerfile, grammatically?" and end with a tested stdio server. No hadolint, no daemon, no framework doing the hard part for you.

At the end you will have built a small version of dockerlint-mcp yourself, and you will understand the three things most lint tools get wrong: parsing (regexes over raw text lie), rule design (findings need a line number and a concrete fix, and must never leak secrets), and domain rules that look like something familiar but are not (.dockerignore is not .gitignore).

Why This Exists

Most "linter" tutorials are a list of regexes. That breaks the first time someone writes

RUN apt-get update \
    # pin the mirror
    && apt-get install -y curl

or RUN echo "apt-get update", or a heredoc. A linter an AI relies on has to be right about structure first, and quiet when the file is fine: every false positive teaches the model to ignore you.

Related MCP server: dockerfile-audit-mcp

Who This Is For

• Developers who built a hello-world MCP server and want a real one

• Anyone who writes Dockerfiles and wants to know why the usual advice is the usual advice

• Anyone curious how a Dockerfile is actually tokenized

Prerequisites: Python and a rough idea of what docker build does. No Docker installation is needed; nothing here ever runs a container.

pip install -r requirements.txt
python verify.py          # runs every module and checks it

Modules

The code lives in minilint/, one file per module, and grows as you go. Each module has a main.py that exercises that stage and checks its own claims with assert; verify.py runs them all.

Design rules that run through every module

1. Parse, then judge. Rules look at parsed commands, never at raw text.

2. Every finding has a line number and a concrete fix. "Consider improving caching" is not a finding.

3. Never echo a secret. Report the variable name; the value stays out of the model's context.

4. Stay quiet on good files. A false-positive corpus is part of the test suite.

5. Static means static. Nothing is built, run, pulled or written.

6. Fail loudly and usefully. Errors say what to do next.