v0.2.1

Changelog

• 53737fb Add Streamlit dev lab with headless UI E2E tests
• 2a85b05 Add negative test script and live semantic wrap scenario
• 9ed20ea ci: add GoReleaser for cross-platform binary releases
• 4b3d674 fix: resolve data race in telemetry control resume test
• 7c7452f fix: resolve go binary lookup for CI integration tests

mcp-breaker v0.2.0

mcp-breaker v0.2.0 — Semantic Tracker, Graph Ledger, Dashboard, Homebrew

Release date: 2026-08-29
Tag: v0.2.0

Second release adding semantic stagnation detection, graph loop ledger, TUI dashboard, and Homebrew packaging.

---

Highlights

• Semantic stagnation tracker — cosine similarity (≥ 0.88) across tool result texts; spec Test Case B
• Sliding-window graph ledger — detects A→B→A→B tool invocation loops; blocks and pauses until dashboard resume
• TUI dashboard — mcp-breaker dashboard shows live metrics, stream, cosine scores
• Model management — mcp-breaker models download|status for All-MiniLM-L6-v2 ONNX cache
• Homebrew formula — Formula/mcp-breaker.rb + install guide

---

New commands

mcp-breaker dashboard
mcp-breaker models download
mcp-breaker models status
mcp-breaker wrap [--no-semantic] [--semantic-threshold=0.88] -- <command> [args...]

---

Semantic tracker (Test Case B)

Compares embedding cosine similarity between turn N and N−2 on tools/call responses. When similarity ≥ 0.88, appends the spec 3.3 intervention notice without killing the session.

Development without ONNX:

export MCP_BREAKER_MOCK_EMBED=1

Production with ONNX:

brew install onnxruntime
mcp-breaker models download
go build -tags=onnx -o mcp-breaker ./cmd/mcp-breaker  # optional ONNX build tag

---

Graph ledger

Tracks the last 10 tool turn keys (tool:argHash). Trips on tail pattern A,B,A,B (and extended A,B,A,B,A,B). Blocks the request and pauses until:

mcp-breaker dashboard   # press R to resume

---

Dashboard

Terminal 1:

mcp-breaker wrap -- ./fakemcp

Terminal 2:

mcp-breaker dashboard

Sockets: ~/.mcp-breaker/run/events.sock, ~/.mcp-breaker/run/control.sock

---

Full changelog

Added

• pkg/breaker/chain.go — interceptor composition
• pkg/breaker/ledger.go — graph loop detection + pause/resume
• pkg/breaker/semantic.go — semantic stagnation on server frames
• pkg/breaker/stack.go — default wrap interceptor stack
• pkg/embed/ — embedder interface, mock, cosine, model download, ONNX stub (-tags=onnx)
• pkg/telemetry/ — event bus, control socket, metrics
• pkg/dashboard/ — Bubble Tea TUI
• pkg/config/ — runtime paths and thresholds
• Formula/mcp-breaker.rb and docs/install/homebrew.md
• Tests: Test Case B, ABAB ledger, chain priority, telemetry, control resume

Changed

• wrap uses full interceptor stack (echo + ledger + semantic)
• Go 1.24+ (Bubble Tea dependency)
• README roadmap updated

---

Links: Repository · v0.1.0

v0.1.0: Initial release: stdio MCP proxy with echo circuit breaker.

mcp-breaker v0.1.0 — Initial Release

Release date: 2026-08-29
Tag: v0.1.0

First public release of mcp-breaker, a semantic MCP circuit breaker that proxies JSON-RPC traffic between AI clients and MCP servers over stdio.

---

Highlights

• Stdio JSON-RPC proxy — transparent wrap layer compatible with Cursor, Claude Desktop, Cline, and any MCP stdio client
• Tool echo detector — blocks the 3rd consecutive identical tools/call per tool before it reaches the backend server
• Graceful intervention — returns structured MCP error results instead of crashing the agent session
• Zero runtime dependencies — single static Go binary (~3 MB)
• Built-in demo — make demo runs end-to-end with no MCP configuration required

---

What's included

Core

Component	Description
mcp-breaker wrap	CLI command to launch and proxy any MCP server process
pkg/proxy	Newline-delimited JSON-RPC framing, bidirectional session proxy
pkg/breaker	Echo detector with per-tool SHA-256 hash ring (size 5)
pkg/protocol	MCP tools/call types and intervention payloads
fakemcp	Built-in fake MCP server for local testing

Detection behavior (Echo Breaker)

• Intercepts every tools/call JSON-RPC request

• Tracks consecutive identical argument hashes per tool name

• Forwards calls 1 and 2; blocks call 3 with:

  Error: Command [<tool>] generated identical failures across consecutive loops.
  Do not retry without modifying parameters.
  

• Resets counter when arguments change; isolates counters per tool

• All other MCP methods (initialize, tools/list, notifications) pass through unchanged

---

Quick start

git clone https://github.com/shunvel/mcp-breaker.git
cd mcp-breaker
make build
make demo

Wrap an MCP server:

./mcp-breaker wrap -- npx -y @modelcontextprotocol/server-filesystem /tmp

---

Client configuration example

{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/mcp-breaker",
      "args": ["wrap", "--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

---

Test coverage

• JSON-RPC framing (round-trip, split delivery, malformed skip, oversize rejection)
• Bidirectional session proxy and stderr isolation
• Echo detector (spec Test Case A): 3 identical write_file calls → 3rd blocked
• Integration: mcp-breaker wrap -- fakemcp end-to-end

Run locally:

make test

---

Known limitations

• Semantic stagnation detection (spec Test Case B) is not yet implemented — placeholder only
• No init command — MCP configs must be wrapped manually
• No TUI dashboard — planned for a future release
• No pre-built binary downloads — build from source for now

---

Requirements

• Go 1.23+
• macOS or Linux (Windows support planned)

---

What's next (v0.2 roadmap)

• Local ONNX embedding engine (All-MiniLM-L6-v2) for semantic trajectory analysis
• Sliding-window graph loop detection
• mcp-breaker init config auto-wrap for Cursor / Claude Desktop
• Terminal dashboard (mcp-breaker dashboard)
• Homebrew formula and release binaries

---

Links

• Repository: https://github.com/shunvel/mcp-breaker
• Specification: spec.md
• Contributing: CONTRIBUTING.md
• License: Apache-2.0

---

Full changelog

Added

• cmd/mcp-breaker CLI with wrap and help commands
• pkg/proxy/jsonrpc.go — NDJSON frame reader/writer, Session, Interceptor interface
• pkg/proxy/stdio.go — child process stdio wrap via RunWrap
• pkg/breaker/echo.go — echo detector (3rd identical call trip)
• pkg/breaker/semantic.go — placeholder for ONNX semantic module
• pkg/protocol/mcp.go — MCP types and intervention helpers
• internal/testmcp — fake MCP server and integration tests
• scripts/demo.sh and make demo target
• Comprehensive README with setup, CLI reference, and client config guides
• Apache-2.0 LICENSE
• GitHub Actions CI workflow (test, vet, build, demo smoke)
• CONTRIBUTING.md

Security

• Max JSON-RPC frame size capped at 1 MiB
• Child stderr isolated from stdout to preserve MCP framing integrity

---

Contributors: @shunvel

Built to stop agents from spinning in circles — so you can ship faster.