# 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

```bash
cd unstuck-mcp
npm install
```

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

### GitHub Copilot CLI

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

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

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

### OpenAI Codex CLI

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

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

### OpenCode

Add to `opencode.json` (project or global):

```json
{
  "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.