Skip to content
Back to search

tripwire-mcp

Describe what must keep working. Tripwire checks it after every change. A regression guard for people who ship fast, as an MCP server.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vc555s--tripwire-mcp/badge.svg)](/listings/vc555s--tripwire-mcp)

HTML

<a href="/listings/vc555s--tripwire-mcp"><img src="/api/listings/vc555s--tripwire-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need Node 18 or newer and Google Chrome.

git clone https://github.com/Vc555s/tripwire-mcp
cd tripwire-mcp
npm install && npm run build

Add it to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for every project):

{
  "mcpServers": {
    "tripwire": {
      "command": "node",
      "args": ["/absolute/path/to/tripwire-mcp/dist/index.js"]
    }
  }
}

Then tell the agent: *"Set up Tripwire for http://localhost:3000, the code is in you/your-repo"*, or run the `guard_my_app` prompt.

To make the agent check on its own, add a project rule:

<!-- .cursor/rules/tripwire.mdc -->
After any change that affects the UI, call tripwire_guard before committing.
If the verdict is BROKEN, show the screenshot and offer to fix it and file an issue.
Never edit a check to make it pass.

Environment

| Variable | Purpose | |---|---| | `TRIPWIRE_HOME` | Data folder (default `./.tripwire`) | | `FIRECRAWL_API_KEY` | Faster, deeper page discovery (optional) | | `GITHUB_REPO` | Default `owner/repo` for issues. Not needed when the repo is given at scan time, which also lets one install guard several projects | | `GITHUB_TOKEN` | Token for filing issues. If unset, Tripwire uses your GitHub CLI login (`gh auth login`) | | `GITHUB_API_URL` | GitHub Enterprise address (optional) | | `TRIPWIRE_BROWSER_WS` | Use a remote browser instead of local Chrome | | `TRIPWIRE_CHROME_PATH`, `TRIPWIRE_HEADFUL=1` | Local browser control | | `TRIPWIRE_STEP_TIMEOUT_MS`, `TRIPWIRE_VISUAL_THRESHOLD` | Tuning (defaults 8000 ms, 0.02) |

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 153 lines
  1. # Tripwire
  2. **Describe what must keep working. Tripwire checks it after every change.**
  3. AI agents write your app, but they forget what you promised your customers. Tripwire is the memory of those promises: you say them once in plain words, and the agent has to prove it kept them before every commit. The answer is one word, **SAFE, CHANGED or BROKEN**, with a screenshot.
  4. Tripwire is an MCP server for Cursor. It is a standard MCP server, so other editors that speak MCP should work too. There is no test code to write and no extra AI key: the agent already in your editor does the thinking. Tripwire is the hands (a real browser) and the memory (your promises, the known-good baseline, the history).
  5. ---
  6. ## Why
  7. AI tools made shipping fast, but checking didn't speed up. Most vibe-coded apps, small-business sites and side projects have **zero tests**, so a "harmless" refactor breaks checkout and nobody notices until a customer emails.
  8. If your app takes money or leads and an AI edits it, something has to check the money path after every edit. Otherwise your customers are the ones who find out.
  9. | Who | Pain | What Tripwire gives them |
  10. |---|---|---|
  11. | Founders who vibe code | Every AI edit might break something unrelated | `Did I break anything?` after each change, inside the editor |
  12. | Small businesses | Forms and checkout fail silently | Promises in plain words, checked in a real browser |
  13. | Agencies | Dozens of client sites, no test budget | One set of promises per client, reports they can forward |
  14. | Small teams | Nobody knows which change broke what | Regressions filed as GitHub issues, linked to the issue that caused them |
  15. ---
  16. ## How it works
  17. ```
  18. you (plain words) ──► editor agent ──► Tripwire MCP ──► real browser
  19. │
  20. scan ─► suggest ─► promises ─► run ─► compare with baseline ─► verdict + report ─► GitHub issue
  21. │
  22. .tripwire/ (sites, promises, runs, screenshots, audit.jsonl)
  23. ```
  24. 1. **Scan**: map the site's pages, links, buttons, inputs and forms. Firecrawl finds the pages when `FIRECRAWL_API_KEY` is set; otherwise Tripwire crawls the site itself and never follows logout or delete links.
  25. 2. **Suggest**: rank what a non-tester cares about: pages load, login and sign-up, search, cart, checkout, contact form, navigation.
  26. 3. **Promise**: you say what must keep working and what it costs you if it breaks. The agent turns it into browser steps. Your words are stored as the spec, next to what is at stake.
  27. 4. **Run**: a real browser, with evidence: screenshot, console errors, failed requests and timing.
  28. 5. **Compare** against the known-good baseline: newly failing promises, new browser errors, new failed requests, slowdowns and visual changes.
  29. 6. **Verdict**: one sentence that names the broken promise and what is at stake, the screenshot, and an HTML report a non-developer can open and forward.
  30. 7. **Close the loop**: file a GitHub issue with the promise, the steps to reproduce in plain words and the error. Tripwire also comments on the issue whose change caused the break.
  31. ### What a broken promise looks like
  32. ```
  33. BROKEN
  34. Broken promise: "If I add the Yirgacheffe and use WELCOME10, the total should be €13.05".
  35. At stake: New customers pay full price and stop trusting the shop.
  36. Used to pass, now fails at step 7: expected €13.05 but it showed €14.49.
  37. ```
  38. ---
  39. ## Tools
  40. | Tool | What it does |
  41. |---|---|
  42. | `tripwire_scan_site` | Crawl a URL and map what a visitor can interact with. Pass `repo` to say which GitHub repo the site belongs to |
  43. | `tripwire_suggest_checks` | Ranked plain-English suggestions with draft steps |
  44. | `tripwire_add_check` | Save or replace a promise: intent, stakes and steps (needs at least one `expect*` step) |
  45. | `tripwire_list_checks` / `tripwire_remove_check` | See or change what is guarded |
  46. | `tripwire_run` | Run the checks, optionally against another deployment (`targetUrl`, e.g. a deploy preview) |
  47. | `tripwire_set_baseline` | Mark a passing run as known-good |
  48. | `tripwire_compare` | Verdict, regressions and report against the baseline |
  49. | **`tripwire_guard`** | **One call after any change: run, compare, verdict.** Sets the first baseline automatically. Pass `change` (label, issue, files) to record what is being checked |
  50. | `tripwire_file_issue` | File the regression as a GitHub issue and comment on the issue that caused it |
  51. | `tripwire_read_issue` | Read a GitHub issue and extract its acceptance criteria, to turn them into checks |
  52. | `tripwire_history` | Recent runs and the audit trail |
  53. **Prompts** (slash commands in most clients): `guard_my_app(url)` and `verify_issue(issue, siteId)`.
  54. **Step actions:** `goto`, `click`, `fill`, `select`, `press`, `wait`, `expectVisible`, `expectNotVisible`, `expectText`, `expectUrlContains`, `expectCount`. Values support `{{PLACEHOLDERS}}` filled from `vars` or `TRIPWIRE_VAR_<NAME>` environment variables, so secrets never live in the check file.
  55. ---
  56. ## Install
  57. You need Node 18 or newer and Google Chrome.
  58. ```bash
  59. git clone https://github.com/Vc555s/tripwire-mcp
  60. cd tripwire-mcp
  61. npm install && npm run build
  62. ```
  63. Add it to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for every project):
  64. ```json
  65. {
  66. "mcpServers": {
  67. "tripwire": {
  68. "command": "node",
  69. "args": ["/absolute/path/to/tripwire-mcp/dist/index.js"]
  70. }
  71. }
  72. }
  73. ```
  74. Then tell the agent: *"Set up Tripwire for http://localhost:3000, the code is in you/your-repo"*, or run the `guard_my_app` prompt.
  75. To make the agent check on its own, add a project rule:
  76. ```md
  77. <!-- .cursor/rules/tripwire.mdc -->
  78. After any change that affects the UI, call tripwire_guard before committing.
  79. If the verdict is BROKEN, show the screenshot and offer to fix it and file an issue.
  80. Never edit a check to make it pass.
  81. ```
  82. ### Environment
  83. | Variable | Purpose |
  84. |---|---|
  85. | `TRIPWIRE_HOME` | Data folder (default `./.tripwire`) |
  86. | `FIRECRAWL_API_KEY` | Faster, deeper page discovery (optional) |
  87. | `GITHUB_REPO` | Default `owner/repo` for issues. Not needed when the repo is given at scan time, which also lets one install guard several projects |
  88. | `GITHUB_TOKEN` | Token for filing issues. If unset, Tripwire uses your GitHub CLI login (`gh auth login`) |
  89. | `GITHUB_API_URL` | GitHub Enterprise address (optional) |
  90. | `TRIPWIRE_BROWSER_WS` | Use a remote browser instead of local Chrome |
  91. | `TRIPWIRE_CHROME_PATH`, `TRIPWIRE_HEADFUL=1` | Local browser control |
  92. | `TRIPWIRE_STEP_TIMEOUT_MS`, `TRIPWIRE_VISUAL_THRESHOLD` | Tuning (defaults 8000 ms, 0.02) |
  93. ---
  94. ## Try the demo
  95. The repo ships a small coffee shop with a **planted** bug: a "tidy-up" of the price helper that silently turns 10% off into 0.1% off.
  96. ```bash
  97. node demo/serve.mjs # good build on :4321
  98. BROKEN=1 PORT=4322 node demo/serve.mjs # the "refactor" that breaks the discount code
  99. node scripts/e2e.mjs # the whole flow, scripted, against a mock GitHub
  100. ```
  101. The same shop is hosted, with the bug on a branch, at [Vc555s/tripwire-demo-shop](https://github.com/Vc555s/tripwire-demo-shop). `scripts/seed-demo.mjs`, `scripts/preflight.mjs`, `scripts/rehearse.mjs` and `scripts/reset-demo.mjs` set up, verify, rehearse and reset a live demo against it (copy `demo.env.example` to `demo.env` first).
  102. More detail, with diagrams: [docs/WORKFLOW.md](docs/WORKFLOW.md).
  103. ---
  104. ## Roadmap
  105. - **Checks that repair themselves**: when the page changed and a step cannot find its element, rebuild the steps from the stored sentence instead of reporting a break.
  106. - **Watch while the laptop is closed**: a hosted runner with scheduled checks and alerts.
  107. - **Deploy-preview gate**: run on every preview deploy and comment the verdict on the pull request.
  108. - **Phone view**: run every promise at phone size too.
  109. - **Editor extension**: one-click install, the verdict in the status bar.
  110. - **Behavioural diff mode**: replay API traffic against the base and changed builds.
  111. ## License
  112. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.