Merge branch 'feat/codex-support' into dev

Author: LittleCoinCoin

.augmentignore

@@ -0,0 +1 @@
+__reports__/

.gitignore

@@ -5,6 +5,14 @@ envs/
 Laghari/
 __temp__/
 
+# IDEs
+## Kiro
+.kiro/
+
+## VS Code
+.vscode/
+
+
 # vvvvvvv  Default Python Ignore vvvvvvvv
 # Byte-compiled / optimized / DLL files
 __pycache__/

README.md

@@ -4,15 +4,15 @@
 
 ## Introduction
 
-Hatch is the package manager for managing Model Context Protocol (MCP) servers with environment isolation, multi-type dependency resolution, and multi-host deployment. Deploy MCP servers to Claude Desktop, VS Code, Cursor, Kiro, and other platforms with automatic dependency management.
+Hatch is the package manager for managing Model Context Protocol (MCP) servers with environment isolation, multi-type dependency resolution, and multi-host deployment. Deploy MCP servers to Claude Desktop, VS Code, Cursor, Kiro, Codex, and other platforms with automatic dependency management.
 
 The canonical documentation is at `docs/index.md` and published at <https://hatch.readthedocs.io/en/latest/>.
 
 ## Key Features
 
 - **Environment Isolation** — Create separate, isolated workspaces for different projects without conflicts
 - **Multi-Type Dependency Resolution** — Automatically resolve and install system packages, Python packages, Docker containers, and Hatch packages
-- **Multi-Host Deployment** — Deploy MCP servers to Claude Desktop, Claude Code, VS Code, Cursor, Kiro, LM Studio, and Google Gemini CLI
+- **Multi-Host Deployment** — Configure MCP servers on multiple host platforms
 - **Package Validation** — Ensure packages meet schema requirements before distribution
 - **Development-Focused** — Optimized for rapid development and testing of MCP server ecosystems
 
@@ -25,6 +25,7 @@ Hatch supports deployment to the following MCP host platforms:
 - **VS Code** — Visual Studio Code with the MCP extension for tool integration
 - **Cursor** — AI-first code editor with built-in MCP server support
 - **Kiro** — Kiro IDE with MCP support
+- **Codex** — OpenAI Codex with MCP server configuration support
 - **LM Studio** — Local LLM inference platform with MCP server integration
 - **Google Gemini CLI** — Command-line interface for Google's Gemini model with MCP support
 

docs/articles/users/CLIReference.md

@@ -395,29 +395,35 @@ Syntax:
 
 `hatch mcp configure <server-name> --host <host> (--command CMD | --url URL) [--args ARGS] [--env-var ENV] [--header HEADER] [--dry-run] [--auto-approve] [--no-backup]`
 
