Fmeca README

fmeca-mcp

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.

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)

npx -y @matthew-cochran/fmeca

The npm launcher downloads the matching release binary, verifies its checksum, caches it and runs it. Point your MCP client at that command (see MCP client config).

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

# 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:

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:

"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 for where state goes.

Docker

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:

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

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):

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

Use "command": "fmeca-mcp" with "args": [] for the binary. Codex uses 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. 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

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/)

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 docs/AGENT-INSTALL.md.

Risk policies

A risk policy reads an analysis through your project's own risk bands, sets a sign-off rule, and suggests tagged actions (design, review, test, ops, process, docs, security). It is computed when you ask and is never written to the log, so one analysis can be read under several policies. fmeca suggests; it never acts.

Presets: compat-0.1 (the default; its sign-off equals readiness.assess), prototype, standard, business-critical, safety-critical and confidence-view. Your own policies are TOML files in .fmeca/policies/<name>.toml and resolve after the presets.

fmeca-mcp policy list                                   # presets and project files
fmeca-mcp policy validate .fmeca/policies/team.toml     # ok <name> <hash>, or the error
fmeca-mcp suggest checkout-implementation --policy standard --format markdown

suggest exits 0 when the policy's sign-off passes, 1 when it fails (usable in CI) and 2 on a usage or policy error. Agents call the same thing as the actions.suggest and policy.list tools. The model, every preset and the action catalog are in docs/policies.md.

Configuration

Matrix strategies

The criticality matrix is a closed, code-resident strategy selected at session.open (and fixed for the session's life). Each strategy ships with a locked S×P matrix and its own scoring catalog:

The caller selects a strategy; it never edits a strategy's cells.

Use fmeca as a library

The kernel is a plain Rust library, independent of MCP. The stateless analyze function takes a strategy and a batch of failure modes and returns the full computed report:

use fmeca::{
    analyze, AnalyzeInput, AnalyzeMitigation, Domain, EntityRef, MatrixStrategy, MitigationKind,
};

let failure_modes = vec![AnalyzeInput {
    id: "fm-1".into(),
    component: EntityRef::new("checkout-service"),
    description: "Payment double-charge on retry".into(),
    cause: Some("Non-idempotent charge endpoint".into()),
    effect: Some("Customer billed twice".into()),
    domain: Domain::Runtime,
    scope: None,
    // Observations, not scores — the kernel derives severity/probability.
    severity_observations: vec!["data_loss".into()],
    probability_observations: vec!["happens_in_normal_use".into()],
    mitigations: vec![AnalyzeMitigation {
        id: "m-1".into(),
        kind: MitigationKind::Prevention,
        description: "Idempotency key on the charge endpoint".into(),
        residual_severity_observations: vec![],
        residual_probability_observations: vec!["rare_edge_case".into()],
    }],
}];

let report = analyze(MatrixStrategy::default(), &failure_modes).unwrap();
println!("risk ranking: {:?}", report.risk_ranking);
println!("ready: {} blockers: {:?}", report.ready, report.blockers);
// report.failure_modes carries per-FM criticality / residual_criticality /
// standing / response_class / issues.

For long-lived, multi-turn analyses use fmeca::Engine over a StateStore (a FilesystemStore is provided), which persists an append-only event log and replays it to compute state. See the API docs.

Development

cargo build
cargo test
cargo fmt --all
cargo clippy --all-targets -- -D warnings

The agent skills under skills/ are embedded in the binary at build time. After adding or removing a skill, a local incremental build does not notice; run touch crates/fmeca-mcp/build.rs and build again.

CI runs build + test on Linux/macOS/Windows, plus rustfmt and clippy (warnings are denied). Please make sure those pass locally before opening a pull request.

Using it with Praxec

This is an MCP tool used by Praxec packs. The easiest way to get it — and a workflow pack that uses it — up and running is the one-command setup:

curl -fsSL https://raw.githubusercontent.com/praxec/packs/main/setup.sh | bash

See the pack registry for this tool's provider coordinates (container image / release binary) and which packs depend on it.

License

Apache-2.0.