io.github.charliemtnez/ghost-inspector-mcp

Creates an empty suite, optionally inside a folder. The folder is honoured at creation, so no follow-up move is needed. Refuses when a suite of the same name already exists in the same place, because Ghost Inspector allows the duplicate and nothing distinguishes the two afterwards. Pass allowDuplicateName only when the repetition is genuinely intended. 🔴 Getting the name right matters more than usual: this server never exposes suite deletion, because DELETE /suites/{id}/ cascades to every test inside with no version history and no recycle bin. Folders have no delete route in the API at all. Anything created here is tidied up by hand, in the web UI. Creating adds and overwrites nothing, so no concurrency token applies.

Copies an existing test, then places it in a suite and renames it in one call. Returns the new test with its steps and its dateUpdated. 🔴 This is how a test comes into existence here, and it is not a create. Ghost Inspector has no endpoint that builds a test from nothing — POST /tests/ is the listing wearing a POST — so a source test is mandatory and there is no way around that. Pick the closest existing test and adapt the copy with gi_update_test. 🔴 The copy's schedule is cleared unless keepSchedule is set. Whether a copy inherits its source's testFrequency is not verified, and in an account whose tests submit live forms against production, an inherited schedule means an unattended run posting real data. The uncertain case is pinned to the safe direction. The copy carries the source's steps verbatim, including any `execute` steps: it imports the same modules, so editing those modules still affects it. If the copy is placed in a suite with a different viewport or browser, selectors that resolved for the source may not resolve for it — validate with gi_validate_test before trusting it. If the copy is made but placing or renaming it fails, the response says so and returns the id, because the copy is already real and needs cleaning up.

Returns a single test's stored definition, identity and current state: steps, startUrl, suite, whether it is a module, its last run, and its `dateUpdated`. 🔴 `dateUpdated` is the concurrency token. gi_update_test requires it as `expectedDateUpdated` and refuses the write if the record moved since you read it. Call this first and pass the value through. Do not discover the token by sending a deliberately wrong one and reading the correct value off the refusal — that defeats the guard, which exists to prove the edit was composed against the definition that is actually stored. The steps returned are the test's OWN steps. An `execute` step names an imported module in `value` and is not expanded here, so the definition you edit may be smaller than the run you observed: a result expands every module inline. If the step you need to fix came from a module, edit that module's test, not this one.

Read-only tour of the whole account: every folder, the suites inside it, and per-suite counts of passing / failing / module / not-yet-run tests, plus the names of the failing ones. Start here — no other question about this account can be answered without knowing what is in it. Import-only tests (modules: shared steps that other tests import, the equivalent of a function) are counted in their own bucket and never as failures. Marking a test import-only deletes its stored results, so every module looks permanently unrun; folding that into a failure count invents breakage that does not exist and aims cleanup at the steps the live tests all share. Read the `notes` field before drawing conclusions. Fetches roughly 440 KB from the API and returns a summary of it, so ask for the whole account rather than probing folder by folder. Totals always describe the entire account even when a filter narrows the listing.

Answers the one question the API cannot: if I edit this module, which tests break? Builds the reverse index of `execute` steps — for every imported test, its direct importers and its full transitive blast radius through nested chains. Run this BEFORE editing any module. Also surfaces three things that only appear once the index exists: import-only tests nobody imports (dead, or a test that lost its caller and is silently not running); imported tests NOT flagged import-only, which run standalone *and* inside their importers, so an edit changes both paths; and execute steps pointing at ids that no longer exist. 🔴 It also finds `vacuousTests`: tests that execute no steps at all, because their definition is only `execute` calls and the chain bottoms out in empty modules. Those pass — nothing can fail — so the dashboard shows them green while they assert nothing, which is worse than a red test and invisible any other way. Emptying one shared module does this to every test that imports it. This is the expensive tool. `steps` is absent from the test listing, so it costs one request per test in the account — a few seconds for a few hundred tests, at deliberately low concurrency because the rate limit is undisclosed. Call it once and work from the result rather than per module. A definition that cannot be read is counted in `scanned.unreadable`, never skipped silently, because a missing definition understates a blast radius.