-| Argument / Flag | Type | Description | Default |
-|---:|---|---|---|
-| `server-name` | string (positional) | Name of the MCP server to configure | n/a |
-| `--host` | string | Target host platform (claude-desktop, cursor, etc.) | n/a |
-| `--command` | string | Command to execute for local servers (mutually exclusive with --url) | none |
-| `--url` | string | URL for remote MCP servers (mutually exclusive with --command) | none |
-| `--http-url` | string | HTTP streaming endpoint URL (Gemini only) | none |
-| `--args` | string | Arguments for MCP server command (only with --command) | none |
-| `--env-var` | string | Environment variables format: KEY=VALUE (can be used multiple times) | none |
-| `--header` | string | HTTP headers format: KEY=VALUE (only with --url) | none |
-| `--timeout` | int | Request timeout in milliseconds (Gemini) | none |
-| `--trust` | flag | Bypass tool call confirmations (Gemini) | false |
-| `--cwd` | string | Working directory for stdio transport (Gemini) | none |
-| `--include-tools` | multiple | Tool allowlist - only these tools will be available (Gemini). Space-separated values. | none |
-| `--exclude-tools` | multiple | Tool blocklist - these tools will be excluded (Gemini). Space-separated values. | none |
-| `--env-file` | string | Path to environment file (Cursor, VS Code, LM Studio) | none |
-| `--input` | multiple | Input variable definitions format: type,id,description[,password=true] (VS Code) | none |
-| `--disabled` | flag | Disable the MCP server (Kiro) | false |
-| `--auto-approve-tools` | multiple | Tool names to auto-approve (Kiro). Can be used multiple times. | none |
-| `--disable-tools` | multiple | Tool names to disable (Kiro). Can be used multiple times. | none |
-| `--dry-run` | flag | Preview configuration without applying changes | false |
-| `--auto-approve` | flag | Skip confirmation prompts | false |
-| `--no-backup` | flag | Skip backup creation before configuration | false |
+| Argument / Flag | Hosts | Type | Description | Default |
+|---:|---|---|---|---|
+| `server-name` | all | string (positional) | Name of the MCP server to configure | n/a |
+| `--host` | all | string | Target host platform (claude-desktop, cursor, etc.) | n/a |
+| `--command` | all | string | Command to execute for local servers (mutually exclusive with --url) | none |
+| `--url` | all except Claude Desktop/Code | string | URL for remote MCP servers (mutually exclusive with --command) | none |
+| `--http-url` | gemini | string | HTTP streaming endpoint URL | none |
+| `--args` | all | string | Arguments for MCP server command (only with --command) | none |
+| `--env-var` | all | string | Environment variables format: KEY=VALUE (can be used multiple times) | none |
+| `--header` | all except Claude Desktop/Code | string | HTTP headers format: KEY=VALUE (only with --url) | none |
+| `--timeout` | gemini | int | Request timeout in milliseconds | none |
+| `--trust` | gemini | flag | Bypass tool call confirmations | false |
+| `--cwd` | gemini, codex | string | Working directory for stdio transport | none |
+| `--include-tools` | gemini, codex | multiple | Tool allowlist / enabled tools. Space-separated values. | none |
+| `--exclude-tools` | gemini, codex | multiple | Tool blocklist / disabled tools. Space-separated values. | none |
+| `--env-file` | cursor, vscode, lmstudio | string | Path to environment file | none |
+| `--input` | vscode | multiple | Input variable definitions format: type,id,description[,password=true] | none |
+| `--disabled` | kiro | flag | Disable the MCP server | false |
+| `--auto-approve-tools` | kiro | multiple | Tool names to auto-approve. Can be used multiple times. | none |
+| `--disable-tools` | kiro | multiple | Tool names to disable. Can be used multiple times. | none |
+| `--env-vars` | codex | multiple | Environment variable names to whitelist/forward. Can be used multiple times. | none |
+| `--startup-timeout` | codex | int | Server startup timeout in seconds (default: 10) | none |
+| `--tool-timeout` | codex | int | Tool execution timeout in seconds (default: 60) | none |
+| `--enabled` | codex | flag | Enable the MCP server | false |
+| `--bearer-token-env-var` | codex | string | Name of env var containing bearer token for Authorization header | none |
+| `--env-header` | codex | multiple | HTTP header from env var format: KEY=ENV_VAR_NAME. Can be used multiple times. | none |
+| `--dry-run` | all | flag | Preview configuration without applying changes | false |
+| `--auto-approve` | all | flag | Skip confirmation prompts | false |
+| `--no-backup` | all | flag | Skip backup creation before configuration | false |
 
 **Behavior**:
 
