Breakwire MCP server

Breakwire clients, MCP config and CI check

Current release: clients 0.12.0 (npm breakwire, PyPI breakwire, PyPI langchain-breakwire) · server 0.12.28 · GitHub Action breakwire-check 1.2.0 · CHANGELOG

Breakwire is a source-linked registry of changes that break AI agents: model retirements, API deprecations, SDK breaking releases, MCP spec changes and security advisories. Send it an error, get back the claim that explains it (e.g. AN-2026-0025) with the vendor's documented error string, affected versions, deadline, fix and primary source.

Try it: one call, no key, no install

curl -X POST https://breakwire.org/api/lookup -H 'content-type: application/json' -d '{"error":"Error: D1_ERROR: Network connection lost.","compact":true}'

Returns explained: true and claim AN-2026-0143 (the vendor-documented D1 error, the fix and its source). Paste your own error text as "error"; add "service" / "model" if you know them, "no_log": true to store nothing.

This repo holds everything that talks to it:

	Path	Install
TypeScript/JS client (zero deps, Node 18+, Workers) + Vercel AI SDK tools	packages/js	npm i breakwire@latest
Python client (stdlib only, 3.9+)	packages/python	pip install -U breakwire
LangChain tools + callback handler	packages/langchain-breakwire	pip install -U langchain-breakwire
MCP server config for Claude, Cursor, VS Code, Cline, Codex, Windsurf, Gemini CLI	mcp/CLIENTS.md	https://breakwire.org/mcp
GitHub Action: fail CI on near deadlines / advisories	action (published as breakwire-org/breakwire-check)	uses: breakwire-org/breakwire-check@v1
Framework snippets: Vercel AI SDK, OpenAI Agents, Anthropic SDK, LangChain, MCP TS client	snippets
Trigger packages: Claude Code plugin (skill + MCP), Cursor rule, AGENTS.md block	triggers	/plugin marketplace add breakwire-org/breakwire
Gemini CLI extension (remote MCP + GEMINI.md context)	gemini-extension.json	gemini extensions install https://github.com/breakwire-org/breakwire

Installed the Claude Code plugin or the Gemini extension earlier? Their manifests stayed at 0.4.0 / 0.8.0, and Claude Code only refreshes a plugin when that version string changes, so later skill/hook updates (session brief, GET forms, fail-open) never reached you. Both now track the clients version (0.12.0). Update with claude plugin marketplace update breakwire && claude plugin update breakwire@breakwire or gemini extensions update breakwire.

30 seconds

curl -s https://breakwire.org/api/lookup -H 'content-type: application/json' \
  -d '{"error":"tool_choice: type \"tool\" and \"any\" are not supported for this model.","service":"anthropic-api"}'

import { withBreakwire } from 'breakwire';
const create = withBreakwire((p) => anthropic.messages.create(p), { service: 'anthropic-api' });
try { await create(params) } catch (e) { console.log(e.breakwire?.id, e.breakwire?.fix); throw e }

from breakwire import with_breakwire
with with_breakwire(service="openai-api"):
    client.responses.create(...)   # exception gets .breakwire (id, fix, url) and a traceback note

When to call it

1. Session start: session_brief (MCP) / sessionBrief() / session_brief() / npx breakwire brief. Silent when nothing changed for your exact stack.
2. An error you do not recognise. 2. Code that names a model id or SDK version. 3. A deploy or upgrade. For 1-3, step one: GET https://breakwire.org/api/changes?from=<your training cutoff> (changes, new model launches, revisions). Fail open: if Breakwire is slow or down, carry on. Details: triggers/TRIGGERS.md.

What's new in 0.12.0 (clients)

Current clients are 0.12.0 (parity with Breakwire 0.12). Upgrade from 0.1–0.7: pip install -U breakwire · npm i breakwire@latest · pip install -U langchain-breakwire. Details: CHANGELOG.md.

• GET forms (0.12.19 / 0.12.23): GET /api/stack?packages=&node= and GET /api/session-brief?packages=&node=&services= match POST. The Action and SDKs still POST; curl-only / GET-only checkers use GET. Docs: https://breakwire.org/llms.txt.
• Trigger packages (Claude Code skill, Cursor rule, AGENTS.md) now document those GET forms and the 0.12.0 upgrade commands.

What's new in 0.7.0 (clients)

• Session brief with a local cursor: sessionBrief() / session_brief() return context: null when clear (inject nothing), else at most 5 source-linked items. Later calls send only a fingerprint and cursor (304 when unchanged).
• npx breakwire brief for session-start hooks; the Claude Code plugin runs it on startup.
• Stack checks are strict + compact by default. No-log lookups return a receipt you can close with an outcome and evidence_type. Details in CHANGELOG.md.

What's new in 0.6.0 (clients)

Security and correctness release; see CHANGELOG.md and SECURITY.md.

• Redirects never carry credentials or bodies to another origin. Clients follow redirects only to https://breakwire.org, the base URL's origin and any trustedOrigins / trusted_origins you pin.
• Stack files are parsed in your process. stack() / subscribe() send only dependency and runtime facts; previewStack() / preview_stack() show the exact body; raw files need rawFiles: true / raw_files=True.
• Retry works in the default no-log mode, and the local cache keys on every lookup option.
• Broader local redaction (IPv6, UUIDs, request/trace ids, filesystem and UNC paths, credentials in any URI scheme, secret-named JSON fields) with previewRedaction() / preview_redaction().
• Python with_breakwire accepts every lookup() option (compact, min_score, max_matches, since, reflex).

Principles

• Opt-in and harmless. Lookups happen only on errors, are time-boxed, and never throw or replace your error.
• Secrets stay home. Keys, tokens, emails, IPv4/IPv6 addresses, UUIDs and request ids, query strings, credentials in URLs and filesystem paths are stripped in your process before sending (shared test cases; previewRedaction() / preview_redaction() show exactly what would leave); the server redacts again. Stack files are parsed locally and only dependency facts are sent. Redirects never carry credentials or bodies to another origin.
• No silent reporting. Outcome reports ("did the fix work") are sent only with autoReport/auto_report on, and only after your retry actually ran.
• Honest data. signature vs related confidence, explicit "not covered" for services without claims, and community verification that has just started: most claims have no outcome reports yet, and each claim says so.

Development

cd packages/js && npm ci && npm test              # offline unit tests (+ npm run test:live)
cd packages/python && python -m unittest discover -s tests
cd packages/langchain-breakwire && python -m unittest discover -s tests
cd action && npm test
cd snippets && npm ci && npm test                  # real SDKs against a mock vendor + live Breakwire
node scripts/versions.mjs --check                  # fails on stale versions (edit versions.json, run without --check)

Versions live in one place, versions.json. node scripts/versions.mjs writes them into the package manifests, source constants and the README banners; CI (.github/workflows/ci.yml) runs the check plus every suite. Shared cross-language fixtures: tests/ (redaction, redirect policy, stack parsing, lookup option contract).

Live tests use log_miss: false and never send outcome reports. Set BREAKWIRE_BASE_URL to point at another deployment.

API: https://breakwire.org/llms.txt · OpenAPI: https://breakwire.org/openapi.json · Data: CC BY 4.0 · Code: MIT