clef-mcp

clef-mcp

AI コーディングエージェントの「反射神経」：文章ではなく、確率を伴う構造化された判断。

ローカルのMCPサーバーで、エージェント（Claude Code、Codex、Cursor、ZCode、…）が単一のツール clef_decide を通じてClef-Flashの意思決定モデル（9B、Cloudflare による Apache-2.0）を利用できます。state と型指定された質問を渡すと、1 回のフォワードパスで選択肢に対する確率分布が得られます。完全にローカルで、オフラインで動作し、トークンを消費しません。

クイックスタート

# 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 でまとめて実行できます。

LLM にそのまま尋ねるのではだめですか？

最適な用途は、エージェントのループ内の判断ポイントです。次のアクション、ルーティング、分類、重大度、はい／いいえの判断などを、タスクごとに何十回も尋ねる場面です。

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 }
}

破壊的な呼び出しやセキュリティに関わる呼び出しでは、分布が明確な場合に限り、argmax に基づいて実行してください。つまり、最上位の p が 0.8 以上で、confidence も高い場合です。

1 回の呼び出しで最大64 件の質問をまとめて処理できます。すべて 1 回のフォワードパスでスコア付けされます。state は厳密にデータとして扱われ、実行されることも、サーバーへの指示として解釈されることもありません。

プロンプトとリソース

サーバーには MCP のプロンプト（あらかじめ用意された、判断形式の質問）が 4 つ含まれています。クライアントは prompts/list を通じて一覧を取得します。

また、リソースが 3 つあります（読み取り専用で、モデルは不要です）。

宣伝文句ではなく、実測値

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 ジョブ、シェルスクリプトから同じモデルをワンショットで呼び出せます：

# 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 形式の結果が出力されます（confidence と usage を含み、MCP ツールと同じ形式です）。エラーは構造化 JSON と終了コードで stderr に出力されます：2 は入力が無効、3 はモデルが未インストール、4 はランタイムが見つからない場合です。decide が何かをダウンロードすることはありません。

decide を通常どおり呼び出すたびにコールドスタートになります（モデルの読み込みを含めて数秒）。ゲートやトリアージには十分です。繰り返し呼び出す場合は、clef-mcp daemon を一度起動してください。モデルを CLEF_HOME 内のアクセス権を制限した Unix ソケット上でウォーム状態に保ちます（TCP ポートは使用せず、CLEF_DAEMON_IDLE 秒後にアンロードします。既定値は 600 秒です）。clef-mcp decide --daemon は 1 秒未満で応答し、デーモンが起動していない場合はコールド実行にフォールバックします。PreToolUse ガードと GitHub Actions のレシピについては、examples/hooks/ をご覧ください。

PreToolUse ガードは、モデルがコマンドを破壊的と判断した場合（p ≥ 0.9）にブロックし、エージェントにユーザーへの確認を求めるよう伝えます。ブロックは一時停止とエスカレーションであり、行き止まりではありません。このゲートは設計上、助言を目的としており、その旨も明示します。初日に実際に発動した際は、履歴を書き換える force push（p=0.94）を検出し、独自のバイパス経路も明らかにしました。その経路は現在修正済みで、レシピにも記載されています。

エージェントに教える（スキル）

スキーマはクライアントに clef_decide が何を受け付けるかを伝えます。エージェントには、いつ利用し、意思決定をどのように組み立てるかも知る必要があります。同梱の 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）によってエンジンが分離されており、MCP API を変更せずに MLX やリモートランタイムを組み込めます。ワイヤ形式は 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 インターフェースの背後で動作する 2 つのローカルランタイム：

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 トークンを超える入力は、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 ライセンス。公式のビルド済みバイナリとしてダウンロードされます。