codex-dev-mcp-suite 1.1.0 → 1.3.0

package/.env.example

@@ -22,6 +22,9 @@
 # MCP_PROVIDER_CHAIN3_API_KEY=<openrouter-key>
 # MCP_PROVIDER_CHAIN3_MODEL=openai/gpt-4o-mini
 
+# Cooldown (ms) before retrying a provider after a 429/5xx/timeout failure.
+# MCP_PROVIDER_COOLDOWN_MS=60000
+
 # Base URL of an OpenAI-compatible API (must expose /v1/...)
 MCP_LLM_BASE_URL=http://localhost:11434/v1
 # API key for that endpoint (leave blank for local servers that don't need one)

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 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`.
+
+
+
+
+### 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).
+
+## 1.2.0 - 2026-06-15
+
+### Added
+- CLI meta handling for all bins: `--help`, `--version`, and `--doctor` (config diagnostics with API keys redacted) before the stdio server starts.
+- Provider diagnostics `providerChainDiagnostics()` that lists active providers with redacted keys and flags incomplete numbered slots.
+- Per-provider cooldown on `429`/`5xx`/timeout/network failures via `MCP_PROVIDER_COOLDOWN_MS` (default `60000`).
+- CI job that packs the tarball, installs it in a temp dir, and runs each bin `--version`.
+
+### Changed
+- Rerank now skips providers that are cooling down and records success/failure outcomes.
+- Rerank never logs API keys or response bodies.
+
 ## 1.1.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 |
@@ -138,6 +186,69 @@ 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.
+
+
+## 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/_meta.mjs

@@ -0,0 +1,69 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function pkgVersion() {
+  try {
+    const raw = fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8");
+    return JSON.parse(raw).version || "unknown";
+  } catch { return "unknown"; }
+}
+
+function redactKey(name) {
+  const v = String(process.env[name] || "");
+  return v ? `set (${v.length} chars)` : "not set";
+}
+
+function doctorLines(meta) {
+  const lines = [];
+  lines.push(`${meta.title} doctor`);
+  lines.push(`version: ${pkgVersion()}`);
+  lines.push(`node: ${process.version}`);
+  for (const [label, name] of meta.storage || []) {
+    lines.push(`${label}: ${process.env[name] || meta.storageDefaults?.[name] || "(default)"}`);
+  }
+  const det = /^(1|true|yes|on)$/i.test(String(process.env.MCP_DETERMINISTIC_FALLBACK || "").trim());
+  lines.push(`deterministic no-network: ${det ? "on" : "off"}`);
+  if (meta.usesModel) {
+    lines.push("model/provider config (keys redacted):");
+    lines.push(`  MCP_LLM_BASE_URL: ${process.env.MCP_LLM_BASE_URL || "(unset)"}`);
+    lines.push(`  MCP_LLM_API_KEY: ${redactKey("MCP_LLM_API_KEY")}`);
+    lines.push(`  MCP_PROVIDER_PRIMARY: ${process.env.MCP_PROVIDER_PRIMARY || "(unset)"}`);
+    lines.push(`  MCP_PROVIDER_PRIMARY_API_KEY: ${redactKey("MCP_PROVIDER_PRIMARY_API_KEY")}`);
+    lines.push(`  MCP_EMBED_API_KEY: ${redactKey("MCP_EMBED_API_KEY")}`);
+    lines.push(`  MCP_RERANK_API_KEY: ${redactKey("MCP_RERANK_API_KEY")}`);
+  } else {
+    lines.push("model/provider config: not used by this server");
+  }
+  return lines;
+}
+
+export function handleCliMeta(meta) {
+  const argv = process.argv.slice(2);
+  if (argv.includes("-v") || argv.includes("--version")) {
+    process.stdout.write(`${pkgVersion()}\n`);
+    process.exit(0);
+  }
+  if (argv.includes("-h") || argv.includes("--help")) {
+    const out = [
+      `${meta.title} (${meta.bin}) v${pkgVersion()}`,
+      "",
+      "An MCP server that speaks JSON-RPC over stdio. Launch it from an MCP client.",
+      "",
+      "Usage:",
+      `  ${meta.bin}            start the MCP stdio server`,
+      `  ${meta.bin} --version  print version`,
+      `  ${meta.bin} --doctor   print config diagnostics (API keys redacted)`,
+      `  ${meta.bin} --help     show this help`,
+    ];
+    process.stdout.write(out.join("\n") + "\n");
+    process.exit(0);
+  }
+  if (argv.includes("--doctor")) {
+    process.stdout.write(doctorLines(meta).join("\n") + "\n");
+    process.exit(0);
+  }
+  return false;
+}

package/bin/checkpoint.mjs

@@ -1,2 +1,9 @@
 #!/usr/bin/env node
-import "../checkpoint/server.js";
+import { handleCliMeta } from "./_meta.mjs";
+handleCliMeta({
+  bin: "checkpoint-mcp",
+  title: "Checkpoint MCP",
+  usesModel: false,
+  storage: [["store", "CHECKPOINT_DIR"]],
+});
+import("../checkpoint/server.js");

package/bin/context-pack.mjs

@@ -1,2 +1,9 @@
 #!/usr/bin/env node
-import "../context-pack/server.js";
+import { handleCliMeta } from "./_meta.mjs";
+handleCliMeta({
+  bin: "context-pack-mcp",
+  title: "Context Pack MCP",
+  usesModel: false,
+  storage: [],
+});
+import("../context-pack/server.js");

package/bin/devjournal.mjs

@@ -1,2 +1,9 @@
 #!/usr/bin/env node
-import "../devjournal/server.js";
+import { handleCliMeta } from "./_meta.mjs";
+handleCliMeta({
+  bin: "devjournal-mcp",
+  title: "Dev Journal MCP",
+  usesModel: true,
+  storage: [["store", "JOURNAL_DIR"]],
+});
+import("../devjournal/server.js");

package/bin/project-memory.mjs

@@ -1,2 +1,9 @@
 #!/usr/bin/env node
-import "../project-memory/server.js";
+import { handleCliMeta } from "./_meta.mjs";
+handleCliMeta({
+  bin: "project-memory-mcp",
+  title: "Project Memory MCP",
+  usesModel: true,
+  storage: [["vault", "MEMORY_VAULT_DIR"]],
+});
+import("../project-memory/server.js");

package/bin/prune.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * bin/prune.mjs — Dev MCP Suite prune CLI.
+ *
+ * Removes temp project slugs (prefix `tmp.`) from all stores. Default is
+ * DRY-RUN — nothing is deleted unless you pass `--yes`.
+ *
+ * Usage:
+ *   prune [--root <path>] [--yes] [--json]
+ *   prune --help | --version
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+import { findTempSlugs, planPrune, applyPrune } from "../lib/prune.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"; }
+}
+
+function resolveRoot() {
+  const fromFlag = process.env.PRUNE_ROOT;
+  if (fromFlag) return path.resolve(fromFlag);
+  for (const k of ["MEMORY_VAULT_DIR", "JOURNAL_DIR", "CHECKPOINT_DIR"]) {
+    const v = process.env[k];
+    if (v) {
+      const sub = k === "MEMORY_VAULT_DIR" ? "vault" : k === "JOURNAL_DIR" ? "journal" : "checkpoints";
+      const parent = path.dirname(v);
+      if (path.basename(parent) === sub) return parent;
+      return parent;
+    }
+  }
+  return path.join(os.homedir(), ".codex", "memories");
+}
+
+function parseArgs(argv) {
+  const opts = { root: null, yes: false, json: false, help: false, version: false };
+  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 === "--yes" || a === "-y") opts.yes = true;
+    else if (a === "--json") opts.json = true;
+    else if (a === "--dry-run") opts.yes = false;
+    else if (a === "--root") opts.root = path.resolve(argv[++i]);
+    else if (a.startsWith("--root=")) opts.root = path.resolve(a.slice("--root=".length));
+    else if (!a.startsWith("-")) opts.root = path.resolve(a);
+    else {
+      process.stderr.write(`prune: unknown flag: ${a}\n`);
+      process.exit(2);
+    }
+  }
+  return opts;
+}
+
+function fmtBytes(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / 1024 / 1024).toFixed(2)} MB`;
+}
+
+function printHelp() {
+  const out = [
+    `prune (Dev MCP Suite) v${pkgVersion()}`,
+    "",
+    "Remove temp project slugs (prefix tmp.) from vault, journal, and",
+    "checkpoints. Default is DRY-RUN — nothing is deleted without --yes.",
+    "",
+    "Usage:",
+    "  prune [root] [--root <path>] [--yes] [--json]",
+    "  prune --help | --version",
+    "",
+    "Options:",
+    "  --yes, -y    Actually delete. Without this, only a dry-run report is printed.",
+    "  --dry-run    Force dry-run mode (default).",
+    "  --json       Machine-readable JSON output.",
+    "  --root <p>   Storage root (default: ~/.codex/memories or first env var of",
+    "               MEMORY_VAULT_DIR / JOURNAL_DIR / CHECKPOINT_DIR)",
+    "  -h, --help",
+    "  -v, --version",
+    "",
+    "Safety: refuses to delete any slug that does not start with `tmp.`.",
+    "",
+    "Examples:",
+    "  prune                       # dry-run report",
+    "  prune --yes                 # delete after seeing the plan",
+    "  prune --yes --json          # machine-readable delete report",
+  ];
+  process.stdout.write(out.join("\n") + "\n");
+}
+
+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); }
+
+const root = opts.root || resolveRoot();
+const plan = planPrune({ root });
+
+if (plan.length === 0) {
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ root, plan: [], removed: [], skipped: [], errors: [] }, null, 2) + "\n");
+  } else {
+    process.stdout.write(`No temp slugs found under ${root}.\n`);
+  }
+  process.exit(0);
+}
+
+if (!opts.yes) {
+  // dry-run report
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ root, dryRun: true, plan, removed: [], skipped: [], errors: [] }, null, 2) + "\n");
+  } else {
+    const lines = [];
+    lines.push(`Dev MCP Suite — prune (DRY RUN)`);
+    lines.push("=================================");
+    lines.push(`Storage root: ${root}`);
+    lines.push(`Found ${plan.length} temp slug${plan.length === 1 ? "" : "s"}:`);
+    let totalBytes = 0;
+    for (const e of plan) {
+      lines.push(`  ${e.slug.padEnd(36)} ${fmtBytes(e.bytes).padStart(10)}   stores: ${e.stores.join(",")}`);
+      totalBytes += e.bytes;
+    }
+    lines.push(`  ${"TOTAL".padEnd(36)} ${fmtBytes(totalBytes).padStart(10)}`);
+    lines.push("");
+    lines.push("Re-run with `--yes` to actually delete.");
+    process.stdout.write(lines.join("\n") + "\n");
+  }
+  process.exit(0);
+}
+
+// actually delete
+const slugs = plan.map((p) => p.slug);
+const result = applyPrune({ root, slugs, dryRun: false });
+const totalFreed = plan.reduce((a, p) => a + p.bytes, 0);
+
+if (opts.json) {
+  process.stdout.write(JSON.stringify({ root, dryRun: false, plan, ...result, bytesFreed: totalFreed }, null, 2) + "\n");
+} else {
+  const lines = [];
+  lines.push(`Dev MCP Suite — prune`);
+  lines.push("=====================");
+  lines.push(`Storage root: ${root}`);
+  lines.push(`Removed ${result.removed.length} slug${result.removed.length === 1 ? "" : "s"} (freed ~${fmtBytes(totalFreed)})`);
+  for (const slug of result.removed) lines.push(`  ✓ ${slug}`);
+  if (result.errors.length) {
+    lines.push("");
+    lines.push(`Errors (${result.errors.length}):`);
+    for (const e of result.errors) lines.push(`  ✗ ${e.slug} [${e.store}]: ${e.error}`);
+  }
+  process.stdout.write(lines.join("\n") + "\n");
+}
+
+process.exit(result.errors.length > 0 ? 1 : 0);

