codex-dev-mcp-suite 1.1.0 → 1.2.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,17 @@
 # Changelog
 
+## 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/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/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();
+}

package/devjournal/rerank.js

@@ -1,14 +1,14 @@
 /**
  * LLM reranker via any OpenAI-compatible /v1/chat/completions model.
- * Used when embeddings are unavailable: keyword prefilter -> LLM picks the
- * most relevant candidates. Degrades gracefully: returns null on any failure
- * so callers fall back to keyword ordering. Never throws.
+ * Tries provider chain slots in order, skipping any currently cooling down
+ * after a recent failure. Degrades gracefully: returns null on any failure so
+ * callers fall back to keyword ordering. Never throws. Never logs keys/bodies.
  */
 import http from "http";
 import https from "https";
 import { URL } from "url";
 import { deterministicEnabled } from "./env.js";
-import { providerChainConfig } from "./provider-chain.js";
+import { providerChainConfig, isCoolingDown, recordOutcome } from "./provider-chain.js";
 
 const TIMEOUT_MS = Number(process.env.RERANK_TIMEOUT_MS || 30000);
 const ENABLED = process.env.RERANK_ENABLED !== "0";
@@ -25,10 +25,19 @@ export function rerankConfig() {
   };
 }
 
+function providerKey(provider) {
+  return `${provider.label}|${provider.base}|${provider.model}`;
+}
+
+/**
+ * Resolves { content, retryable }. retryable=true means try the next provider
+ * (timeout, network error, 429, or 5xx). retryable=false with null content
+ * means a definitive non-retryable response (e.g. 4xx auth).
+ */
 function chatWithProvider(provider, messages) {
   return new Promise((resolve) => {
     let u;
-    try { u = new URL("/v1/chat/completions", provider.base); } catch { return resolve(null); }
+    try { u = new URL("/v1/chat/completions", provider.base); } catch { return resolve({ content: null, retryable: false }); }
     const payload = Buffer.from(JSON.stringify({ model: provider.model, stream: false, temperature: 0, max_tokens: 200, messages }));
     const lib = u.protocol === "https:" ? https : http;
     const req = lib.request(
@@ -44,10 +53,14 @@ function chatWithProvider(provider, messages) {
         let body = "";
         res.on("data", (c) => (body += c));
         res.on("end", () => {
-          if (res.statusCode !== 200) return resolve(null);
+          const status = res.statusCode || 0;
+          if (status !== 200) {
+            const retryable = status === 429 || status >= 500;
+            return resolve({ content: null, retryable });
+          }
           try {
             const j = JSON.parse(body);
-            return resolve(j?.choices?.[0]?.message?.content ?? null);
+            return resolve({ content: j?.choices?.[0]?.message?.content ?? null, retryable: false });
           } catch { /* maybe SSE */ }
           try {
             let acc = "";
@@ -59,13 +72,13 @@ function chatWithProvider(provider, messages) {
               const j = JSON.parse(d);
               acc += j?.choices?.[0]?.delta?.content || j?.choices?.[0]?.message?.content || "";
             }
-            return resolve(acc || null);
-          } catch { return resolve(null); }
+            return resolve({ content: acc || null, retryable: false });
+          } catch { return resolve({ content: null, retryable: true }); }
         });
       }
     );
-    req.on("error", () => resolve(null));
-    req.on("timeout", () => { req.destroy(); resolve(null); });
+    req.on("error", () => resolve({ content: null, retryable: true }));
+    req.on("timeout", () => { req.destroy(); resolve({ content: null, retryable: true }); });
     req.write(payload);
     req.end();
   });
@@ -75,8 +88,11 @@ async function chat(messages) {
   if (!ENABLED || deterministicEnabled()) return null;
   const { providers } = providerChainConfig();
   for (const provider of providers) {
-    const out = await chatWithProvider(provider, messages);
-    if (out) return out;
+    const key = providerKey(provider);
+    if (isCoolingDown(key)) continue;
+    const { content, retryable } = await chatWithProvider(provider, messages);
+    if (content) { recordOutcome(key, true); return content; }
+    if (retryable) recordOutcome(key, false);
   }
   return null;
 }

package/docs/configuration.md

@@ -73,6 +73,20 @@ MCP_PROVIDER_CHAIN3_MODEL=openai/gpt-4o-mini
 
 You can add `MCP_PROVIDER_CHAIN4_*`, `MCP_PROVIDER_CHAIN5_*`, and so on. The provider name is only a label; any OpenAI-compatible endpoint works when `BASE_URL`, `API_KEY`, and `MODEL` are set.
 