@@ -509,6 +515,42 @@ Configure MCP server 'my-server' on host 'kiro'? [y/N]: y
 [SUCCESS] Successfully configured MCP server 'my-server' on host 'kiro'
 ```
 
+**Example - Codex Configuration with Timeouts and Tool Filtering**:
+
+```bash
+$ hatch mcp configure context7 --host codex --command npx --args "-y" "@upstash/context7-mcp" --env-vars PATH --env-vars HOME --startup-timeout 15 --tool-timeout 120 --enabled --include-tools read write --exclude-tools delete
+
+Server 'context7' created for host 'codex':
+  name: UPDATED None --> 'context7'
+  command: UPDATED None --> 'npx'
+  args: UPDATED None --> ['-y', '@upstash/context7-mcp']
+  env_vars: UPDATED None --> ['PATH', 'HOME']
+  startup_timeout_sec: UPDATED None --> 15
+  tool_timeout_sec: UPDATED None --> 120
+  enabled: UPDATED None --> True
+  enabled_tools: UPDATED None --> ['read', 'write']
+  disabled_tools: UPDATED None --> ['delete']
+
+Configure MCP server 'context7' on host 'codex'? [y/N]: y
+[SUCCESS] Successfully configured MCP server 'context7' on host 'codex'
+```
+
+**Example - Codex HTTP Server with Authentication**:
+
+```bash
+$ hatch mcp configure figma --host codex --url https://mcp.figma.com/mcp --bearer-token-env-var FIGMA_OAUTH_TOKEN --env-header "X-Figma-Region=FIGMA_REGION" --header "X-Custom=static-value"
+
+Server 'figma' created for host 'codex':
+  name: UPDATED None --> 'figma'
+  url: UPDATED None --> 'https://mcp.figma.com/mcp'
+  bearer_token_env_var: UPDATED None --> 'FIGMA_OAUTH_TOKEN'
+  env_http_headers: UPDATED None --> {'X-Figma-Region': 'FIGMA_REGION'}
+  http_headers: UPDATED None --> {'X-Custom': 'static-value'}
+
+Configure MCP server 'figma' on host 'codex'? [y/N]: y
+[SUCCESS] Successfully configured MCP server 'figma' on host 'codex'
+```
+
 **Example - Remote Server Configuration**:
 
 ```bash
@@ -550,6 +592,7 @@ Different MCP hosts support different configuration fields. The conversion repor
 - **Cursor / LM Studio**: Supports universal fields + envFile
 - **VS Code**: Supports universal fields + envFile, inputs
 - **Gemini CLI**: Supports universal fields + 14 additional fields (cwd, timeout, trust, OAuth settings, etc.)
+- **Codex**: Supports universal fields + Codex-specific fields for URL-based servers (http_headers, env_http_headers, bearer_token_env_var, enabled, startup_timeout_sec, tool_timeout_sec, env_vars)
 
 When configuring a server with fields not supported by the target host, those fields are marked as UNSUPPORTED in the report and automatically excluded from the configuration.
 

docs/articles/users/MCPHostConfiguration.md

@@ -20,6 +20,7 @@ Hatch currently supports configuration for these MCP host platforms:
 - **VS Code** - Microsoft Visual Studio Code with MCP extensions
 - **Cursor** - AI-powered code editor
 - **Kiro** - Kiro IDE with MCP support
+- **Codex** - OpenAI Codex with MCP server configuration support
 - **LM Studio** - Local language model interface
 - **Gemini** - Google's AI development environment
 

docs/articles/users/tutorials/04-mcp-host-configuration/01-host-platform-overview.md

