@triflux/core 10.1.0 → 10.25.1

package/scripts/lib/mcp-guard-engine.mjs

@@ -1,12 +1,38 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+} from "node:path";
 import { fileURLToPath } from "node:url";
 
 const PROJECT_ROOT = fileURLToPath(new URL("../../", import.meta.url));
-const REGISTRY_PATH = join(PROJECT_ROOT, "config", "mcp-registry.json");
+const DEFAULT_REGISTRY_PATH = join(PROJECT_ROOT, "config", "mcp-registry.json");
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
 const DEFAULT_HUB_PATH = "/mcp";
+const SERVER_POLICIES = new Set(["hosted", "gateway-sse", "stdio"]);
+const GATEWAY_PORTS = Object.freeze({
+  context7: 8100,
+  "brave-search": 8101,
+  exa: 8102,
+  tavily: 8103,
+  jira: 8104,
+  serena: 8105,
+  notion: 8106,
+  "notion-guest": 8107,
+});
 const DEFAULT_REGISTRY = Object.freeze({
   $schema: "mcp-registry-schema",
   version: 1,
@@ -15,24 +41,37 @@ const DEFAULT_REGISTRY = Object.freeze({
     transport: "hub-url",
     hub_base: "http://127.0.0.1:27888",
   },
+  policy_notes: {
+    transport:
+      'Server transport accepts "hub-url" for triflux Hub URL flow, "http" for direct Streamable HTTP MCP endpoints, or "stdio" for upstream-stdio-only MCP servers (rare; only for servers that have no hosted HTTP endpoint, e.g. brave-search). stdio servers require command, args, and may include env.',
+    headers:
+      'Optional headers are allowed only for HTTP-compatible transports. Each header value must be a descriptor: {"value":"literal"} for non-secret static values, {"env":"ENV_VAR_NAME"} for secrets resolved at sync/runtime, or {"env":"ENV_VAR_NAME","prefix":"Bearer "} for common authorization formats.',
+    secret_safety:
+      "Resolved secret values must not be written back to this registry file. Missing env vars warn during sync and do not emit empty secret headers.",
+  },
   servers: {
     "tfx-hub": {
+      policy: "hosted",
       transport: "hub-url",
       url: "http://127.0.0.1:27888/mcp",
       safe: true,
-      targets: ["claude", "gemini", "codex"],
+      targets: ["claude", "gemini", "codex", "antigravity"],
       description: "triflux Hub MCP 서버",
     },
   },
   policies: {
     stdio_action: "replace-with-hub",
     unknown_server_action: "warn",
+    sync_denylist: [],
     watched_paths: [
       "~/.gemini/settings.json",
       "~/.codex/config.toml",
+      "~/.claude.json",
       "~/.claude/settings.json",
       "~/.claude/settings.local.json",
+      ".claude/mcp.json",
       ".mcp.json",
+      "~/.gemini/config/mcp_config.json",
     ],
   },
 });
@@ -43,13 +82,39 @@ function cloneDefaultRegistry() {
 
 function expandHome(filePath) {
   if (typeof filePath !== "string") return "";
-  if (!filePath.startsWith("~/") && !filePath.startsWith("~\\")) return filePath;
+  if (!filePath.startsWith("~/") && !filePath.startsWith("~\\"))
+    return filePath;
   return join(homedir(), filePath.slice(2));
 }
 
 function resolveFilePath(filePath) {
   const expanded = expandHome(filePath);
-  return isAbsolute(expanded) ? resolve(expanded) : resolve(process.cwd(), expanded);
+  return isAbsolute(expanded)
+    ? resolve(expanded)
+    : resolve(process.cwd(), expanded);
+}
+
+function defaultProjectsRoot() {
+  return process.env.TFX_MCP_PROJECTS_ROOT
+    ? resolve(expandHome(process.env.TFX_MCP_PROJECTS_ROOT))
+    : join(homedir(), "Projects");
+}
+
+function globToRegExp(glob) {
+  const source = String(glob || "")
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*/g, ".*")
+    .replace(/\?/g, ".");
+  return new RegExp(`^${source}$`);
+}
+
+function isExcludedProjectPath(relativePath, excludePatterns = []) {
+  const normalized = relativePath.replace(/\\/g, "/").replace(/^\/+/, "");
+  const basenameValue = basename(normalized);
+  return excludePatterns.some((pattern) => {
+    const re = globToRegExp(pattern);
+    return re.test(normalized) || re.test(basenameValue);
+  });
 }
 
 function normalizeForMatch(filePath) {
@@ -60,6 +125,14 @@ function pathBasename(filePath) {
   return basename(filePath.replace(/\\/g, "/")).toLowerCase();
 }
 
+function isClaudeProjectMcpConfig(filePath) {
+  return normalizeForMatch(filePath).endsWith("/.claude/mcp.json");
+}
+
+function isClaudeUserConfig(filePath) {
+  return normalizeForMatch(filePath).endsWith("/.claude.json");
+}
+
 function readJsonFile(filePath) {
   return JSON.parse(readFileSync(filePath, "utf8"));
 }
@@ -69,6 +142,12 @@ function writeJsonFile(filePath, data) {
   writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf8");
 }
 
+function registryPath() {
+  return process.env.TFX_MCP_REGISTRY_PATH
+    ? resolve(process.env.TFX_MCP_REGISTRY_PATH)
+    : DEFAULT_REGISTRY_PATH;
+}
+
 function ensureBackup(filePath) {
   const backupPath = `${filePath}.bak`;
   copyFileSync(filePath, backupPath);
@@ -77,7 +156,15 @@ function ensureBackup(filePath) {
 
 function isJsonMcpConfig(filePath) {
   const name = pathBasename(filePath);
-  return name === "settings.json" || name === "settings.local.json" || name === ".mcp.json";
+  return (
+    isAntigravityConfig(filePath) ||
+    isClaudeUserConfig(filePath) ||
+    name === "settings.json" ||
+    name === "settings.local.json" ||
+    name === "mcp_config.json" ||
+    name === ".mcp.json" ||
+    isClaudeProjectMcpConfig(filePath)
+  );
 }
 
 function isCodexConfig(filePath) {
@@ -85,14 +172,59 @@ function isCodexConfig(filePath) {
   return normalized.endsWith("/.codex/config.toml");
 }
 
+function isAntigravityConfig(filePath) {
+  const normalized = normalizeForMatch(filePath);
+  return normalized.endsWith("/.gemini/config/mcp_config.json");
+}
+
+function plaintextSecretHeaderClient(filePath) {
+  const client = detectClient(filePath);
+  return client === "gemini" || client === "antigravity" ? client : null;
+}
+
+function plaintextSecretPermissionHint(filePath) {
+  const normalized = normalizeForMatch(filePath);
+  if (normalized.endsWith("/.gemini/settings.json")) {
+    return "~/.gemini/settings.json";
+  }
+  if (normalized.endsWith("/.gemini/config/mcp_config.json")) {
+    return "~/.gemini/config/mcp_config.json";
+  }
+  return filePath;
+}
+
+function shouldLockJsonConfigPermissions(filePath) {
+  return Boolean(plaintextSecretHeaderClient(filePath));
+}
+
+function lockJsonConfigPermissions(filePath) {
+  if (!shouldLockJsonConfigPermissions(filePath)) return;
+  chmodSync(filePath, 0o600);
+}
+
+function isProtectedCodexConfigMutationEnv(env = process.env) {
+  return env.NODE_ENV === "test" || env.CI === "true" || env.TFX_TEST === "1";
+}
+
+function shouldSkipCodexConfigMutation() {
+  return (
+    process.env.TFX_CODEX_CONFIG_SYNC !== "1" &&
+    isProtectedCodexConfigMutationEnv()
+  );
+}
+
 function detectClient(filePath) {
   const normalized = normalizeForMatch(filePath);
+  if (normalized.endsWith("/.gemini/config/mcp_config.json"))
+    return "antigravity";
   if (normalized.endsWith("/.gemini/settings.json")) return "gemini";
   if (normalized.endsWith("/.codex/config.toml")) return "codex";
   if (
-    normalized.endsWith("/.claude/settings.json")
-    || normalized.endsWith("/.claude/settings.local.json")
-    || normalized.endsWith("/.mcp.json")
+    normalized.endsWith("/.claude.json") ||
+    normalized.endsWith("/.claude/settings.json") ||
+    normalized.endsWith("/.claude/settings.local.json") ||
+    normalized.endsWith("/.claude/mcp.json") ||
+    normalized.endsWith("/.mcp.json")
   ) {
     return "claude";
   }
@@ -101,19 +233,31 @@ function detectClient(filePath) {
 
 function detectLabel(filePath) {
   const normalized = normalizeForMatch(filePath);
+  if (normalized.endsWith("/.gemini/config/mcp_config.json"))
+    return "Antigravity";
   if (normalized.endsWith("/.gemini/settings.json")) return "Gemini";
+  if (normalized.endsWith("/.gemini/config/mcp_config.json"))
+    return "Antigravity";
   if (normalized.endsWith("/.codex/config.toml")) return "Codex";
+  if (normalized.endsWith("/.claude.json")) return "Claude User MCP";
   if (normalized.endsWith("/.claude/settings.json")) return "Claude User";
-  if (normalized.endsWith("/.claude/settings.local.json")) return "Claude Local";
+  if (normalized.endsWith("/.claude/settings.local.json"))
+    return "Claude Local";
+  if (normalized.endsWith("/.claude/mcp.json")) return "Claude Project MCP";
   if (normalized.endsWith("/.mcp.json")) return "Project MCP";
   return basename(filePath);
 }
 
 function isPrimaryConfigTarget(filePath) {
   const normalized = normalizeForMatch(filePath);
-  return normalized.endsWith("/.gemini/settings.json")
-    || normalized.endsWith("/.codex/config.toml")
-    || normalized.endsWith("/.mcp.json");
+  return (
+    normalized.endsWith("/.gemini/settings.json") ||
+    normalized.endsWith("/.gemini/config/mcp_config.json") ||
+    normalized.endsWith("/.codex/config.toml") ||
+    normalized.endsWith("/.claude.json") ||
+    normalized.endsWith("/.claude/mcp.json") ||
+    normalized.endsWith("/.mcp.json")
+  );
 }
 
 function normalizeUrl(value) {
@@ -139,12 +283,95 @@ function parseTomlScalar(rawValue) {
   if (value === "true") return true;
   if (value === "false") return false;
   if (/^-?\d[\d_]*$/.test(value)) return Number(value.replace(/_/g, ""));
+  if (value.startsWith("[") && value.endsWith("]")) {
+    return parseTomlArray(value);
+  }
+  if (value.startsWith("{") && value.endsWith("}")) {
+    return parseTomlInlineTable(value);
+  }
   if (value.startsWith('"') && value.endsWith('"')) {
     return value.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
   }
   return value;
 }
 
+function parseTomlArray(rawValue) {
+  const source = String(rawValue || "").trim();
+  const body = source.slice(1, -1).trim();
+  if (!body) return [];
+
+  const parts = [];
+  let current = "";
+  let inString = false;
+  let escaped = false;
+  for (const char of body) {
+    if (escaped) {
+      current += char;
+      escaped = false;
+      continue;
+    }
+    if (char === "\\" && inString) {
+      current += char;
+      escaped = true;
+      continue;
+    }
+    if (char === '"') inString = !inString;
+    if (char === "," && !inString) {
+      parts.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (current.trim()) parts.push(current.trim());
+
+  return parts.map((part) => parseTomlScalar(part));
+}
+
+function parseTomlInlineTable(rawValue) {
+  const source = String(rawValue || "").trim();
+  const body = source.slice(1, -1).trim();
+  if (!body) return {};
+
+  const parts = [];
+  let current = "";
+  let inString = false;
+  let escaped = false;
+  for (const char of body) {
+    if (escaped) {
+      current += char;
+      escaped = false;
+      continue;
+    }
+    if (char === "\\" && inString) {
+      current += char;
+      escaped = true;
+      continue;
+    }
+    if (char === '"') inString = !inString;
+    if (char === "," && !inString) {
+      parts.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (current.trim()) parts.push(current.trim());
+
+  const table = {};
+  for (const part of parts) {
+    const match = part.match(
+      /^\s*(?:"((?:\\"|[^"])*)"|([A-Za-z0-9_-]+))\s*=\s*(.+?)\s*$/,
+    );
+    if (!match) continue;
+    const key = (match[1] || match[2] || "")
+      .replace(/\\"/g, '"')
+      .replace(/\\\\/g, "\\");
+    table[key] = parseTomlScalar(match[3]);
+  }
+  return table;
+}
+
 function parseCodexMcpServers(raw) {
   const lines = String(raw || "").split(/\r?\n/);
   const servers = {};
@@ -173,6 +400,231 @@ function parseCodexMcpServers(raw) {
   return servers;
 }
 
+function isValidHeaderName(name) {
+  return /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(String(name || ""));
+}
+
+function isValidEnvName(name) {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(String(name || ""));
+}
+
+function normalizeHeaderDescriptors(headers = {}) {
+  const normalized = {};
+  if (!headers || typeof headers !== "object" || Array.isArray(headers)) {
+    return normalized;
+  }
+  for (const [name, descriptor] of Object.entries(headers)) {
+    if (!isValidHeaderName(name)) continue;
+    if (
+      descriptor &&
+      typeof descriptor === "object" &&
+      !Array.isArray(descriptor)
+    ) {
+      if (
+        Object.hasOwn(descriptor, "value") &&
+        typeof descriptor.value === "string"
+      ) {
+        normalized[name] = { value: descriptor.value };
+      } else if (
+        Object.hasOwn(descriptor, "env") &&
+        typeof descriptor.env === "string" &&
+        descriptor.env.trim()
+      ) {
+        normalized[name] = { env: descriptor.env.trim() };
+        if (typeof descriptor.prefix === "string") {
+          normalized[name].prefix = descriptor.prefix;
+        }
+      }
+    }
+  }
+  return normalized;
+}
+
+function normalizeEnvDescriptors(env = {}) {
+  const normalized = {};
+  if (!env || typeof env !== "object" || Array.isArray(env)) {
+    return normalized;
+  }
+  for (const [name, descriptor] of Object.entries(env)) {
+    if (!isValidEnvName(name)) continue;
+    if (
+      descriptor &&
+      typeof descriptor === "object" &&
+      !Array.isArray(descriptor) &&
+      Object.hasOwn(descriptor, "env") &&
+      typeof descriptor.env === "string" &&
+      descriptor.env.trim()
+    ) {
+      normalized[name] = { env: descriptor.env.trim() };
+    }
+  }
+  return normalized;
+}
+
+function resolveEnvDescriptors(name, serverConfig) {
+  const descriptors = normalizeEnvDescriptors(serverConfig?.env || {});
+  const env = {};
+  const warnings = [];
+
+  for (const [envKey, descriptor] of Object.entries(descriptors)) {
+    const envName = descriptor.env;
+    const envValue = process.env[envName];
+    if (typeof envValue !== "string" || envValue.length === 0) {
+      warnings.push(
+        `[mcp-guard] ${name}.${envKey} env skipped: env ${envName} is not set`,
+      );
+      continue;
+    }
+    env[envKey] = envValue;
+  }
+
+  return { descriptors, env, warnings };
+}
+
+function resolveHeaderDescriptors(name, serverConfig, filePath) {
+  const descriptors = normalizeHeaderDescriptors(serverConfig?.headers || {});
+  const headers = {};
+  const warnings = [];
+  const codex = {
+    bearer_token_env_var: null,
+    env_http_headers: {},
+    http_headers: {},
+  };
+  const codexTarget = isCodexConfig(filePath);
+
+  for (const [headerName, descriptor] of Object.entries(descriptors)) {
+    if (Object.hasOwn(descriptor, "value")) {
+      headers[headerName] = descriptor.value;
+      if (codexTarget) codex.http_headers[headerName] = descriptor.value;
+      continue;
+    }
+
+    const envName = descriptor.env;
+    const envValue = process.env[envName];
+    const prefix = descriptor.prefix || "";
+    if (typeof envValue !== "string" || envValue.length === 0) {
+      warnings.push(
+        `[mcp-guard] ${name}.${headerName} header skipped: env ${envName} is not set`,
+      );
+      continue;
+    }
+
+    headers[headerName] = `${prefix}${envValue}`;
+
+    const plaintextClient = plaintextSecretHeaderClient(filePath);
+    if (plaintextClient) {
+      warnings.push(
+        `[tfx mcp sync] warn: ${plaintextClient} server '${name}' headers contain plaintext secret resolved from $${envName}. Ensure ${plaintextSecretPermissionHint(filePath)} permissions stay 600.`,
+      );
+    }
+
+    if (!codexTarget) continue;
+
+    if (
+      headerName.toLowerCase() === "authorization" &&
+      /^Bearer\s+$/i.test(prefix)
+    ) {
+      codex.bearer_token_env_var = envName;
+    } else if (!prefix) {
+      codex.env_http_headers[headerName] = envName;
+    } else {
+      codex.http_headers[headerName] = `${prefix}${envValue}`;
+      warnings.push(
+        `[mcp-guard] ${name}.${headerName} header uses resolved literal in Codex TOML because prefixed env headers are unsupported`,
+      );
+    }
+  }
+
+  return {
+    descriptors,
+    headers,
+    warnings,
+    codex: {
+      ...(codex.bearer_token_env_var
+        ? { bearer_token_env_var: codex.bearer_token_env_var }
+        : {}),
+      env_http_headers: codex.env_http_headers,
+      http_headers: codex.http_headers,
+    },
+  };
+}
+
+function hasOwnEntries(value) {
+  return value && typeof value === "object" && Object.keys(value).length > 0;
+}
+
+function redactHeaders(headers = {}) {
+  const redacted = {};
+  for (const key of Object.keys(headers || {})) {
+    redacted[key] = "***REDACTED***";
+  }
+  return redacted;
+}
+
+function redactServerConfig(config = {}) {
+  if (!config || typeof config !== "object") return config;
+  return {
+    ...config,
+    ...(config.headers ? { headers: redactHeaders(config.headers) } : {}),
+  };
+}
+
+function descriptorsFromCodexConfig(config = {}) {
+  const descriptors = {};
+  if (typeof config.bearer_token_env_var === "string") {
+    descriptors.Authorization = {
+      env: config.bearer_token_env_var,
+      prefix: "Bearer ",
+    };
+  }
+  if (config.env_http_headers && typeof config.env_http_headers === "object") {
+    for (const [name, envName] of Object.entries(config.env_http_headers)) {
+      if (typeof envName === "string") descriptors[name] = { env: envName };
+    }
+  }
+  if (config.http_headers && typeof config.http_headers === "object") {
+    for (const [name, value] of Object.entries(config.http_headers)) {
+      if (typeof value === "string") descriptors[name] = { value };
+    }
+  }
+  return descriptors;
+}
+
+function descriptorsFromJsonConfig(config = {}) {
+  const descriptors = {};
+  if (!config?.headers || typeof config.headers !== "object") {
+    return descriptors;
+  }
+  for (const [name, value] of Object.entries(config.headers)) {
+    if (typeof value === "string") descriptors[name] = { value };
+  }
+  return descriptors;
+}
+
+function headerNames(headers = {}) {
+  return Object.keys(headers || {}).sort();
+}
+
+function sameHeaderDescriptors(left = {}, right = {}) {
+  const leftNames = headerNames(left);
+  const rightNames = headerNames(right);
+  if (JSON.stringify(leftNames) !== JSON.stringify(rightNames)) return false;
+  return leftNames.every(
+    (name) => JSON.stringify(left[name]) === JSON.stringify(right[name]),
+  );
+}
+
+function headerStatus(expected = {}, actual = {}) {
+  const expectedNames = headerNames(expected);
+  const actualNames = headerNames(actual);
+  if (expectedNames.length === 0 && actualNames.length === 0) return "ok";
+  if (expectedNames.some((name) => !Object.hasOwn(actual, name))) {
+    return "missing";
+  }
+  if (!sameHeaderDescriptors(expected, actual)) return "stale";
+  return "ok";
+}
+
 function removeTomlSection(raw, sectionName) {
   const lines = String(raw || "").split(/\r?\n/);
   const output = [];
@@ -192,30 +644,113 @@ function removeTomlSection(raw, sectionName) {
     if (!skipping) output.push(line);
   }
 
-  const cleaned = output.join("\n").replace(/\n{3,}$/g, "\n\n").replace(/^\n+/, "");
+  const cleaned = output
+    .join("\n")
+    .replace(/\n{3,}$/g, "\n\n")
+    .replace(/^\n+/, "");
   return cleaned.length > 0 ? cleaned.replace(/\n{3,}/g, "\n\n") : "";
 }
 
-function upsertTomlUrlServer(raw, name, url) {
-  const section = [
-    `[mcp_servers.${name}]`,
-    `url = ${formatTomlString(url)}`,
-  ];
-  const withoutExisting = removeTomlSection(raw, name).trimEnd();
-  return withoutExisting.length > 0
-    ? `${withoutExisting}\n\n${section.join("\n")}\n`
-    : `${section.join("\n")}\n`;
+function formatTomlInlineTable(data = {}) {
+  const entries = Object.entries(data);
+  if (entries.length === 0) return null;
+  return `{ ${entries
+    .map(
+      ([key, value]) => `${formatTomlString(key)} = ${formatTomlString(value)}`,
+    )
+    .join(", ")} }`;
+}
+
+function formatTomlArray(values = []) {
+  return `[${values.map((value) => formatTomlString(value)).join(", ")}]`;
+}
+
+function upsertTomlServer(raw, name, config, codex = {}) {
+  const lines = String(raw || "").split(/\r?\n/);
+  const header = `[mcp_servers.${name}]`;
+  const managedKeys = new Set([
+    "url",
+    "transport",
+    "command",
+    "args",
+    "bearer_token_env_var",
+    "http_headers",
+    "env_http_headers",
+    "env",
+  ]);
+  const nextManagedLines = [];
+  if (typeof config.url === "string") {
+    nextManagedLines.push(`url = ${formatTomlString(config.url)}`);
+  }
+  if (typeof config.transport === "string") {
+    nextManagedLines.push(`transport = ${formatTomlString(config.transport)}`);
+  }
+  if (typeof config.command === "string") {
+    nextManagedLines.push(`command = ${formatTomlString(config.command)}`);
+  }
+  if (Array.isArray(config.args)) {
+    nextManagedLines.push(`args = ${formatTomlArray(config.args)}`);
+  }
+  const env = formatTomlInlineTable(config.env || {});
+  if (env) nextManagedLines.push(`env = ${env}`);
+  if (codex.bearer_token_env_var) {
+    nextManagedLines.push(
+      `bearer_token_env_var = ${formatTomlString(codex.bearer_token_env_var)}`,
+    );
+  }
+  const httpHeaders = formatTomlInlineTable(codex.http_headers || {});
+  if (httpHeaders) nextManagedLines.push(`http_headers = ${httpHeaders}`);
+  const envHttpHeaders = formatTomlInlineTable(codex.env_http_headers || {});
+  if (envHttpHeaders) {
+    nextManagedLines.push(`env_http_headers = ${envHttpHeaders}`);
+  }
+
+  const sectionStart = lines.findIndex((line) => line.trim() === header);
+  if (sectionStart < 0) {
+    const section = [header, ...nextManagedLines].join("\n");
+    const withoutTrailing = String(raw || "").trimEnd();
+    return withoutTrailing.length > 0
+      ? `${withoutTrailing}\n\n${section}\n`
+      : `${section}\n`;
+  }
+
+  const output = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    output.push(lines[index]);
+    if (index !== sectionStart) continue;
+
+    index += 1;
+    const preserved = [];
+    while (index < lines.length && !/^\s*\[/.test(lines[index])) {
+      const keyMatch = lines[index].match(/^\s*([A-Za-z0-9_]+)\s*=/);
+      if (!keyMatch || !managedKeys.has(keyMatch[1])) {
+        preserved.push(lines[index]);
+      }
+      index += 1;
+    }
+    output.push(...nextManagedLines, ...preserved.filter(Boolean));
+    index -= 1;
+  }
+
+  return output.join("\n");
 }
 
 function getHubServerEntry(registry) {
   const entries = Object.entries(registry?.servers || {});
   if (entries.length === 0) {
-    return ["tfx-hub", { url: `${registry?.defaults?.hub_base || "http://127.0.0.1:27888"}${DEFAULT_HUB_PATH}` }];
+    return [
+      "tfx-hub",
+      {
+        url: `${registry?.defaults?.hub_base || "http://127.0.0.1:27888"}${DEFAULT_HUB_PATH}`,
+      },
+    ];
   }
 
-  return entries.find(([name]) => name === "tfx-hub")
-    || entries.find(([, config]) => config?.transport === "hub-url")
-    || entries[0];
+  return (
+    entries.find(([name]) => name === "tfx-hub") ||
+    entries.find(([, config]) => config?.transport === "hub-url") ||
+    entries[0]
+  );
 }
 
 function _makeHubRuntimeConfig() {
@@ -224,30 +759,157 @@ function _makeHubRuntimeConfig() {
 
 function serverTargets(serverConfig) {
   if (Array.isArray(serverConfig?.targets) && serverConfig.targets.length > 0) {
-    return [...new Set(serverConfig.targets.map((value) => String(value).trim()).filter(Boolean))];
+    return [
+      ...new Set(
+        serverConfig.targets
+          .map((value) => String(value).trim())
+          .filter(Boolean),
+      ),
+    ];
   }
-  return ["claude", "gemini", "codex"];
+  return ["claude", "gemini", "codex", "antigravity"];
 }
 
 function serverAppliesToClient(serverConfig, client) {
   return serverTargets(serverConfig).includes(client);
 }
 
-function buildDesiredServerRecord(name, serverConfig, filePath) {
-  const url = serverConfig?.transport === "hub-url"
-    ? resolveHubUrl()
-    : normalizeUrl(serverConfig?.url || "");
+function serverPolicy(serverConfig = {}, registry = {}) {
+  if (SERVER_POLICIES.has(serverConfig.policy)) return serverConfig.policy;
+  const transport = serverConfig.transport || registry?.defaults?.transport;
+  if (transport === "stdio") return "stdio";
+  return "hosted";
+}
+
+function gatewaySseUrl(name, serverConfig = {}) {
+  if (typeof serverConfig.url === "string" && serverConfig.url.trim()) {
+    return normalizeUrl(serverConfig.url);
+  }
+  const port =
+    Number(serverConfig.gateway_port || serverConfig.port || 0) ||
+    GATEWAY_PORTS[name];
+  if (!Number.isFinite(port) || port <= 0) return "";
+  return `http://127.0.0.1:${port}/sse`;
+}
+
+function syncDenylistEntries(policy = {}) {
+  if (!Array.isArray(policy?.sync_denylist)) return new Set();
+  return new Set(
+    policy.sync_denylist
+      .map((entry) =>
+        String(entry || "")
+          .trim()
+          .toLowerCase(),
+      )
+      .filter(Boolean),
+  );
+}
+
+function syncDenylistKey(client, serverName) {
+  return `${String(client || "")
+    .trim()
+    .toLowerCase()}:${String(serverName || "")
+    .trim()
+    .toLowerCase()}`;
+}
+
+export function buildDesiredServerRecord(name, serverConfig, filePath) {
+  const policy = serverPolicy(serverConfig);
+  if (policy === "stdio") {
+    const resolvedEnv = resolveEnvDescriptors(name, serverConfig);
+    const envConfig = hasOwnEntries(resolvedEnv.env)
+      ? { env: resolvedEnv.env }
+      : {};
+    return {
+      name,
+      config: {
+        command: serverConfig.command,
+        args: Array.isArray(serverConfig.args) ? [...serverConfig.args] : [],
+        ...envConfig,
+      },
+      envDescriptors: resolvedEnv.descriptors,
+      codex: {},
+      warnings: resolvedEnv.warnings,
+    };
+  }
+
+  const url =
+    policy === "gateway-sse"
+      ? gatewaySseUrl(name, serverConfig)
+      : serverConfig?.transport === "hub-url"
+        ? resolveHubUrl()
+        : normalizeUrl(serverConfig?.url || "");
   const basenameValue = pathBasename(filePath);
+  const resolvedHeaders = resolveHeaderDescriptors(
+    name,
+    serverConfig,
+    filePath,
+  );
+  const headerConfig = hasOwnEntries(resolvedHeaders.headers)
+    ? { headers: resolvedHeaders.headers }
+    : {};
+
+  if (policy === "gateway-sse") {
+    if (isCodexConfig(filePath)) {
+      return {
+        name,
+        config: { url, transport: "sse" },
+        headerDescriptors: {},
+        codex: {},
+        warnings: [],
+      };
+    }
+
+    return {
+      name,
+      config: { type: "sse", url },
+      headerDescriptors: {},
+      codex: {},
+      warnings: [],
+    };
+  }
 
-  if (basenameValue === ".mcp.json") {
-    return { name, config: { type: "url", url } };
+  if (
+    basenameValue === ".mcp.json" ||
+    isClaudeProjectMcpConfig(filePath) ||
+    isClaudeUserConfig(filePath)
+  ) {
+    return {
+      name,
+      config: { type: "http", url, ...headerConfig },
+      headerDescriptors: resolvedHeaders.descriptors,
+      codex: resolvedHeaders.codex,
+      warnings: resolvedHeaders.warnings,
+    };
+  }
+
+  if (isAntigravityConfig(filePath)) {
+    return {
+      name,
+      config: { url, type: "http", ...headerConfig },
+      headerDescriptors: resolvedHeaders.descriptors,
+      codex: resolvedHeaders.codex,
+      warnings: resolvedHeaders.warnings,
+    };
   }
 
   if (isCodexConfig(filePath)) {
-    return { name, config: { url } };
+    return {
+      name,
+      config: { url, ...headerConfig },
+      headerDescriptors: resolvedHeaders.descriptors,
+      codex: resolvedHeaders.codex,
+      warnings: resolvedHeaders.warnings,
+    };
   }
 
-  return { name, config: { url } };
+  return {
+    name,
+    config: { url, ...headerConfig },
+    headerDescriptors: resolvedHeaders.descriptors,
+    codex: resolvedHeaders.codex,
+    warnings: resolvedHeaders.warnings,
+  };
 }
 
 function scanJsonConfig(filePath) {
@@ -266,22 +928,54 @@ function scanJsonConfig(filePath) {
   try {
     const parsed = readJsonFile(filePath);
     const mcpServers = parsed?.mcpServers;
-    const servers = !mcpServers || typeof mcpServers !== "object"
-      ? []
-      : Object.entries(mcpServers)
-        .filter(([name, config]) => typeof name === "string" && config && typeof config === "object")
-        .map(([name, config]) => ({
-          name: name.trim(),
-          url: typeof config.url === "string" ? normalizeUrl(config.url) : "",
-          command: typeof config.command === "string" ? config.command : "",
-          type: typeof config.type === "string" ? config.type : "",
-          transport: typeof config.url === "string" && config.url
-            ? "url"
-            : typeof config.command === "string" && config.command
-              ? "stdio"
-              : "unknown",
-          raw: config,
-        }));
+    const servers =
+      !mcpServers || typeof mcpServers !== "object"
+        ? []
+        : Object.entries(mcpServers)
+            .filter(
+              ([name, config]) =>
+                typeof name === "string" &&
+                config &&
+                typeof config === "object",
+            )
+            .map(([name, config]) => ({
+              name: name.trim(),
+              url:
+                typeof config.url === "string" ? normalizeUrl(config.url) : "",
+              command: typeof config.command === "string" ? config.command : "",
+              args: Array.isArray(config.args)
+                ? config.args.filter((value) => typeof value === "string")
+                : [],
+              env:
+                config.env &&
+                typeof config.env === "object" &&
+                !Array.isArray(config.env)
+                  ? Object.fromEntries(
+                      Object.entries(config.env).filter(
+                        ([, value]) => typeof value === "string",
+                      ),
+                    )
+                  : {},
+              type: typeof config.type === "string" ? config.type : "",
+              headers:
+                config.headers &&
+                typeof config.headers === "object" &&
+                !Array.isArray(config.headers)
+                  ? Object.fromEntries(
+                      Object.entries(config.headers).filter(
+                        ([, value]) => typeof value === "string",
+                      ),
+                    )
+                  : {},
+              headerDescriptors: descriptorsFromJsonConfig(config),
+              transport:
+                typeof config.url === "string" && config.url
+                  ? "url"
+                  : typeof config.command === "string" && config.command
+                    ? "stdio"
+                    : "unknown",
+              raw: config,
+            }));
 
     return {
       filePath,
@@ -325,11 +1019,30 @@ function scanCodexConfig(filePath) {
       name,
       url: typeof config.url === "string" ? normalizeUrl(config.url) : "",
       command: typeof config.command === "string" ? config.command : "",
-      transport: typeof config.url === "string" && config.url
-        ? "url"
-        : typeof config.command === "string" && config.command
-          ? "stdio"
-          : "unknown",
+      args: Array.isArray(config.args)
+        ? config.args.filter((value) => typeof value === "string")
+        : [],
+      env:
+        config.env &&
+        typeof config.env === "object" &&
+        !Array.isArray(config.env)
+          ? Object.fromEntries(
+              Object.entries(config.env).filter(
+                ([, value]) => typeof value === "string",
+              ),
+            )
+          : {},
+      headers:
+        config.http_headers && typeof config.http_headers === "object"
+          ? config.http_headers
+          : {},
+      headerDescriptors: descriptorsFromCodexConfig(config),
+      transport:
+        typeof config.url === "string" && config.url
+          ? "url"
+          : typeof config.command === "string" && config.command
+            ? "stdio"
+            : "unknown",
       raw: config,
     }));
 
@@ -368,7 +1081,11 @@ function updateJsonConfig(filePath, updates = [], removals = []) {
     parsed = {};
   }
 
-  if (!parsed.mcpServers || typeof parsed.mcpServers !== "object" || Array.isArray(parsed.mcpServers)) {
+  if (
+    !parsed.mcpServers ||
+    typeof parsed.mcpServers !== "object" ||
+    Array.isArray(parsed.mcpServers)
+  ) {
     parsed.mcpServers = {};
   }
 
@@ -383,8 +1100,34 @@ function updateJsonConfig(filePath, updates = [], removals = []) {
 
   for (const update of updates) {
     const current = parsed.mcpServers[update.name];
-    const nextConfig = { ...(current && typeof current === "object" ? current : {}), ...update.config };
-    const changed = JSON.stringify(current || null) !== JSON.stringify(nextConfig);
+    const nextConfig = {
+      ...(current && typeof current === "object" ? current : {}),
+      ...update.config,
+    };
+    if (Object.hasOwn(update.config, "command")) {
+      delete nextConfig.url;
+      delete nextConfig.type;
+      delete nextConfig.headers;
+    }
+    if (Object.hasOwn(update.config, "url")) {
+      delete nextConfig.command;
+      delete nextConfig.args;
+      delete nextConfig.env;
+    }
+    if (!Object.hasOwn(update.config, "type")) {
+      delete nextConfig.type;
+    }
+    if (!Object.hasOwn(update.config, "transport")) {
+      delete nextConfig.transport;
+    }
+    if (!Object.hasOwn(update.config, "headers")) {
+      delete nextConfig.headers;
+    }
+    if (!Object.hasOwn(update.config, "env")) {
+      delete nextConfig.env;
+    }
+    const changed =
+      JSON.stringify(current || null) !== JSON.stringify(nextConfig);
     if (changed) {
       parsed.mcpServers[update.name] = nextConfig;
       modified = true;
@@ -396,11 +1139,21 @@ function updateJsonConfig(filePath, updates = [], removals = []) {
   }
 
   writeJsonFile(resolvedPath, parsed);
+  lockJsonConfigPermissions(resolvedPath);
   return { modified: true, filePath: resolvedPath };
 }
 
 function updateCodexConfig(filePath, updates = [], removals = []) {
   const resolvedPath = resolveFilePath(filePath);
+  if (shouldSkipCodexConfigMutation()) {
+    return {
+      modified: false,
+      filePath: resolvedPath,
+      skipped: true,
+      reason: "protected-env",
+    };
+  }
+
   let raw = existsSync(resolvedPath) ? readFileSync(resolvedPath, "utf8") : "";
 
   for (const name of removals) {
@@ -408,11 +1161,13 @@ function updateCodexConfig(filePath, updates = [], removals = []) {
   }
 
   for (const update of updates) {
-    raw = upsertTomlUrlServer(raw, update.name, update.config.url);
+    raw = upsertTomlServer(raw, update.name, update.config, update.codex || {});
   }
 
   const finalRaw = raw.trim().length > 0 ? `${raw.trimEnd()}\n` : "";
-  const previousRaw = existsSync(resolvedPath) ? readFileSync(resolvedPath, "utf8") : "";
+  const previousRaw = existsSync(resolvedPath)
+    ? readFileSync(resolvedPath, "utf8")
+    : "";
   if (finalRaw === previousRaw) {
     return { modified: false, filePath: resolvedPath };
   }
@@ -439,7 +1194,7 @@ function scanConfig(filePath) {
 }
 
 export function getRegistryPath() {
-  return REGISTRY_PATH;
+  return registryPath();
 }
 
 export function createDefaultRegistry() {
@@ -460,7 +1215,11 @@ export function validateRegistry(registry) {
     errors.push("registry.defaults must be an object");
   }
 
-  if (!registry.servers || typeof registry.servers !== "object" || Array.isArray(registry.servers)) {
+  if (
+    !registry.servers ||
+    typeof registry.servers !== "object" ||
+    Array.isArray(registry.servers)
+  ) {
     errors.push("registry.servers must be an object");
   } else {
     for (const [name, server] of Object.entries(registry.servers)) {
@@ -472,23 +1231,233 @@ export function validateRegistry(registry) {
         errors.push(`registry.servers.${name} must be an object`);
         continue;
       }
-      if (typeof server.url !== "string" || !server.url.trim()) {
+      const policy = serverPolicy(server, registry);
+      if (
+        typeof server.policy !== "string" ||
+        !SERVER_POLICIES.has(server.policy)
+      ) {
+        errors.push(
+          `registry.servers.${name}.policy must be hosted, gateway-sse, or stdio`,
+        );
+      }
+      const transport = server.transport || registry.defaults?.transport;
+      if (!["hub-url", "http", "stdio"].includes(transport)) {
+        errors.push(
+          `registry.servers.${name}.transport must be hub-url, http, or stdio`,
+        );
+      }
+      if (
+        policy === "hosted" &&
+        (typeof server.url !== "string" || !server.url.trim())
+      ) {
         errors.push(`registry.servers.${name}.url must be a non-empty string`);
       }
+      if (policy === "gateway-sse") {
+        const port = Number(server.gateway_port || server.port || 0);
+        const hasGatewayUrl =
+          typeof server.url === "string" && server.url.trim().length > 0;
+        if (
+          !hasGatewayUrl &&
+          (!Number.isInteger(port) || port <= 0 || port > 65535)
+        ) {
+          errors.push(
+            `registry.servers.${name}.gateway_port must be a valid TCP port for gateway-sse`,
+          );
+        }
+      }
+      if (policy === "stdio" && server.url !== undefined) {
+        errors.push(`registry.servers.${name}.url is not used for stdio`);
+      }
+      if (policy === "stdio") {
+        if (typeof server.command !== "string" || !server.command.trim()) {
+          errors.push(
+            `registry.servers.${name}.command must be a non-empty string for stdio`,
+          );
+        }
+        if (
+          !Array.isArray(server.args) ||
+          server.args.some((arg) => typeof arg !== "string")
+        ) {
+          errors.push(
+            `registry.servers.${name}.args must be an array of strings for stdio`,
+          );
+        }
+      }
+      if (policy !== "stdio" && server.command !== undefined) {
+        errors.push(
+          `registry.servers.${name}.command is allowed only for stdio transport`,
+        );
+      }
+      if (policy !== "stdio" && server.args !== undefined) {
+        errors.push(
+          `registry.servers.${name}.args is allowed only for stdio transport`,
+        );
+      }
+      if (server.env !== undefined) {
+        if (policy !== "stdio") {
+          errors.push(
+            `registry.servers.${name}.env is allowed only for stdio transport`,
+          );
+        }
+        if (
+          !server.env ||
+          typeof server.env !== "object" ||
+          Array.isArray(server.env)
+        ) {
+          errors.push(`registry.servers.${name}.env must be an object`);
+        } else {
+          for (const [envKey, descriptor] of Object.entries(server.env)) {
+            if (!isValidEnvName(envKey)) {
+              errors.push(
+                `registry.servers.${name}.env contains invalid env name ${envKey}`,
+              );
+              continue;
+            }
+            if (
+              !descriptor ||
+              typeof descriptor !== "object" ||
+              Array.isArray(descriptor)
+            ) {
+              errors.push(
+                `registry.servers.${name}.env.${envKey} must be a descriptor object`,
+              );
+              continue;
+            }
+            const keys = Object.keys(descriptor);
+            if (
+              keys.length !== 1 ||
+              !Object.hasOwn(descriptor, "env") ||
+              typeof descriptor.env !== "string" ||
+              !descriptor.env.trim()
+            ) {
+              errors.push(
+                `registry.servers.${name}.env.${envKey}.env must be a non-empty string`,
+              );
+            }
+          }
+        }
+      }
+      if (server.headers !== undefined) {
+        if (policy !== "hosted") {
+          errors.push(
+            `registry.servers.${name}.headers is allowed only for hosted policy`,
+          );
+        }
+        if (
+          !server.headers ||
+          typeof server.headers !== "object" ||
+          Array.isArray(server.headers)
+        ) {
+          errors.push(`registry.servers.${name}.headers must be an object`);
+        } else {
+          for (const [headerName, descriptor] of Object.entries(
+            server.headers,
+          )) {
+            if (!isValidHeaderName(headerName)) {
+              errors.push(
+                `registry.servers.${name}.headers contains invalid header name ${headerName}`,
+              );
+              continue;
+            }
+            if (
+              !descriptor ||
+              typeof descriptor !== "object" ||
+              Array.isArray(descriptor)
+            ) {
+              errors.push(
+                `registry.servers.${name}.headers.${headerName} must be a descriptor object`,
+              );
+              continue;
+            }
+            const keys = Object.keys(descriptor);
+            const hasValue = Object.hasOwn(descriptor, "value");
+            const hasEnv = Object.hasOwn(descriptor, "env");
+            if (hasValue && hasEnv) {
+              errors.push(
+                `registry.servers.${name}.headers.${headerName} must use either value or env`,
+              );
+            } else if (hasValue) {
+              if (
+                keys.length !== 1 ||
+                typeof descriptor.value !== "string" ||
+                descriptor.value.length === 0
+              ) {
+                errors.push(
+                  `registry.servers.${name}.headers.${headerName}.value must be a non-empty string`,
+                );
+              }
+            } else if (hasEnv) {
+              if (
+                !["env", "prefix"].every((key) => keys.includes(key)) &&
+                keys.some((key) => !["env", "prefix"].includes(key))
+              ) {
+                errors.push(
+                  `registry.servers.${name}.headers.${headerName} supports only env and optional prefix`,
+                );
+              }
+              if (
+                typeof descriptor.env !== "string" ||
+                !descriptor.env.trim()
+              ) {
+                errors.push(
+                  `registry.servers.${name}.headers.${headerName}.env must be a non-empty string`,
+                );
+              }
+              if (
+                descriptor.prefix !== undefined &&
+                typeof descriptor.prefix !== "string"
+              ) {
+                errors.push(
+                  `registry.servers.${name}.headers.${headerName}.prefix must be a string`,
+                );
+              }
+            } else {
+              errors.push(
+                `registry.servers.${name}.headers.${headerName} must use value or env`,
+              );
+            }
+          }
+        }
+      }
       if (server.targets !== undefined && !Array.isArray(server.targets)) {
         errors.push(`registry.servers.${name}.targets must be an array`);
       }
     }
   }
 
-  if (!registry.policies || typeof registry.policies !== "object" || Array.isArray(registry.policies)) {
+  if (
+    !registry.policies ||
+    typeof registry.policies !== "object" ||
+    Array.isArray(registry.policies)
+  ) {
     errors.push("registry.policies must be an object");
   } else {
     if (!Array.isArray(registry.policies.watched_paths)) {
       errors.push("registry.policies.watched_paths must be an array");
     }
-    if (registry.policies.stdio_action && !["replace-with-hub", "warn"].includes(registry.policies.stdio_action)) {
-      errors.push("registry.policies.stdio_action must be replace-with-hub or warn");
+    if (
+      registry.policies.sync_denylist !== undefined &&
+      !Array.isArray(registry.policies.sync_denylist)
+    ) {
+      errors.push("registry.policies.sync_denylist must be an array");
+    }
+    if (Array.isArray(registry.policies.sync_denylist)) {
+      for (const entry of registry.policies.sync_denylist) {
+        if (typeof entry !== "string" || !entry.includes(":")) {
+          errors.push(
+            "registry.policies.sync_denylist entries must use client:server format",
+          );
+          break;
+        }
+      }
+    }
+    if (
+      registry.policies.stdio_action &&
+      !["replace-with-hub", "warn"].includes(registry.policies.stdio_action)
+    ) {
+      errors.push(
+        "registry.policies.stdio_action must be replace-with-hub or warn",
+      );
     }
   }
 
@@ -496,9 +1465,9 @@ export function validateRegistry(registry) {
 }
 
 export function inspectRegistry() {
-  if (!existsSync(REGISTRY_PATH)) {
+  if (!existsSync(registryPath())) {
     return {
-      path: REGISTRY_PATH,
+      path: registryPath(),
       exists: false,
       valid: false,
       errors: ["registry file missing"],
@@ -507,10 +1476,10 @@ export function inspectRegistry() {
   }
 
   try {
-    const registry = readJsonFile(REGISTRY_PATH);
+    const registry = readJsonFile(registryPath());
     const errors = validateRegistry(registry);
     return {
-      path: REGISTRY_PATH,
+      path: registryPath(),
       exists: true,
       valid: errors.length === 0,
       errors,
@@ -518,7 +1487,7 @@ export function inspectRegistry() {
     };
   } catch (error) {
     return {
-      path: REGISTRY_PATH,
+      path: registryPath(),
       exists: true,
       valid: false,
       errors: [error.message],
@@ -560,7 +1529,7 @@ export function saveRegistry(registry) {
   if (errors.length > 0) {
     throw new Error(`MCP registry invalid: ${errors.join("; ")}`);
   }
-  writeJsonFile(REGISTRY_PATH, registry);
+  writeJsonFile(registryPath(), registry);
   return registry;
 }
 
@@ -577,8 +1546,75 @@ export function listManagedConfigTargets(registry = loadRegistryOrDefault()) {
   });
 }
 
+export function discoverProjectMcpTargets(options = {}) {
+  const root = resolve(expandHome(options.root || defaultProjectsRoot()));
+  const maxDepth = Number.isFinite(Number(options.maxDepth))
+    ? Number(options.maxDepth)
+    : 4;
+  const excludePatterns = Array.isArray(options.exclude)
+    ? options.exclude.filter(Boolean).map(String)
+    : [];
+  const targets = [];
+  const seen = new Set();
+
+  function addTarget(filePath) {
+    const normalized = normalizeForMatch(filePath);
+    if (seen.has(normalized)) return;
+    seen.add(normalized);
+    targets.push({
+      watchedPath: filePath,
+      filePath,
+      client: detectClient(filePath),
+      label: detectLabel(filePath),
+      exists: existsSync(filePath),
+    });
+  }
+
+  function walk(dirPath, depth) {
+    if (depth > maxDepth) return;
+    let entries;
+    try {
+      entries = readdirSync(dirPath, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const entryPath = join(dirPath, entry.name);
+      const relativePath = relative(root, entryPath).replace(/\\/g, "/");
+      if (isExcludedProjectPath(relativePath, excludePatterns)) continue;
+
+      if (entry.isDirectory()) {
+        if (depth < maxDepth) walk(entryPath, depth + 1);
+        continue;
+      }
+
+      if (!entry.isFile() || depth + 1 > maxDepth) continue;
+      const normalized = entryPath.replace(/\\/g, "/");
+      if (
+        entry.name === ".mcp.json" ||
+        normalized.endsWith("/.claude/mcp.json")
+      ) {
+        addTarget(resolve(entryPath));
+      }
+    }
+  }
+
+  walk(root, 0);
+  return {
+    root,
+    maxDepth,
+    exclude: excludePatterns,
+    targets: targets.sort((left, right) =>
+      left.filePath.localeCompare(right.filePath),
+    ),
+  };
+}
+
 export function listPrimaryConfigTargets(registry = loadRegistryOrDefault()) {
-  return listManagedConfigTargets(registry).filter((target) => isPrimaryConfigTarget(target.filePath));
+  return listManagedConfigTargets(registry).filter((target) =>
+    isPrimaryConfigTarget(target.filePath),
+  );
 }
 
 export function scanManagedConfigs(registry = loadRegistryOrDefault()) {
@@ -590,17 +1626,35 @@ export function scanManagedConfigs(registry = loadRegistryOrDefault()) {
 
 export function inspectRegistryStatus(registry = loadRegistryOrDefault()) {
   const configs = scanManagedConfigs(registry);
-  const primaryTargets = new Set(listPrimaryConfigTargets(registry).map((target) => normalizeForMatch(target.filePath)));
+  const primaryTargets = new Set(
+    listPrimaryConfigTargets(registry).map((target) =>
+      normalizeForMatch(target.filePath),
+    ),
+  );
   const rows = [];
 
   for (const config of configs) {
     const isPrimary = primaryTargets.has(normalizeForMatch(config.filePath));
-    const managedServers = Object.entries(registry.servers || {})
-      .filter(([, serverConfig]) => isPrimary && serverAppliesToClient(serverConfig, config.client));
+    const managedServers = Object.entries(registry.servers || {}).filter(
+      ([, serverConfig]) =>
+        isPrimary && serverAppliesToClient(serverConfig, config.client),
+    );
 
     for (const [name, serverConfig] of managedServers) {
-      const expectedUrl = buildDesiredServerRecord(name, serverConfig, config.filePath).config.url;
-      const actual = config.servers.find((server) => server.name === name) || null;
+      const desired = buildDesiredServerRecord(
+        name,
+        serverConfig,
+        config.filePath,
+      );
+      const expectedUrl = desired.config.url || "";
+      const expectedCommand = desired.config.command || "";
+      const expectedHeaders = isCodexConfig(config.filePath)
+        ? desired.headerDescriptors || {}
+        : descriptorsFromJsonConfig(desired.config);
+      const actual =
+        config.servers.find((server) => server.name === name) || null;
+      const actualHeaders = actual?.headerDescriptors || {};
+      const currentHeaderStatus = headerStatus(expectedHeaders, actualHeaders);
       let status = "missing";
 
       if (!config.exists) {
@@ -609,10 +1663,17 @@ export function inspectRegistryStatus(registry = loadRegistryOrDefault()) {
         status = "invalid-config";
       } else if (!actual) {
         status = "missing";
+      } else if (expectedCommand) {
+        status =
+          actual.command === expectedCommand &&
+          JSON.stringify(actual.args || []) ===
+            JSON.stringify(desired.config.args || [])
+            ? "present"
+            : "mismatch";
       } else if (!actual.url) {
         status = actual.transport === "stdio" ? "stdio" : "invalid";
       } else if (normalizeUrl(actual.url) === normalizeUrl(expectedUrl)) {
-        status = "present";
+        status = currentHeaderStatus === "ok" ? "present" : "mismatch";
       } else {
         status = "mismatch";
       }
@@ -624,8 +1685,13 @@ export function inspectRegistryStatus(registry = loadRegistryOrDefault()) {
         label: config.label,
         filePath: config.filePath,
         expectedUrl,
+        expectedCommand,
         actualUrl: actual?.url || "",
+        actualCommand: actual?.command || "",
         status,
+        headerStatus: currentHeaderStatus,
+        expectedHeaderNames: headerNames(expectedHeaders),
+        actualHeaderNames: headerNames(actualHeaders),
       });
     }
 
@@ -658,7 +1724,9 @@ export function scanForStdioServers(filePath) {
 
 export function remediate(filePath, stdioServers, policy = {}) {
   const resolvedPath = resolveFilePath(filePath);
-  const offenders = Array.isArray(stdioServers) ? stdioServers.filter((server) => server?.name) : [];
+  const offenders = Array.isArray(stdioServers)
+    ? stdioServers.filter((server) => server?.name)
+    : [];
   const action = policy?.stdio_action || "warn";
 
   if (offenders.length === 0) {
@@ -722,10 +1790,19 @@ export function remediate(filePath, stdioServers, policy = {}) {
   let replacement = null;
 
   if (action === "replace-with-hub") {
-    const registry = loadRegistryOrDefault();
-    const [hubServerName, hubServerConfig] = getHubServerEntry(registry);
-    const desired = buildDesiredServerRecord(hubServerName, hubServerConfig, resolvedPath);
-    replacement = { name: desired.name, ...desired.config };
+    const registry = policy.registry || loadRegistryOrDefault();
+    const matchingOffender = offenders.find((server) =>
+      Object.hasOwn(registry.servers || {}, server.name),
+    );
+    const [hubServerName, hubServerConfig] = matchingOffender
+      ? [matchingOffender.name, registry.servers[matchingOffender.name]]
+      : getHubServerEntry(registry);
+    const desired = buildDesiredServerRecord(
+      hubServerName,
+      hubServerConfig,
+      resolvedPath,
+    );
+    replacement = { name: desired.name, ...redactServerConfig(desired.config) };
     updates.push(desired);
   }
 
@@ -736,15 +1813,19 @@ export function remediate(filePath, stdioServers, policy = {}) {
     backupPath,
     removedServers: removals,
     replacement,
-    warnings: [],
+    warnings: updates.flatMap((update) => update.warnings || []),
   };
 }
 
 export function resolveHubUrl() {
   const registryState = inspectRegistry();
-  const registry = registryState.valid ? registryState.registry : cloneDefaultRegistry();
+  const registry = registryState.valid
+    ? registryState.registry
+    : cloneDefaultRegistry();
   const [, hubServer] = getHubServerEntry(registry);
-  const fallbackRaw = hubServer?.url || `${registry?.defaults?.hub_base || "http://127.0.0.1:27888"}${DEFAULT_HUB_PATH}`;
+  const fallbackRaw =
+    hubServer?.url ||
+    `${registry?.defaults?.hub_base || "http://127.0.0.1:27888"}${DEFAULT_HUB_PATH}`;
 
   let fallback;
   try {
@@ -754,22 +1835,25 @@ export function resolveHubUrl() {
   }
 
   const envPortRaw = Number(process.env.TFX_HUB_PORT || "");
-  const envPort = Number.isFinite(envPortRaw) && envPortRaw > 0 ? envPortRaw : null;
+  const envPort =
+    Number.isFinite(envPortRaw) && envPortRaw > 0 ? envPortRaw : null;
   const target = {
     protocol: fallback.protocol || "http:",
     host: fallback.hostname || "127.0.0.1",
     port: envPort || Number(fallback.port || 27888),
-    pathname: fallback.pathname && fallback.pathname !== "/" ? fallback.pathname : DEFAULT_HUB_PATH,
+    pathname:
+      fallback.pathname && fallback.pathname !== "/"
+        ? fallback.pathname
+        : DEFAULT_HUB_PATH,
   };
 
+  // PR #158 정책: port = TFX_HUB_PORT env (없으면 registry/default 27888) single source.
+  // hub.pid 는 loopback host 힌트 전용. 과거 pid port cascade 는 오염된 port 영속화의
+  // 원인이었고 hub-ensure.resolveHubTarget 에서 이미 제거됨. 여기도 일관 적용.
   const hubPidPath = join(homedir(), ".claude", "cache", "tfx-hub", "hub.pid");
   if (existsSync(hubPidPath)) {
     try {
       const info = readJsonFile(hubPidPath);
-      if (!envPort) {
-        const pidPort = Number(info?.port);
-        if (Number.isFinite(pidPort) && pidPort > 0) target.port = pidPort;
-      }
       if (typeof info?.host === "string") {
         const host = info.host.trim();
         if (LOOPBACK_HOSTS.has(host)) target.host = host;
@@ -785,7 +1869,9 @@ export function resolveHubUrl() {
 
 export function isWatchedPath(filePath) {
   const registryState = inspectRegistry();
-  const registry = registryState.valid ? registryState.registry : cloneDefaultRegistry();
+  const registry = registryState.valid
+    ? registryState.registry
+    : cloneDefaultRegistry();
   const candidate = normalizeForMatch(filePath);
 
   return (registry?.policies?.watched_paths || []).some((watchedPath) => {
@@ -802,7 +1888,10 @@ export function isWatchedPath(filePath) {
       return pathBasename(candidate) === trimmed.toLowerCase();
     }
 
-    const suffix = trimmed.replace(/^[.][\\/]/, "").replace(/\\/g, "/").toLowerCase();
+    const suffix = trimmed
+      .replace(/^[.][\\/]/, "")
+      .replace(/\\/g, "/")
+      .toLowerCase();
     return candidate.endsWith(`/${suffix}`);
   });
 }
@@ -814,16 +1903,34 @@ export function addRegistryServer(name, url, options = {}) {
   if (!normalizedUrl) throw new Error("server url is required");
 
   const registryState = inspectRegistry();
-  const registry = registryState.valid ? loadRegistry() : cloneDefaultRegistry();
-  const transport = options.transport || (trimmedName === "tfx-hub" ? "hub-url" : "url");
+  const registry = registryState.valid
+    ? loadRegistry()
+    : cloneDefaultRegistry();
+  const transport =
+    options.transport || (trimmedName === "tfx-hub" ? "hub-url" : "http");
+  const policy =
+    options.policy ||
+    (transport === "stdio"
+      ? "stdio"
+      : options.gateway_port || options.port
+        ? "gateway-sse"
+        : "hosted");
 
   registry.servers[trimmedName] = {
+    policy,
     transport,
     url: normalizedUrl,
     safe: options.safe ?? true,
-    targets: Array.isArray(options.targets) && options.targets.length > 0
-      ? [...new Set(options.targets.map((value) => String(value).trim()).filter(Boolean))]
-      : ["claude", "gemini", "codex"],
+    targets:
+      Array.isArray(options.targets) && options.targets.length > 0
+        ? [
+            ...new Set(
+              options.targets
+                .map((value) => String(value).trim())
+                .filter(Boolean),
+            ),
+          ]
+        : ["claude", "gemini", "codex", "antigravity"],
     description: options.description || `${trimmedName} MCP 서버`,
   };
 
@@ -851,10 +1958,13 @@ export function removeServerFromTargets(name, options = {}) {
   const trimmedName = String(name || "").trim();
   if (!trimmedName) throw new Error("server name is required");
 
-  const registry = options.registry || (inspectRegistry().valid ? loadRegistry() : cloneDefaultRegistry());
-  const targetsFilter = Array.isArray(options.targets) && options.targets.length > 0
-    ? new Set(options.targets)
-    : null;
+  const registry =
+    options.registry ||
+    (inspectRegistry().valid ? loadRegistry() : cloneDefaultRegistry());
+  const targetsFilter =
+    Array.isArray(options.targets) && options.targets.length > 0
+      ? new Set(options.targets)
+      : null;
   const actions = [];
 
   for (const target of listManagedConfigTargets(registry)) {
@@ -896,11 +2006,20 @@ export function removeServerFromTargets(name, options = {}) {
 
 export function syncRegistryTargets(options = {}) {
   const registry = options.registry || loadRegistryOrDefault();
+  const syncTargets = Array.isArray(options.targets)
+    ? options.targets
+    : listManagedConfigTargets(registry);
+  const primaryTargets = syncTargets.filter((target) =>
+    isPrimaryConfigTarget(target.filePath),
+  );
   const actions = [];
+  const invalidConfigs = new Set();
+  const denylist = syncDenylistEntries(registry.policies);
 
-  for (const target of listManagedConfigTargets(registry)) {
+  for (const target of syncTargets) {
     const snapshot = scanConfig(target.filePath);
     if (snapshot.parseError) {
+      invalidConfigs.add(normalizeForMatch(target.filePath));
       actions.push({
         type: "sync",
         filePath: target.filePath,
@@ -911,8 +2030,14 @@ export function syncRegistryTargets(options = {}) {
       continue;
     }
 
-    if (snapshot.stdioServers.length > 0) {
-      const remediation = remediate(target.filePath, snapshot.stdioServers, registry.policies);
+    if (
+      snapshot.stdioServers.length > 0 &&
+      !isClaudeUserConfig(target.filePath)
+    ) {
+      const remediation = remediate(target.filePath, snapshot.stdioServers, {
+        ...registry.policies,
+        registry,
+      });
       actions.push({
         type: "remediate",
         filePath: target.filePath,
@@ -925,10 +2050,50 @@ export function syncRegistryTargets(options = {}) {
     }
   }
 
-  for (const target of listPrimaryConfigTargets(registry)) {
-    const updates = Object.entries(registry.servers || {})
-      .filter(([, serverConfig]) => serverAppliesToClient(serverConfig, target.client))
-      .map(([name, serverConfig]) => buildDesiredServerRecord(name, serverConfig, target.filePath));
+  for (const target of primaryTargets) {
+    const snapshot = scanConfig(target.filePath);
+    const targetKey = normalizeForMatch(target.filePath);
+    if (snapshot.parseError) {
+      if (!invalidConfigs.has(targetKey)) {
+        actions.push({
+          type: "sync",
+          filePath: target.filePath,
+          label: target.label,
+          status: "invalid-config",
+          message: snapshot.parseError.message,
+        });
+      }
+      continue;
+    }
+
+    const updates = [];
+    for (const [name, serverConfig] of Object.entries(registry.servers || {})) {
+      if (serverConfig?.safe !== true) continue;
+      if (!serverAppliesToClient(serverConfig, target.client)) continue;
+
+      const denyKey = syncDenylistKey(target.client, name);
+      if (denylist.has(denyKey)) {
+        const existing = snapshot.servers.find(
+          (server) => server.name === name,
+        );
+        if (!existing) {
+          actions.push({
+            type: "sync",
+            filePath: target.filePath,
+            label: target.label,
+            status: "policy-skip",
+            server: name,
+            client: target.client,
+            message: `[mcp-guard] policy skip: ${denyKey}`,
+          });
+        }
+        continue;
+      }
+
+      updates.push(
+        buildDesiredServerRecord(name, serverConfig, target.filePath),
+      );
+    }
 
     if (updates.length === 0) continue;
 
@@ -947,6 +2112,7 @@ export function syncRegistryTargets(options = {}) {
       label: target.label,
       status: result.modified ? "updated" : "ok",
       serverCount: updates.length,
+      warnings: updates.flatMap((update) => update.warnings || []),
     });
   }