[![prek](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/j178/prek/master/docs/assets/badge-v0.json)](https://github.com/j178/prek)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
[![Tests](https://github.com/conda-incubator/conda-meta-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/conda-incubator/conda-meta-mcp/actions/workflows/tests.yml)

# conda-meta-mcp

An MCP (Model Context Protocol) server exposing authoritative, read-only Conda ecosystem metadata for AI agents.

📖 **Read the introduction blog post:** [conda-meta-mcp: Expert Conda Ecosystem Data for AI Agents](https://conda.org/blog/conda-meta-mcp)

> [!NOTE]
> `conda-meta-mcp` provides read-only access to conda ecosystem metadata from channel data
> (packages and repodata), conda-forge data, and the OpenTeams search index for package
> content. Users are solely responsible for all requests they initiate, authorize, automate,
> or cause to be made through `conda-meta-mcp`, including compliance with any applicable
> third-party terms, rate limits, access requirements, and package licenses.
>
> Metadata and license fields may be incomplete, outdated, or informational only. This
> project does not provide legal advice or grant rights to use third-party services or
> content.

## What “Meta” Means Here

“Meta” refers to structured, machine-consumable ecosystem intelligence about packages — not the upstream project documentation itself. This server provides (see also the schema [server-info.json](server-info.json) for current capabilities):

Currently available:

- Version metadata (MCP tool/library versions) via the `info` tool
- Package info tarball data via the `package_insights` tool
- Package search via the `package_search` tool
- Import to package heuristic mapping via the `import_mapping` tool
- File path to package mapping via the `file_path_search` tool
- PyPI name to conda package mapping via the `pypi_to_conda` tool
- CLI help (for conda) via the `cli_help` tool
- Repository metadata queries (depends / whoneeds) via the `repoquery` tool

Tools backed by channel-specific data sources require an explicit `channel` argument and
fail for unsupported channels before reading their data source.

Planned:

- Solver feasibility signals (dry-run outputs)
- Schema references and selected spec excerpts
- Binary linkage information
- Links (not copies) to sections of knowledge bases

It does not embed, index, or serve full library docs (e.g. numpy API pages); that remains out of scope by design.

## 1. Purpose

Enable agents to answer packaging questions by providing up-to-date critical and fragmented expert knowledge. This project provides a safe, inspectable, zero‑side‑effect surface so agents deliver accurate, up‑to‑date guidance.

## 2. Scope

### Goals

- Trustworthy machine interface
- Read‑only, hostable
- Fast startup, low latency
- Clear extension & testing pattern

### Non‑Goals

- Performing installs / mutations
- Replacing human docs
- Re‑implementing conda‑forge processing logic

## 3. Design Principles

- Side‑effect free by contract
- Tool registration pattern (`conda_meta_mcp.tools`)
- Test + pre‑commit enforced consistency
- Incremental expansion

## 4. Installation

### Via pixi (recommended)

Install globally as a tool:

```shell
pixi global install conda-meta-mcp
```

Or add to your project:

```shell
pixi add conda-meta-mcp
```

### Via conda/mamba

```shell
conda install -c conda-forge conda-meta-mcp
```

Or with mamba/micromamba:

```shell
mamba install -c conda-forge conda-meta-mcp
```

### From source (development)

Prerequisites: [pixi](https://pixi.sh/latest/installation/)

```shell
git clone https://github.com/conda-incubator/conda-meta-mcp.git
cd conda-meta-mcp
pixi run cmm --help
```

## 5. Agent Setup

### Installed as conda package

Call `cmm mcp-json` to get an json snippet containing the command with args to add to your agent configuration.

### Installed from source

Call `pixi run cmm mcp-json` to get an json snippet containing the command with args to add to your agent configuration.

## 6. Usage inside GitHub Copilot coding agent

Create a GitHub workflow named `copilot-setup-steps.yml` containing (see also [GitHub Documentation](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment)):

```yaml
jobs:
  copilot-setup-steps:
    ...
    steps:
      ...
      - name: Setup conda-meta-mcp
        uses: conda-incubator/conda-meta-mcp@main
      ...
```

Add this MCP configuration inside your repository under Settings -> Copilot -> Coding agent -> MCP Configuration:

```json
{
  "mcpServers": {
    "conda-meta-mcp": {
      "type": "local",
      "command": "cmm",
      "args": [
        "run"
      ],
      "tools": [
        "*"
      ]
    }
  }
}
```

## 7. Development

Tasks (pixi):

- Tests: `pixi run test` (for coverage open `htmlcov/index.html`)
- Lint / format / type / regenerate metadata: `pixi run pre-commit`

## 8. Extending (New Tool)

1. Create `conda_meta_mcp/tools/<name>.py` with:

   ```python
   from .registry import register_tool

   @register_tool  # or @register_tool(cache_clearers=[...]) for custom cache clearers
   async def my_tool(...) -> dict:
       """Tool description (becomes MCP tool description)."""
       return await asyncio.to_thread(_helper_function, ...)
   ```

1. Add unit tests (mock heavy deps)

1. `pixi run prek`

1. `pixi run test`

1. Open PR

## 8. Safety Model

- No environment mutation
- No external command side effects
- Future additions must preserve read‑only contract