@@ -54,6 +54,7 @@ Hatch currently supports configuration for these MCP host platforms:
 - [**Cursor**](https://cursor.com/) - AI-powered code editor
 - [**VS Code**](https://code.visualstudio.com/) - Microsoft Visual Studio Code
 - [**Kiro**](https://kiro.ai/) - Kiro IDE with MCP support
+- [**Codex**](https://github.com/openai/codex) - OpenAI Codex with MCP server configuration support
 - [**LM Studio**](https://lmstudio.ai/) - Local language model interface
 - [**Gemini**](https://github.com/google-gemini/gemini-cli) - Google's AI Command Line Interface
 

docs/index.md

@@ -6,6 +6,8 @@ Welcome to the documentation for Hatch, the official package manager for the Hat
 
 Hatch provides powerful tools for managing MCP server packages, environments, and interacting with the Hatch registry. It serves as the package management foundation for [Hatchling](https://github.com/CrackingShells/Hatchling) and other projects in the ecosystem.
 
+Hatch also supports MCP host configuration across popular platforms including Claude Desktop/Code, VS Code, Cursor, Kiro, Codex, LM Studio, and Gemini.
+
 ## Documentation Sections
 
 ### For Users

hatch/cli_hatch.py

@@ -716,6 +716,12 @@ def handle_mcp_configure(
     disabled: Optional[bool] = None,
     auto_approve_tools: Optional[list] = None,
     disable_tools: Optional[list] = None,
+    env_vars: Optional[list] = None,
+    startup_timeout: Optional[int] = None,
+    tool_timeout: Optional[int] = None,
+    enabled: Optional[bool] = None,
+    bearer_token_env_var: Optional[str] = None,
+    env_header: Optional[list] = None,
     no_backup: bool = False,
     dry_run: bool = False,
     auto_approve: bool = False,
@@ -837,6 +843,27 @@ def handle_mcp_configure(
         if disable_tools is not None:
             omni_config_data["disabledTools"] = disable_tools
 
+        # Host-specific fields (Codex)
+        if env_vars is not None:
+            omni_config_data["env_vars"] = env_vars
+        if startup_timeout is not None:
+            omni_config_data["startup_timeout_sec"] = startup_timeout
+        if tool_timeout is not None:
+            omni_config_data["tool_timeout_sec"] = tool_timeout
+        if enabled is not None:
+            omni_config_data["enabled"] = enabled
+        if bearer_token_env_var is not None:
+            omni_config_data["bearer_token_env_var"] = bearer_token_env_var
+        if env_header is not None:
+            # Parse KEY=ENV_VAR_NAME format into dict
+            env_http_headers = {}
+            for header_spec in env_header:
+                if '=' in header_spec:
+                    key, env_var_name = header_spec.split('=', 1)
+                    env_http_headers[key] = env_var_name
+            if env_http_headers:
+                omni_config_data["env_http_headers"] = env_http_headers
+
         # Partial update merge logic
         if is_update:
             # Merge with existing configuration
@@ -1568,101 +1595,137 @@ def main():
     mcp_configure_parser = mcp_subparsers.add_parser(
         "configure", help="Configure MCP server directly on host"
     )
-    mcp_configure_parser.add_argument("server_name", help="Name for the MCP server")
+    mcp_configure_parser.add_argument(
+        "server_name", help="Name for the MCP server [hosts: all]"
+    )
     mcp_configure_parser.add_argument(
         "--host",
         required=True,
-        help="Host platform to configure (e.g., claude-desktop, cursor)",
+        help="Host platform to configure (e.g., claude-desktop, cursor) [hosts: all]",
     )
 
     # Create mutually exclusive group for server type
     server_type_group = mcp_configure_parser.add_mutually_exclusive_group()
     server_type_group.add_argument(
         "--command",
         dest="server_command",
-        help="Command to execute the MCP server (for local servers)",
+        help="Command to execute the MCP server (for local servers) [hosts: all]",
     )
     server_type_group.add_argument(
-        "--url", help="Server URL for remote MCP servers (SSE transport)"
+        "--url", help="Server URL for remote MCP servers (SSE transport) [hosts: all except claude-desktop, claude-code]"
     )
     server_type_group.add_argument(
-        "--http-url", help="HTTP streaming endpoint URL (Gemini only)"
+        "--http-url", help="HTTP streaming endpoint URL [hosts: gemini]"
     )
 
     mcp_configure_parser.add_argument(
         "--args",
         nargs="*",
-        help="Arguments for the MCP server command (only with --command)",
+        help="Arguments for the MCP server command (only with --command) [hosts: all]",
     )
     mcp_configure_parser.add_argument(
-        "--env-var", action="append", help="Environment variables (format: KEY=VALUE)"
+        "--env-var",
+        action="append",
+        help="Environment variables (format: KEY=VALUE) [hosts: all]",
     )
     mcp_configure_parser.add_argument(
         "--header",
         action="append",
-        help="HTTP headers for remote servers (format: KEY=VALUE, only with --url)",
+        help="HTTP headers for remote servers (format: KEY=VALUE, only with --url) [hosts: all except claude-desktop, claude-code]",
     )
 
     # Host-specific arguments (Gemini)
     mcp_configure_parser.add_argument(
-        "--timeout", type=int, help="Request timeout in milliseconds (Gemini)"
+        "--timeout", type=int, help="Request timeout in milliseconds [hosts: gemini]"
     )
     mcp_configure_parser.add_argument(
-        "--trust", action="store_true", help="Bypass tool call confirmations (Gemini)"
+        "--trust", action="store_true", help="Bypass tool call confirmations [hosts: gemini]"
     )
     mcp_configure_parser.add_argument(
-        "--cwd", help="Working directory for stdio transport (Gemini)"
+        "--cwd", help="Working directory for stdio transport [hosts: gemini, codex]"
     )
     mcp_configure_parser.add_argument(
         "--include-tools",
         nargs="*",
-        help="Tool allowlist - only these tools will be available (Gemini)",
+        help="Tool allowlist / enabled tools [hosts: gemini, codex]",
     )
     mcp_configure_parser.add_argument(
         "--exclude-tools",
         nargs="*",
-        help="Tool blocklist - these tools will be excluded (Gemini)",
+        help="Tool blocklist / disabled tools [hosts: gemini, codex]",
     )
 
     # Host-specific arguments (Cursor/VS Code/LM Studio)
     mcp_configure_parser.add_argument(
-        "--env-file", help="Path to environment file (Cursor, VS Code, LM Studio)"
+        "--env-file", help="Path to environment file [hosts: cursor, vscode, lmstudio]"
     )
 
     # Host-specific arguments (VS Code)
     mcp_configure_parser.add_argument(
         "--input",
         action="append",
-        help="Input variable definitions in format: type,id,description[,password=true] (VS Code)",
+        help="Input variable definitions in format: type,id,description[,password=true] [hosts: vscode]",
     )
 
     # Host-specific arguments (Kiro)
     mcp_configure_parser.add_argument(
         "--disabled",
         action="store_true",
-        help="Disable the MCP server (Kiro)"
+        help="Disable the MCP server [hosts: kiro]"
     )
     mcp_configure_parser.add_argument(
         "--auto-approve-tools",
         action="append",
-        help="Tool names to auto-approve without prompting (Kiro)"
+        help="Tool names to auto-approve without prompting [hosts: kiro]"
     )
     mcp_configure_parser.add_argument(
         "--disable-tools",
         action="append",
-        help="Tool names to disable (Kiro)"
+        help="Tool names to disable [hosts: kiro]"
+    )
+
+    # Codex-specific arguments
+    mcp_configure_parser.add_argument(
+        "--env-vars",
+        action="append",
+        help="Environment variable names to whitelist/forward [hosts: codex]"
+    )
+    mcp_configure_parser.add_argument(
+        "--startup-timeout",
+        type=int,
+        help="Server startup timeout in seconds (default: 10) [hosts: codex]"
+    )
+    mcp_configure_parser.add_argument(
+        "--tool-timeout",
+        type=int,
+        help="Tool execution timeout in seconds (default: 60) [hosts: codex]"
+    )
+    mcp_configure_parser.add_argument(
+        "--enabled",
+        action="store_true",
+        help="Enable the MCP server [hosts: codex]"
+    )
+    mcp_configure_parser.add_argument(
+        "--bearer-token-env-var",
+        type=str,
+        help="Name of environment variable containing bearer token for Authorization header [hosts: codex]"
+    )
+    mcp_configure_parser.add_argument(
+        "--env-header",
+        action="append",
+        help="HTTP header from environment variable in KEY=ENV_VAR_NAME format [hosts: codex]"
     )
 
     mcp_configure_parser.add_argument(
         "--no-backup",
         action="store_true",
-        help="Skip backup creation before configuration",
+        help="Skip backup creation before configuration [hosts: all]",
     )
     mcp_configure_parser.add_argument(
-        "--dry-run", action="store_true", help="Preview configuration without execution"
+        "--dry-run", action="store_true", help="Preview configuration without execution [hosts: all]"
     )
     mcp_configure_parser.add_argument(
-        "--auto-approve", action="store_true", help="Skip confirmation prompts"
+        "--auto-approve", action="store_true", help="Skip confirmation prompts [hosts: all]"
     )
 
     # Remove MCP commands (object-action pattern)
@@ -2724,6 +2787,12 @@ def main():
                 getattr(args, "disabled", None),
                 getattr(args, "auto_approve_tools", None),
                 getattr(args, "disable_tools", None),
+                getattr(args, "env_vars", None),
+                getattr(args, "startup_timeout", None),
+                getattr(args, "tool_timeout", None),
+                getattr(args, "enabled", None),
+                getattr(args, "bearer_token_env_var", None),
+                getattr(args, "env_header", None),
                 args.no_backup,
                 args.dry_run,
                 args.auto_approve,