Skip to content

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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): Promi
const 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.ts
index 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,