package/bin/stats.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * bin/stats.mjs — Dev MCP Suite stats CLI.
+ *
+ * Usage:
+ *   stats [--root <path>] [--json] [--top N] [--help] [--version]
+ *
+ * Default storage root: ~/.codex/memories (override via --root or
+ * MEMORY_VAULT_DIR / JOURNAL_DIR / CHECKPOINT_DIR siblings).
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+import { computeStats, formatText, formatJson } from "../lib/stats.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"; }
+}
+
+function resolveRoot() {
+  // Precedence: explicit --root > vault env > journal env > checkpoint env > ~/.codex/memories
+  const fromFlag = process.env.STATS_ROOT;
+  if (fromFlag) return path.resolve(fromFlag);
+  for (const k of ["MEMORY_VAULT_DIR", "JOURNAL_DIR", "CHECKPOINT_DIR"]) {
+    const v = process.env[k];
+    if (v) {
+      // each server stores under <root>/<subdir>, so the root is the parent
+      const sub = k === "MEMORY_VAULT_DIR" ? "vault" : k === "JOURNAL_DIR" ? "journal" : "checkpoints";
+      const parent = path.dirname(v);
+      if (path.basename(parent) === sub) return parent;
+      return parent;
+    }
+  }
+  return path.join(os.homedir(), ".codex", "memories");
+}
+
+function parseArgs(argv) {
+  const opts = { root: null, json: false, top: 10, help: false, version: false };
+  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 === "--root") opts.root = path.resolve(argv[++i]);
+    else if (a.startsWith("--root=")) opts.root = path.resolve(a.slice("--root=".length));
+    else if (a === "--top") opts.top = parseInt(argv[++i], 10) || 10;
+    else if (a.startsWith("--top=")) opts.top = parseInt(a.slice("--top=".length), 10) || 10;
+    else if (a === "--") { /* ignore rest */ break; }
+    else if (!a.startsWith("-")) opts.root = path.resolve(a);
+    else {
+      process.stderr.write(`stats: unknown flag: ${a}\n`);
+      process.exit(2);
+    }
+  }
+  return opts;
+}
+
+function printHelp() {
+  const out = [
+    `stats (Dev MCP Suite) v${pkgVersion()}`,
+    "",
+    "Summarize local memory storage (vault / journal / checkpoints).",
+    "",
+    "Usage:",
+    "  stats [root] [--root <path>] [--json] [--top N]",
+    "  stats --help | --version",
+    "",
+    "Options:",
+    "  --root <path>   Storage root (default: ~/.codex/memories or first env var of",
+    "                  MEMORY_VAULT_DIR / JOURNAL_DIR / CHECKPOINT_DIR)",
+    "  --json          Emit machine-readable JSON instead of human text",
+    "  --top N         How many entries in top-project / recent-activity lists",
+    "                  (default: 10)",
+    "  -h, --help      Show this help",
+    "  -v, --version   Print version",
+    "",
+    "Examples:",
+    "  stats                       # summary of default storage",
+    "  stats --json | jq .totals   # totals only",
+    "  stats --root /tmp/mem       # use a different root",
+  ];
+  process.stdout.write(out.join("\n") + "\n");
+}
+
+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); }
+
+const root = opts.root || resolveRoot();
+const stats = computeStats({ root, topLimit: opts.top });
+
+if (opts.json) {
+  process.stdout.write(formatJson(stats) + "\n");
+} else {
+  process.stdout.write(formatText(stats) + "\n");
+}

