Multi-Client MCP Configuration Support

[savinmikhail]

Summary

Adds interactive multi‑client support to ctx mcp:config, enabling users to generate client‑specific MCP configurations for Claude Desktop, Codex, Cursor, and Generic clients. Updates documentation to reflect the new interactive flow and that CTX works with multiple MCP clients, not only Claude.

Initial issue: see #267

Motivation

The MCP ecosystem now includes several clients. Previously, ctx mcp:config assumed Claude Desktop. This change introduces a client selection experience and explicit flags so users can set up their preferred MCP client quickly and correctly.

What’s included

• CLI: Interactive mode and client selection

  • -i, --interactive guided setup with OS detection, project selection, and client choice
  • -c, --client=claude|codex|cursor|generic explicit non‑interactive selection
  • -e, --explain prints client‑specific setup instructions
  • -p, --project-path and -g, --global/--no-global to choose project scoping
  • -f, --wsl to force WSL mode on Windows

• Architecture: Strategy + registry for client‑specific config

  • src/McpServer/McpConfig/Client/ClientStrategyRegistry.php
  • src/McpServer/McpConfig/Client/ClientStrategyInterface.php
  • src/McpServer/McpConfig/Client/AbstractClientStrategy.php
  • src/McpServer/McpConfig/Client/ClaudeDesktopClientStrategy.php
  • src/McpServer/McpConfig/Client/CodexClientStrategy.php
  • src/McpServer/McpConfig/Client/CursorClientStrategy.php
  • src/McpServer/McpConfig/Client/GenericClientStrategy.php

• Command integration

  • src/McpServer/Console/McpConfigCommand.php: integrates interactive flow, strategy registry, and flags

• Docs update

  • README.md:223 — renamed section to “Connect to an MCP Client (Optional)” and documented ctx mcp:config -i
  • README.md:130 — Quick Start updated to mention multiple MCP clients (Claude Desktop, Cursor, Continue, Windsurf)

Usage

Interactive (recommended):

ctx mcp:config -i

Non‑interactive examples:

# Claude Desktop
ctx mcp:config --client=claude

# Codex (outputs TOML snippet)
ctx mcp:config --client=codex

# Cursor (generic config + notes)
ctx mcp:config --client=cursor

# Generic MCP config
ctx mcp:config --client=generic

Additional options:

# Show client‑specific setup instructions
ctx mcp:config -i --explain

# Single‑project config
ctx mcp:config --client=claude --project-path /path/to/project --no-global

# Force WSL config detection
ctx mcp:config --client=claude --wsl

Validation

• Ran ctx mcp:config -i and verified:
  • Client menu appears with Claude Desktop (default), Codex, Cursor, Generic
  • OS detection prints detected environment
  • Project scope selection (global vs specific) works
  • Generated config matches the selected client
  • --explain shows client‑specific instructions
• Non‑interactive runs for each client completed without errors
• Verified README changes render and link correctly

Notes on defaults

• Interactive mode defaults to Claude Desktop in the client menu.
• If running non‑interactive without --client, the command generates a Generic MCP configuration. Use --client=claude to mirror Claude‑specific defaults.

Screenshots/Examples (text)

• Codex TOML snippet is rendered under “Generated Configuration” with command and args.
• Cursor shows Generic config plus setup notes.
• Claude renders copy‑paste‑ready JSON and setup guidance.

Checklist

• Interactive client selection flow
• Strategy/registry pattern with Claude, Codex, Cursor, Generic
• Client‑specific rendering and instructions
• README updated for interactive setup and multi‑client support
• Manual and non‑interactive paths verified

Related files

• src/McpServer/Console/McpConfigCommand.php
• src/McpServer/McpConfig/Client/ClientStrategyRegistry.php
• src/McpServer/McpConfig/Client/ClientStrategyInterface.php
• src/McpServer/McpConfig/Client/AbstractClientStrategy.php
• src/McpServer/McpConfig/Client/ClaudeDesktopClientStrategy.php
• src/McpServer/McpConfig/Client/CodexClientStrategy.php
• src/McpServer/McpConfig/Client/CursorClientStrategy.php
• src/McpServer/McpConfig/Client/GenericClientStrategy.php
• README.md

