Metadata-Version: 2.4
Name: copernicus-mcp
Version: 0.1.2
Summary: MCP server for safe, validated, cost-aware access to Copernicus Earth observation data.
Author: Ivan Kuznetsov, CliDyn
License: BSD 3-Clause License
        
        Copyright (c) 2026, Ivan Kuznetsov
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: aiosqlite<1,>=0.20
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp<1.28,>=1.27.0
Requires-Dist: pydantic-settings<3,>=2.0
Requires-Dist: pydantic<3,>=2.0
Requires-Dist: python-dateutil<3,>=2.8
Requires-Dist: pyyaml<7,>=6
Requires-Dist: rich<14,>=13
Requires-Dist: typer<1,>=0.12
Provides-Extra: all
Requires-Dist: copernicusmarine<3,>=2.4; extra == 'all'
Provides-Extra: cmems
Requires-Dist: copernicusmarine<3,>=2.4; extra == 'cmems'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# copernicus-mcp

`copernicus-mcp` is a Model Context Protocol (MCP) server that gives LLM agents and CLI users safe, validated, cost-aware, reproducible access to Copernicus Earth observation data. It exposes discovery, estimation and subset-download workflows as MCP tools, returns large scientific data as file descriptors (filepath + metadata + provenance) rather than inline bytes, and produces a deterministic provenance record for every retrieval.

## Status

**Iteration 1 — Marine-first walking skeleton.** Iteration 1 ships the Copernicus Marine (CMEMS) backend through the official [`copernicusmarine`](https://help.marine.copernicus.eu/en/articles/7949409-copernicus-marine-toolbox-introduction) toolbox. Climate Data Store (CDS), Atmosphere Data Store (ADS), Early Warning Data Store (EWDS), Copernicus Data Space Ecosystem (CDSE), Sentinel Hub and WEkEO are planned for subsequent iterations and are explicitly out of scope for Iteration 1.

## Quick start

```bash
# 1. Create and activate a virtual environment.
python -m venv .venv && source .venv/bin/activate

# 2. Install the package with the CMEMS backend.
pip install "copernicus-mcp[cmems]"

# 3. Configure CMEMS credentials (free account at
#    https://data.marine.copernicus.eu/register).
#    Recommended — the toolbox writes the credentials file once:
copernicusmarine login
#    Alternative — environment variables in your shell profile:
# export COPERNICUSMARINE_SERVICE_USERNAME=your_user
# export COPERNICUSMARINE_SERVICE_PASSWORD=your_pass

# 4. Try a search from the terminal.
copernicus-mcp marine search-datasets --keyword temperature --limit 3

# 5. Run the MCP server (used by Claude Desktop / Claude Code / any
#    MCP-compatible client over stdio). See "Claude Desktop integration"
#    below.
copernicus-mcp serve
```

## Features

Iteration 1 implements the full MCP-core infrastructure so subsequent iterations add backends as small additive changes. Today the package provides:

- **Tools** (CMEMS): `marine_search_datasets`, `marine_describe_dataset`, `marine_estimate_subset`, `marine_subset_dataset`, plus a `copernicus_mcp_status` diagnostic.
- **Resources**: `copernicus://datasets/cmems/{id}`, `copernicus://files/{cache_key}`, `copernicus://provenance/{record_id}`.
- **CLI** (Typer + Rich): `copernicus-mcp {serve, version, status, marine ...}` with a global `--json` flag for scripting.
- **Confirmation flow**: large or approximate-estimate subsets gate on a structured confirmation prompt before any download.
- **Cache + provenance**: each retrieval produces a sidecar JSON record with file MD5, software versions, request envelope, and a deterministic cache key.
- **Sanitisation**: defence-in-depth redaction of credential-shaped strings on every outbound payload.
- **Structured errors**: eleven canonical error classes with recovery hints (e.g. `recovery_action="configure_credentials"`).
- **Cancellation discipline**: `asyncio.CancelledError` propagates without being wrapped, per project invariant.

## Why this exists

LLM agents can already call APIs, but for scientific data three properties matter and are easy to lose:

1. **Reproducibility** — the agent can hand a colleague the exact request and get the exact same file back tomorrow.
2. **Cost-awareness** — multi-gigabyte downloads should be confirmed, not silently triggered by a fuzzy prompt.
3. **Credential isolation** — credentials must never leak into tool output, logs, or provenance, regardless of the prompt or the upstream library's exception messages.

`copernicus-mcp` enforces all three at the protocol layer, so the agent does not need to.

## Tool reference, in brief

- **`marine_search_datasets`** (MCP tool) / `copernicus-mcp marine search-datasets` (CLI) — discover dataset ids by keyword, bbox, time range, or service type. Returns `{datasets, total_count}`.
- **`marine_describe_dataset`** / `marine describe DATASET_ID` — full metadata for a single dataset: variables, axes, services, terms.
- **`marine_estimate_subset`** / `marine estimate ...` — preview byte size and confirmation status for a subset request without downloading. Use this before large requests.
- **`marine_subset_dataset`** / `marine subset ...` — download a spatio-temporal subset. Returns `{filepath, uri, metadata, provenance}` — never inline bytes. Large requests gate on a structured confirmation prompt.
- **`copernicus_mcp_status`** / `status` — server diagnostics: backends, credential sources (without values), cache metrics, configuration snapshot.

For complete schemas, options and exit codes, run `copernicus-mcp marine subset --help` or read the inline tool descriptions surfaced by your MCP client (each tool's docstring is its protocol description).

## Claude Desktop integration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent on your platform:

```json
{
  "mcpServers": {
    "copernicus": {
      "command": "copernicus-mcp",
      "args": ["serve"]
    }
  }
}
```

Restart Claude Desktop. The five tools listed above become available to the assistant. Tool results that wrap large data return a `filepath` plus metadata and provenance — never inline bytes.

### Credentials

`copernicus-mcp` resolves CMEMS credentials in this precedence:

1. **Toolbox credentials file** (recommended): `~/.copernicusmarine/.copernicusmarine-credentials`. Created by running `copernicusmarine login` once. The same file is used by the official CLI and by us — set it once, share it across tools.
2. **Environment variables** in your shell profile: `COPERNICUSMARINE_SERVICE_USERNAME` and `COPERNICUSMARINE_SERVICE_PASSWORD`. Convenient on CI or in a project-local `direnv` setup.
3. (Possible but **not recommended** for the desktop client) `env: {...}` block inside `claude_desktop_config.json`. The file lives in plain text and gets backed up by macOS / cloud sync, so credentials embedded there leave a wider trace than necessary.

Verify resolution: `copernicus-mcp status --json | jq '.backends.cmems'`. The output reports `credential_source` as `config_file`, `env`, or `missing` — the actual values are never printed.

## Configuration

The system is usable with no configuration file at all — every Pydantic field has a sensible default. Override via environment variables (`COPERNICUS_MCP_LOG_LEVEL`, `COPERNICUS_MCP_CACHE_DIR`, `COPERNICUS_MCP_STATE_DB`, plus `COPERNICUS_MCP_<SECTION>__<FIELD>` for nested fields), or with a YAML file at `~/.config/copernicus-mcp/config.yaml` or `~/.copernicus-mcp.yaml`.

State directories: `~/.cache/copernicus-mcp/` (downloaded files + `.provenance.json` sidecars), `~/.local/state/copernicus-mcp/state.db` (SQLite cache index, workflow rows, persisted provenance).

## Troubleshooting

- **`AuthError`** on tool call → run `copernicus-mcp status` and check `backends.cmems.configured`. If `false`, your env vars are not visible to the running process (common Claude Desktop pitfall — restart the client after editing config) or the credentials file is missing/unreadable.
- **`CoverageUnavailableError`** → bbox or time range is outside the dataset's actual extent. Use `marine_describe_dataset` to inspect coverage and narrow the request.
- **`ValidationError` with `recovery_action="modify_request_parameters"`** → request was structurally invalid (e.g. inverted bbox, antimeridian-crossing bbox, naive datetime). The `next_action_hint` field tells you exactly how to fix it.
- **Subset hangs** → set `COPERNICUS_MCP_LOG_LEVEL=DEBUG` and watch for retry messages. Reduce bbox or time range if request is genuinely large.

## License

BSD 3-Clause. See [`LICENSE`](LICENSE). Dependencies are EUPL-1.2 (`copernicusmarine`), Apache-2.0, MIT or BSD. Iteration 1 does not depend on `sentinelhub-py`; when the Sentinel Hub backend lands in a later iteration, this section will document the relevant CC BY-NC restriction on its SDK.

## Acknowledgements

- [Mercator Ocean International](https://www.mercator-ocean.eu/) for the [`copernicusmarine`](https://github.com/mercator-ocean/copernicus-marine-toolbox) Python toolbox.
- The [Copernicus Marine Service](https://marine.copernicus.eu/) and the European Commission's Copernicus programme for the underlying data.
- The Anthropic team for the [Model Context Protocol](https://modelcontextprotocol.io/) specification and Python SDK.