package/devjournal/provider-chain.js

@@ -7,6 +7,11 @@ function value(name) {
   return String(process.env[name] || "").trim();
 }
 
+export function redactKey(key) {
+  const k = String(key || "");
+  return k ? `set (${k.length} chars)` : "not set";
+}
+
 function providerEnv(prefix) {
   const label = value(prefix);
   const base = value(`${prefix}_BASE_URL`);
@@ -16,20 +21,34 @@ function providerEnv(prefix) {
   return { label, base, key, model };
 }
 
-function numberedProviders() {
-  const providers = [];
-  const primary = providerEnv("MCP_PROVIDER_PRIMARY");
-  if (primary) providers.push(primary);
+function slotIssues(prefix) {
+  const present = ["", "_BASE_URL", "_API_KEY", "_MODEL"].some((s) => value(`${prefix}${s}`));
+  if (!present) return null;
+  const missing = [];
+  if (!value(prefix)) missing.push(`${prefix}`);
+  if (!value(`${prefix}_BASE_URL`)) missing.push(`${prefix}_BASE_URL`);
+  if (!value(`${prefix}_API_KEY`)) missing.push(`${prefix}_API_KEY`);
+  if (!value(`${prefix}_MODEL`)) missing.push(`${prefix}_MODEL`);
+  return missing.length ? { prefix, missing } : null;
+}
 
-  const slots = Object.keys(process.env)
-    .map((name) => name.match(/^MCP_PROVIDER_CHAIN(\d+)$/)?.[1])
+function numberedPrefixes() {
+  const prefixes = ["MCP_PROVIDER_PRIMARY"];
+  const nums = Object.keys(process.env)
+    .map((name) => name.match(/^MCP_PROVIDER_CHAIN(\d+)/)?.[1])
     .filter(Boolean)
     .map(Number)
-    .filter((n) => n >= 2)
-    .sort((a, b) => a - b);
+    .filter((n) => n >= 2);
+  for (const n of [...new Set(nums)].sort((a, b) => a - b)) {
+    prefixes.push(`MCP_PROVIDER_CHAIN${n}`);
+  }
+  return prefixes;
+}
 
-  for (const n of slots) {
-    const provider = providerEnv(`MCP_PROVIDER_CHAIN${n}`);
+function numberedProviders() {
+  const providers = [];
+  for (const prefix of numberedPrefixes()) {
+    const provider = providerEnv(prefix);
     if (provider) providers.push(provider);
   }
   return providers;
@@ -54,3 +73,37 @@ export function providerChainConfig() {
   }
   return { providers, enabled: providers.length > 0, deterministic };
 }
+
+export function providerChainDiagnostics() {
+  const cfg = providerChainConfig();
+  const issues = [];
+  for (const prefix of numberedPrefixes()) {
+    const issue = slotIssues(prefix);
+    if (issue) issues.push(issue);
+  }
+  return {
+    deterministic: cfg.deterministic,
+    enabled: cfg.enabled,
+    providers: cfg.providers.map((p) => ({ label: p.label, base: p.base, model: p.model, apiKey: redactKey(p.key) })),
+    issues,
+  };
+}
+
+const COOLDOWN_MS = Number(process.env.MCP_PROVIDER_COOLDOWN_MS || 60000);
+const cooldowns = new Map();
+
+export function isCoolingDown(key, now = Date.now()) {
+  const until = cooldowns.get(key);
+  if (!until) return false;
+  if (now >= until) { cooldowns.delete(key); return false; }
+  return true;
+}
+
+export function recordOutcome(key, ok, now = Date.now()) {
+  if (ok) { cooldowns.delete(key); return; }
+  cooldowns.set(key, now + COOLDOWN_MS);
+}
+
+export function _resetCooldowns() {
+  cooldowns.clear();
+}