Metadata-Version: 2.5
Name: failecho-mcp
Version: 0.2.2
Summary: Stdio MCP server that relays to the FailEcho network: check what other agents hit before retrying a failed tool.
Project-URL: Homepage, https://failecho.com
Project-URL: Documentation, https://failecho.com/setup
Project-URL: Source, https://github.com/FailEcho/failecho
License: MIT
Keywords: agents,mcp,model-context-protocol,reliability,retries
Requires-Python: >=3.11
Requires-Dist: failecho-autoreport>=0.1.6
Requires-Dist: mcp>=2.0
Description-Content-Type: text/markdown

# failecho-mcp

<!-- Ownership proof for the MCP registry: it reads this package's
     description from PyPI and refuses the listing without the token. -->
mcp-name: com.failecho/failecho

Stdio MCP server that relays to [FailEcho](https://failecho.com): before your
agent retries a failed tool, check what other agents already tried and whether
it worked.

For hosts that can only start a local process. If your client speaks
Streamable HTTP, point it straight at `https://failecho.com/mcp` instead --
this package exists for the ones that cannot.

```bash
uvx failecho-mcp
```

```json
{
  "mcpServers": {
    "failecho": { "command": "uvx", "args": ["failecho-mcp"] }
  }
}
```

Four tools: `check_tool_failure` before a retry, and `report_tool_failure`,
`report_tool_success`, `report_recovery_outcome` to contribute. No account, no
API key. Set `FAILECHO_URL` to relay to your own server instead.

The relay stores nothing itself.

## Proxy: FailEcho in front of your other MCP servers

A model given FailEcho's tools has to think of asking, and while it is
handling a failure it mostly does not. The proxy puts the answer where the
model is already looking. Wrap the command a client would start:

```json
{
  "mcpServers": {
    "github": {
      "command": "uvx",
      "args": ["failecho-mcp", "proxy", "--", "npx", "-y", "@modelcontextprotocol/server-github"]
    }
  }
}
```

or a remote server (a header token works; OAuth does not -- connect those
directly):

```bash
uvx failecho-mcp proxy --header "Authorization: Bearer $TOKEN" -- https://mcp.example.com/mcp
```

Every message passes through unchanged, as the same bytes, except the
response to a tool call that failed. That one gets one line added:

```
FailEcho: try backoff, worked 128/251 (confidence 0.61).
```

-- or `no clear fix yet; other agents tried ...`, or `skip -- nothing other
agents tried recently has fixed this failure`, or nothing at all when the
network has no evidence. Nothing is acted on for you.

Each tool call's outcome is reported as its shape only: the server's name,
the tool name, an error class and code, the latency. Never arguments,
results or the error text. A call that failed transiently and is repeated
with the same arguments within two minutes is reported as a retry, and
whether it worked; the arguments are compared as a hash in memory and never
leave. Advice waits at most 3 seconds, holds only the failed response, and
if FailEcho is unreachable the error passes through unchanged.

An MCP server that wraps an API reports under its own name, so its failures
do not meet the evidence other agents filed under the API's host. Tell the
proxy which host each tool calls and, when the server's name has no advice,
it asks under that host and says so (`FailEcho (evidence from
api.github.com): ...`). Reports stay under the server's name.

```bash
uvx failecho-mcp proxy --upstream 'github_*=api.github.com' --upstream 'pypi_*=pypi.org' -- <server>
```

A bare host (`--upstream api.example.com`) covers every tool;
`FAILECHO_UPSTREAM` takes the same, comma-separated. The GitHub MCP server's
own names map to `api.github.com` without being told.

| Variable | Default | Purpose |
|---|---|---|
| `FAILECHO_DISABLED` | unset | `1`: a plain pipe, nothing reported or added |
| `FAILECHO_ADVISE` | `1` | `0`: report, but do not add advice |
| `FAILECHO_ENDPOINT` | `https://failecho.com` | Network to report to and read from |
| `FAILECHO_REPORTER_ID` | random per run | Stable id, so your machine counts as one reporter |

MIT.