Moves a suite, with all of its tests, into another folder. Reversible — unlike everything else on the write path — and the response carries `previousFolder` so the undo is one call. `expectedCurrentFolder` is required: state the folder you believe the suite is in, and the move is refused if it is somewhere else, which is the case where you are about to move the wrong suite. The result is verified by re-reading: the folder must have changed and `testCount` must be identical, since a move should never detach a test. Note that `DELETE /folders/{id}/` does not exist, so a folder left empty by a move can only be removed from the web UI. Folder names have to be right the first time.

Turns a diagnosis into a concrete argument: what to change, in which test, and the token needed to write it. Read-only — it applies nothing and returns steps for you to validate first. 🔴 This server cannot see the page. It has the definition, the error and the Ghost Inspector contract, so proposals come in two kinds and are never blurred. `applicable` proposals carry a rewritten step and come from rules that hold whatever the page contains — an assertTextPresent with no target always fails, an eval without an explicit return is always undefined. `advisory` ones name a real problem that cannot be fixed without looking at the DOM, and deliberately stop there rather than inventing a selector. Refuses outright on a stale diagnosis. A failure that predates a change describes a definition that is no longer stored, so a repair built on it would overwrite whatever replaced it, with no version history to recover. 🔴 `editTarget` is frequently NOT the test you asked about. Results expand imported modules inline, so the failing step often belongs to a module — and `proposedSteps` is that module's full step list, not this test's. Editing a module affects every test importing it. Validate `proposedSteps` with gi_validate_test before writing. A proposal that has not been run is a hypothesis.

Executes a test exactly as saved and waits for the verdict. Use it to confirm a repair actually worked, or to get a fresh result when the stored one is stale. 🔴 Nothing is truncated here. Unlike gi_validate_test, which runs a throwaway copy and stops before anything can submit, this runs the real test against the real startUrl — in most accounts, production. If the test fills and submits a form, this posts a real record into whatever that form feeds, and nothing here can withdraw it. Because of that, a test that submits is refused unless `confirmSubmit` is set. The check inlines imported modules first, since a test whose steps are only `execute` calls hides its submit inside one. A test that submits nothing runs without the flag. If a chain cannot be fully expanded it counts as submitting — an unnecessary confirmation is cheaper than an unintended record. If you only need to know whether the selectors still resolve, this is the wrong tool: gi_validate_test answers that without submitting. 🔴 A wait that expires is NOT a failure. Browser runs take 20-70 seconds and slow ones take longer; the response returns the result id and says the run is still going. Read the outcome with gi_test_result rather than concluding the test failed.

Call this BEFORE diagnosing or editing any red test. Splits failures into two piles by comparing the whole `execute` chain's `dateUpdated` against each test's last run. `staleFailures` are red tests whose definition or module chain changed AFTER the failing run. The failure describes a version that no longer exists — a colleague may already have fixed it and the test simply has not run again. Editing on top of one destroys their work, and Ghost Inspector keeps no version history of steps. One level deep is not enough here, because modules nest; the whole chain is walked. `genuineFailures` have had no change since the failing run, so the failure still describes the current definition. Start there, oldest first. 🔴 Re-running is not free advice: many Ghost Inspector suites submit real forms against production. Confirm what a test does before triggering it. Also reports the case nobody looks for: passing tests whose chain changed after their last run, whose green result describes the old definition and proves nothing about the current one. Import-only modules are excluded rather than evaluated, since they have no results to compare against. Costs one request per test, a few seconds for a few hundred tests.

The last run of one test: the step that failed, its error, and whether the result can be trusted at all. Read-only. This is the starting point for repairing a failure — gi_stale_tests tells you which tests to look at, this tells you what happened in one of them. 🔴 Read `verdict` and `staleness` BEFORE the error. A verdict of `stale` means the test or one of its imported modules changed after this run, so the failure describes a definition that is no longer stored. Diagnosing from it is diagnosing from nothing, and a colleague may already have fixed it. Re-run the test and read the fresh result instead. 🔴 `failingStep.resolvedTarget` is the selector that resolved, NOT what the test looks for. Ghost Inspector collapses an authored fallback array to the one it used, and sometimes normalises it so it matches nothing in the definition textually. `authoredTargets` is what was actually written. Reporting the resolved one as the intent is a real and easy misreading. 🔴 `failingStep.ownedBy` names the test that contributed the step. Results expand imported modules inline, so the failing step frequently belongs to a module rather than to the test you asked about — that module is what needs editing, and editing it affects every test that imports it. The step's position in the result is meaningless against the definition; use `ownedBy.sequenceInOwner`. Other cases it distinguishes rather than blurring: a module (import-only tests have no results at all), a run still in flight (`passing: null` is pending, never failed), a red run with no failing step (the failure was outside the steps — a start URL that would not load), and results that have been purged, which it reports as a horizon instead of as silence.

