unstuck-mcp

Stops coding agents from looping on the same failed fix. Tracks failed attempts per-problem, and once the same error has been "fixed" a couple of times without success, it blocks further fixes until the agent actually uses its own web search tool — instead of guessing again from stale memory.

Works with GitHub Copilot CLI, OpenAI Codex CLI, and OpenCode, because all three speak MCP, all three read AGENTS.md, and all three already ship a web search tool of their own. This server doesn't duplicate that search — it just gates on whether it happened.

How it works

1. The agent calls report_attempt(error_signature, fix_summary) after any failed fix.
2. The server normalizes the error text (strips line numbers, file paths, quoted values) and hashes it, so near-identical failures are recognized as "the same problem" even if the wording drifts slightly.
3. On the 3rd attempt at the same normalized problem (configurable), the tool response tells the agent it's blocked: it must use its own web search tool before trying anything else.
4. Once it has searched, the agent calls confirm_search(error_signature, findings_summary). This clears the block and resets the attempt count for that problem, informed by what it just found.
5. If the agent tries another fix while still blocked (i.e. it skipped the search), report_attempt calls it out explicitly instead of quietly logging it.

This is enforced through instructions, not a hard runtime block — MCP servers can't intercept an agent's other tool calls the way an editor plugin can. It works because the tool descriptions and the bundled AGENTS.md rule make calling it the obvious, expected thing to do, the same pattern that made docs-lookup MCP servers like Context7 stick. confirm_search closes the loop: the agent can't just claim it's unblocked without a tool call that says so.

Install

cd unstuck-mcp
npm install

Then wire it into whichever CLI(s) you use:

GitHub Copilot CLI

copilot mcp add
# Command: node
# Args: /absolute/path/to/unstuck-mcp/index.js

or edit ~/.copilot/mcp-config.json directly:

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

OpenAI Codex CLI

Add to your Codex config (~/.codex/config.toml):

[mcp_servers.unstuck]
command = "node"
args = ["/absolute/path/to/unstuck-mcp/index.js"]

OpenCode

Add to opencode.json (project or global):

{
  "mcp": {
    "unstuck": {
      "type": "local",
      "command": ["node", "/absolute/path/to/unstuck-mcp/index.js"],
      "enabled": true
    }
  }
}

Enable the enforcement rule

Copy the contents of AGENTS.snippet.md into your project's AGENTS.md (all three tools read this file). Without it, the agent still can call these tools, but won't reliably choose to on its own.

Configuration

Environment variables (set them in the MCP server config's env block):

Variable	Default	Purpose
UNSTUCK_THRESHOLD	2	How many failed attempts before blocking (3rd attempt = 1st time blocked)
UNSTUCK_DIR	<cwd>/.unstuck	Where attempt history is stored

Tools exposed

• report_attempt(error_signature, fix_summary) — log a failed attempt, get back whether you're blocked
• confirm_search(error_signature, findings_summary) — clear a block after actually searching
• loop_status() — see everything currently tracked as stuck, for debugging
• reset_loop(error_signature?, clear_all?) — clear history manually

Known limitation

This relies on the agent following its instructions honestly — calling report_attempt after failures, and not calling confirm_search without actually searching. It's not a hard sandbox-level block like an OpenCode plugin hook could be. In exchange, it works identically across every MCP-compatible agent instead of being locked to one tool's plugin architecture, and it doesn't duplicate a search tool the agent already has.