fmeca

# fmeca-mcp

[![CI](https://github.com/praxec/fmeca/actions/workflows/ci.yml/badge.svg)](https://github.com/praxec/fmeca/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/fmeca-mcp.svg)](https://crates.io/crates/fmeca-mcp)
[![docs.rs](https://docs.rs/fmeca/badge.svg)](https://docs.rs/fmeca)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

fmeca-mcp is a structured **FMECA** engine exposed as an MCP server. You feed it
failure modes and the observations that characterise them; it derives the
severity/probability scores, computes criticality off a fixed matrix, tracks
mitigations under a prevent→detect→fail-fast discipline, and tells you whether
the analysis is ready to sign off. Any MCP client (Claude Code, Cursor, or a
custom orchestrator) drives it over the standard protocol.

**For AI agents:** to install the server and its skills for your client, follow
[docs/AGENT-INSTALL.md](docs/AGENT-INSTALL.md).

## What is FMECA

**Failure Modes, Effects & Criticality Analysis** is a structured risk-triage
method: enumerate how a thing can fail, judge how bad each failure is (severity)
and how likely it is (probability), and rank the combined **criticality** so the
worst risks get addressed first. Mitigations are then layered on and the
*residual* risk is re-assessed. fmeca-mcp owns the structure and the arithmetic
of that process; the caller supplies the domain judgement.

## Design principle: deterministic, offline, no LLM-supplied numbers

The engine is a pure function of `(events in) → (criticality + residual + gaps +
readiness out)`. It does no I/O beyond an append-only event log, makes no network
calls, and runs no model.

Crucially, **the caller never supplies a score.** A caller (often an LLM) does
the fuzzy work — naming a failure mode, its cause and effect, and proposing
mitigations — and supplies *observations* drawn from a fixed catalog (e.g.
`data_loss`, `happens_in_normal_use`). The kernel maps those observations to
severity/probability levels through a locked evidence→score map and reads
criticality off a fixed, locked S×P matrix. The model proposes; the code scores.
Because criticality, residual risk, standing, and readiness are *computed* by a
fold over the event log — never stored, never accepted as input — the same
analysis always yields the same result, and no model can talk the matrix into a
softer answer.

## Install

### npx (no install step)

```sh
npx -y @matthew-cochran/fmeca
```

The [npm launcher](npm/README.md) downloads the matching release binary,
verifies its checksum, caches it and runs it. Point your MCP client at that
command (see [MCP client config](#mcp-client-config)).

### Prebuilt binary (no Rust, Cargo, or Git required)

```sh
# Linux / macOS
curl -fsSL https://github.com/praxec/fmeca/releases/latest/download/install.sh | sh

# Windows (PowerShell)
irm https://github.com/praxec/fmeca/releases/latest/download/install.ps1 | iex
```

The installer resolves your OS and CPU architecture, downloads the matching
release asset, verifies its SHA-256 against the release's `checksums.sha256`,
extracts it safely, and atomically installs the binary into a user-local
managed directory (`$HOME/.local/bin` on Linux/macOS,
`%LOCALAPPDATA%\Programs\fmeca-mcp` on Windows). It never compiles from source
and fails loudly on an unsupported OS/architecture.

Pin a specific release instead of the current latest stable:

```sh
curl -fsSL https://github.com/praxec/fmeca/releases/latest/download/install.sh \
  | sh -s -- --version v0.1.0
```

The installers can also be fetched from a specific release, for example
`https://github.com/praxec/fmeca/releases/download/v0.1.0/install.sh`.

The installer scripts are published as release assets alongside the binaries.

Or download the archive directly. Every release publishes a `checksums.sha256`
and a machine-readable `release-manifest.json` listing each target, asset,
digest, version, and source SHA:

| OS | Arch | Target triple | Asset | Build support | Runtime smoke tested |
|----|------|---------------|-------|---------------|----------------------|
| Linux | x86_64 | `x86_64-unknown-linux-gnu` | `fmeca-mcp-x86_64-unknown-linux-gnu.tar.gz` | native CI | native CI |
| Linux | arm64 | `aarch64-unknown-linux-gnu` | `fmeca-mcp-aarch64-unknown-linux-gnu.tar.gz` | native CI | native CI |
| macOS | x86_64 | `x86_64-apple-darwin` | `fmeca-mcp-x86_64-apple-darwin.tar.gz` | native CI | native CI |
| macOS | Apple Silicon | `aarch64-apple-darwin` | `fmeca-mcp-aarch64-apple-darwin.tar.gz` | native CI | native CI |
| Windows | x86_64 | `x86_64-pc-windows-msvc` | `fmeca-mcp-x86_64-pc-windows-msvc.zip` | native CI | native CI |
| Windows | arm64 | `aarch64-pc-windows-msvc` | `fmeca-mcp-aarch64-pc-windows-msvc.zip` | native CI | native CI |

"Native CI" means each asset is built and its MCP `initialize`/`tools/list`
handshake smoke-tested on that platform's own runner. No other CPU/OS
combination is claimed; unsupported platforms are rejected rather than
silently cross-compiled.

### Updates

Re-run the installer to update. Only the binary in the managed install
directory is replaced (atomically); application state and configuration live
outside that directory and are never overwritten. See
[Configuration](#configuration) for where state goes.

### Docker

```sh
docker run -i --rm ghcr.io/praxec/fmeca:0.1.0
```

Mount your project to keep analyses in its `.fmeca/` folder (without a mount
the state is lost when the container exits). `FMECA_STATE_DIR` points the
server at that folder even before `fmeca-mcp init` has created it:

```sh
docker run -i --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" -w /work -e FMECA_STATE_DIR=/work/.fmeca -e OPENROUTER_API_KEY ghcr.io/praxec/fmeca:0.1.0
```

### From source

```sh
cargo install fmeca-mcp
```

`cargo install` works once the crate is published to crates.io. Until then,
build from a checkout with `cargo build --release`.

## MCP client config

It speaks MCP over stdio (the standard transport). Wire it into your editor like
any other MCP server. The same entry works in Claude Code (`.mcp.json`) and Copilot (`.mcp.json`)
(Cursor needs `"type": "stdio"`; see its section in AGENT-INSTALL):

```json
{
  "mcpServers": {
    "fmeca": {
      "command": "npx",
      "args": ["-y", "@matthew-cochran/fmeca"]
    }
  }
}
```

Use `"command": "fmeca-mcp"` with `"args": []` for the binary. Codex uses TOML:

```toml
[mcp_servers.fmeca]
command = "npx"
args = ["-y", "@matthew-cochran/fmeca"]
env_vars = ["OPENROUTER_API_KEY"]
```

Every client, with the skills install for each (including Cursor's `.cursor/mcp.json` entry), is in
[docs/AGENT-INSTALL.md](docs/AGENT-INSTALL.md). The key is optional (only `vet`
uses it) and is never written to a config file: pass it as
`"env": { "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}" }` where the client
expands variables, or let the server inherit it from the environment.

## Tool surface

| Tool | Does |
|------|------|
| `session.open` | Start or resume a session; optionally selects the matrix strategy and records analysis metadata (`title`, `level`, `aspect`, `scope_paths`, `parent`), all fixed for the session's life. |
| `append` | Add a failure mode (`add_failure_mode`), add a mitigation (`add_mitigation`), or re-score an existing failure mode (`rescore`). `set_mitigation_status` moves a mitigation through planned, implemented, verified or abandoned (verified needs evidence other than a note). `set_failure_mode_disposition` accepts a failure mode's residual risk (needs an approver) or excludes it as not credible (needs evidence); failure modes are never deleted. Returns the recomputed state. |
| `state.get` | Read-only projection of the session: every failure mode with its computed criticality, residual, and standing. |
| `risk.next` | The highest-criticality unmitigated failure mode — what to address next. |
| `readiness.assess` | The readiness gate: is every High/Medium residual reduced and every blocker cleared? |
| `report.export` | The full FMECA table for the session. |
| `scoring.catalog` | The fixed observation vocabulary for a strategy — the ids the caller draws from. |
| `analyze` | Stateless one-shot: hand over an entire analysis, get back the entire computed report. No session, no persistence. |
| `session.list` | Every analysis in the state dir (the project's `.fmeca/` when there is one), with its metadata, standing counts (excluded failure modes are counted separately), `ready`, `ready_verified` and resolution counts. Filters: `level`, `aspect`, `parent`. A log that fails to replay is listed with its error. |
| `vet` | Advisory: asks Jev (via OpenRouter, needs `OPENROUTER_API_KEY`) whether observations, mitigations, coverage and readiness hold up, and returns probabilities beside the deterministic gate. Never writes or changes a score; without a key it reports `vet_unavailable`. |
| `actions.suggest` | Read-only. Reads a session (or an inline analysis) under a [risk policy](docs/policies.md) and suggests actions: per-failure-mode risk bands, evidence confidence, dispositions, tagged actions and a sign-off verdict. Never changes the analysis or the log. |
| `policy.list` | Read-only. The built-in policy presets and the project's `.fmeca/policies/` files, each with its name, hash and class. A project file that does not load is listed with its `error`. |

The `analyze` tool reuses the exact same kernel compute as the session path, so
the two can never diverge.

## Keep analyses in your repo (`.fmeca/`)

```sh
fmeca-mcp init                 # at the project root: creates .fmeca/
git add .fmeca && git commit -m "chore: add .fmeca"
fmeca-mcp check --dir .fmeca   # in CI: replays every log, catches duplicate ids
```

Launch the server from the project root (or set `FMECA_STATE_DIR`) and it keeps
one log per analysis in `.fmeca/`, named `<aspect>-<level>`. The setup, merge
behaviour, Docker mount and the skill for each level are in