+On a `429`, `5xx`, timeout, or network error, a provider is put on a short cooldown and the next slot is tried. Tune the window with `MCP_PROVIDER_COOLDOWN_MS` (default `60000`).
+
+## Diagnostics
+
+Each server bin supports inspection flags that never start the server:
+
+```bash
+project-memory-mcp --version
+project-memory-mcp --doctor   # storage + model/provider config, API keys redacted
+project-memory-mcp --help
+```
+
+`--doctor` reports configured providers and storage paths and shows API keys only as `set (<n> chars)` or `not set`, never the raw value.
+
 Example OpenRouter-style config:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-dev-mcp-suite",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Four local, file-based MCP servers for solo devs/vibecoders: persistent project memory, session handoff/resume, git-independent file checkpoints, and token-efficient project briefings. Works with any MCP client.",
   "type": "module",
   "license": "MIT",
@@ -42,6 +42,7 @@
   },
   "files": [
     "bin/*.mjs",
+    "bin/_meta.mjs",
     "project-memory/*.js",
     "project-memory/server.js",
     "project-memory/embedding.js",

package/project-memory/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();
+}

package/project-memory/rerank.js

@@ -1,14 +1,14 @@
 /**
  * LLM reranker via any OpenAI-compatible /v1/chat/completions model.
- * Used when embeddings are unavailable: keyword prefilter -> LLM picks the
- * most relevant candidates. Degrades gracefully: returns null on any failure
- * so callers fall back to keyword ordering. Never throws.
+ * Tries provider chain slots in order, skipping any currently cooling down
+ * after a recent failure. Degrades gracefully: returns null on any failure so
+ * callers fall back to keyword ordering. Never throws. Never logs keys/bodies.
  */
 import http from "http";
 import https from "https";
 import { URL } from "url";
 import { deterministicEnabled } from "./env.js";
-import { providerChainConfig } from "./provider-chain.js";
+import { providerChainConfig, isCoolingDown, recordOutcome } from "./provider-chain.js";
 
 const TIMEOUT_MS = Number(process.env.RERANK_TIMEOUT_MS || 30000);
 const ENABLED = process.env.RERANK_ENABLED !== "0";
@@ -25,10 +25,19 @@ export function rerankConfig() {
   };
 }
 
+function providerKey(provider) {
+  return `${provider.label}|${provider.base}|${provider.model}`;
+}
+
+/**
+ * Resolves { content, retryable }. retryable=true means try the next provider
+ * (timeout, network error, 429, or 5xx). retryable=false with null content
+ * means a definitive non-retryable response (e.g. 4xx auth).
+ */
 function chatWithProvider(provider, messages) {
   return new Promise((resolve) => {
     let u;
-    try { u = new URL("/v1/chat/completions", provider.base); } catch { return resolve(null); }
+    try { u = new URL("/v1/chat/completions", provider.base); } catch { return resolve({ content: null, retryable: false }); }
     const payload = Buffer.from(JSON.stringify({ model: provider.model, stream: false, temperature: 0, max_tokens: 200, messages }));
     const lib = u.protocol === "https:" ? https : http;
     const req = lib.request(
@@ -44,10 +53,14 @@ function chatWithProvider(provider, messages) {
         let body = "";
         res.on("data", (c) => (body += c));
         res.on("end", () => {
-          if (res.statusCode !== 200) return resolve(null);
+          const status = res.statusCode || 0;
+          if (status !== 200) {
+            const retryable = status === 429 || status >= 500;
+            return resolve({ content: null, retryable });
+          }
           try {
             const j = JSON.parse(body);
-            return resolve(j?.choices?.[0]?.message?.content ?? null);
+            return resolve({ content: j?.choices?.[0]?.message?.content ?? null, retryable: false });
           } catch { /* maybe SSE */ }
           try {
             let acc = "";
@@ -59,13 +72,13 @@ function chatWithProvider(provider, messages) {
               const j = JSON.parse(d);
               acc += j?.choices?.[0]?.delta?.content || j?.choices?.[0]?.message?.content || "";
             }
-            return resolve(acc || null);
-          } catch { return resolve(null); }
+            return resolve({ content: acc || null, retryable: false });
+          } catch { return resolve({ content: null, retryable: true }); }
         });
       }
     );
-    req.on("error", () => resolve(null));
-    req.on("timeout", () => { req.destroy(); resolve(null); });
+    req.on("error", () => resolve({ content: null, retryable: true }));
+    req.on("timeout", () => { req.destroy(); resolve({ content: null, retryable: true }); });
     req.write(payload);
     req.end();
   });
@@ -75,8 +88,11 @@ async function chat(messages) {
   if (!ENABLED || deterministicEnabled()) return null;
   const { providers } = providerChainConfig();
   for (const provider of providers) {
-    const out = await chatWithProvider(provider, messages);
-    if (out) return out;
+    const key = providerKey(provider);
+    if (isCoolingDown(key)) continue;
+    const { content, retryable } = await chatWithProvider(provider, messages);
+    if (content) { recordOutcome(key, true); return content; }
+    if (retryable) recordOutcome(key, false);
   }
   return null;
 }