Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

feat(notfair-cmo): TTL cache on MCP probe results (0.4.2)

Yuting Zhong9d287515aeda
diff --git a/notfair-cmo/CHANGELOG.md b/notfair-cmo/CHANGELOG.md
index 4907e587..91e1df0d 100644
--- a/notfair-cmo/CHANGELOG.md
+++ b/notfair-cmo/CHANGELOG.md
@@ -1,5 +1,18 @@
# notfair-cmo
+## 0.4.2 — 2026-06-01
+
+**TTL cache on MCP probe results.** Every server render of `/connections` (and the chat thread page's notfair-googleads banner) used to fan out one `initialize` JSON-RPC call per connector to verify liveness. With six connectors that was six round-trips on every page load — fine for one user dogfooding, rude to upstreams as usage grows.
+
+New `mcp/probe-cache.ts` wraps `getMcpStatus` with an in-process TTL cache keyed by `(project_slug, catalog_key)`. State-aware TTLs:
+- `connected` → 60 s (access tokens live for hours; staleness within a minute is invisible)
+- `unreachable` → 10 s (recover quickly when the provider comes back)
+- `stale_token` / `not_configured` / `configured_no_token` → no cache (user-actionable states where instant feedback matters)
+
+Invalidated explicitly in `setMcpBearer` (after fresh OAuth callback) and `disconnectMcp` so reconnects show updated state on the very next render rather than waiting out the TTL. Pinned to `globalThis` so Next.js HMR doesn't drop the cache on every code edit.
+
+Tradeoff: the status badge can be up to 60 s out of date if you revoke an OAuth grant from the provider's dashboard. Acceptable for a local single-user tool.
+
## 0.4.1 — 2026-06-01
**Silent OAuth refresh for MCP connections.** The Connections page stopped flapping to "token expired" every hour for providers with short-lived access tokens (Stripe, Mixpanel, Supabase, PostHog). The MCP OAuth callback used to discard the `refresh_token`, `expires_in`, and `scope` fields from the token-endpoint response and store only the access token — so when the upstream rotated it (~1h for most providers), the only recovery path was a manual "Reconnect" click.
diff --git a/notfair-cmo/package.json b/notfair-cmo/package.json
index b458d951..56d984c4 100644
--- a/notfair-cmo/package.json
+++ b/notfair-cmo/package.json
@@ -1,6 +1,6 @@
{
"name": "notfair-cmo",
- "version": "0.4.1",
+ "version": "0.4.2",
"description": "Open-source AI marketing CMO portal. Run locally; orchestrates marketing agents (Google Ads, SEO, and more) on top of Claude Code, Codex, or other local AI coding agents.",
"license": "MIT",
"bin": {
diff --git a/notfair-cmo/src/server/mcp/probe-cache.test.ts b/notfair-cmo/src/server/mcp/probe-cache.test.ts
new file mode 100644
index 00000000..d738caa7
--- /dev/null
+++ b/notfair-cmo/src/server/mcp/probe-cache.test.ts
@@ -0,0 +1,133 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+ _clearProbeCacheForTests,
+ getCachedProbe,
+ invalidateProbe,
+ setCachedProbe,
+} from "./probe-cache";
+import type { McpRuntimeStatus } from "./state";
+
+const connected: McpRuntimeStatus = {
+ state: "connected",
+ url: "https://example.com/mcp",
+ tools_count: null,
+ last_checked_at: "2026-06-01T00:00:00.000Z",
+};
+
+const unreachable: McpRuntimeStatus = {
+ state: "unreachable",
+ url: "https://example.com/mcp",
+ error: "HTTP 500",
+ last_checked_at: "2026-06-01T00:00:00.000Z",
+};
+
+const staleToken: McpRuntimeStatus = {
+ state: "stale_token",
+ url: "https://example.com/mcp",
+ http_status: 401,
+ last_checked_at: "2026-06-01T00:00:00.000Z",
+};
+
+beforeEach(() => {
+ _clearProbeCacheForTests();
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date("2026-06-01T00:00:00.000Z"));
+});
+
+afterEach(() => {
+ vi.useRealTimers();
+ _clearProbeCacheForTests();
+});
+
+describe("probe-cache: TTL by state", () => {
+ it("caches connected results for 60 seconds", () => {
+ setCachedProbe("acme", "stripe", connected);
+ expect(getCachedProbe("acme", "stripe")).toEqual(connected);
+
+ vi.advanceTimersByTime(59_999);
+ expect(getCachedProbe("acme", "stripe")).toEqual(connected);
+
+ vi.advanceTimersByTime(2);
+ expect(getCachedProbe("acme", "stripe")).toBeNull();
+ });
+
+ it("caches unreachable results for 10 seconds", () => {
+ setCachedProbe("acme", "stripe", unreachable);
+ expect(getCachedProbe("acme", "stripe")).toEqual(unreachable);
+
+ vi.advanceTimersByTime(9_999);
+ expect(getCachedProbe("acme", "stripe")).toEqual(unreachable);
+
+ vi.advanceTimersByTime(2);
+ expect(getCachedProbe("acme", "stripe")).toBeNull();
+ });
+
+ it("does not cache stale_token (immediate feedback after reconnect)", () => {
+ setCachedProbe("acme", "stripe", staleToken);
+ expect(getCachedProbe("acme", "stripe")).toBeNull();
+ });
+
+ it("does not cache not_configured", () => {
+ setCachedProbe("acme", "stripe", { state: "not_configured" });
+ expect(getCachedProbe("acme", "stripe")).toBeNull();
+ });
+
+ it("does not cache configured_no_token", () => {
+ setCachedProbe("acme", "stripe", {
+ state: "configured_no_token",
+ url: "https://example.com/mcp",
+ });
+ expect(getCachedProbe("acme", "stripe")).toBeNull();
+ });
+});
+
+describe("probe-cache: keying", () => {
+ it("scopes entries by (project_slug, catalog_key)", () => {
+ setCachedProbe("acme", "stripe", connected);
+ expect(getCachedProbe("acme", "stripe")).toEqual(connected);
+ expect(getCachedProbe("acme", "supabase")).toBeNull();
+ expect(getCachedProbe("other-project", "stripe")).toBeNull();
+ });
+});
+
+describe("probe-cache: replacement and invalidation", () => {
+ it("clears a previously-cached connected entry when overwritten with a non-cacheable state", () => {
+ setCachedProbe("acme", "stripe", connected);
+ expect(getCachedProbe("acme", "stripe")).not.toBeNull();
+
+ setCachedProbe("acme", "stripe", staleToken);
+ expect(getCachedProbe("acme", "stripe")).toBeNull();
+ });
+
+ it("invalidateProbe drops the cached entry", () => {
+ setCachedProbe("acme", "stripe", connected);
+ invalidateProbe("acme", "stripe");
+ expect(getCachedProbe("acme", "stripe")).toBeNull();
+ });
+
+ it("invalidateProbe on a missing entry is a no-op (no throw)", () => {
+ expect(() => invalidateProbe("acme", "ghost")).not.toThrow();
+ });
+
+ it("overwriting a connected entry resets its TTL window", () => {
+ setCachedProbe("acme", "stripe", connected);
+ vi.advanceTimersByTime(50_000);
+ // Refresh — the second write resets the 60s window.
+ setCachedProbe("acme", "stripe", connected);
+ vi.advanceTimersByTime(50_000);
+ // 100s since the first write; 50s since the refresh — still valid.
+ expect(getCachedProbe("acme", "stripe")).toEqual(connected);
+ });
+});
+
+describe("probe-cache: read-time eviction", () => {
+ it("removes expired entries on read so the next setCachedProbe starts clean", () => {
+ setCachedProbe("acme", "stripe", connected);
+ vi.advanceTimersByTime(120_000);
+ expect(getCachedProbe("acme", "stripe")).toBeNull();
+ // After eviction, a write with a non-cacheable state is still a clear-no-op.
+ setCachedProbe("acme", "stripe", staleToken);
+ expect(getCachedProbe("acme", "stripe")).toBeNull();
+ });
+});
diff --git a/notfair-cmo/src/server/mcp/probe-cache.ts b/notfair-cmo/src/server/mcp/probe-cache.ts
new file mode 100644
index 00000000..09c99e34
--- /dev/null
+++ b/notfair-cmo/src/server/mcp/probe-cache.ts
@@ -0,0 +1,99 @@
+import type { McpRuntimeStatus } from "./state";
+
+/**
+ * In-process TTL cache for `getMcpStatus` probe results.
+ *
+ * Every server render of the Connections page (and the chat thread page,
+ * which checks notfair-googleads liveness for its banner) fans out one
+ * `initialize` JSON-RPC call per connector. Without a cache, navigating to
+ * `/connections` thirty times in five minutes means thirty round-trips per
+ * provider — fine for one user dogfooding, rude to upstreams long-term.
+ *
+ * The cache wraps just the RPC-bearing states. Stable "I have a token and
+ * the server answered" results live for 60s (access tokens last hours, so
+ * staleness here is invisible). "Provider is sick" results live for 10s so
+ * we recover quickly when the provider comes back. "Token is stale" and
+ * "nothing configured" are not cached — both are user-actionable states
+ * where instant feedback matters after a reconnect or a fresh setup.
+ *
+ * Pinned to `globalThis` so Next.js HMR doesn't drop the cache on every
+ * code edit (same pattern as `mcp-pending.ts`).
+ */
+
+type CacheEntry = { result: McpRuntimeStatus; expiresAt: number };
+
+const GLOBAL_KEY = "__notfair_cmo_probe_cache__";
+type GlobalSlot = { [GLOBAL_KEY]?: Map<string, CacheEntry> };
+const slot = globalThis as unknown as GlobalSlot;
+const STORE: Map<string, CacheEntry> =
+ slot[GLOBAL_KEY] ?? (slot[GLOBAL_KEY] = new Map());
+
+const TTL_CONNECTED_MS = 60_000;
+const TTL_UNREACHABLE_MS = 10_000;
+
+function cacheKey(project_slug: string, catalog_key: string): string {
+ return `${project_slug}|${catalog_key}`;
+}
+
+/**
+ * TTL (ms) for a given probe result. Returns 0 when the result should not
+ * be cached at all — `stale_token` (user just needs to reconnect, instant
+ * feedback wins), `not_configured` / `configured_no_token` (cheap DB-only
+ * derivations, no upstream RPC to amortize).
+ */
+function ttlFor(state: McpRuntimeStatus["state"]): number {
+ switch (state) {
+ case "connected":
+ return TTL_CONNECTED_MS;
+ case "unreachable":
+ return TTL_UNREACHABLE_MS;
+ default:
+ return 0;
+ }
+}
+
+/** Read the cache. Returns null on miss or expired entry (and evicts the latter). */
+export function getCachedProbe(
+ project_slug: string,
+ catalog_key: string,
+): McpRuntimeStatus | null {
+ const key = cacheKey(project_slug, catalog_key);
+ const entry = STORE.get(key);
+ if (!entry) return null;
+ if (entry.expiresAt <= Date.now()) {
+ STORE.delete(key);
+ return null;
+ }
+ return entry.result;
+}
+
+/** Populate the cache, or clear any prior entry when the new state is not cacheable. */
+export function setCachedProbe(
+ project_slug: string,
+ catalog_key: string,
+ result: McpRuntimeStatus,
+): void {
+ const key = cacheKey(project_slug, catalog_key);
+ const ttl = ttlFor(result.state);
+ if (ttl <= 0) {
+ // A previously-cached "connected" entry is now wrong; drop it so the
+ // next read doesn't serve a stale-positive.
+ STORE.delete(key);
+ return;
+ }
+ STORE.set(key, { result, expiresAt: Date.now() + ttl });
+}
+
+/**
+ * Drop the cached entry. Called from `setMcpBearer` (right after a fresh
+ * OAuth callback writes new credentials — the badge should update on the
+ * next render, not 60s later) and from `disconnectMcp`.
+ */
+export function invalidateProbe(project_slug: string, catalog_key: string): void {
+ STORE.delete(cacheKey(project_slug, catalog_key));
+}
+
+/** Test-only escape hatch. */
+export function _clearProbeCacheForTests(): void {
+ STORE.clear();
+}
diff --git a/notfair-cmo/src/server/mcp/state.ts b/notfair-cmo/src/server/mcp/state.ts
index 5b6981f3..3ddca634 100644
--- a/notfair-cmo/src/server/mcp/state.ts
+++ b/notfair-cmo/src/server/mcp/state.ts
@@ -1,6 +1,11 @@
import { findMcpToken, upsertMcpToken, deleteMcpToken } from "./tokens";
import { mcpSpecByKey } from "@/server/mcp-catalog";
import { mcpRpcAutoRefresh } from "./rpc";
+import {
+ getCachedProbe,
+ invalidateProbe,
+ setCachedProbe,
+} from "./probe-cache";
/**
* Status surface for the Connections page + dashboard banners.
@@ -41,7 +46,17 @@ export async function getMcpStatus(
if (!spec) return { state: "not_configured" };
const token = findMcpToken(project_slug, catalog_key);
if (!token) return { state: "not_configured" };
- return probe(project_slug, catalog_key, spec.resource_url);
+
+ // Cache short-circuit: only `connected` (60s) and `unreachable` (10s)
+ // results live in the cache. `stale_token` is deliberately uncached so
+ // a reconnect surfaces fresh state on the very next render. See
+ // probe-cache.ts for the rationale.
+ const cached = getCachedProbe(project_slug, catalog_key);
+ if (cached) return cached;
+
+ const fresh = await probe(project_slug, catalog_key, spec.resource_url);
+ setCachedProbe(project_slug, catalog_key, fresh);
+ return fresh;
}
async function probe(
@@ -118,6 +133,7 @@ async function probe(
export async function disconnectMcp(project_slug: string, catalog_key: string): Promise<void> {
const token = findMcpToken(project_slug, catalog_key);
if (token) deleteMcpToken(token.id);
+ invalidateProbe(project_slug, catalog_key);
}
export async function setMcpBearer(
@@ -144,4 +160,7 @@ export async function setMcpBearer(
client_id: options.client_id,
client_secret: options.client_secret,
});
+ // Drop any cached probe result so the badge reflects the new credentials
+ // on the very next render instead of waiting out the TTL.
+ invalidateProbe(project_slug, catalog_key);
}