clef-mcp

clef-mcp

AI 编码 Agent 的“反射”：基于概率的结构化决策，而非散文。

本地 MCP 服务，让 Agent（Claude Code、Codex、Cursor、ZCode，……）通过单个工具 clef_decide 使用 Clef-Flash 决策模型（9B，Cloudflare 以 Apache-2.0 协议开源）。传入 state 和类型化问题，一次前向计算即可获得各选项的概率分布。完全本地运行、离线可用，不消耗令牌。

快速开始

# 1. Detect hardware, download the model (~6 GB) + llama.cpp runtime, verify checksum + inference
npx clef-mcp install

# 2. Register the MCP server + agent skill in your clients (zcode, claude-code, codex, cursor)
npx clef-mcp setup

# 3. Run the MCP server (stdio)
npx clef-mcp

clef-mcp（第 3 步）不会下载任何内容。如果缺少模型，工具调用会返回结构化的 MODEL_NOT_INSTALLED 错误并附带提示。第 1 步和第 2 步可合并执行：npx clef-mcp install --setup。

为什么不直接询问大模型？

最佳适用场景：Agent 工作循环中的决策点——下一步操作、路由、分类、严重程度、是非判断——每项任务会询问数十次。

clef_decide 工具

{
  "state": {
    "task": "Fix failing tests",
    "error": "TypeError: Cannot read properties of undefined"
  },
  "questions": {
    "next_action": {
      "type": "choice",
      "instructions": "What should the coding agent do next?",
      "criteria": {
        "inspect": "Inspect the code and gather more information",
        "modify": "Modify the code",
        "test": "Run additional tests",
        "ask_user": "Ask the user for clarification"
      }
    },
    "confidence": {
      "type": "score",
      "instructions": "How confident are you in this decision?",
      "criteria": ["very_low", "low", "medium", "high", "very_high"]
    },
    "is_outage": { "type": "noul", "instructions": "Is a service down?" }
  }
}

响应严格结构化，绝不使用散文。每项决策都包含模型报告的 confidence（运行时提供时），以及本次调用的令牌 usage：

{
  "model": "clef-flash",
  "decisions": {
    "next_action": { "answer": { "inspect": 0.72, "modify": 0.12, "test": 0.14, "ask_user": 0.02 }, "confidence": 0.83 },
    "confidence":  { "answer": { "very_low": 0.01, "low": 0.04, "medium": 0.18, "high": 0.61, "very_high": 0.16 }, "confidence": 0.61 },
    "is_outage":   { "answer": { "true": 0.9, "false": 0.1 } }
  },
  "usage": { "input_tokens": 228, "output_tokens": 0, "latency_ms": 512 }
}

仅当概率分布明确时才根据最大概率选项采取行动——对于破坏性操作或与安全相关的调用，最高概率 p ≥ 0.8 且 confidence 较高。

每次调用最多批量处理 64 个问题——所有问题都会在一次前向计算中评分。state 严格视为数据：绝不执行，也绝不解释为服务端指令。

提示词与资源

服务提供四种 MCP 提示词（预设的决策型请求，客户端通过 prompts/list 列出）：

以及三种资源（只读，无需模型）：

实测数据，而非营销宣传

Apple M4 Pro、Clef-Flash Q4_K_M（6 GB），通过完整 MCP stdio 路径发送单个请求：

质量门槛：30 个用例的评估数据集（编码 / 安全 / 分类 / 路由 / 是非题）——线上模型通过率为 86.7%。亲自运行：clef-mcp evals。

在 MCP 客户端中注册

claude mcp add clef-mcp -- clef-mcp
# or, without a global install:
claude mcp add clef-mcp -- npx -y clef-mcp

[mcp_servers.clef-mcp]
command = "clef-mcp"
args = []

{
  "mcpServers": {
    "clef-mcp": { "command": "clef-mcp", "args": [] }
  }
}

{
  "mcp": {
    "servers": {
      "clef-mcp": { "command": "clef-mcp", "args": [], "type": "stdio" }
    }
  }
}

现成的代码片段：examples/。

脚本与钩子

无需 MCP 客户端——钩子、CI 任务和 Shell 脚本都可以直接调用同一个模型：

# Full document on stdin
echo '{"state": "checkout 500s after deploy", "questions": {"is_outage": {"type": "noul", "instructions": "Is a service down?"}}}' \
  | clef-mcp decide

# Or split across files
clef-mcp decide --questions questions.json --state state.json

stdout 输出严格的 JSON 结果（格式与 MCP 工具相同，包括 confidence 和 usage）；错误以结构化 JSON 写入 stderr，并使用以下退出代码：2 输入无效，3 模型未安装，4 缺少运行时。decide 不会下载任何内容。

每次直接调用 decide 都会冷启动（包括模型加载，耗时数秒），适用于门禁检查和分流。若要重复调用，可启动一次 clef-mcp daemon：它会在 CLEF_HOME 中权限受限的 unix 套接字上保持模型热运行（不使用 TCP 端口，在 CLEF_DAEMON_IDLE 秒后卸载，默认值为 600），clef-mcp decide --daemon 可在不到一秒内响应；如果没有正在运行的守护进程，则回退到冷启动。有关 PreToolUse 防护和 GitHub Action 示例，请参阅 examples/hooks/。

当模型判定某条命令具有破坏性（p ≥ 0.9）时，PreToolUse 防护会阻止该命令，并告知 Agent 询问用户——阻止意味着暂停并升级处理，而不是彻底封锁；该门禁按设计仅提供建议，并会明确说明这一点。上线首日首次实际触发：它拦截了一次改写历史记录的强制推送（p=0.94），并发现了自身的绕过路径；该问题现已修复，并在示例中记录。

