Open-source SEO, GEO, and marketing skills for AI agents.
refactor(notfair-cmo): per-project Codex MCP namespacing + orphan prune
Yuting Zhong612f9f3fcba0
diff --git a/notfair-cmo/src/server/actions/mcp.ts b/notfair-cmo/src/server/actions/mcp.tsindex e78ce1dd..9b817bdc 100644--- a/notfair-cmo/src/server/actions/mcp.ts+++ b/notfair-cmo/src/server/actions/mcp.ts@@ -370,7 +370,11 @@ export async function removeUserMcpServerAction(input: {const agents = await listProjectAgents(project.slug);for (const agent of agents) {try {- await adapter.unregisterMcp(input.mcp_key, agent.agent_id);+ await adapter.unregisterMcp({+ serverName: input.mcp_key,+ projectSlug: project.slug,+ agentId: agent.agent_id,+ });} catch {// best-effort}diff --git a/notfair-cmo/src/server/adapters/claude-code-local/index.ts b/notfair-cmo/src/server/adapters/claude-code-local/index.tsindex bf7760ef..e9317cab 100644--- a/notfair-cmo/src/server/adapters/claude-code-local/index.ts+++ b/notfair-cmo/src/server/adapters/claude-code-local/index.ts@@ -6,6 +6,7 @@ import type {HarnessEvent,AgentProvisionSpec,McpRegistrationSpec,+ McpUnregistrationSpec,} from "../types";import { executeClaudeCodeLocal } from "./execute";import { provisionClaudeCodeAgent } from "./provision";@@ -32,7 +33,7 @@ export const claudeCodeLocalAdapter: HarnessAdapter = {async registerMcp(spec: McpRegistrationSpec): Promise<void> {await registerClaudeCodeMcp(workspaceDirFor(spec.agentId), spec);},- async unregisterMcp(serverName: string, agentId: string): Promise<void> {- await unregisterClaudeCodeMcp(workspaceDirFor(agentId), serverName);+ async unregisterMcp(spec: McpUnregistrationSpec): Promise<void> {+ await unregisterClaudeCodeMcp(workspaceDirFor(spec.agentId), spec.serverName);},};diff --git a/notfair-cmo/src/server/adapters/codex-local/index.ts b/notfair-cmo/src/server/adapters/codex-local/index.tsindex a1573b54..e61cec47 100644--- a/notfair-cmo/src/server/adapters/codex-local/index.ts+++ b/notfair-cmo/src/server/adapters/codex-local/index.ts@@ -4,6 +4,7 @@ import type {HarnessEvent,AgentProvisionSpec,McpRegistrationSpec,+ McpUnregistrationSpec,} from "../types";import { executeCodexLocal } from "./execute";import { provisionCodexAgent } from "./provision";@@ -22,7 +23,7 @@ export const codexLocalAdapter: HarnessAdapter = {async registerMcp(spec: McpRegistrationSpec): Promise<void> {await registerCodexMcp(spec);},- async unregisterMcp(serverName: string, agentId: string): Promise<void> {- await unregisterCodexMcp(serverName, agentId);+ async unregisterMcp(spec: McpUnregistrationSpec): Promise<void> {+ await unregisterCodexMcp(spec.serverName, spec.projectSlug);},};diff --git a/notfair-cmo/src/server/adapters/codex-local/mcp.test.ts b/notfair-cmo/src/server/adapters/codex-local/mcp.test.tsindex 332beec1..2496cfd7 100644--- a/notfair-cmo/src/server/adapters/codex-local/mcp.test.ts+++ b/notfair-cmo/src/server/adapters/codex-local/mcp.test.ts@@ -39,6 +39,7 @@ afterEach(() => {// Imported after the mock so the in-memory fs is the one the module uses.import {CODEX_BEARER_ENV_VAR,+ pruneOrphanCodexNamespaces,registerCodexMcp,unregisterCodexMcp,} from "./mcp";@@ -65,7 +66,7 @@ describe("registerCodexMcp (http)", () => {await registerCodexMcp(makeHttpSpec());const toml = fsState.files.get("/codex/config.toml") ?? "";expect(toml).toContain(- `[mcp_servers.notfair_acme_cmo_greg__notfair_orchestration]`,+ `[mcp_servers.notfair_acme__notfair_orchestration]`,);expect(toml).toContain(`url = "http://127.0.0.1:3326/api/mcp/orchestration"`,@@ -102,22 +103,39 @@ describe("registerCodexMcp (http)", () => {await registerCodexMcp(makeHttpSpec());const toml = fsState.files.get("/codex/config.toml") ?? "";const matches = toml.match(- /\[mcp_servers\.notfair_acme_cmo_greg__notfair_orchestration\]/g,+ /\[mcp_servers\.notfair_acme__notfair_orchestration\]/g,);expect(matches?.length).toBe(1);});- it("namespaces by agent id so two agents don't collide", async () => {- await registerCodexMcp(makeHttpSpec({ agentId: "acme-cmo-greg" }));- await registerCodexMcp(makeHttpSpec({ agentId: "acme-google-ads-ana" }));+ it("namespaces by project slug so two projects don't collide", async () => {+ await registerCodexMcp(makeHttpSpec({ projectSlug: "acme" }));+ await registerCodexMcp(makeHttpSpec({ projectSlug: "globex" }));const toml = fsState.files.get("/codex/config.toml") ?? "";expect(toml).toContain(- `[mcp_servers.notfair_acme_cmo_greg__notfair_orchestration]`,+ `[mcp_servers.notfair_acme__notfair_orchestration]`,);expect(toml).toContain(- `[mcp_servers.notfair_acme_google_ads_ana__notfair_orchestration]`,+ `[mcp_servers.notfair_globex__notfair_orchestration]`,);});++ it("collapses two agents in the same project into one shared entry", async () => {+ await registerCodexMcp(+ makeHttpSpec({ projectSlug: "acme", agentId: "acme-cmo-greg" }),+ );+ await registerCodexMcp(+ makeHttpSpec({ projectSlug: "acme", agentId: "acme-google-ads-ana" }),+ );+ const toml = fsState.files.get("/codex/config.toml") ?? "";+ const matches = toml.match(+ /\[mcp_servers\.notfair_acme__notfair_orchestration\]/g,+ );+ expect(matches?.length).toBe(1);+ // No per-agent suffixes left in the file from either registration.+ expect(toml).not.toContain("notfair_acme_cmo_greg__");+ expect(toml).not.toContain("notfair_acme_google_ads_ana__");+ });});describe("registerCodexMcp (stdio)", () => {@@ -142,12 +160,101 @@ describe("registerCodexMcp (stdio)", () => {});describe("unregisterCodexMcp", () => {- it("removes only the matching section", async () => {- await registerCodexMcp(makeHttpSpec({ agentId: "acme-cmo-greg" }));- await registerCodexMcp(makeHttpSpec({ agentId: "acme-google-ads-ana" }));- await unregisterCodexMcp("notfair-orchestration", "acme-cmo-greg");+ it("removes only the matching project's section", async () => {+ await registerCodexMcp(makeHttpSpec({ projectSlug: "acme" }));+ await registerCodexMcp(makeHttpSpec({ projectSlug: "globex" }));+ await unregisterCodexMcp("notfair-orchestration", "acme");+ const toml = fsState.files.get("/codex/config.toml") ?? "";+ expect(toml).not.toContain("notfair_acme__");+ expect(toml).toContain("notfair_globex__");+ });+});++describe("pruneOrphanCodexNamespaces", () => {+ it("strips legacy per-agent sections (prefix is an agent id, not a project slug)", async () => {+ // Hand-write a config that looks like what an upgraded 0.3.x install+ // would have: per-agent prefixes from before per-project namespacing.+ fsState.files.set(+ "/codex/config.toml",+ [+ `[mcp_servers.notfair_acme_cmo_greg__notfair_orchestration]`,+ `url = "http://x"`,+ ``,+ `[mcp_servers.notfair_acme_google_ads_ana__notfair_orchestration]`,+ `url = "http://x"`,+ ``,+ `[mcp_servers.notfair_acme__notfair_orchestration]`,+ `url = "http://x"`,+ ``,+ ].join("\n"),+ );+ const removed = await pruneOrphanCodexNamespaces(new Set(["acme"]));+ expect(removed).toBe(2);const toml = fsState.files.get("/codex/config.toml") ?? "";+ expect(toml).toContain("notfair_acme__notfair_orchestration");expect(toml).not.toContain("notfair_acme_cmo_greg__");- expect(toml).toContain("notfair_acme_google_ads_ana__");+ expect(toml).not.toContain("notfair_acme_google_ads_ana__");+ });++ it("strips sections for deleted projects", async () => {+ fsState.files.set(+ "/codex/config.toml",+ [+ `[mcp_servers.notfair_acme__notfair_orchestration]`,+ `url = "http://x"`,+ ``,+ `[mcp_servers.notfair_oldproject__notfair_orchestration]`,+ `url = "http://x"`,+ ``,+ ].join("\n"),+ );+ const removed = await pruneOrphanCodexNamespaces(new Set(["acme"]));+ expect(removed).toBe(1);+ const toml = fsState.files.get("/codex/config.toml") ?? "";+ expect(toml).toContain("notfair_acme__");+ expect(toml).not.toContain("notfair_oldproject__");+ });++ it("leaves user-installed non-notfair servers alone", async () => {+ fsState.files.set(+ "/codex/config.toml",+ [+ `[mcp_servers.user_linear]`,+ `command = "linear-mcp"`,+ ``,+ `[mcp_servers.notfair_dead__notfair_orchestration]`,+ `url = "http://x"`,+ ``,+ ].join("\n"),+ );+ const removed = await pruneOrphanCodexNamespaces(new Set(["acme"]));+ expect(removed).toBe(1);+ const toml = fsState.files.get("/codex/config.toml") ?? "";+ expect(toml).toContain(`[mcp_servers.user_linear]`);+ expect(toml).toContain(`command = "linear-mcp"`);+ expect(toml).not.toContain("notfair_dead__");+ });++ it("normalizes dashed slugs to underscored prefixes before comparing", async () => {+ fsState.files.set(+ "/codex/config.toml",+ [+ `[mcp_servers.notfair_acme_co__notfair_orchestration]`,+ `url = "http://x"`,+ ``,+ ].join("\n"),+ );+ // Project slug uses a dash; namespace prefix uses underscore.+ const removed = await pruneOrphanCodexNamespaces(new Set(["acme-co"]));+ expect(removed).toBe(0);+ expect(fsState.files.get("/codex/config.toml")).toContain(+ "notfair_acme_co__",+ );+ });++ it("is a no-op when the config file is absent", async () => {+ const removed = await pruneOrphanCodexNamespaces(new Set(["acme"]));+ expect(removed).toBe(0);+ expect(fsState.files.has("/codex/config.toml")).toBe(false);});});diff --git a/notfair-cmo/src/server/adapters/codex-local/mcp.ts b/notfair-cmo/src/server/adapters/codex-local/mcp.tsindex a82b78d3..85e8960b 100644--- a/notfair-cmo/src/server/adapters/codex-local/mcp.ts+++ b/notfair-cmo/src/server/adapters/codex-local/mcp.ts@@ -5,12 +5,25 @@ import { join } from "node:path";import type { McpRegistrationSpec } from "../types";/**- * Per-agent MCP wiring for Codex.+ * Project-scoped MCP wiring for Codex.*- * Codex reads MCP servers from `~/.codex/config.toml`. notfair-cmo wants- * project-scoped tokens, but codex's MCP config is global, so we namespace- * server names with the agent id: `<serverName>__<agentId>`. The- * orchestration MCP that needs to know the agent context can read that.+ * Codex reads MCP servers from `~/.codex/config.toml` — a single global file+ * shared across every project and agent on the machine. MCP tokens in+ * notfair-cmo are project-scoped (one (project, server) pair → one bearer+ * shared by every agent in the project), so we namespace by project slug:+ * `notfair_<projectSlug>__<serverName>`. Every agent in the same project+ * sees the same entry; sibling projects don't duplicate.+ *+ * Earlier versions namespaced by agent id, which produced N entries per+ * project (one per agent) and let agents see each other's prefixes when+ * Codex enumerated the global config. Per-project namespacing collapses+ * that to one entry per project per server.+ *+ * Cross-project visibility in the global config is a residual: an agent in+ * project A can still see `notfair_B__*` headers because Codex reads the+ * whole file. Fully isolating that would require pointing CODEX_HOME at a+ * per-project path, which would also break the user's `~/.codex/auth.json`+ * login. Left as a future change.** We rewrite the [mcp_servers.*] sections under our namespace prefix; we* never touch user-installed servers outside our prefix.@@ -25,8 +38,8 @@ function codexConfigPath(): string {const NOTFAIR_NS = "notfair_";-function namespaced(serverName: string, agentId: string): string {- return `${NOTFAIR_NS}${agentId.replace(/-/g, "_")}__${serverName.replace(/[^a-zA-Z0-9]/g, "_")}`;+function namespaced(serverName: string, projectSlug: string): string {+ return `${NOTFAIR_NS}${projectSlug.replace(/-/g, "_")}__${serverName.replace(/[^a-zA-Z0-9]/g, "_")}`;}async function readConfig(): Promise<string> {@@ -86,7 +99,7 @@ export function bearerEnvVarForServer(serverName: string): string {export const CODEX_BEARER_ENV_VAR = "NOTFAIR_ORCHESTRATION_BEARER";function renderServer(spec: McpRegistrationSpec): string {- const header = `[mcp_servers.${namespaced(spec.serverName, spec.agentId)}]`;+ const header = `[mcp_servers.${namespaced(spec.serverName, spec.projectSlug)}]`;if (spec.transport.type === "stdio") {const lines = [header,@@ -127,17 +140,63 @@ function tomlInlineTable(record: Record<string, string>): string {export async function registerCodexMcp(spec: McpRegistrationSpec): Promise<void> {await mkdir(codexConfigDir(), { recursive: true });let toml = await readConfig();- toml = stripSection(toml, `mcp_servers.${namespaced(spec.serverName, spec.agentId)}`);+ toml = stripSection(toml, `mcp_servers.${namespaced(spec.serverName, spec.projectSlug)}`);toml = toml.trimEnd() + "\n\n" + renderServer(spec);await writeFile(codexConfigPath(), toml.trimStart(), "utf8");}export async function unregisterCodexMcp(serverName: string,- agentId: string,+ projectSlug: string,): Promise<void> {let toml = await readConfig();if (!toml) return;- toml = stripSection(toml, `mcp_servers.${namespaced(serverName, agentId)}`);+ toml = stripSection(toml, `mcp_servers.${namespaced(serverName, projectSlug)}`);await writeFile(codexConfigPath(), toml.trimStart(), "utf8");}++/**+ * Strip `[mcp_servers.notfair_<prefix>__<server>]` sections from the global+ * Codex config when `<prefix>` is not the slug of any currently-known+ * project. Catches two kinds of orphans:+ *+ * 1. Legacy per-agent entries written before per-project namespacing+ * (`notfair_demo1_cmo_greg__notfair_googleads`) — the prefix is an+ * agent id, not a project slug.+ * 2. Entries from projects that have since been deleted without going+ * through cascade-delete (manual db edits, crashes mid-delete).+ *+ * Returns the number of sections removed. Best-effort: leaves the file+ * untouched on parse errors.+ */+export async function pruneOrphanCodexNamespaces(+ activeProjectSlugs: ReadonlySet<string>,+): Promise<number> {+ const toml = await readConfig();+ if (!toml) return 0;+ // Project slugs in the namespace use `_` where the slug uses `-`, so+ // normalize both sides for comparison.+ const validPrefixes = new Set(+ Array.from(activeProjectSlugs, (s) => s.replace(/-/g, "_")),+ );+ // Match `[mcp_servers.notfair_<prefix>__<rest>]` and capture the prefix.+ // The prefix is greedy-up-to-the-final-`__` so multi-underscore agent ids+ // (`acme_cmo_greg`) collapse to one capture.+ const headerRe = /\[mcp_servers\.notfair_([A-Za-z0-9_]+?)__[A-Za-z0-9_]+\]/g;+ const orphans = new Set<string>();+ for (const m of toml.matchAll(headerRe)) {+ const prefix = m[1];+ if (!validPrefixes.has(prefix)) {+ // Strip the leading `[mcp_servers.` + trailing `]` to get the section+ // header `stripSection` expects.+ orphans.add(m[0].slice(1, -1));+ }+ }+ if (orphans.size === 0) return 0;+ let next = toml;+ for (const section of orphans) {+ next = stripSection(next, section);+ }+ await writeFile(codexConfigPath(), next.trimStart(), "utf8");+ return orphans.size;+}diff --git a/notfair-cmo/src/server/adapters/types.ts b/notfair-cmo/src/server/adapters/types.tsindex 2d3b29d0..3d3b1a8e 100644--- a/notfair-cmo/src/server/adapters/types.ts+++ b/notfair-cmo/src/server/adapters/types.ts@@ -118,5 +118,14 @@ export interface HarnessAdapter {provisionAgent(spec: AgentProvisionSpec): Promise<void>;registerMcp(spec: McpRegistrationSpec): Promise<void>;- unregisterMcp(serverName: string, agentId: string): Promise<void>;+ unregisterMcp(spec: McpUnregistrationSpec): Promise<void>;+}++export interface McpUnregistrationSpec {+ /** Logical server name. */+ serverName: string;+ /** Project slug — Codex's project-namespaced global config key. */+ projectSlug: string;+ /** Agent id — Claude Code's per-workspace `.mcp.json` lives under it. */+ agentId: string;}diff --git a/notfair-cmo/src/server/agents/cascade-delete.ts b/notfair-cmo/src/server/agents/cascade-delete.tsindex d8100176..55a0c6a2 100644--- a/notfair-cmo/src/server/agents/cascade-delete.ts+++ b/notfair-cmo/src/server/agents/cascade-delete.ts@@ -107,13 +107,18 @@ export async function cascadeDeleteProjectArtifacts(project_slug: string): Promiconst agents = await listProjectAgents(project_slug);// Unregister any MCP servers the adapter wrote into its config (so codex- // global config doesn't leak agent-namespaced rows for deleted agents).+ // global config doesn't leak rows for deleted projects, and claude-code+ // workspaces don't reference dead bearers).if (adapter) {const catalog = getMcpCatalog(project_slug);for (const agent of agents) {for (const spec of catalog) {try {- await adapter.unregisterMcp(spec.key, agent.agent_id);+ await adapter.unregisterMcp({+ serverName: spec.key,+ projectSlug: project_slug,+ agentId: agent.agent_id,+ });} catch {// best-effort}diff --git a/notfair-cmo/src/server/mcp-server/registration.ts b/notfair-cmo/src/server/mcp-server/registration.tsindex a2009af4..1ba586ef 100644--- a/notfair-cmo/src/server/mcp-server/registration.ts+++ b/notfair-cmo/src/server/mcp-server/registration.ts@@ -1,9 +1,10 @@import { requireAdapter } from "@/server/adapters/registry";-import { getProject } from "@/server/db/projects";+import { getProject, listProjects } from "@/server/db/projects";import { listProjectAgents } from "@/server/agent-meta";import { mcpSpecByKey } from "@/server/mcp-catalog";import { findMcpToken } from "@/server/mcp/tokens";import { getOrCreateMcpServerSecret } from "./secret";+import type { HarnessAdapterId } from "@/server/adapters/types";/*** Register notfair-cmo's outbound MCP server (`notfair-orchestration`) with@@ -28,6 +29,39 @@ function defaultMcpUrl(): string {return `http://127.0.0.1:${port}/api/mcp/orchestration`;}+/**+ * One-shot per-process cleanup of legacy per-agent + dead-project rows in+ * `~/.codex/config.toml`. Per-project namespacing landed in 0.4.x; older+ * installs still have `[mcp_servers.notfair_<agentId>__...]` headers from+ * before the switch, which keep showing up when an agent introspects its+ * tools. Strip them once on the first registration we run after start.+ *+ * Claude Code's per-workspace `.mcp.json` doesn't have this problem, so+ * the prune is no-op for that adapter.+ */+let codexPruneRan = false;+async function maybePruneCodexOrphans(adapterId: HarnessAdapterId): Promise<void> {+ if (adapterId !== "codex-local" || codexPruneRan) return;+ codexPruneRan = true;+ try {+ const { pruneOrphanCodexNamespaces } = await import(+ "@/server/adapters/codex-local/mcp"+ );+ const slugs = new Set(+ listProjects({ includeArchived: true }).map((p) => p.slug),+ );+ const removed = await pruneOrphanCodexNamespaces(slugs);+ if (removed > 0) {+ console.info(+ `[mcp] pruned ${removed} orphan notfair_* section(s) from ~/.codex/config.toml`,+ );+ }+ } catch (err) {+ // Best-effort. A broken prune must not block actual registration.+ console.warn("[mcp] codex orphan prune failed:", err);+ }+}+export type InstallResult =| { ok: true; key: string; url: string }| { ok: false; key: string; url: string; error: string };@@ -43,6 +77,7 @@ export async function registerOrchestrationForAgent(}try {const adapter = requireAdapter(project.harness_adapter);+ await maybePruneCodexOrphans(adapter.id);await adapter.registerMcp({serverName: ORCHESTRATION_MCP_KEY,agentId: agent_id,@@ -107,6 +142,7 @@ export async function registerCatalogMcpForAgent(}try {const adapter = requireAdapter(project.harness_adapter);+ await maybePruneCodexOrphans(adapter.id);await adapter.registerMcp({serverName: catalog_key,agentId: agent_id,