Standardizing Cross-Client MCP Configurations

graph TD
    SSOT[Unified SSOT: .mcp-registry.yaml] --> CLI[mcp-sync Transpiler CLI]
    
    CLI -->|Generate JSON| Cursor[.cursor/mcp.json]
    CLI -->|Generate JSON| Claude[claude_desktop_config.json]
    CLI -->|Generate JSON| Windsurf[~/.codeium/windsurf/mcp_config.json]
    CLI -->|Generate TOML| Codex[~/.codex/config.toml]
    CLI -->|Generate JSON| VSCode[.vscode/mcp.json]

version: "1.0"
registry_name: "enterprise-engineering-mcp"

defaults:
  env:
    NODE_ENV: "production"
    LOG_LEVEL: "info"

servers:
  filesystem:
    description: "Sandboxed workspace filesystem reader"
    transport: "stdio"
    command: "npx"
    args:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "${WORKSPACE_ROOT}"
    env:
      FILE_ACCESS_TIER: "restricted"
    clients: ["cursor", "windsurf", "claude_desktop", "vscode"]

  enterprise-db:
    description: "Read-only production PostgreSQL analytics pool"
    transport: "sse"
    url: "https://mcp-gateway.internal.enterprise.com/sse"
    headers:
      Authorization: "Bearer ${ENTERPRISE_MCP_TOKEN}"
      X-Developer-Email: "${USER_EMAIL}"
    clients: ["cursor", "windsurf", "codex", "claude_desktop"]

  github-actions:
    description: "CI/CD pipeline workflow auditor"
    transport: "stdio"
    command: "docker"
    args:
      - "run"
      - "-i"
      - "--rm"
      - "-e"
      - "GITHUB_TOKEN"
      - "registry.enterprise.internal/ai/mcp-github:v1.2"
    env:
      GITHUB_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}"
    clients: ["codex", "cursor"]

import fs from 'fs';
import path from 'path';
import os from 'os';
import yaml from 'js-yaml';

const WORKSPACE_DIR = process.cwd();
const REGISTRY_PATH = path.join(WORKSPACE_DIR, '.mcp-registry.yaml');

if (!fs.existsSync(REGISTRY_PATH)) {
  console.error(`Error: Missing ${REGISTRY_PATH}`);
  process.exit(1);
}

const rawConfig = fs.readFileSync(REGISTRY_PATH, 'utf8');
const parsed = yaml.load(rawConfig);

// Helper: Safely substitute environment variables
function interpolateEnv(str) {
  if (typeof str !== 'string') return str;
  return str.replace(/\$\{([^}]+)\}/g, (_, key) => {
    if (key === 'WORKSPACE_ROOT') return WORKSPACE_DIR;
    return process.env[key] || `\${${key}}`;
  });
}

function processObjectEnv(obj) {
  const result = {};
  for (const [k, v] of Object.entries(obj || {})) {
    result[k] = interpolateEnv(v);
  }
  return result;
}

// 1. Generate Standard JSON Client Format (Cursor / Claude / Windsurf)
function generateJsonConfig(targetClient) {
  const mcpServers = {};

  for (const [id, srv] of Object.entries(parsed.servers)) {
    if (!srv.clients.includes(targetClient)) continue;

    if (srv.transport === 'stdio') {
      mcpServers[id] = {
        command: srv.command,
        args: srv.args.map(interpolateEnv),
        env: processObjectEnv({ ...parsed.defaults.env, ...srv.env })
      };
    } else if (srv.transport === 'sse') {
      mcpServers[id] = {
        url: interpolateEnv(srv.url),
        headers: processObjectEnv(srv.headers)
      };
    }
  }

  return JSON.stringify({ mcpServers }, null, 2);
}

// 2. Generate TOML Format (OpenAI Codex CLI)
function generateCodexToml() {
  const lines = ['# Auto-generated by mcp-sync. DO NOT EDIT DIRECTLY.\n'];

  for (const [id, srv] of Object.entries(parsed.servers)) {
    if (!srv.clients.includes('codex')) continue;

    const tomlId = id.replace(/-/g, '_');
    lines.push(`[mcp_servers.${tomlId}]`);

    if (srv.transport === 'stdio') {
      lines.push(`command = "${srv.command}"`);
      const argsStr = srv.args.map(a => `"${interpolateEnv(a)}"`).join(', ');
      lines.push(`args = [${argsStr}]`);

      const mergedEnv = { ...parsed.defaults.env, ...srv.env };
      if (Object.keys(mergedEnv).length > 0) {
        lines.push(`\n[mcp_servers.${tomlId}.env]`);
        for (const [k, v] of Object.entries(mergedEnv)) {
          lines.push(`${k} = "${interpolateEnv(v)}"`);
        }
      }
    } else if (srv.transport === 'sse') {
      lines.push(`url = "${interpolateEnv(srv.url)}"`);
      if (srv.headers?.Authorization) {
        lines.push(`bearer_token = "${interpolateEnv(srv.headers.Authorization).replace('Bearer ', '')}"`);
      }
    }
    lines.push('');
  }

  return lines.join('\n');
}

// 3. Write Targets
const targets = [
  { client: 'cursor', path: path.join(WORKSPACE_DIR, '.cursor', 'mcp.json'), content: generateJsonConfig('cursor') },
  { client: 'windsurf', path: path.join(os.homedir(), '.codeium', 'windsurf', 'mcp_config.json'), content: generateJsonConfig('windsurf') },
  { client: 'codex', path: path.join(WORKSPACE_DIR, 'config.toml'), content: generateCodexToml() }
];

// OS-Specific Claude Desktop Path
const claudePath = process.platform === 'darwin'
  ? path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json')
  : path.join(process.env.APPDATA || '', 'Claude', 'claude_desktop_config.json');

targets.push({ client: 'claude_desktop', path: claudePath, content: generateJsonConfig('claude_desktop') });

for (const target of targets) {
  try {
    const dir = path.dirname(target.path);
    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
    fs.writeFileSync(target.path, target.content, 'utf8');
    console.log(`✓ Synchronized [${target.client}] config -> ${target.path}`);
  } catch (err) {
    console.warn(`! Skipped [${target.client}]: ${err.message}`);
  }
}

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/workspace/repo"
      ],
      "env": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "info",
        "FILE_ACCESS_TIER": "restricted"
      }
    },
    "enterprise-db": {
      "url": "https://mcp-gateway.internal.enterprise.com/sse",
      "headers": {
        "Authorization": "Bearer eyJhbGci...",
        "X-Developer-Email": "jane@enterprise.com"
      }
    }
  }
}

# Auto-generated by mcp-sync. DO NOT EDIT DIRECTLY.

[mcp_servers.enterprise_db]
url = "https://mcp-gateway.internal.enterprise.com/sse"
bearer_token = "eyJhbGci..."

[mcp_servers.github_actions]
command = "docker"
args = ["run", "-i", "--rm", "-e", "GITHUB_TOKEN", "registry.enterprise.internal/ai/mcp-github:v1.2"]

[mcp_servers.github_actions.env]
NODE_ENV = "production"
LOG_LEVEL = "info"
GITHUB_TOKEN = "ghp_secure_token_991"

name: Verify MCP Configuration Sync

on: [push, pull_request]

jobs:
  verify-sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install js-yaml
      - name: Run MCP Transpiler
        run: node scripts/mcp-sync.mjs
      - name: Assert No Git Drift
        run: |
          git diff --exit-code .cursor/mcp.json config.toml || (echo "Error: MCP configuration drift detected. Run 'node scripts/mcp-sync.mjs' and commit changes." && exit 1)