教会你的 Agent（技能）

架构定义了客户端可以向 clef_decide 传入什么；Agent 还需要知道何时使用它，以及如何组织决策。随附的 clef-decisions 技能涵盖决策模式、批处理、标准撰写、分布解读和错误恢复：

clef-mcp setup                                                    # automatic
cp -r skills/clef-decisions ~/.agents/skills/                     # manual, from repo
cp -r "$(npm root -g)/clef-mcp/skills/clef-decisions" ~/.agents/skills/  # from npm package

架构

flowchart LR
    subgraph clients [MCP clients]
        CC[Claude Code]
        CX[Codex]
        CU[Cursor]
        ZC[ZCode]
    end
    clients -- MCP stdio --> S[clef-mcp<br/>validation · limits · structured errors]
    S -- SystemOne adapter --> R[ClefRuntime<br/>llama.cpp subprocess<br/>127.0.0.1]
    R -- single forward pass --> M[("Clef-Flash<br/>9B · GGUF · local")]
    M -. probabilities .-> S -. strict JSON .-> clients

ClefRuntime 接口（load / decide / unload / health）将引擎隔离开来：MLX 或远程运行时都可以接入，而无需更改 MCP API。线路格式为 POST /v1/systemone——llama.cpp 和其他 Clef 运行时使用相同的契约。

CLI

clef-mcp              # run the MCP server on stdio (default command)
clef-mcp decide       # one-shot decision (no MCP session): JSON in, JSON out — for hooks, CI, scripts
clef-mcp daemon       # keep the model warm on a local unix socket; `decide --daemon` uses it
clef-mcp install      # detect hardware → download model + runtime → verify checksum → verify inference
clef-mcp setup        # register the MCP server + agent skill in zcode / claude-code / codex / cursor
clef-mcp models       # list models/quantizations and install status
clef-mcp status       # runtime, model, memory summary
clef-mcp doctor       # full diagnosis (platform, RAM, GPU, binary, model, checksum*, inference, MCP config)
clef-mcp uninstall    # remove the model (and optionally the managed runtime)
clef-mcp evals        # run the evaluation dataset against the installed model

参数：install --quant Q8_0 --yes --skip-probe、install --setup、setup --clients zcode,cursor --no-skill、doctor --deep（重新计算模型文件的哈希值）、uninstall --runtime --yes。

运行时：llama.cpp 和 MLX

两个本地运行时采用相同的 ClefRuntime 接口：

运行时可通过 CLEF_RUNTIME=mlx 切换（必须为 MCP 服务进程设置，例如在客户端的 env 块中设置）。两者都使用相同的 POST /v1/systemone 契约。MLX 快照通过 uv 管理的 huggingface_hub 下载到 CLEF_HOME 中（不使用全局 Python 状态），并固定在特定修订版本。

配置

运行时解析顺序：CLEF_LLAMA_BIN → CLEF_HOME/runtime 中的托管二进制文件 → PATH 上的 llama-server。

存储位置：CLEF_HOME/models/<model>/<quant>/（模型及包含仓库／修订版本／sha256／许可证信息的 manifest.json）和 CLEF_HOME/runtime/llama.cpp/。

模型从固定版本的官方 GGUF 转换版本（ggml-org/Clef-Flash-GGUF）下载，并根据 Hugging Face 的内容哈希进行 sha256 校验。clef-mcp 绝不会重新打包模型。它也已列入官方 MCP Registry，标识为 io.github.HighlyLoadedEgo/clef-mcp。

错误处理

{
  "error": {
    "code": "MODEL_NOT_INSTALLED",
    "message": "Clef model \"clef-flash\" is not installed.",
    "hint": "Run `clef-mcp install`."
  }
}

错误代码：MODEL_NOT_INSTALLED、MODEL_LOAD_FAILED、RUNTIME_NOT_FOUND、RUNTIME_INIT_FAILED、RUNTIME_NOT_SUPPORTED、INVALID_INPUT、CLEF_INFERENCE_FAILED、UNSUPPORTED_PLATFORM、OUT_OF_MEMORY、CHECKSUM_MISMATCH、DOWNLOAD_FAILED。如果输入超出模型的 16k-token 上下文限制，系统会拒绝处理，并提示缩减 state。

安全与数据处理

• 不运行网络服务，不进行遥测，不需要账户；所有操作都在本地运行。
• 仅在明确执行 install 时通过 HTTPS 下载模型，并校验校验和。
• state 内容会作为数据传递给模型；服务端绝不会执行或将其解释为指令。
• 文件系统访问仅限于 CLEF_HOME（doctor 中读取标准 MCP 客户端配置路径除外）。
• 托管运行时是官方 llama.cpp 构建版本；使用 CLEF_LLAMA_RELEASE_TAG 固定其版本。

完整政策请参阅 SECURITY.md。

开发

npm install
npm run build
npm test          # unit + integration (fake llama-server, no model needed)
npm run evals     # needs an installed model; exit code reflects pass rate

请参阅 CONTRIBUTING.md 和 tests/evals/dataset.jsonl。

许可证

• 代码：Apache-2.0。
• Clef / Clef-Flash 模型：© Cloudflare，Apache-2.0——请参阅 NOTICE。
• llama.cpp 运行时：© 其作者，采用 MIT 许可证；以官方预编译二进制文件形式下载。