lema-mcp

Your coding agent can read the code. It can't read the argument behind it. lema-mcp gives your agent the recorded why — and the alternatives a project already ruled out — cited to the source. For React, Kubernetes, and Rust out of the box, and for your own repo with one command.

A local MCP server. No account, no database, no network for your own repo — install it in 30 seconds and ask why a project decided something, or whether the approach you're about to take was already rejected.

❌ Without lema

• The agent invents the why from training recall — fluently, and sometimes wrongly. The rationale lives in RFC / KEP / PR threads; it was never in the code.
• It re-proposes the approach the maintainers already rejected two years ago — because a rejected alternative leaves no trace in the source.
• Ask "was this ever ruled out?" and you get a confident guess, with no way to tell a real ruling from a hallucinated one.

✅ With lema

• One cited answer from the project's actual recorded deliberation — every [n] links to the RFC / PR where the call was made.
• A typed ruled_out verdict when a project already rejected your approach, with the recorded reason and a pointer to where the docs say to do it instead.
• A typed settled verdict when your approach is the project's in-force recorded choice — the governing decision cited, with a docs pointer for the how.
• An honest "no recorded ruling" when the record is silent — which means unknown, not approved. lema never fills the gap with a guess.

lema holds reasoning — why a decision was made, what was rejected — not API syntax or code samples. For those, reach for a docs tool. lema is the right place for why.

Try it in 30 seconds — no account

npx lema-mcp try react        # or: kubernetes · rust

That writes a read-only public server to your project's .mcp.json. Reload your agent's MCP servers (in Claude Code: /mcp) and try the flagship tool, check_approach — name a direction, get the recorded verdict:

> "Let's add a delayMs prop to Suspense to debounce the fallback."   (repo: react)

  ⛔ ruled_out — the React team considered and rejected this.
     "<the recorded rationale, summarized — not a quote>"  [1]
     Where to look instead →  https://react.dev/reference/react
     [1] reactjs/rfcs#212

> "I'll add a global event bus for cross-component communication."   (repo: react)

  ◦ no_recorded_ruling — React's public record doesn't settle this.
     (Unknown — not approved.)

Or just ask in plain language — "why did React adopt Hooks over mixins?" — and get one cited answer, with an honest abstain when the record is silent.

Covered today: React · Kubernetes · Rust, served from lema's public API (api.lema.sh). Tokenless. It's a curated three-project demo corpus — not analytics over a graph you own.

Install

No-account public demo (React's recorded decisions, zero setup):

If the Cursor button doesn't open an install prompt (common when the browser can't hand off the cursor:// deeplink), paste this into .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "lema": {
      "command": "npx",
      "args": ["-y", "lema-mcp@latest"],
      "env": { "LEMA_MCP_MODE": "public", "LEMA_PUBLIC_REPO": "react-rfcs" }
    }
  }
}

That drops you into React's public record — ask "why did React rule out X?" and get a cited answer, no account. To wire your own repo for capture, or point the demo at Kubernetes or Rust, use the per-client setup below.

npx needs only Node — no Go toolchain, no account. Two commands cover both ways to use lema:

npx lema-mcp try react   # read-only: ask React/Kubernetes/Rust why + what's ruled out
npx lema-mcp init        # your repo: decision capture + the never-reopen guard

Both are non-destructive and idempotent — they merge into existing config and re-running changes nothing. init and try share the same lema server key; the authed init server is a superset (it serves the public tools too), so the two coexist and try never downgrades it.

npx lema-mcp init        # or: npx lema-mcp try react

{
  "mcpServers": {
    "lema": { "command": "npx", "args": ["-y", "lema-mcp@latest"] }
  }
}

{
  "mcpServers": {
    "lema": { "command": "npx", "args": ["-y", "lema-mcp@latest"] }
  }
}

{
  "mcpServers": {
    "lema": {
      "command": "npx",
      "args": ["-y", "lema-mcp@latest"],
      "env": { "LEMA_MCP_MODE": "public", "LEMA_PUBLIC_REPO": "react-rfcs" }
    }
  }
}

{
  "mcpServers": {
    "lema": {
      "command": "npx",
      "args": ["-y", "lema-mcp@latest"],
      "env": { "LEMA_MCP_MODE": "public", "LEMA_PUBLIC_REPO": "react-rfcs" }
    }
  }
}

{
  "mcpServers": {
    "lema": { "command": "npx", "args": ["-y", "lema-mcp@latest"] }
  }
}

{
  "servers": {
    "lema": { "command": "npx", "args": ["-y", "lema-mcp@latest"] }
  }
}

go install github.com/lemahq/lema-mcp/cmd/lema-mcp@latest

The public config sets only LEMA_MCP_MODE + LEMA_PUBLIC_REPO (react-rfcs · k8s-enhancements · rust-rfcs) — the API URL is compiled in.

Hosted teams: sign in once; the repository resolves automatically

After you sign in to Lema, save one Organization-scoped credential outside your repositories. The normal setup contains identity credentials, not a copied workspace UUID:

# ~/.config/lema/credentials
LEMA_API_URL=https://api.lema.sh
LEMA_API_TOKEN=lema_live_...

chmod 600 ~/.config/lema/credentials
npx lema-mcp@latest doctor context

Restart the coding agent after changing MCP configuration. From then on, Lema matches the checkout's verified Git remote to a Repository, finds its Project, and passes one immutable target receipt to every operation. Opening two repositories in parallel does not create a mutable “active repository,” and each user keeps their own Organization-scoped credential.

For multi-repo Projects, ambiguity recovery, repositories without a remote, worktrees, and compatibility overrides, read Target context: Projects, repositories, and Runs.

Two ways to use it

1. The public record — React, Kubernetes, Rust (read-only, no account)

Ask why a popular project decided something, or check whether a direction was already rejected, over its recorded RFC/KEP deliberation. This is the try server.

2. Your own repo — capture + never-reopen (local, no account)

Most "context" tools are read-only — a nicer way to grep your docs. lema reads too, but its real job is never-reopen:

• Your agent settles a choice → it calls record_decision with the option it chose and the alternatives it rejected, with why each was killed (the part that never survives into the code).
• Before anyone proposes a direction → check_decided returns the prior decision if that option is CLOSED.
• On every edit, a PreToolUse guard hook (installed by init) reads the draft change and surfaces a CLOSED decision before the dead option gets re-proposed — enforced off both your captured decisions and the repo's own ADRs.

Decisions are captured to .lema/decisions.jsonl — a plain append-only file you commit, so your whole team's agents share the same memory through git. No key, no LLM call on our side: your agent forms the decision; lema stores it and serves it back.

What never-reopen looks like

Your agent reaches for an option you already killed — and it comes back CLOSED, with the original reason attached: