site-kit
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@site-kit Make me a website about the chess lessons I teach. Then review it and explain what is wrong."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 | shWhat 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 --versionWhat 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
.pkgfrom nodejs.org is the same software with none of that.
Back in Terminal (a new window again, after installing):
node --versionWhat 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-kitWhat 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 listWhat 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
codexThen 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 doctorIt 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⌘ Qto 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 neededWhat 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_responsivemeasures 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 chromiumThe twelve tools
Tool | What it is for |
| The route from never having made a website to understanding one. Ten stops, generated from the rulebook. Start here. |
| Scaffold a complete working site. No framework, no build step; double-clicking |
| Read the real colours off a photograph of the subject, with a WCAG contrast matrix. |
| Derive a palette when there is no photograph yet. |
| The whole rulebook, as an annotated critique. The one worth knowing about. |
| The full teaching note behind any finding: the threshold, the reasoning, the sources, the confidence. |
| Just the words, so you can edit the writing without the page in front of you. |
| Loads real pages in a real browser and reports actual pixel numbers. |
| Invented testimonials, ratings, counts, and quotations carrying names nobody checked. |
| Every file the site points at, and whether it exists. |
| Values written down in more than one place. A price in two files is two prices. |
| 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 missingThere 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 toolscheck_assetsCheck that every file the site points at existsARead-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 wordsARead-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 contentARead-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 scrollARead-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 placeARead-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 fixARead-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 ruleARead-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 oneARead-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 photographARead-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 yetARead-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 rulebookARead-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
Scored across 12 tools
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.
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.
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.
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
Related MCP Connectors
Review frontend code and live pages against 386 quality-gated web development rules.
Build, version, review, and export websites, web apps, and games from a conversation.
Serves your design system and coding standards to coding agents, so they stop guessing.
Scan a web page for accessibility, security, privacy, quality and SEO issues, with fixes.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI coding agents to plan, build, and review websites and product interfaces with a persistent, user-led process, including design direction, component contracts, and implementation review.-
- AlicenseCqualityCmaintenanceEnables 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.40MIT
- AlicenseBqualityCmaintenanceEnables 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.6MIT
- AlicenseNot gradedqualityBmaintenanceEnables Codex to inspect, edit, validate, and run image and video canvas boards, including generation, asset saving, timeline editing, export, and version comparison through local stdio tools.MIT