Skip to main content
Glama
Light Decision MCP
by light-cheng
README.md
<p align="center">
  <img src="./assets/icon.png" alt="Light Decision MCP" width="112" height="112" />
</p>

<h1 align="center">Light Decision MCP</h1>

<p align="center">
  <strong>Multi-backend Decision MCP &amp; Magpie Plugin for System One models</strong><br />
  Google <code>gemini-decision-1</code> · TypeSafe <code>Jev</code> · Perplexity Decisions · OpenAI <code>gpt-6-luna</code> · Local <code>OpenDecider</code> / Ollama / MLX
</p>

<p align="center">
  <strong>English</strong> | <a href="./README.zh-CN.md">简体中文</a>
</p>

---

**Light Decision MCP** (`light-decision-mcp`) is a zero-dependency, vendor-agnostic MCP server and [Magpie](https://usemagpie.ai) plugin that turns fast, typed **"System One" decision models** (`noul` / yes-no, `choice`, `score`) into clean agent tools—with calibrated probabilities, multimodal image input, hard data-destination boundaries, circuit-breaker local fallback, and a hardware-aware local model setup wizard.

## Highlights

- **Multi-Backend & Multi-Provider**: Route through a local **Magpie gateway** (zero keys stored in the plugin, inheriting Magpie rotation & privacy redaction), connect directly to **TypeSafe Jev**, **Perplexity Decisions API** (with optional `web_grounding`), **Google Gemini Decisions**, or **OpenAI Decisions**, or run **100% on-device** with local `opendecider serve` / Ollama / MLX.
- **3 Routing Modes + Instant Local Fallback**:
  - `api_with_local_fallback`: Cloud API primary with automatic local fallback on connection errors, timeouts, `429`, `5xx`, or an open circuit breaker window (0 ms primary skip).
  - `api_only`: Cloud/API backend only, fail fast.
  - `local_only`: On-device local backends only; automatically locks `max_data_destination = "on-device"`.
- **Cross-Protocol Alignment**: Normalizes `input` vs. `state` payloads and aligns `score` responses (`level` + `label` + probability-weighted `expected_level`/`score` + `probabilities` + `confidence` + `provider_confidence`) identically across Gemini, OpenDecider, TypeSafe Jev, Perplexity, and OpenAI.
- **Multimodal Safety Gate**: Supports local image files (magic-byte MIME checked, ≤10 MB), data URIs, and `https://` URLs. Never silently drops images when falling back to a text-only local backend unless explicitly opted in.
- **Dual Delivery (Zero External Dependencies)**:
  - **Magpie Plugin Tools → Library MCP** (covers HTTP/Hub agents: Antigravity, Claude Code, Codex, Cursor, Zed, Pi, etc.)
  - **Thin stdio MCP binary** (`bin/stdio.mjs`, covers Claude Desktop and any stdio-only MCP client)
- **Hardware-Aware Advisor & Setup Wizard**: `light-decision-mcp doctor`, `recommend`, and `setup` measure real host CPU/RAM/GPU/disk and guide local model and cloud provider setup without storing plaintext API keys.

## Routing Architecture

```mermaid
flowchart LR
  Agent["AI Agent<br/>(Magpie Hub / stdio MCP)"] --> Tools["light-decision-mcp<br/>decide · choose · yes_no · score · decide_batch · status"]
  Tools --> Router["Router + Data-Boundary Guard<br/>+ Per-Backend Circuit Breaker"]
  Router -->|"Primary (api_only / api_with_local_fallback)"| Cloud["Magpie Gateway / Cloud APIs<br/>Gemini Decision · Jev · Perplexity · gpt-6-luna"]
  Router -->|"local_only or Instant Fallback<br/>(timeout / 429 / 5xx / circuit open)"| Local["On-Device Local Models<br/>OpenDecider (:8001) · Ollama · MLX"]
```

## Visual Interfaces

### Standalone Local Admin Console (`light-decision-mcp ui`)

Runs on `127.0.0.1` only (CSRF-protected, zero Magpie required) with live backend & circuit-breaker monitoring, custom gateway editing, `0600`/Keychain key management, live playground, hardware advisor, and client config snippets.

<p align="center">
  <img src="./assets/screenshots/admin-overview-en.png" alt="Standalone Web Admin UI — Overview and Live Backends" width="820" />
</p>

<details>
  <summary>Routing Modes &amp; Custom Third-Party Gateways Editor</summary>
  <p align="center">
    <img src="./assets/screenshots/admin-routing-en.png" alt="Standalone Web Admin UI — Routing Modes and Custom Gateways" width="720" />
  </p>
</details>

### Magpie Embedded Settings Page

Automatically registered alongside the 6 MCP tools when installed as a Magpie plugin — matches Magpie's light/dark theme and language with zero background daemon.

<details>
  <summary>Magpie Plugin Settings Page Screenshot</summary>
  <p align="center">
    <img src="./assets/screenshots/magpie-page-en.png" alt="Magpie Embedded Settings Page" width="760" />
  </p>
</details>

---

## Quick Start

### 1. Install as a Magpie Plugin (Recommended)

```bash
# From GitHub (after publishing)
magpie plugin add github:light-cheng/Light-Decision-MCP

# Or from a local checkout
magpie plugin add /absolute/path/to/Light-Decision-MCP
```

Verify registration:

```bash
magpie plugin list
magpie tools
magpie tool status
```

Configure a cloud decision provider in Magpie (optional; plugin stores zero API keys):

```bash
magpie provider add google <YOUR_GOOGLE_AI_STUDIO_API_KEY>
# Also supported in Magpie: typesafe, openai, azure, bailian-decision, qwen-decision, volcengine-decision
```

Then enable `light-decision-mcp` per agent inside **Magpie → Library → MCP**.

### 2. Run Standalone Over stdio (Zero Magpie Required — Claude Desktop, Claude Code, Cursor, CC Switch, etc.)

`light-decision-mcp` is completely decoupled from Magpie. When no local Magpie gateway is present, it automatically disables Magpie and selects your configured direct provider (`GEMINI_API_KEY`, `TYPESAFE_API_KEY`, `PERPLEXITY_API_KEY`, `OPENAI_API_KEY`), cloud aggregator (**OpenRouter** `/api/alpha/decisions`), self-hosted gateway (**LiteLLM Proxy**), or local `opendecider` (`127.0.0.1:8001`). You can also register this stdio server in **CC Switch → MCP Servers** to sync it across Claude Code, Codex, Gemini CLI, and Hermes in one click.

```json
{
  "mcpServers": {
    "light-decision-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/Light-Decision-MCP/bin/stdio.mjs"],
      "env": {
        "GEMINI_API_KEY": "your-key-or-omit-to-use-local-opendecider"
      }
    }
  }
}
```

Or connect **OpenRouter** (`type: "systemone"`, `endpointPath: "/api/alpha/decisions"`), **LiteLLM Proxy** (`type: "openai-decisions"`, `http://127.0.0.1:4000`), or any custom Decisions / System One gateway in `~/.config/light-decision-mcp/config.json` (or via the one-click preset picker in `light-decision-mcp ui`):

```json
{
  "defaultBackend": "my-gateway",
  "backends": {
    "my-gateway": {
      "type": "openai-decisions",
      "enabled": true,
      "baseUrl": "https://gateway.example.com",
      "endpointPath": "/v1/decisions",
      "defaultModel": "gemini-decision-1",
      "apiKeyEnv": "MY_GATEWAY_KEY",
      "dataDestination": "private-network"
    }
  }
}
```

If you also use Magpie Library and want stdio registered for `claude-desktop`:

```bash
magpie library mcp add light-decision-mcp node /absolute/path/to/Light-Decision-MCP/bin/stdio.mjs agents=claude-desktop
```

### 3. Standalone Web Admin UI, Magpie Page, Key Management & Setup Wizard

- **Standalone Local Web Admin UI (No Magpie Required)**: Run `node ./bin/cli.mjs ui` (or `npm run ui`) to open a loopback-only (`127.0.0.1:4395`, CSRF-protected) browser console with live backend & circuit-breaker monitoring, custom third-party gateway editing, 0600/Keychain direct-key management, live decision playground, hardware recommendations, and one-click MCP client config snippets. Changes hot-reload automatically into running stdio MCP / Magpie instances.
- **Inside Magpie App**: Open the built-in **Light Decision** plugin page in Magpie's sidebar/pages tab for quick theme-matched routing & model controls with zero daemon process.
- **Direct Provider Keys (e.g. Perplexity Decisions, or standalone stdio)**:

```bash
# Store a direct provider key in 0600 ~/.config/light-decision-mcp/secrets.json
# (or add --keychain on macOS) — works in both GUI Magpie and stdio
node ./bin/cli.mjs key set PERPLEXITY_API_KEY
node ./bin/cli.mjs key list
```

- **Hardware Check, Local Model Recommendations & Interactive Setup**:

```bash
# Read-only hardware & backend health check
node ./bin/cli.mjs doctor

# Read-only local & cloud model recommendations based on measured hardware
node ./bin/cli.mjs recommend

# Interactive confirmation-gated setup wizard
node ./bin/cli.mjs setup
```

---

## Configuration

Precedence (highest to lowest):

1. Per-call tool arguments (`mode`, `backend`, `model`, `max_data_destination`, `web_grounding`)
2. Magpie plugin options (`magpie plugin options light-decision-mcp`)
3. User config file (`~/.config/light-decision-mcp/config.json` or `LIGHT_DECISION_CONFIG`)
4. Environment variables (`MAGPIE_GATEWAY`, `LIGHT_DECISION_MODE`, `LIGHT_DECISION_BACKEND`, `LIGHT_DECISION_FALLBACK_BACKEND`, `LIGHT_DECISION_MODEL`, `OPENDECIDER_URL`, `TYPESAFE_API_KEY`, `PERPLEXITY_API_KEY`, `GEMINI_API_KEY`, `OPENAI_API_KEY`)
5. Zero-config auto-discovery (local Magpie `gateway.json` + local `opendecider` at `http://127.0.0.1:8001/ready`)

Example `~/.config/light-decision-mcp/config.json` (**no plaintext API keys**—direct providers reference environment variable names via `apiKeyEnv`):

```json
{
  "version": 1,
  "routingMode": "api_with_local_fallback",
  "defaultBackend": "magpie",
  "fallbackBackend": "local-opendecider",
  "defaultModel": "google/gemini-decision-1",
  "timeoutMs": 25000,
  "primaryTimeoutMs": 15000,
  "fallbackTimeoutMs": 10000,
  "fallbackOnNotConfigured": false,
  "circuitBreaker": {
    "failureThreshold": 2,
    "cooldownMs": 30000,
    "maxCooldownMs": 120000
  },
  "maxDataDestination": "third-party",
  "backends": {
    "magpie": {
      "type": "magpie",
      "enabled": true,
      "defaultModel": "google/gemini-decision-1"
    },
    "local-opendecider": {
      "type": "systemone",
      "enabled": true,
      "baseUrl": "http://127.0.0.1:8001",
      "sendModel": false,
      "dataDestination": "on-device"
    },
    "typesafe": {
      "type": "systemone",
      "enabled": false,
      "baseUrl": "https://api.typesafe.ai",
      "defaultModel": "jev-latest",
      "apiKeyEnv": "TYPESAFE_API_KEY",
      "dataDestination": "third-party"
    },
    "perplexity": {
      "type": "perplexity",
      "enabled": false,
      "baseUrl": "https://api.perplexity.ai",
      "defaultModel": "pplx-decider-v1.3",
      "apiKeyEnv": "PERPLEXITY_API_KEY",
      "dataDestination": "third-party"
    }
  }
}
```

---

## Exposed Tools (6)

| Tool | Purpose | Key Inputs |
| :--- | :--- | :--- |
| `decide` | Answer multiple independent typed questions (`noul`, `choice`, `score`) over one state | `state`, `questions`, optional `images`, `mode`, `backend`, `model`, `max_data_destination`, `web_grounding` |
| `choose` | Single multiple-choice classification | `state`, `question`, `options` (`string[]` or `{label: desc}`), optional routing & `images` |
| `yes_no` | Single binary (`noul`) judgment | `state`, `question`, optional `true_description`, `false_description`, routing & `images` |
| `score` | Single ordered-rubric rating (lowest first) | `state`, `question`, `levels`, optional routing & `images` |
| `decide_batch` | Evaluate the same `questions` across up to 64 `states` (≤512 total items) with bounded concurrency | `states`, `questions`, optional routing |
| `status` | Read-only health, circuit-breaker, available models & capabilities probe | Optional filters: `backend`, `data_destination`, `multimodal` |

### Unified Response Shape

Every backend—including mid-flight local fallbacks—returns the same normalized structure:

```json
{
  "backend": "magpie",
  "model": "google/gemini-decision-1",
  "data_destination": "third-party",
  "fallback_used": false,
  "level": 2,
  "label": "high",
  "expected_level": 1.85,
  "score": 1.85,
  "probabilities": { "low": 0.02, "medium": 0.11, "high": 0.87 },
  "confidence": 0.87,
  "provider_confidence": 0.91,
  "latency_ms": 182.4,
  "usage": { "input_tokens": 42, "output_tokens": 0, "total_tokens": 42 }
}
```

When fallback triggers, `fallback_used` is `true` and `fallback_info` records `{ primary_backend, primary_model, reason, primary_status, circuit_state }`.

---

## Development & Tests

Requires Node.js ≥ 20 (or Bun). Zero npm install needed.

```bash
npm test
```

See [SPEC.md](./SPEC.md) for the full technical specification.

## License

[MIT](./LICENSE)