Skip to main content
Glama

codex-site-kit

An MCP server for Codex. It builds small websites with no framework and no build step, and it criticises them the way a coach annotates a game.

Every finding carries four things and never fewer: what was found, with the measurement · why it is worse than the alternative · who says so, by name, with a confidence tag · and the better move. Nothing comes back as a bare pass or fail, because a pass/fail teaches you nothing and this tool is trying to teach you something.

Findings are annotated in chess notation, which is not decoration — severity needs a vocabulary, and if you read one already this is the one:

Means

??

A blunder. Somebody with no design vocabulary at all spots it in five seconds, on a phone.

?

A mistake. Felt rather than named, and decisive.

?!

An inaccuracy. A habit worth dropping; rarely fatal on its own.

!?

The trap tier. Reads as sophisticated today and will not next year. Reported as a question, not a verdict.

!

A good move. Something the page already does right, and why.


Installing it on a Mac

Three commands. You do not need Homebrew, you do not need to know what a terminal is, and nothing below asks you to fix anything.

Open Terminal first. Press ⌘ Space, type Terminal, press Return. A window appears with some text and a blinking cursor. Everything below is typed into that window, one line at a time, pressing Return after each.

1. Install Codex

curl -fsSL https://chatgpt.com/codex/install.sh | sh

What you should see: a few lines of progress, then a line telling you Codex has been installed and, usually, where. It finishes in under a minute.

Then close the Terminal window and open a new one. The installer puts codex somewhere your current window does not know about yet; a new window picks it up. Check it took:

codex --version

What you should see: a version number, such as codex-cli 0.5.0. If you instead see command not found: codex, close Terminal completely (⌘ Q) and open it again.

2. Install Node

Codex does not need Node. This kit does — it is written in JavaScript and Node is what runs it.

Go to https://nodejs.org and click the button offering the LTS version. It downloads a file ending in .pkg. Double-click it and click Continue until it says Install. That is the whole installation.

Not Homebrew. You will find instructions telling you to install Homebrew first and then use it to install Node. Do not. Homebrew is a package manager that has to be installed and maintained itself, and it is a second thing to go wrong before you have made your first web page. The .pkg from nodejs.org is the same software with none of that.

Back in Terminal (a new window again, after installing):

node --version

What you should see: a version number starting with v20, v22 or higher — anything at v18.17 or above works.

3. Add this kit to Codex

codex mcp add site-kit -- npx -y github:Javendean/codex-site-kit

What you should see: a short confirmation that the server site-kit was added. Nothing downloads yet; that happens the first time Codex starts it.

Check it is registered:

codex mcp list

What you should see: a list with site-kit in it, and next to it the command npx -y github:Javendean/codex-site-kit.

4. Use it

codex

Then type, in ordinary English:

Make me a website about the chess lessons I teach. Then review it and explain what is wrong.

The first run takes about half a minute while npx fetches the package. After that it is instant. There is no build step, nothing to compile, and no configuration file to edit.


Related MCP server: motionvault

If something goes wrong

One command diagnoses everything:

npx -y github:Javendean/codex-site-kit doctor

It checks your Node version, whether the package loads, whether every tool registers, and whether the optional browser for check_responsive is present — and for anything that fails it prints the exact command that fixes it. It never prints a stack trace.

The two failures worth knowing in advance:

  • command not found: codex — you have not opened a new Terminal window since installing. Press ⌘ Q to quit Terminal completely, then open it again.

  • Codex says the server failed to start — almost always Node missing or too old. Run node --version. If it prints nothing, go back to step 2.

Where the config lives, if you ever want to look

codex mcp add writes to ~/.codex/config.toml. The entry it makes looks like this, and you can also write it by hand:

[mcp_servers.site-kit]
command = "npx"
args = ["-y", "github:Javendean/codex-site-kit"]

[mcp_servers.site-kit.env]
# nothing needed

What it will not do

Stated plainly, because a tool that hides its limits is worse than one that has fewer of them.

  • No telemetry, ever. Nothing about you, your machine or your sites leaves the computer.

  • No network calls. Not one tool fetches anything. The rulebook is a set of files in this package, and it is read off disk.

  • No secrets, no accounts, no API keys. There is nothing to configure.

  • It does not render your page. Most rules read the source text, which is enough for most of them and not enough for a few. Sideways scroll on a phone, a button label wrapping to two lines, the real contrast of a colour after the cascade resolves: those need a browser, and check_responsive measures them. When it cannot, it reports skipped and the command that installs the browser. A skipped check is never reported as a pass.

  • It cannot tell you whether a page looks dated. Technical age is parseable and is covered. Aesthetic age needs a screenshot and a vision model. No amount of text parsing substitutes, and the tool says so rather than letting a clean report imply otherwise.