Replaces a test's steps and/or renames it. 🔴 Ghost Inspector keeps NO version history of steps and no recycle bin, so this is permanent. Four guards run on every call and none can be turned off. (1) The whole `execute` chain's `dateUpdated` is compared against the test's last run; if anything changed after it, the test is stale and the call is refused, because a fix diagnosed from a failure that describes a deleted version is diagnosed from nothing — and a colleague may already have fixed it. (2) The complete prior definition comes back as `backup`, on refusals too; it is the only rollback that exists, so keep it. (3) The change is applied. (4) The record is re-read and diffed, both that what was sent landed exactly and that every field you did not send is untouched — `HTTP 200` proves neither. `expectedDateUpdated` is required: state the `dateUpdated` you believe is current, and the write is refused if the record has moved since. Read the test first; a refusal tells you the current value so a retry is one step. Before overwriting a red test, prefer gi_validate_test, which runs the current definition without saving and without submitting a form. If the staleness guard trips and you have genuinely verified the current state, `confirmStaleDiagnosis` proceeds — read what the refusal says first.

Finds tests that pass while verifying nothing. Green is the dangerous colour: a red test gets investigated, a hollow green one sits there while every report says coverage is fine. Three classes, kept apart because conflating them hides two of them. `executesNothing` runs zero steps — its definition is only `execute` calls into empty modules. `assertsNothing` runs its steps and contains no assertion anywhere in the chain, so it can only fail if a step errors; act on this one first, it is usually the largest. `worthChecking` is a SHORTLIST, not a verdict: their single assertion is the final step, so if its target also exists on the page the test starts from, it passes with the feature completely broken. 🔴 That third class cannot be settled from the definition — the selector is simply present on the starting page and no earlier step mentions it. Scanning for a repeated target finds none of them. To decide, run the test with the decisive action removed and see whether the assertion still passes; if it does, the test proves nothing. Modules are excluded before counting: import-only deletes results, so including them would condemn the shared layer every live test depends on. Costs one request per test.

Runs a test definition through on-demand execution, which executes it and discards it — nothing in the account is created or changed. Use it to check that a selector chain still resolves before editing a test, and to check a definition you are authoring before saving it. 🔴 It drives a real browser against a real URL, so it is an action with real-world effects even though nothing is saved. Two guards apply and neither can be turned off. Modules are inlined first, because a test whose steps are just `execute` calls hides its submit inside a module and guarding the definition as written would miss it. Then the run is truncated at the first step that could submit a form, and that step is replaced by an assertion on the same target — so the whole chain is verified, including that the submit control is reachable, without ever activating it. There is no way to make this tool submit; that stays a deliberate curl. For an existing test the suite's viewport and browser are replicated, because tests inherit those and a selector can resolve on desktop and fail on mobile. Read `ranAs.configSource` to see what was actually used. A browser run takes 20-100 seconds; the tool polls until it finishes. `passing: null` in the raw API means not finished, never failed.

Confirms the configured API key works, lists the organizations it can reach, and reports whether writing is enabled. Read-only and safe to call first when diagnosing setup. 🔴 Call this before concluding that this server cannot modify anything. Every tool is registered whether or not its gate is open, so a tool being listed says nothing about whether it will run. `writesEnabled` and `runsEnabled` are the authority — GHOST_INSPECTOR_ALLOW_WRITES and GHOST_INSPECTOR_ALLOW_RUNS. When one is false the operator must set the matching variable and restart this server; it cannot be turned on from a tool call. Returns each organization's id — export the one you want as GHOST_INSPECTOR_ORG_ID to enable on-demand validation runs.