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.mdindex 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.jsonindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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);}