[codecov]

Codecov Report

❌ Patch coverage is 86.02151% with 13 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...cpServer/McpConfig/Client/CursorClientStrategy.php	46.15%	7 Missing ⚠️
...Server/McpConfig/Client/AbstractClientStrategy.php	33.33%	4 Missing ⚠️
src/McpServer/Console/McpConfigCommand.php	93.33%	1 Missing ⚠️
...Server/McpConfig/Client/ClientStrategyRegistry.php	95.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[savinmikhail]

codex output:

❯ ./ctx mcp:config -i

MCP Configuration Generator
===========================

 This tool generates configuration snippets for connecting CTX to MCP clients like Claude Desktop.
 It automatically detects your operating system and generates the appropriate configuration format.

Interactive Configuration Mode
------------------------------

 Let's configure your MCP client step by step...

 Which MCP client are you configuring? [Claude Desktop]:
  [claude ] Claude Desktop
  [codex  ] Codex
  [cursor ] Cursor
  [generic] Generic MCP Client
 > codex

Environment Detection
---------------------

 ------------------ -------- 
  Operating System   macOS   
  PHP OS             Darwin  
  Architecture       arm64   
 ------------------ -------- 


 How do you want to configure project access? [Use global project registry (switch between projects dynamically)]:
  [global  ] Use global project registry (switch between projects dynamically)
  [specific] Use specific project path (single project)
 > global

 Do you need to configure environment variables (e.g., GitHub token)? (yes/no) [no]:
 > 

Generated Configuration
-----------------------

 Codex configuration (TOML):

[mcp_servers.ctx]
command = "ctx"
args = ["server"]


Setup Instructions
------------------

    1. Copy the TOML snippet above to your Codex MCP client configuration.
    2. Ensure the `ctx` binary is available in your PATH.
    3. Restart the Codex client and verify the MCP server connection.


generator on feature/mult…nfig-support ❯

[savinmikhail]

claude example

Generated Configuration
-----------------------

 Configuration type: claude
 Operating system: macOS
 Project mode: Global project registry
 Command: ctx server

 Add this configuration to your Claude Desktop config file:

{
    "mcpServers": {
        "ctx": {
            "command": "ctx",
            "args": [
                "server"
            ]
        }
    }
}

 Claude Desktop configuration file location:
   • ~/Library/Application Support/Claude/claude_desktop_config.json

Setup Instructions
------------------

 To set up Claude Desktop with CTX:
    1. Close Claude Desktop if it's running
    2. Open the Claude Desktop configuration file (see paths above)
    3. If the file doesn't exist, create it with the generated configuration
    4. If the file exists, merge the "mcpServers" section with your existing configuration
    5. Save the file and restart Claude Desktop
    6. You should see CTX listed in the MCP servers when you start a new conversation

 ! [NOTE] Global project registry configuration:                                                                        
 !                                                                                                                      
 !        • This configuration uses CTX's project registry system                                                       
 !                                                                                                                      
 !        • You can switch between different registered projects dynamically                                            
 !                                                                                                                      
 !        • Use "ctx project:add" to register projects first                                                            
 !                                                                                                                      
 !        • Good for multi-project workflows                                                                            

Troubleshooting Tips
--------------------

 If Claude doesn't show CTX as available:
   • Check that the configuration file syntax is valid JSON
   • Verify that the CTX binary is installed and accessible
   • Check the Claude Desktop logs for any error messages
   • Try restarting Claude Desktop completely

 ! [NOTE] For more help:                                                                                                
 !                                                                                                                      
 !        • Visit the CTX documentation at https://context-hub.github.io/generator/                                     
 !                                                                                                                      
 !        • Check the MCP server documentation for troubleshooting guides                                               
 !                                                                                                                      
 !        • Join the community discussions on GitHub