PRD: Codex CLI TOML Configuration Support

Problem Statement

The Sync-McpConfig.ps1 script currently supports synchronizing MCP server configurations from Claude Code's .mcp.json to VS Code (.vscode/mcp.json) and Factory (.factory/mcp.json) formats. Both targets use JSON format.

Critical Blocker: Codex CLI requires TOML format configuration (.codex/config.toml) to function. Without TOML support in Sync-McpConfig.ps1, Codex CLI cannot be used in this project, which blocks users who want to use Codex as their AI coding assistant.

Secondary Issue: AGENTS.md requires Serena initialization at session start, which Codex CLI cannot perform without proper MCP configuration.

Current State

Sync-McpConfig.ps1 Capabilities

• Source: .mcp.json (Claude Code format with mcpServers root key)
• Targets: VS Code (JSON), Factory (JSON)
• Format: JSON only
• Server transformations: Serena (context/port changes for VS Code compatibility)

Gap

• No TOML format generation capability
• Codex CLI target not supported
• Users cannot sync MCP configurations to Codex

Goals

1. Enable Sync-McpConfig.ps1 to generate TOML format configuration for Codex CLI
2. Add 'codex' as a target option (alongside 'vscode' and 'factory')
3. Support both repo-local (.codex/config.toml) and user home (~/.codex/config.toml) paths
4. Implement platform-specific transformations for Codex if needed (similar to Serena transformations)
5. Maintain backward compatibility with existing JSON targets

Non-Goals

• Building MCP servers for Codex
• Modifying authentication mechanisms for AI services
• Supporting other AI CLI tools beyond Codex
• Installing or managing Codex CLI itself

Codex TOML Format Requirements

File Locations

• Repo-local: .codex/config.toml (recommended for project-specific configs)
• User home: ~/.codex/config.toml (global configs)

TOML Structure

From OpenAI Codex documentation:

[mcp_servers.server_name]
command = "executable"
args = ["arg1", "arg2"]
startup_timeout_sec = 30
tool_timeout_sec = 120
enabled = true

[mcp_servers.server_name.env]
ENV_VAR = "value"

Key Differences from JSON

Example Transformation

Source (.mcp.json):

{
  "mcpServers": {
    "serena": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server"],
      "env": {
        "SOME_VAR": "value"
      }
    }
  }
}

Target (.codex/config.toml):

[mcp_servers.serena]
command = "uvx"
args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server"]

[mcp_servers.serena.env]
SOME_VAR = "value"

Acceptance Criteria

AC1: Codex Target Support

Given Sync-McpConfig.ps1 is invoked with -Target codex
When a valid .mcp.json exists
Then the script generates .codex/config.toml in valid TOML format without errors

AC2: TOML Format Correctness

Given an .mcp.json with multiple MCP servers (serena, deepwiki, forgetful)
When syncing to Codex target
Then the generated TOML file:

• Uses [mcp_servers.name] table syntax for each server
• Preserves all server properties (command, args, type, etc.)
• Creates separate [mcp_servers.name.env] tables for environment variables
• Uses proper TOML data types (strings quoted, arrays bracketed, booleans unquoted)

AC3: SyncAll Support

Given Sync-McpConfig.ps1 is invoked with -SyncAll
When the script runs
Then it generates configurations for all three targets:

• .vscode/mcp.json (JSON)
• .factory/mcp.json (JSON)
• .codex/config.toml (TOML)

AC4: Custom Destination Path

Given Sync-McpConfig.ps1 is invoked with -Target codex -DestinationPath ~/.codex/config.toml
When the script runs
Then it writes to user home directory instead of repo-local path

AC5: Server-Specific Transformations (Future)

Given Codex requires platform-specific transformations (TBD - research needed)
When syncing to Codex target
Then the script applies necessary transformations (similar to Serena's context/port changes)

Note: Initial implementation may use pass-through (no transformations) until Codex-specific needs are identified.

AC6: Documentation

Given new Codex target support
When users review script help
Then documentation includes:

• Codex target option in SYNOPSIS and PARAMETER sections
• Example showing Codex sync: .\Sync-McpConfig.ps1 -Target codex
• TOML format explanation in DESCRIPTION
• Link to Codex MCP documentation

AC7: Test Coverage

Given new TOML generation functionality
When Pester tests run
Then tests cover:

• Basic TOML generation from JSON input
• Array formatting in TOML
• Environment variable table generation
• All three targets (vscode, factory, codex)
• SyncAll with Codex included
• Edge cases (empty servers, missing properties)

AC8: Security

Given MCP configurations may contain sensitive data
When configuration is synced
Then the script:

• Validates TOML destination is not a symlink (like JSON validation)
• Does not log or expose environment variable values
• Preserves security patterns from JSON targets

Implementation Plan

Phase 1: TOML Generation Function

1. Create ConvertTo-Toml helper function
2. Support hashtable to TOML conversion
3. Handle nested objects (env vars as separate tables)
4. Handle arrays, strings, numbers, booleans
5. Generate properly formatted TOML with correct escaping

Phase 2: Target Integration

1. Add 'codex' to ValidateSet for -Target parameter
2. Add default path resolution for Codex (.codex/config.toml)
3. Implement Codex transform logic (initially pass-through)
4. Update SyncAll to include Codex target

Phase 3: Testing

1. Create Pester tests for ConvertTo-Toml function
2. Add integration tests for Codex target
3. Test SyncAll with all three targets
4. Verify TOML output with TOML parsers

Phase 4: Documentation

1. Update script help text
2. Add Codex examples
3. Document TOML format differences
4. Add link to Codex MCP documentation

Technical Design

ConvertTo-Toml Function Signature

function ConvertTo-Toml {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [hashtable]$Data,

        [string]$TablePrefix = 'mcp_servers'
    )

    # Generate TOML string
}

Script Changes

# Add codex to ValidateSet
[ValidateSet('factory', 'vscode', 'codex')]
[string]$Target = 'vscode',

# Add default path for codex
if ($Target -eq 'codex') {
    $codexPath = Join-Path $repoRoot '.codex'
    $DestinationPath = Join-Path $codexPath 'config.toml'
}

# Add codex transform
if ($Target -eq 'codex') {
    # Generate TOML format
    $destContent = ConvertTo-Toml -Data $sourceJson['mcpServers']
} else {
    # Existing JSON logic
}

Open Questions

1. Does Codex require specific transformations like Serena? → Research during implementation
2. Should we support HTTP-type servers in TOML? (deepwiki uses "type": "http") → Yes, TOML supports all types
3. Should default target remain 'vscode' or change to detect available CLI? → Keep 'vscode' for backward compatibility
4. Should SyncAll default behavior change to include Codex? → Yes, SyncAll should sync to all three targets

Dependencies

• PowerShell 7.4+ (existing requirement)
• .mcp.json source file (existing)
• TOML validator for testing (optional, e.g., tomli Python package)

Success Metrics

• Zero errors when syncing to Codex target
• All Pester tests passing (including new TOML tests)
• Documentation complete and accurate
• Users can successfully use Codex CLI with synced MCP servers

References

• Codex MCP documentation: https://developers.openai.com/codex/mcp
• Current Sync-McpConfig.ps1: scripts/Sync-McpConfig.ps1
• Existing tests: scripts/tests/Sync-McpConfig.Tests.ps1
• TOML specification: https://toml.io/en/v1.0.0
• Issue Add OpenAI Codex MCP support to Sync-McpConfig.ps1 #804 comment with TOML format: Add OpenAI Codex MCP support to Sync-McpConfig.ps1 #804 (comment)