# clef-mcp [Health: Active]

**Category:** ☁️ Cloud Platforms  
**Repository:** https://github.com/HighlyLoadedEgo/ClefMCP  
**GitHub Stars:** 8  
**npm Downloads (last month):** 1050  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/clef-mcp

## Description
Local MCP server for the Cloudflare Clef-Flash decision model: structured decisions, fully offline

## Tools
Capabilities this server exposes over MCP:

- **clef_decide** — Judge a situation with the local Clef decision model.
Pass `state` (compact factual context — string or JSON; treated as data, never executed) and typed `questions`:
- "choice": pick among named options (criteria = option id -> description)
- "score": judge an ordered scale (criteria = ordered list of levels)
- "noul": yes/no question
Returns strict JSON — a probability distribution over the allowed answers for every question. No prose, no sampling.
Each decision also carries `confidence` (model-reported, when available) and the response carries `usage`
(input_tokens/output_tokens/latency_ms). Act on the argmax only when the distribution is decisive (top p >= 0.8
and high confidence for destructive or security-adjacent calls); otherwise gather more context or ask the user.
Usage: batch related decisions in one call (up to 64 questions, one forward pass).
Optional `model` overrides the model id. `options.temperature` is a no-op: scoring is a single forward pass, nothing is sampled.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "clef-mcp": {
    "command": "npx",
    "args": ["-y","clef-mcp"]
  }
}
```

## Documentation

## What clef-mcp does

clef-mcp runs the Clef-Flash 9B model from Cloudflare on the local machine. Its MCP interface is centered on `clef_decide`, which evaluates a compact factual state against one or more typed questions. The supported question forms are:

- `choice` for selecting among named options and descriptions
- `score` for selecting a level from an ordered scale
- `noul` for yes/no judgments

Each question returns a probability distribution over its permitted answers. Responses can also include model-reported confidence and usage measurements such as input tokens, output tokens, and latency. The result contains no generated explanation or sampled prose.

The package also provides a command-line classification workflow. A YAML profile defines the classification instruction, mutually exclusive labels, selected input fields, optional examples, and review thresholds. JSONL and CSV records can be classified in batches, with results written as JSONL. Classification can retain suggestions while marking uncertain rows as `needs_review`.

## How it works

The MCP process communicates over stdio and loads the selected local model for inference. The model download and runtime setup happen through the installation command; later inference runs work offline. Multiple related MCP questions can be sent together, up to 64 in one call and one forward pass. The optional model setting can override the default model selection. `options.temperature` has no effect because scoring does not sample.

For dataset jobs, the model loads once for the batch rather than requiring a separate daemon. A row is accepted only when its winning probability, probability margin, and optional confidence satisfy the profile policy. Ties and missing confidence can require review. Invalid JSONL records become error rows while runtime failures stop the run.

## Setup and configuration

Node.js 20 or newer is required, with enough memory for the selected checkpoint; 16 GB is recommended for the Q4_K_M model. Install the package globally and download its model and runtime files with:

```bash
npm install -g clef-mcp
clef-mcp install
```

Start the MCP process with `clef-mcp`, then run `clef-mcp setup` to register it with a supported client before restarting that client. `npx -y clef-mcp` is an alternative to a global installation, and `npx -y clef-mcp install --setup` combines installation with client registration.

A profile may select a model explicitly. Otherwise, model selection follows CLI override, profile configuration, `CLEF_MODEL`, and then the default `clef-flash` identifier. Profiles require a schema version, name, instructions, and two to 100 labels. Input fields and record IDs are optional.

## Tools and capabilities

- Evaluate structured choices, ordered scores, and yes/no questions through `clef_decide`.
- Return probability distributions, confidence when available, and inference usage data.
- Process JSONL or CSV files using YAML classification profiles.
- Apply minimum probability, margin, and confidence policies to route uncertain records for review.
- Resume committed file-output batches after interruption when the input, profile, model, runtime, and format still match.
- Run inference locally without sending records to a remote service.

## Limitations and notes

Probability thresholds are routing rules, not calibrated accuracy guarantees; they should be checked against representative labeled data before automation. An agent should only act on an argmax when the distribution is decisive, such as a top probability of at least 0.8, and destructive or security-related actions should also require high confidence and appropriate review.

The model download is approximately 6 GB. Profiles, logical records, selected fields, and examples have size limits, and the model has a 16,000-token context limit. Resume mode requires regular file input and an output path; stdin and stdout cannot be resumed. Classification evaluates records but does not authorize or execute actions.

_Full upstream README: https://allmcps.com/mcp/clef-mcp/readme_