codex-dev-mcp-suite 1.2.0 → 1.4.0

package/.env.example

@@ -40,6 +40,25 @@ MCP_RERANK_MODEL=llama3.1:8b
 RERANK_TIMEOUT_MS=30000
 RERANK_ENABLED=1
 
+
+# === Cloudflare Workers AI (REST-only, NOT OpenAI-compatible) ===
+# Free tier: 10,000 neurons/day. No laptop resource usage.
+# To get started: dash.cloudflare.com → Workers & Pages → Create Worker → Workers AI → enable
+# Account ID: from dashboard sidebar. API Token: My Profile → API Tokens → "Edit Cloudflare Workers".
+# Note: base URL has trailing slash; model name goes in URL path, not body.
+# Set CLOUDFLARE_EMBED_MODEL (e.g. @cf/baai/bge-base-en-v1.5) to enable semantic recall
+# via Cloudflare instead of 9router/OpenAI/etc.
+# MCP_EMBED_BASE_URL=https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai/run/
+# MCP_EMBED_API_KEY=<cf-token>
+# MCP_EMBED_MODEL=@cf/baai/bge-base-en-v1.5
+
+# === Google Gemini (OpenAI-compatible, generous free tier) ===
+# Get key: https://aistudio.google.com/app/apikey
+# Free tier: 60 req/min, 1500/day for text-embedding-004
+# GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
+# GEMINI_API_KEY=<gemini-key>
+# GEMINI_MODEL=text-embedding-004
+
 # Storage locations (defaults shown; override if you want)
 # MEMORY_VAULT_DIR=~/.codex/memories/vault
 # JOURNAL_DIR=~/.codex/memories/journal

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 1.4.0 - 2026-06-17
+
+### Added
+- **`provider-smoke` CLI** (`bin/provider-smoke.mjs`): probe every configured LLM provider (chat + embeddings) and print a matrix of latency / status / sample. Useful after adding a new API key or comparing providers.
+  - Usage: `npx -y -p codex-dev-mcp-suite provider-smoke` (or globally `provider-smoke`)
+  - Flags: `--json`, `--markdown`, `--save-md <path>`, `--chat-only`, `--embed-only`, `--env-file <path>`, `--only a,b,c`, `--timeout <ms>`, `--help`, `--version`
+  - Auto-detects providers from `MCP_PROVIDER_*` slots + named env (`GROQ_*`, `CEREBRAS_*`, `MISTRAL_*`, `OPENROUTER_*`, `OPENAI_*`, `OLLAMA_*`, `ANTHROPIC_*`, `GEMINI_*`, `COHERE_*`, `VOYAGE_*`, `CLOUDFLARE_*`) + `MCP_LLM_BASE_URL` / `NINEROUTER_URL` fallback.
+  - Pure-function library at `lib/provider-smoke.js` (18 offline tests).
+  - `KNOWN_PROVIDERS` registry covers 11 providers with `supportsChat` / `supportsEmbed` flags + `endpoint: "openai-compatible" | "cloudflare"`.
+  - Cloudflare embed-only models (`@cf/baai/*`, `@cf/google/embedding*`, etc.) are detected and the chat probe is skipped with a clear annotation.
+- **Cloudflare Workers AI support** for embeddings: drop-in alternative when 9router/OpenAI are unavailable. Set `MCP_EMBED_BASE_URL=https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai/run/`, `MCP_EMBED_API_KEY=<token>`, `MCP_EMBED_MODEL=@cf/baai/bge-base-en-v1.5`.
+  - Cloudflare's REST API (non-OpenAI-compatible, model-in-path) is auto-detected by URL pattern and dispatched to a separate code path in `project-memory/embedding.js`.
+  - New `isCloudflareURL()` + `httpPostJson()` helpers; `embedCloudflare()` handles `{text: [...]}` body and `{result: {data: [[...]]}}` response.
+  - `embeddingConfig().mode` and `recallMode()` helpers expose what retrieval mode is active (`semantic` / `keyword` / `deterministic`).
+- **`memory_recall` mode arg** (default `"auto"`): explicit control over fallback behavior. `mode: "semantic"` requires embedding (returns `isError: true` if unavailable), `mode: "keyword"` skips embedding entirely.
+- **Recall output annotation** now shows `[semantic+rerank]` / `[keyword+rerank]` when LLM rerank is active, making the active mode fully transparent.
+- **Top-level test runner hook** (added in 1.3.0, expanded in 1.4.0): `tests/*.test.mjs` are auto-picked-up by `node run-tests.mjs`.
+
+### Tests
+- 85 tests pass (was 60 in v1.3.0): 26 project-memory + 6 checkpoint + 6 context-pack + 11 devjournal + 18 provider-smoke + 9 prune + 9 stats.
+- New fallback tests: `mode=keyword` skips semantic, `mode=semantic` without embed key returns isError, default mode=auto, no `+rerank` suffix when rerank disabled.
+
+### Docs
+- `docs/providers.md` rewritten: 11-provider matrix, Cloudflare setup caveat, Ollama resource cost, "no API key" graceful degradation notes.
+- `README.md` updated: "Memory Recall Modes" section, Cloudflare + Gemini setup examples, 4-mode annotation examples.
+- `.env.example` updated: copy-pasteable config blocks for Cloudflare Workers AI and Google Gemini.
+
+
+
+## 1.3.0 - 2026-06-17
+
+### Added
+- New `stats` CLI: summarize local memory storage across vault / journal / checkpoints. Shows totals, top projects by notes, most recent activity, and temp-slug cleanup candidates.
+  - Usage: `npx -y -p codex-dev-mcp-suite stats` (or globally `stats`)
+  - Flags: `--root <path>`, `--json`, `--top N`, `--help`, `--version`
+  - Pure-function library at `lib/stats.js` (no MCP / no stdio); tested offline.
+- New top-level test runner hook: `tests/*.test.mjs` are auto-picked-up by `node run-tests.mjs`.
+- New `provider-smoke` CLI: probe every configured LLM provider (chat + embeddings) and print a matrix of latency / status / sample. Useful after adding a new API key or to compare providers.
+  - Usage: `npx -y -p codex-dev-mcp-suite provider-smoke`
+  - Flags: `--json`, `--markdown`, `--save-md <path>`, `--chat-only`, `--embed-only`, `--env-file <path>`, `--timeout <ms>`
+  - Detects providers from `MCP_PROVIDER_*` slots + named env (`GROQ_*`, `CEREBRAS_*`, `MISTRAL_*`, `OPENROUTER_*`, `OPENAI_*`, `OLLAMA_*`, `ANTHROPIC_*`, `GEMINI_*`, `COHERE_*`) + `MCP_LLM_BASE_URL` / `NINEROUTER_URL` fallback.
+  - Pure-function library at `lib/provider-smoke.js`; tested offline.
+- New docs page `docs/providers.md` — auto-generated smoke matrix from latest run.
+
+
+
+
+
+
+### Added
+- New `prune` CLI: remove temp project slugs (prefix `tmp.`) from vault, journal, and checkpoints. Default is DRY-RUN — nothing is deleted without `--yes`.
+  - Usage: `npx -y -p codex-dev-mcp-suite prune` (or globally `prune`)
+  - Flags: `--root <path>`, `--yes`, `--json`, `--help`, `--version`
+  - Pure-function library at `lib/prune.js`; tested offline.
+  - Safety: refuses to delete any slug that does not start with `tmp.`.
+- New MCP tool `memory_stats` on the project-memory server: returns the same summary as the `stats` CLI. Useful for in-session introspection from an MCP client.
+  - Args: `root?`, `top?` (default 10), `json?` (default false).
+
+
+
+### Added
+- **Cloudflare Workers AI support** for embeddings and chat: drop-in alternative when 9router/OpenAI are unavailable. Set `MCP_EMBED_BASE_URL=https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai/run/`, `MCP_EMBED_API_KEY=<token>`, `MCP_EMBED_MODEL=@cf/baai/bge-base-en-v1.5`. Cloudflare's REST API (non-OpenAI-compatible) is auto-detected by URL pattern and dispatched to a separate code path in `project-memory/embedding.js`. Includes `isCloudflareURL()` detection + `endpoint: "cloudflare"` field in provider matrix.
+- `provider-smoke` CLI: probe Cloudflare alongside OpenAI-compatible providers. Cloudflare chat returns 400 for embed-only models (expected — they don't support chat).
+
 ## 1.2.0 - 2026-06-15
 
 ### Added

package/README.md

@@ -2,6 +2,9 @@
 
 [![CI](https://github.com/verrysimatupang99/codex-dev-mcp-suite/actions/workflows/ci.yml/badge.svg)](https://github.com/verrysimatupang99/codex-dev-mcp-suite/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/codex-dev-mcp-suite.svg)](https://www.npmjs.com/package/codex-dev-mcp-suite)
+[![npm downloads](https://img.shields.io/npm/dm/codex-dev-mcp-suite.svg)](https://www.npmjs.com/package/codex-dev-mcp-suite)
+[![license](https://img.shields.io/npm/l/codex-dev-mcp-suite.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/codex-dev-mcp-suite.svg)](https://nodejs.org)
 
 Published as `codex-dev-mcp-suite` for backward compatibility.
 
@@ -14,6 +17,51 @@ per-project** by the working directory. Works with any MCP-capable client
 (Codex CLI, Claude Code, Cursor, Cline, Gemini-compatible launchers, Hermes,
 or any stdio MCP host).
 
+## Quickstart
+
+Try it in 10 seconds (no clone, no config):
+
+```bash
+npx -y -p codex-dev-mcp-suite project-memory-mcp --help
+```
+
+Local-first by default: no hosted backend, no telemetry. Works offline with
+keyword recall; model/provider config is optional. For strict no-network mode,
+set `MCP_DETERMINISTIC_FALLBACK=true`.
+
+Register all four servers with an MCP client (Codex CLI shown):
+
+```toml
+# ~/.codex/config.toml
+[mcp_servers.project-memory]
+command = "npx"
+args = ["-y", "-p", "codex-dev-mcp-suite", "project-memory-mcp"]
+
+[mcp_servers.devjournal]
+command = "npx"
+args = ["-y", "-p", "codex-dev-mcp-suite", "devjournal-mcp"]
+
+[mcp_servers.checkpoint]
+command = "npx"
+args = ["-y", "-p", "codex-dev-mcp-suite", "checkpoint-mcp"]
+
+[mcp_servers.context-pack]
+command = "npx"
+args = ["-y", "-p", "codex-dev-mcp-suite", "context-pack-mcp"]
+```
+
+Inspect any server without starting it:
+
+```bash
+project-memory-mcp --version
+project-memory-mcp --doctor   # config diagnostics; API keys redacted
+```
+
+Other clients (Claude Code, Cursor, Cline, ...): see
+[`docs/clients/`](docs/clients/). Full env reference:
+[`docs/configuration.md`](docs/configuration.md). Data flow:
+[`docs/privacy.md`](docs/privacy.md).
+
 ## The four servers
 
 | Server | What it does | Key tools |
@@ -120,6 +168,30 @@ idea — use the npm bin commands (`project-memory-mcp`, `devjournal-mcp`,
 `checkpoint-mcp`, `context-pack-mcp`) or `node /abs/path/<server>/server.js`,
 with optional `env`.
 
+## Memory Recall Modes
+
+`memory_recall` supports a `mode` arg (default `"auto"`) that controls fallback behavior:
+
+| Mode | Behavior |
+|---|---|
+| `auto` (default) | Smart: try semantic → keyword → LLM rerank |
+| `semantic` | Require embedding. Returns `isError: true` if no embed key configured |
+| `keyword` | Skip embedding entirely (faster, pure keyword scoring) |
+
+The recall output annotates the active mode for transparency:
+
+```
+Recall for "how do users sign in" in my-project [semantic+rerank]:
+### JWT login flow (id:..., sim:0.603, ...)
+```
+
+The `+rerank` suffix is appended when LLM rerank is active (MCP_RERANK_ENABLED + key).
+Without embeddings, recall falls back to `[keyword]` or `[keyword+rerank]`.
+With `MCP_DETERMINISTIC_FALLBACK=true`, the mode is always `[deterministic]`.
+
+This means you can run codex-dev-mcp-suite with **zero API keys configured** —
+`memory_recall` still works via keyword scoring, just no semantic similarity.
+
 ## Daily workflow
 
 - Session start: `pack_overview` + `journal_resume` + `memory_recall "<topic>"`
@@ -138,6 +210,113 @@ node backfill-sessions-v2.mjs --dry --min-prompts 2     # preview
 node backfill-sessions-v2.mjs --min-prompts 2           # import
 ```
 
+## Stats CLI
+
+A read-only summary of your local memory storage — totals, top projects,
+recent activity, and temp-slug cleanup candidates.
+
+```bash
+npx -y -p codex-dev-mcp-suite stats             # human-readable
+npx -y -p codex-dev-mcp-suite stats --json      # machine-readable
+npx -y -p codex-dev-mcp-suite stats --root /tmp/mem   # different root
+npx -y -p codex-dev-mcp-suite stats --top 5     # trim top lists
+```
+
+Example output:
+
+```
+Dev MCP Suite — stats
+======================
+Storage root: /home/you/.codex/memories
+
+Totals
+------
+  Notes:           89
+  Journal projects:19
+  Checkpoints:     1
+  Distinct projects: 25
+
+Top projects by notes (top 10)
+------------------------
+    24  mrtrickster99-fd1ff0fa
+    14  Coding-17e063ef
+    ...
+
+Temp/cleanup candidates (2)
+------------------------
+  tmp.itbtDn9eB3-b62798fd
+  tmp.iHqM2Uh5K2-8d3660a2
+```
+
+The CLI is a thin wrapper around `lib/stats.js`, which is also importable
+directly from your own scripts. The default storage root is
+`~/.codex/memories`, but `--root` (or the existing `MEMORY_VAULT_DIR` /
+`JOURNAL_DIR` / `CHECKPOINT_DIR` env vars) override it.
+
+
+## Provider Smoke CLI
+
+Verify every configured LLM provider (chat + embeddings) with one command.
+Useful after adding a new API key, or when comparing provider latency.
+
+```bash
+npx -y -p codex-dev-mcp-suite provider-smoke                          # uses process.env
+npx -y -p codex-dev-mcp-suite provider-smoke --env-file ~/secrets.env  # separate secrets file
+npx -y -p codex-dev-mcp-suite provider-smoke --markdown --save-md docs/providers.md
+```
+
+Auto-detects providers from these env vars (highest precedence first):
+
+- **Numbered slots**: `MCP_PROVIDER_PRIMARY` / `_CHAIN2` / `_CHAIN3` / ...
+- **Named env**: `GROQ_*`, `CEREBRAS_*`, `MISTRAL_*`, `OPENROUTER_*`, `OPENAI_*`, `GEMINI_*`, `COHERE_*`, `VOYAGE_*`, `OLLAMA_*`, `ANTHROPIC_*`
+- **Catch-all**: `MCP_LLM_BASE_URL` / `MCP_RERANK_BASE_URL` / `MCP_EMBED_BASE_URL` / `NINEROUTER_URL` / `LLM_BASE_URL` (any OpenAI-compatible endpoint)
+
+For each detected provider, runs:
+- **chat probe** (`/v1/chat/completions`) — if the provider supports it
+- **embed probe** (`/v1/embeddings`) — if the provider supports it
+
+**Inference-only providers** (Groq, Cerebras, Anthropic) skip the embed probe automatically.
+**Non-OpenAI-compatible providers** (Cloudflare Workers AI) require a custom code path in
+`project-memory/embedding.js` — see [docs/providers.md](docs/providers.md).
+
+**No provider assumption is baked in**: the tool only probes what's in your env. Zero-config users
+get an empty matrix; pass `--env-file` to point at a secrets file.
+
+Chat-only providers (Groq, Cerebras) skip the embeddings probe automatically
+— they don't expose `/v1/embeddings`. Embedding-capable providers (Mistral,
+OpenRouter, OpenAI, Ollama, Gemini, Cohere) run both probes.
+
+Example output (Groq + Cerebras, both configured):
+
+```
+[groq]
+  ✓ chat       200 310ms  "OK"
+
+[cerebras]
+  ✓ chat       200 476ms
+```
+
+See [`docs/providers.md`](docs/providers.md) for a saved smoke matrix.
+
+## Prune CLI
+
+Remove temp project slugs (prefix `tmp.`) from vault / journal / checkpoints.
+Default is DRY-RUN — nothing is deleted without `--yes`.
+
+```bash
+npx -y -p codex-dev-mcp-suite prune           # dry-run report
+npx -y -p codex-dev-mcp-suite prune --yes     # actually delete
+npx -y -p codex-dev-mcp-suite prune --json    # machine-readable
+npx -y -p codex-dev-mcp-suite prune --root /tmp/mem   # different root
+```
+
+Safety: refuses to delete any slug that does not start with `tmp.`. Useful
+right after heavy refactors or after imports that left tmp scratch dirs.
+
+For in-session use from an MCP client, the project-memory server exposes a
+`memory_stats` tool that returns the same summary text (or JSON) as the `stats`
+CLI above.
+
 ## Tests
 
 ```bash

package/bin/provider-smoke.mjs

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+/**
+ * bin/provider-smoke.mjs — Dev MCP Suite provider smoke test.
+ *
+ * Probes every provider that can be derived from the current env:
+ *   - MCP_LLM_BASE_URL / NINEROUTER_URL / LLM_BASE_URL (9router-like)
+ *   - MCP_PROVIDER_PRIMARY / _CHAIN2 / _CHAIN3 / ... (numbered slots)
+ *   - Named: GROQ_*, CEREBRAS_*, MISTRAL_*, OPENROUTER_*, OPENAI_*, OLLAMA_*, ...
+ *
+ * For each provider, runs:
+ *   - chat probe (/v1/chat/completions, short prompt)         if supportsChat
+ *   - embed probe (/v1/embeddings, single string)             if supportsEmbed
+ *
+ * Output: human text by default; --json for machines; --markdown for docs.
+ *
+ * Env override:
+ *   --env-file <path>   Source env from this file before probing (e.g. /tmp/secrets.env)
+ *
+ * Exit code:
+ *   0 = all probes ok
+ *   1 = at least one probe failed
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+import { buildProviderMatrix, shapeProbe, formatText, formatJson, formatMarkdown, isCloudflareURL } from "../lib/provider-smoke.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function pkgVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8")).version || "unknown";
+  } catch { return "unknown"; }
+}
+
+
+/** Strip a trailing /v1 (only the literal segment, not /openai/v1) so we can re-append /v1/<endpoint>. */
+function stripV1(baseUrl) {
+  return String(baseUrl || "").replace(/\/v1\/?$/, "").replace(/\/$/, "");
+}
+
+function parseArgs(argv) {
+  const opts = {
+    help: false, version: false,
+    json: false, markdown: false,
+    saveMd: null, envFile: null,
+    chatOnly: false, embedOnly: false,
+    timeoutMs: 15000,
+    only: null,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") opts.help = true;
+    else if (a === "-v" || a === "--version") opts.version = true;
+    else if (a === "--json") opts.json = true;
+    else if (a === "--markdown") opts.markdown = true;
+    else if (a === "--save-md") opts.saveMd = argv[++i];
+    else if (a === "--env-file") opts.envFile = argv[++i];
+    else if (a === "--chat-only") opts.chatOnly = true;
+    else if (a === "--embed-only") opts.embedOnly = true;
+    else if (a === "--timeout") opts.timeoutMs = parseInt(argv[++i], 10) || 15000;
+    else if (a === "--only") opts.only = (argv[++i] || "").split(",").map(s => s.trim()).filter(Boolean);
+    else { process.stderr.write(`provider-smoke: unknown flag: ${a}\n`); process.exit(2); }
+  }
+  return opts;
+}
+
+function printHelp() {
+  const out = [
+    `provider-smoke (Dev MCP Suite) v${pkgVersion()}`,
+    "",
+    "Probe every configured LLM provider (chat + embeddings) and print a matrix.",
+    "",
+    "Usage:",
+    "  provider-smoke [--json] [--markdown] [--save-md <path>]",
+    "                 [--chat-only | --embed-only] [--env-file <path>]",
+    "  provider-smoke --help | --version",
+    "",
+    "Options:",
+    "  --json            Machine-readable JSON output",
+    "  --markdown        Markdown table (for docs/)",
+    "  --save-md <path>  Write markdown report to this file",
+    "  --env-file <path> Source env vars from this file before probing",
+    "                    (KEY=value lines, one per line)",
+    "  --chat-only       Only probe /v1/chat/completions",
+    "  --embed-only      Only probe /v1/embeddings",
+    "  --timeout <ms>    Per-probe timeout (default 15000)",
+    "  --only a,b,c      Only probe these provider ids (comma-separated); others ignored",
+    "",
+    "Detected providers (precedence):",
+    "  MCP_PROVIDER_PRIMARY / _CHAIN2 / _CHAIN3 / ...   (numbered slots)",
+    "  GROQ_*, CEREBRAS_*, MISTRAL_*, OPENROUTER_*,     (named)",
+    "  OPENAI_*, OLLAMA_*, ANTHROPIC_*, GEMINI_*, COHERE_*",
+    "  MCP_LLM_BASE_URL / NINEROUTER_URL / LLM_BASE_URL  (9router / agentrouter)",
+    "",
+    "Examples:",
+    "  provider-smoke",
+    "  provider-smoke --env-file /tmp/codex-dev-smoke.env",
+    "  provider-smoke --json | jq '.[] | select(.ok == false)'",
+    "  provider-smoke --markdown --save-md docs/providers.md",
+  ];
+  process.stdout.write(out.join("\n") + "\n");
+}
+
+function loadEnvFile(file) {
+  if (!file) return {};
+  const text = fs.readFileSync(file, "utf8");
+  const env = {};
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const m = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+    if (m) env[m[1]] = m[2];
+  }
+  return env;
+}
+
+function buildHeaders(provider) {
+  const h = { "Content-Type": "application/json" };
+  if (provider.apiKey) h["Authorization"] = `Bearer ${provider.apiKey}`;
+  return h;
+}
+
+
+const CF_EMBED_ONLY_PREFIXES = ["@cf/baai/", "@cf/google/embedding", "@cf/baai/sentence-"];
+
+function isEmbedOnlyModel(model) {
+  if (!model) return false;
+  return CF_EMBED_ONLY_PREFIXES.some((p) => model.startsWith(p));
+}
+
+async function probeCloudflare(provider, timeoutMs, kind) {
+  // Skip chat probe for known embed-only Cloudflare model prefixes (annotate, not error).
+  if (kind === "chat" && isEmbedOnlyModel(provider.chatModel || provider.embedModel)) {
+    return shapeProbe({ name: provider.id, kind: "chat", ok: false, error: "embed-only model (chat not supported)" });
+  }
+  // Cloudflare Workers AI REST: POST {baseUrl}/{model}, body shape depends on kind.
+  // Cloudflare model names contain "/" (e.g. "@cf/baai/bge-base-en-v1.5"); do NOT URL-encode.
+  const url = `${provider.baseUrl.replace(/\/$/, "")}/${provider.chatModel || provider.embedModel}`;
+  let body;
+  if (kind === "chat") {
+    body = JSON.stringify({
+      messages: [{ role: "user", content: "Say the single word: OK" }],
+      max_tokens: 8,
+    });
+  } else {
+    body = JSON.stringify({ text: ["ping"] });
+  }
+  const t0 = Date.now();
+  try {
+    const res = await fetch(url, { method: "POST", headers: buildHeaders(provider), body, signal: AbortSignal.timeout(timeoutMs) });
+    const text = await res.text();
+    const latencyMs = Date.now() - t0;
+    if (res.status !== 200) {
+      return shapeProbe({ name: provider.id, kind, ok: false, status: res.status, latencyMs, error: text.slice(0, 200) });
+    }
+    let sample = null, dim = null;
+    try {
+      const j = JSON.parse(text);
+      if (kind === "embed") {
+        const data = j?.result?.data;
+        if (Array.isArray(data) && Array.isArray(data[0])) dim = data[0].length;
+      } else {
+        sample = j?.result?.response ?? null;
+      }
+    } catch { /* ignore */ }
+    return shapeProbe({ name: provider.id, kind, ok: true, status: res.status, latencyMs, sample, dim });
+  } catch (e) {
+    return shapeProbe({ name: provider.id, kind, ok: false, latencyMs: Date.now() - t0, error: String(e && e.message || e) });
+  }
+}
+
+async function probeChat(provider, timeoutMs) {
+  if (!provider.baseUrl || !provider.chatModel) {
+    return shapeProbe({ name: provider.id, kind: "chat", ok: false, error: "missing baseUrl or chatModel" });
+  }
+  const endpoint = provider.endpoint || (isCloudflareURL(provider.baseUrl) ? "cloudflare" : "openai-compatible");
+  if (endpoint === "cloudflare") return probeCloudflare(provider, timeoutMs, "chat");
+  const url = `${stripV1(provider.baseUrl)}/v1/chat/completions`;
+  const body = JSON.stringify({
+    model: provider.chatModel,
+    messages: [{ role: "user", content: "Say the single word: OK" }],
+    max_tokens: 8,
+    temperature: 0,
+  });
+  const t0 = Date.now();
+  try {
+    const res = await fetch(url, { method: "POST", headers: buildHeaders(provider), body, signal: AbortSignal.timeout(timeoutMs) });
+    const text = await res.text();
+    const latencyMs = Date.now() - t0;
+    if (res.status !== 200) {
+      return shapeProbe({ name: provider.id, kind: "chat", ok: false, status: res.status, latencyMs, error: text.slice(0, 200) });
+    }
+    let sample = null;
+    try {
+      const j = JSON.parse(text);
+      sample = j?.choices?.[0]?.message?.content ?? null;
+    } catch { /* ignore */ }
+    return shapeProbe({ name: provider.id, kind: "chat", ok: true, status: res.status, latencyMs, sample });
+  } catch (e) {
+    return shapeProbe({ name: provider.id, kind: "chat", ok: false, latencyMs: Date.now() - t0, error: String(e && e.message || e) });
+  }
+}
+
+async function probeEmbed(provider, timeoutMs) {
+  if (!provider.supportsEmbed) {
+    return shapeProbe({ name: provider.id, kind: "embed", ok: false, error: "provider has no /v1/embeddings endpoint" });
+  }
+  if (!provider.baseUrl || !provider.embedModel) {
+    return shapeProbe({ name: provider.id, kind: "embed", ok: false, error: "missing baseUrl or embedModel" });
+  }
+  if (provider.endpoint === "cloudflare" || isCloudflareURL(provider.baseUrl)) return probeCloudflare(provider, timeoutMs, "embed");
+  const url = `${stripV1(provider.baseUrl)}/v1/embeddings`;
+  const body = JSON.stringify({ model: provider.embedModel, input: "ping" });
+  const t0 = Date.now();
+  try {
+    const res = await fetch(url, { method: "POST", headers: buildHeaders(provider), body, signal: AbortSignal.timeout(timeoutMs) });
+    const text = await res.text();
+    const latencyMs = Date.now() - t0;
+    if (res.status !== 200) {
+      return shapeProbe({ name: provider.id, kind: "embed", ok: false, status: res.status, latencyMs, error: text.slice(0, 200) });
+    }
+    let dim = null;
+    try {
+      const j = JSON.parse(text);
+      dim = Array.isArray(j?.data?.[0]?.embedding) ? j.data[0].embedding.length : null;
+    } catch { /* ignore */ }
+    return shapeProbe({ name: provider.id, kind: "embed", ok: true, status: res.status, latencyMs, dim });
+  } catch (e) {
+    return shapeProbe({ name: provider.id, kind: "embed", ok: false, latencyMs: Date.now() - t0, error: String(e && e.message || e) });
+  }
+}
+
+const opts = parseArgs(process.argv.slice(2));
+if (opts.version) { process.stdout.write(`${pkgVersion()}\n`); process.exit(0); }
+if (opts.help) { printHelp(); process.exit(0); }
+
+// Merge env: process.env + (optional) env file
+const fileEnv = loadEnvFile(opts.envFile);
+const env = { ...process.env, ...fileEnv };
+
+let matrix = buildProviderMatrix(env);
+if (opts.only && opts.only.length) {
+  matrix = matrix.filter(p => opts.only.includes(p.id));
+}
+if (matrix.length === 0) {
+  const hint = opts.only && opts.only.length ? " (--only filter: " + opts.only.join(",") + ")" : "";
+  process.stderr.write("No providers detected. Set MCP_PROVIDER_PRIMARY / GROQ_API_KEY / NINEROUTER_URL etc., or pass --env-file." + hint + "\n");
+  process.exit(2);
+}
+
+process.stderr.write(`Probing ${matrix.length} provider${matrix.length === 1 ? "" : "s"}...\n`);
+const results = [];
+for (const p of matrix) {
+  if (!opts.embedOnly && p.supportsChat) {
+    results.push(await probeChat(p, opts.timeoutMs));
+  }
+  if (!opts.chatOnly && p.supportsEmbed) {
+    results.push(await probeEmbed(p, opts.timeoutMs));
+  }
+}
+
+let out;
+if (opts.markdown) out = formatMarkdown(results);
+else if (opts.json) out = formatJson(results);
+else out = formatText(results);
+
+process.stdout.write(out + "\n");
+
+if (opts.saveMd) {
+  fs.mkdirSync(path.dirname(opts.saveMd), { recursive: true });
+  fs.writeFileSync(opts.saveMd, formatMarkdown(results));
+  process.stderr.write(`Markdown saved to ${opts.saveMd}\n`);
+}
+
+const failed = results.filter((r) => !r.ok).length;
+process.exit(failed === 0 ? 0 : 1);