conda-cli-mcp: Instructions file for Codex

AGENTS.md — conda-cli-mcp coding guidelines

Project contract

• The repository and distribution are named conda-cli-mcp. The standalone console command is ccm, and the Python package is conda_cli_mcp. conda-mcp is reserved for the future umbrella package that brings conda-cli-mcp and conda-meta-mcp together.

• The distribution registers conda mcp through conda's public subcommand plugin hook. It launches the server in a clean process and targets the conda installation that loaded the plugin by default.

• The server exposes the CLI accepted by the configured conda executable, including subcommands contributed through conda plugin hooks.

• Every CLI operation must remain reachable through a raw argv tool. Commands with introspectable argparse definitions also receive generated structured tools.

• Discover the command catalog once at server startup. Keep the MCP tool list stable for that server lifetime. Installing, removing, or updating a plugin reports that a restart is required.

• Run conda commands out of process. Conda owns parser dispatch, configuration loading, plugin ordering, command hooks, solver hooks, transaction hooks, reporters, authentication, and exception handling.

• Do not expose every conda plugin hook as an independent MCP tool. Non-command hooks participate through normal conda execution.

• Optional plugin integrations must run through public interfaces in the target interpreter. Do not duplicate a plugin's cache format, path resolution, or validation in the MCP server.

• Shell commands may return activation code or environment changes. Never claim to mutate the shell of the MCP host.

Project structure

• Keep the package flat until a real grouping requires a subpackage.

• server.py owns MCP capabilities, tool listing, and dispatch.

• discovery.py owns argparse traversal and conversion into the public command catalog.

• execution.py owns argv construction, subprocess lifetime, cancellation, and output capture.