The only optional extra is a browser for check_responsive, and only when you want it:

npx playwright install chromium

The twelve tools

Tool

What it is for

learning_path

The route from never having made a website to understanding one. Ten stops, generated from the rulebook. Start here.

init_site

Scaffold a complete working site. No framework, no build step; double-clicking index.html opens a finished page.

palette_from_image

Read the real colours off a photograph of the subject, with a WCAG contrast matrix.

palette_from_subject

Derive a palette when there is no photograph yet.

review_site

The whole rulebook, as an annotated critique. The one worth knowing about.

explain_rule

The full teaching note behind any finding: the threshold, the reasoning, the sources, the confidence.

check_copy

Just the words, so you can edit the writing without the page in front of you.

check_responsive

Loads real pages in a real browser and reports actual pixel numbers.

check_honesty

Invented testimonials, ratings, counts, and quotations carrying names nobody checked.

check_assets

Every file the site points at, and whether it exists.

check_single_source

Values written down in more than one place. A price in two files is two prices.

doctor

What is wrong with this machine, and the command that fixes it.


Why the rules are what they are

Every rule in this kit names its source, and the kit refuses to load a rule that does not — provenance is a startup error here, not a habit. RULES.md is the index; run explain_rule on any id for the full note.

Each source carries the confidence tag the research gave it:

Tag

Meaning

DEMONSTRATED

The source ships runnable code, a live comparator, production library CSS, or a counted sample. Verifiable without trusting anyone.

MEASURED

Produced by inspecting real files, reproducibly.

ASSERTED

Expert opinion, blog prose, or forum anecdote. May be right; is not evidence.

This distinction is load-bearing. Where the research says ASSERTED, the tool reports the finding as a question about your page rather than as a gate it failed, and says so in the output. A hypothesis laundered into a hard gate is exactly the failure the kit exists to avoid. Where a source has a caveat — a self-reported false-positive rate, a commercial interest, an unverifiable revenue claim — the caveat is printed with the citation.

Named sources include the practitioners the research ranked: Emil Kowalski on motion (and the shipped Sonner and Vaul CSS where you can check he follows his own numbers), Josh W. Comeau on transitions, shadows and reduced motion, Gesso Build's deterministic anti-slop detectors, Adrian Krebs's empirical scoring of 1,590 landing pages, Nutlope's Hallmark catalogue, Rauno Freiberg's 90/10 novelty rule, CodeStitch's audited local-business practice, the GOV.UK type scale, and WCAG 2.2 AA. It also credits the Impeccable design plugin (v4.3.1) where a rule overlaps with its craft floor, and deliberately does not restate what that plugin's editor hook already enforces while you type.

One thing the rulebook refuses to let onto a page: the claim that "94% of first impressions are design-related — Stanford". It is a documented misattribution, it is the first statistic anyone reaches for, and there is a rule that catches it. The real figures are Lindgaard et al. 2006 on 50-millisecond first impressions, or the Stanford Web Credibility Project's actual 46.1%.


Learning it

LEARNING-PATH.md — ten stops, from "I have never made a website" to "I understand why that gradient was wrong."

It is generated from the rulebook, not written alongside it. Every stop names the rule ids that carry its reasoning, and npm run docs:check fails if a stop names a rule that no longer exists. A course maintained separately from the linter drifts away from it within a month, and then it teaches rules the tool does not run — which teaches you to distrust the tool.

The order is deliberately not the rulebook's order. review_site sorts by how fast a visitor notices a fault, which is right for a critique and wrong for learning. The path sorts by what you need first: make it work, then make it not look broken, then make it not look generic, then make it honest, then understand why the escape routes keep closing.

Ask Codex for it in words — "walk me through the learning path" — or one stop at a time.


Working on the kit itself

git clone https://github.com/Javendean/codex-site-kit
cd codex-site-kit
npm install

npm test              # the full suite
npm run handshake     # speak MCP to the server over stdio and print what it says
npm run docs          # regenerate LEARNING-PATH.md and RULES.md from the rulebook
npm run docs:check    # fail if they are stale
npm run doctor        # what this machine is missing

There is deliberately no build step and no prepack script, and a test enforces it: adding one would make npx -y github:... do work at install time, which is the difference between an install that works on a beginner's machine and one that does not.

Licence

MIT.

Available Tools

12 tools
check_assetsCheck that every file the site points at existsA
Read-onlyIdempotent

Follows every image, stylesheet, script, icon and internal link in the site and confirms the file is really there. Reports file:line for anything that is not.

