Metadata-Version: 2.4
Name: environments-mcp-server
Version: 1.0.0
Summary: Environments MCP server
Project-URL: Homepage, https://github.com/anaconda/environments-mcp
Project-URL: Source, https://github.com/anaconda/environemnts-mcp
Project-URL: Issues, https://github.com/anaconda/environments-mcp/issues
Author: Anaconda, Inc.
License: Apache-2.0
License-File: LICENSE
Keywords: anaconda,conda,mcp,server
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <3.14,>=3.10
Requires-Dist: anaconda-auth<0.15.0,>=0.13.0
Requires-Dist: click<9.0,>=8.1
Requires-Dist: environs<12.0,>=9.0
Requires-Dist: fastmcp>=2.12
Requires-Dist: httpx<1.0,>=0.24
Requires-Dist: orjson
Requires-Dist: typer<1.0,>=0.7
Provides-Extra: dev
Requires-Dist: ipdb>=0.13; extra == 'dev'
Requires-Dist: ipython>=8.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pip-audit; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=1.2.0; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest<8.5.0,>=8.4.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: tox; extra == 'dev'
Requires-Dist: tox-conda<0.10,>=0.9; extra == 'dev'
Description-Content-Type: text/markdown

# environments-mcp-server

Environments MCP Server

# About
The Environments MCP server uses FastMCP in the forefront and leverages `anaconda-connector-conda` offloading all the conda operations to this component.


### Architecture Diagram
![Architecture](/./docs/images/architecture-mcp.png)


# Makefile - Quick guide

### This repo ships a Makefile to make common tasks one-liners. It runs the server from source (no install needed) by exporting PYTHONPATH=src.

Check all the commands by running:
```bash
make help
```


# Setup

## 1) Requirements
Make sure to have the basic requirements installed:

* **Python 3.10+** (project is tested on 3.10–3.13).
* **Conda**
* **Git**
* Make


## 2) Clone and enter the repo

```bash
git clone git@github.com:anaconda/environments-mcp.git environments-mcp-server
cd environments-mcp-server
```

## 3) Setup the environment
```bash
make setup
```
This should create an environment named `environments-mcp-server-dev`.

## 4) Activate the environment
```bash
conda activate environments-mcp-server-dev
```

# Running the project from source

The Makefile exports `PYTHONPATH=src`, so you can run directly:

```bash
make run-http                 # streamable-http on port 4041
# or a custom port:
make run-http PORT=5050

# stdio transport (quiet by design; intended for MCP hosts)
make run-stdio
```

Equivalent raw command:

```bash
PYTHONPATH=src python -m environments_mcp_server start --transport streamable-http --port 4041
```

In case you wish to enable only a selection of tools you can use either the `--toolset` argument or the `CONDA_MCP_TOOLSET` environment variable. Both expect a string containing a comma-separated list of tools.

```bash
PYTHONPATH=src python -m environments_mcp_server start --toolset "list_environments,create_environment"
```

# Configuration

All options can be set via CLI flags or environment variables. Environment variables take the prefix `ENVIRONMENTS_MCP_SERVER_`.

## Transport

| CLI flag | Environment variable | Default | Description |
|---|---|---|---|
| `--transport` | `ENVIRONMENTS_MCP_SERVER_TRANSPORT` | `stdio` | Transport type: `stdio`, `streamable-http`, or `sse` |
| `--port` | `ENVIRONMENTS_MCP_SERVER_CONDA_MCP_PORT` | `4041` | Port for HTTP-based transports (ignored for `stdio`) |
| `--host` | `ENVIRONMENTS_MCP_SERVER_HOST` | `0.0.0.0` | Bind host for HTTP-based transports |

## Tools

| CLI flag | Environment variable | Default | Description |
|---|---|---|---|
| `--toolset` | `CONDA_MCP_TOOLSET` | _(all tools)_ | Comma-separated list of tool names to enable |
| `--allow-override-channels` | `ENVIRONMENTS_MCP_SERVER_ALLOW_OVERRIDE_CHANNELS` | `false` | Expose the `override_channels` argument in tool schemas (see below) |

## Server behaviour

| CLI flag | Environment variable | Default | Description |
|---|---|---|---|
| `--max-retries` | `ENVIRONMENTS_MCP_SERVER_MAX_RETRIES` | `5` | Retry attempts when the HTTP port is already in use |
| `--retry-interval` | `ENVIRONMENTS_MCP_SERVER_RETRY_INTERVAL` | `1.0` | Seconds between port-availability retries |

## Logging & Telemetry

| Environment variable | Default | Description |
|---|---|---|
| `ENVIRONMENTS_MCP_SERVER_LOG_LEVEL` | `INFO` | Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
| `ENVIRONMENTS_MCP_SERVER_IS_TELEMETRY_ENABLED` | `true` | Enable or disable telemetry |
| `ENVIRONMENTS_MCP_SERVER_ENVIRONMENT` | `production` | Deployment environment (`production` or `staging`) |

---

### `override_channels` — opt-in channel control

By default the `override_channels` parameter is **hidden from the tool schema** exposed to the agent. This means the agent cannot discover or pass the argument, so package installs always use the channels configured in the user's conda profile.

Enable it when you explicitly want to allow the agent to specify custom channels:

```bash
# via CLI flag
python -m environments_mcp_server start --allow-override-channels

# via environment variable
ENVIRONMENTS_MCP_SERVER_ALLOW_OVERRIDE_CHANNELS=true python -m environments_mcp_server start
```

> **Why opt-in?** Advertising `override_channels` to the agent increases the risk of it pulling packages from unintended or untrusted channels. Keeping it hidden by default enforces the user's configured channel policy.

# Building and Installing (optional)

If you want to test the wheel:

```bash
make wheel                    # creates dist/*.whl
make install                  # force-reinstalls the new wheel
```

To remove the installed package:

```bash
make uninstall
```

# Run tests

* **Pytest in the current environment**:

  ```bash
  make test                    # add flags via: make test ARGS="-k smoke -vv"
  ```
* **Tox matrix (runs on multiple Python versions if available)**:

  ```bash
  make test-tox                # add flags via: make test-tox ARGS="-e py311 -q"
  ```

### Notes on async tests

If you write `async def` tests, ensure `pytest-asyncio` is active. We use:

```ini
# pytest.ini at repo root
[pytest]
asyncio_mode = auto
asyncio_default_fixture_loop_scope = function
```
