engineering-audit MCP server
Commit Nov 14, 2026Turns AI coding assistants into engineering practice auditors through full repository sweeps or inline decision-time rule checks.
Also known as rodlunt/engineering-audit
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- Apache-2.0
What is engineering-audit MCP?
engineering-audit turns AI coding assistants into engineering practice auditors through full repository sweeps or inline decision-time rule checks.
Summary generated from the project's README
About engineering-audit MCP server
Engineering practice auditing is made possible by turning existing AI coding assistants into specialized auditors. This tool works with Claude Code, OpenAI Codex CLI, and Gemini CLI to perform either comprehensive repository sweeps or real-time rule checks during the development process. By integrating directly into your terminal-based workflow, it allows an assistant to evaluate your codebase against established engineering standards.
Users can choose between a full repository audit that generates a self-contained HTML report or inline decision-time checks that load specific rules exactly when needed, such as when designing a schema or shaping an API. The system includes three complete rule domains for data modelling, testing strategy, and presenting data, covering 54 rules with full source citations. For those starting new projects, the Engineering Grill integration provides a guided interview to establish necessary project checks before any code is written. Setup requires uv to run the server via uvx and a local clone of the rules directory.
What you can do with it
- 1Plan new projects with guided interviewsUse a guided conversation to determine which engineering domains and checks your new project will require.
- 2File findings as GitHub issuesAutomatically convert audit findings into actionable GitHub issues for your team to address.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
ENGINEERING_AUDIT_RULES_DIR
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablerodlunt/engineering-audit is public and reachablegithub.com/rodlunt/engineering-audit ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/rodlunt/engineering-audit ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubengineering-audit
TL;DR: engineering-audit turns the AI coding assistant you already use (Claude Code, Codex CLI, Gemini CLI) into an engineering-practice auditor. It has two audit modes:
- Full repository audit: your assistant sweeps a whole repository against a pack of sourced engineering rules and produces a self-contained HTML report. Every finding says what is wrong, why it matters and how to fix it, with the citation behind the claim attached, and can be filed as a GitHub issue or copied out for pasting anywhere.
- Inline decision-time checks: one-line triggers in your assistant's context make it load the relevant rules at the moment you are making a matching decision (designing a schema, cutting a branch, shaping an API). No report, just the right rules at the right moment.
Starting a new project? The optional Engineering Grill uses the same rules before you build. Your assistant interviews you, works out which domains matter, and records the decisions and checks the project will need, without expecting you to understand the framework first.
Three complete rule domains ship in this repository, ready to run: data modelling, testing strategy and presenting data, 54 rules with their full source citations, in examples/taster-rules/. You can run a real audit right now with no sign-up; the full sixteen-domain, 260-rule pack is available on request (Rules access).
Need a walk through? There is a free interactive walkthrough → that takes you from a bare Windows, Mac or Linux PC to a finished audit of your own repository. It rehearses every step below in a simulated terminal, with the wrong turns coached, before you do them for real. No terminal experience assumed.
Save me the chit chat: show me how to install it →
How to use
From nothing to a first audit in five steps. The taster rules ship in this repository, so none of this needs access to the full pack.
Never touched a terminal? Rehearse these five steps first in the free interactive walkthrough linked at the top: it takes a non-technical founder from a bare Windows, Mac or Linux PC to a finished audit, in a simulated terminal with the wrong turns coached.
Step 1: pick your assistant
The tool works through the assistant you already drive: Claude Code or OpenAI Codex CLI (both proven end to end; standalone audits recorded 2026-08-09 and 2026-08-10, with a further Codex run on Linux 2026-08-19), or Gemini CLI (documented, not yet exercised end to end; see the support matrix). GitHub Copilot is not supported.
Step 2: dependencies
| Dependency | Why you need it | Check it |
|---|---|---|
| uv | runs the MCP server via uvx straight from a pinned release tag, and installs its own Python (3.10+) if the machine lacks one |
uvx --version |
| git | clones this repository for the taster rules, and any other rules pack | git --version |
| your assistant's CLI | drives the audit and hosts the MCP registration | claude --version (or codex, gemini) |
GitHub CLI gh, optional |
only if the assistant should file findings as GitHub issues; filing from the report page instead needs only a PAT in your browser | gh auth status |
There is no pip install and no npm anywhere: uvx fetches and runs the tagged release
directly.
Step 3: get the rules onto disk
Clone this repository. The taster pack (the three complete domains named in the TL;DR) is
a working rules directory at examples/taster-rules/:
git clone https://github.com/rodlunt/engineering-audit
cd engineering-audit
Have the full pack instead? Registration below is identical, just point --rules-dir at
that clone's domains/ directory. See Rules access for how to ask.
Step 4: register the tool with your assistant
Every command below is pinned to the current release tag (@v0.15.0) rather than the
moving main branch: an unpinned git dependency resolves to whatever main holds at
install time and silently moves on later cache refreshes. Find the latest tag on the
Releases page. Updating to a newer
tag is a deliberate act with its own command, below, not something that happens on a
git pull: the pin lives in your assistant's MCP registration, not in this repository.
Paths beginning with /path/to/ are placeholders. Replace them with the real absolute path
on your computer; run pwd inside a folder when you need to see its absolute path.
Claude Code
Register the server (swap in the taster path from Step 3, or your full-pack path):
claude mcp add engineering-audit --scope user -- uvx --from git+https://github.com/rodlunt/engineering-audit@v0.15.0 \
engineering-audit-mcp --rules-dir /path/to/engineering-audit/examples/taster-rules
--scope user registers it for every repository. Without it claude mcp add defaults to
local scope, which registers the server for the current directory alone and leaves it
unavailable everywhere else. That failure is silent and lands later (issue #245): a skill
run in any other project reports list_domains unavailable with nothing pointing at scope
as the cause. If that happens, run claude mcp list in the project where it failed; if
engineering-audit is missing there but present in the directory you installed from, it
was registered without --scope user. Fix it with claude mcp remove engineering-audit
followed by the add command above.
To update to a newer tag, remove first and re-add. claude mcp add refuses to
overwrite an existing name (MCP server engineering-audit already exists in user config),
so changing the tag on its own is not enough:
claude mcp remove engineering-audit
claude mcp add engineering-audit --scope user -- uvx --from git+https://github.com/rodlunt/engineering-audit@v0.15.0 \
engineering-audit-mcp --rules-dir /path/to/engineering-audit/examples/taster-rules
The change only takes effect in a new session. The one you are in keeps the server it started with, so verify after restarting rather than before:
claude mcp list | grep engineering-audit # must show the tag you just set
begin_run's response states tool_version too. If it names the old version, the session
predates the re-registration and the run is not exercising the build you think it is.
Install the audit skill (gives you a natural-language entry point: "audit this repo"):
cd /path/to/engineering-audit
scripts/install-skills.sh audit
It copies rather than symlinks, so the installed skill does not change under you when this
checkout switches branch. scripts/install-skills.sh --check reports when a copy is stale.
Full details: integrations/claude-code/.
OpenAI Codex CLI
Register the server (verified against codex-cli 0.114.0):
codex mcp add engineering-audit \
--env ENGINEERING_AUDIT_RULES_DIR=/path/to/engineering-audit/examples/taster-rules \
-- uvx --from git+https://github.com/rodlunt/engineering-audit@v0.15.0 engineering-audit-mcp
Inline mode: generate the trigger fragment and append it to your repo's AGENTS.md (or
~/.codex/AGENTS.md for all repos):
uvx --from git+https://github.com/rodlunt/engineering-audit@v0.15.0 engineering-audit-fragments \
--rules-dir /path/to/engineering-audit/examples/taster-rules --out-dir .
cat AGENTS-fragment.md >> AGENTS.md
Standalone audit: in a codex session, ask it to read AUDIT.md from this repository and
run the audit. Headless notes and caveats: integrations/codex/.
Gemini CLI
There is no packaged extension. Gemini CLI resolves an extension only from a repository
root, which would put a manifest, a GEMINI.md and a commands/ directory in the root of a
tool that also serves Claude Code and Codex, and none of it was ever exercised against a real
Gemini CLI. Registering the server by hand is one paste and has no such cost.
Add the server to ~/.gemini/settings.json (or a project-level .gemini/settings.json),
swapping in the taster path from Step 3:
{
"mcpServers": {
"engineering-audit": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/rodlunt/engineering-audit@v0.15.0",
"engineering-audit-mcp"
],
"env": {
"ENGINEERING_AUDIT_RULES_DIR": "/path/to/engineering-audit/examples/taster-rules"
}
}
}
}
Then start gemini in the repository you want audited and paste:
Audit this repository against the engineering rules. Read AUDIT.md from the
engineering-audit repository and follow it, driving the engineering-audit MCP tools
through to a rendered report.
Inline triggers work too, and need no extension: generate the fragment and merge it into
whichever GEMINI.md tier you want it to apply to.
uvx --from git+https://github.com/rodlunt/engineering-audit@v0.15.0 engineering-audit-fragments \
--rules-dir /path/to/engineering-audit/examples/taster-rules --out-dir .
cat GEMINI-fragment.md >> GEMINI.md
Gemini support is documented, untested: Gemini CLI was not available to exercise any of
it. Check gemini --help before an unattended run. Details and caveats:
integrations/gemini/.
Optional: plan before you build
Install Engineering Grill after registering the MCP server if you want a guided, plain-English planning conversation before code is written. It reads the domains from the connected rules pack, so the taster pack gives a three-domain grill and the full rules pack gives the complete framework.
Headless / CI
Skip the interactive configuration page by pointing ENGINEERING_AUDIT_CONFIG at a saved
configuration JSON (shape documented in AUDIT.md); get_config then returns
immediately. Example driver, Claude Code:
claude -p "Read AUDIT.md at <path> and audit this repository via the engineering-audit \
MCP tools." --mcp-config mcp.json --allowedTools "mcp__engineering-audit__*,Read,Glob,Grep"
Every run also checks this repository's tags for a newer release, on by default (see
Security for what that discloses). On an air-gapped machine, or anywhere the
network cost or the call itself is unwanted, pass --no-update-check to engineering-audit-mcp
or set the ENGINEERING_AUDIT_NO_UPDATE_CHECK environment variable.
What keeps the staleness checks working
Two checks tell you whether what you are running is current: one for the tool, one for the rules
pack. Neither ever guesses. A check that could not run reports could-not-check, which is a
distinct state from current, so a stale build is never reported as fine. What that honesty does
not do is tell you when a check has gone blind, and both go blind on install shapes that look
perfectly ordinary.
| Check | Attached when | Blind when | What you lose |
|---|---|---|---|
| Tool build | installed from a git URL, which is what every command in Step 4 does | installed from a downloaded archive or a plain wheel, or run from a local or editable checkout | nothing warns you that a pin left on an old tag, or a stale uvx cache, is serving an old build |
| Rules pack | the rules directory is a git clone with an origin remote, which is what Step 3 produces |
the rules arrived as a downloaded zip, were vendored into another repository, have no remote, or have uncommitted changes | nothing warns you that the run is judging your repository against superseded rules |
Following Step 3 and Step 4 as written keeps both attached: git clone for the rules, and
uvx --from git+...@<tag> for the tool. Any other shape still runs and still audits correctly.
It just cannot tell you it is out of date.
The provenance rows in the report header carry the answer for the run in front of you. Both
reading could-not-check at once is the combination to watch for, because that is a build of
unknown age judging your repository against rules of unknown age, with nothing able to detect
either.
Step 5: run your first audit
Ask your assistant to audit the repository you have open ("audit this repo against the
engineering rules"), tick the domains on the configuration page that opens, wait for the
sweep, then open audit-output/report.html. What to expect while it runs is in
What a run looks like; what it costs in tokens is in
What a full run costs.
Engineering Grill, before the code exists (BETA)
Status: beta, and the label is meant literally. The interview shipped in v0.13.0 as a separate
interrogate skill and was folded into Engineering Grill by issue #239: one pre-build skill, not
two. Nobody has yet completed a full interactive session with it. Expect it to change.
An audit sweeps the rules over a repository that already exists. Engineering Grill runs them the other way, as questions about work that has not started. It classifies every domain the pack returns, derives the full question set from the rules of those whose triggers genuinely fire, then puts the highest-consequence questions first, one at a time, in the Hot Seat. The rest are held, not discarded: it names the total, offers a deep dive through everything remaining, and records what was answered, what was deferred and what was never asked.
Triage is global on purpose. One domain's third-best question routinely matters more than another's first, and a per-domain ranking cannot see that. Questions carry a reversibility grade and a blast radius so they can be compared across domains at all.
The rule that shapes the whole design is that no full domain document enters the conversation with the user. That is stated as an invariant rather than an architecture: sub-agents satisfy it where the host has them, serial read-and-discard satisfies it where the host does not, which is what keeps one skill shippable on more than one assistant.
Ten of the sixteen domains are design-time by their own Load this when: statements, so most of
the pack was already pointed at the moment before the code, with nothing to deliver it there.
It never starts a run. It calls list_domains and get_domain only, both of which work with no
run in progress, so it works on a directory that is not a repository yet or on nothing but a
description. Setup is in integrations/engineering-grill/, and
the optional hook that offers it when plan mode starts is in
integrations/claude-code/README.md.
What has been exercised: question derivation on three domains (d02, d01, d15) against one brief, the no-run guarantee, and the hook's failure paths.
What has never been run even once: the cross-domain triage. It is the newest part and the part everything else now depends on, so treat its output with more suspicion than the rest.
What has not: the other thirteen domains, and the interactive loop itself with a real person answering. Nobody has yet finished a full interrogation. Until they have, treat the shape of the session as unproven and the question quality as sampled rather than measured.
This is a beta of a Claude Code integration specifically. There is no Codex or Gemini equivalent,
and unlike audit there is no assistant-neutral protocol document behind it: the skill file is
the whole specification. That is deliberate for now and is the first thing to change if it earns
its place.
Scope
This documentation states functional behaviour (what the tool does) and the security and
privacy properties documented inline (how the access token is held, what telemetry you opt
into, what leaves your machine and when). The two human-facing surfaces, the configuration page
and the report page, target WCAG 2.2 Level AA. Applying the
same proven versus documented, untested distinction used below for the
assistant integrations: one criterion is proven, the rest are documented, untested. Contrast is
machine-checked on every test run, tests/test_report_stylesheet.py computes contrast ratios
from the CSS custom properties and asserts 4.5:1 in both the light and dark palettes. No
keyboard-only pass and no screen reader pass has been recorded against either surface, and
neither template currently sets an explicit minimum target size on its interactive controls, so
those criteria (and WCAG 2.2's target size, success criterion 2.5.8, specifically) have not been
checked by anyone. The target is real; only the contrast ratio has a recorded check behind it.
Performance is explicitly out of scope for now: no throughput or latency target is stated or
tested anywhere in this repository.
How it works
The tool is a local MCP server (Python, stdio). It points at a local directory of rule documents and serves them to the agent driving the audit. The agent supplies the judgement; the server supplies everything that must not depend on an LLM's memory: schema-validated finding capture (a rule the agent did not check can never be recorded as a pass), the configuration page, deterministic report rendering, source citations attached from the rules pack itself, and GitHub issue filing with an explicit confirmation step.
Two audit modes, plus an optional project-start skill:
- Engineering Grill: before code is written, the assistant sorts the loaded domains by
relevance, asks framework-backed questions and records the resulting plan. It uses only the
read-only
list_domainsandget_domaintools and does not start an audit run. - Standalone audit: tick the domains to audit on a local configuration page (or supply
a saved config for headless runs), the agent sweeps the repository, and you get
report.htmlplus optional GitHub issues. - Inline: one-line triggers merged into your assistant's instruction context tell it to
call
get_domain(...)at decision moments (designing a schema, cutting a branch, shaping an API), so the rules arrive exactly when they are useful.
Support matrix
| Assistant | Inline mode | Standalone audit |
|---|---|---|
| Claude Code | proven (in daily use via skills) | proven (recorded run 2026-08-09) |
| OpenAI Codex CLI | documented, untested | proven (recorded run 2026-08-10) |
| Gemini CLI | documented, untested | documented, untested |
| GitHub Copilot | unsupported | unsupported |
"Proven" means a recorded end-to-end run exists. "Documented, untested" means the integration follows the assistant's official documentation, with individually verified pieces labelled in the integration README, but no full audit has been exercised on it yet. Copilot is deliberately unsupported rather than silently absent.
What a run looks like
A standalone audit is a conversation plus one browser page. From your seat:
- Ask for the audit ("audit this repo against the engineering rules"). The assistant gathers run metadata and starts the run.
- A configuration page opens in your browser (
http://127.0.0.1:<port>/). Opening it is best-effort: in a remote or display-less session no tab can appear, so the assistant also prints the URL; open it yourself if nothing popped up. Tick the domains to audit, choose report-only or GitHub issue filing, and submit. Nothing proceeds until you submit: the tool never falls back to a domain selection you did not make. - The assistant sweeps the repository domain by domain. This is the slow part: minutes for a small repository and a few domains, longer for a big selection. You can ask for progress; it can report which domains are recorded and which remain.
- Everything lands in
audit-output/inside the audited repository:report.html(the deliverable, openable in any browser; the assistant offers to open it when the run finishes) andrun-state.json(the raw machine-readable results, which can re-render the same report later viaengineering-audit-render). If you chose GitHub filing, the assistant previews the issues and asks before filing anything.
audit-output/ belongs to the audited repository, not to this tool. Commit it, ignore it
or delete it as that repository's own conventions dictate.
engineering-audit MCP questions
Which AI assistants are supported?
Claude Code and OpenAI Codex CLI are proven to work end to end, while Gemini CLI is documented but untested.
Does it support GitHub Copilot?
No, GitHub Copilot is not supported by this tool.
How do I install the server?
You can install it using uvx to run the tagged release directly from GitHub, avoiding the need for pip or npm.