Catches the case-sensitivity trap specifically: a file that resolves on a Mac because macOS ignores capitalisation, and 404s the moment the site is published to a Linux host. That one cannot be found by looking at the site in a browser on the machine that built it.

Also audits the stylesheet theme contract, because var(--token) is a reference too. A custom property defined only inside @media (prefers-color-scheme: dark) has no value in the state most visitors are in.

Inputs: directory (required), ignore, check_links, check_theme. Returns: fix, why, tool, theme, +9 more

check_copyCheck the wordsA
Read-onlyIdempotent

Run the copy and honesty rules over a folder, or over a block of text pasted straight in.

Benefit-speak, the "not just X, it's Y" cadence, em dashes in short interface copy, fabricated precision, invented proof, unverified attributions, and claims that cannot be true or false.

Pass either directory or text. Everything it finds carries the same four answers as a full review: what, why, who says so, and the better move.

Inputs: text, ignore, directory. Returns: fix, why, tool, counts, +9 more

check_honestyCheck the site for invented contentA
Read-onlyIdempotent

Scans a site for content that claims something nobody earned: testimonials, star ratings, "as seen in", customer counts, lorem ipsum, placeholder brand names and contact details, and quotations that carry an attribution.

The attribution check is the one a generic linter misses. A name set on its own line under a quotation is an attribution even with no "said" and no dash, and a misattributed quote is a false statement about a real person. Report it, find a source, and record the source in .honesty.json to silence it. An entry with no source silences nothing.

Reports file:line for everything. status is "fail" only when there are errors; warnings are things to verify, not things that are definitely wrong.

Inputs: directory (required), ignore, ledger, strict, +1 more. Returns: fix, why, tool, counts, +8 more

check_responsiveMeasure every page for sideways scrollA
Read-only

Loads each page in a real headless Chromium at a set of widths and asserts that document.documentElement.scrollWidth does not exceed window.innerWidth. Reports the actual numbers at every width, pass or fail, and names the specific elements whose edge crosses the line.

Requires Playwright, which is NOT installed with this kit. If it is missing this tool returns status "skipped" with the one command that installs it. It never reports a pass it did not measure.

Inputs: directory (required), pages, height, ignore, +2 more. Returns: fix, why, tool, status, +13 more

check_single_sourceFind values that are written down in more than one placeA
Read-onlyIdempotent

Scans for values that look like a fact a visitor can act on — prices, email addresses, phone numbers, times, product codes — and reports every one that appears in more than one file.

A second copy of a value is a second value. It has not disagreed yet. The storefront this kit was built from advertised one price and charged another, because the number was typed into three files and only one of them was updated.

Pass source_of_truth to enforce the strict form: the value may appear in that one file, and anywhere else is a copy.

Preset patterns: price, email, phone, sku, time, percentage, dimension. Anything else is treated as a regular expression.

Inputs: directory (required), ignore, patterns, min_files, +2 more. Returns: fix, why, tool, status, +10 more

doctorCheck this machine and print exactly what to fixA
Read-onlyIdempotent

Checks Node, the optional headless browser, and whether Codex has this server registered.

For anything missing it prints the literal command to paste. Nothing here is a suggestion to "check your configuration": every failure comes with the line that fixes it.

Run this first whenever something does not work.

Inputs: no named parameters. Returns: fix, why, tool, ready, +6 more

explain_ruleRead the full teaching note for one ruleA
Read-onlyIdempotent

Given a rule id from a review — the part in square brackets — return the whole note: the exact trigger condition and where that number came from, why it matters, what it is teaching, the better move with its code, every source with its own caveat, and what the rule measured across the corpus the rulebook was built from.

Call it with no id to list the rulebook. Pass a tier, a category, or a search term to narrow it.

Inputs: rule, tier, search. Returns: fix, why, rule, tool, +6 more

init_siteScaffold a site that passes the rulebookB

Write index.html, styles.css and NOTES.md into a folder.

The page is built to come back clean from review_site: three theme states, neutrals that carry a trace of the anchor hue, press feedback with a hover guard, 48px touch targets, 16px inputs, minmax(0, 1fr) grid tracks, overflow-x: clip, no animation above the fold, no eyebrow, no emoji icons, no side stripes, no backdrop blur.

The structure is chosen from a local ledger of what was scaffolded last, so two consecutive sites differ in their SECTIONS, not only in their colours. That is the axis the research ranks highest and recolouring the axis it ranks lowest.

Every unwritten field is a visible, labelled hole rather than filler. Nothing is invented: no testimonials, no ratings, no counts, no press.

Inputs: subject (required), directory (required), hue, name, +2 more. Returns: fix, why, next, tool, +12 more

learning_pathThe route from never having made a website to understanding oneA
Read-only

Ten stops, in the order a beginner needs them — which is NOT the order the critique uses. review_site sorts by how fast a visitor notices a fault. That is right for a critique and wrong for learning. This sorts by what you need first: make it work, then make it not look broken, then make it not look generic, then make it honest, then understand why the escape routes keep closing.

Every stop is built from the rulebook itself and names the rule ids that carry its reasoning, so it cannot drift away from what the tool actually checks. Pass a stop number to read one at a time.

Inputs: stop, depth. Returns: fix, why, tool, stops, +6 more

palette_from_imageDerive a palette from a photographA
Read-onlyIdempotent

Quantises an image with median cut or k-means and returns a small, considered palette: the colours the subject is actually made of, with how much of the image each one covers.

Returns a full WCAG 2.1 contrast matrix alongside the colours, computed from relative luminance, so an unreadable pair cannot be chosen by accident. Also returns a ready-made token set for both theme states, which can be passed straight to init_site.

Reads PNG and JPEG (.png, .jpg, .jpeg). Everything is done locally; nothing is uploaded.

Inputs: image (required), count, algorithm, merge_similar, +1 more. Returns: fix, why, tool, image, +14 more

palette_from_subjectDerive a palette from a subject, when there is no photograph yetA
Read-onlyIdempotent

Builds a complete two-state palette from one anchor hue, in OKLCH, and emits hex.

It cannot return one of the ten banned Tailwind indigos or the emerald that replaced them, cannot return pure black or pure white, holds every neutral at 0.005-0.015 chroma of the anchor hue so the greys belong to the same page as the accent, never shifts the hue between light and dark, and returns a WCAG contrast matrix for every pair a page actually puts together — so an unreadable pair cannot be chosen by accident.

It also tells you where the hue came from. If the subject names something real, it names the object. If it does not, it says the hue came from a hash of the words — which is not the same thing, and palette_from_image on a photograph is the stronger move.

Inputs: subject (required), hue, accent_chroma. Returns: css, fix, why, dark, +14 more

review_siteReview a site against the whole rulebookA
Read-onlyIdempotent

Read every page and stylesheet in a folder and return an annotated critique.

Each finding carries: WHAT was found with the evidence, WHY it matters, what it is teaching, WHO says so with a confidence tag and that source's caveat, WHERE the line is drawn, and the better MOVE. Findings are ordered by how fast a visitor would notice them and annotated the way a chess game is: ?? clocked in five seconds, ? felt but not named, ?! a habit worth dropping.

Rules that could not run are listed as prominently as the ones that failed, with the reason each one could not run. They are never counted as passes.

Use explain_rule with any rule id from the output to read the full teaching note, every source, every caveat, and what that rule measured across the corpus it was built from.

Inputs: directory (required), skip, tier, focus, +3 more. Returns: fix, why, tool, clean, +14 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 12 tools

    Disambiguation4/5

    The tool families are well separated by target, and each checker addresses a distinct concern. The only real overlap is between check_copy and check_honesty, both of which claim some honesty/attribution territory, and review_site naturally overlaps with the individual checkers. The detailed descriptions make selection feasible, so this is not a serious weakness.

    Naming Consistency3/5

    There is a strong check_* family and a clear palette_from_* pair, but the set mixes verb-first names like review_site and explain_rule, noun phrases like learning_path and palette_from_subject, and a single bare verb in doctor. The names are all lowercase and readable, but the overall convention is mixed rather than uniform.

    Tool Count5/5

    12 tools is squarely in the well-scoped range for a site review and scaffolding kit. Each checker targets a separate concern, and the supporting tools for explanation, learning, scaffolding, palette generation, and diagnostics all earn their place.

    Completeness5/5

    The set covers the full workflow: scaffold a site, generate palettes, run a full critique, run targeted checks, explain findings, and diagnose the environment. There are no obvious dead ends or missing operations that would block an agent from completing a meaningful task.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      C
      maintenance
      Enables agents to discover cinematic website templates, generate executable scroll and WebGL code, create design systems, inspect HTML, validate assets and dependencies, and plan source-delivery and launch QA through 40 validated tools, resources, and prompts.
      40
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI agents to build and audit web UIs by serving a fixed workflow and rule-priority guide, running deterministic static linting of source, rendering pages headlessly at multiple widths for screenshots and accessibility snapshots, and gathering element-level design feedback. All output is written only to a local log folder, leaving project files untouched and external network access blocked by default.
      6
      MIT