copernicus-mcp 0.1.2__tar.gz

copernicus_mcp-0.1.2/.gitignore

@@ -0,0 +1,49 @@
+openai/
+claude/
+plan/
+
+# Secrets — never commit
+.env
+.env.local
+.env.*.local
+.envrc
+!.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+
+# Venvs
+.venv/
+venv/
+env/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Project runtime artifacts
+.cache/
+*.db
+*.sqlite
+*.sqlite3
+
+# NB: *.provenance.json is intentionally NOT ignored — provenance sidecars
+# are user-facing artifacts.
+.mcp.json

copernicus_mcp-0.1.2/LICENSE

@@ -0,0 +1,28 @@
+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.

copernicus_mcp-0.1.2/PKG-INFO

@@ -0,0 +1,173 @@
+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.

copernicus_mcp-0.1.2/README.md

@@ -0,0 +1,116 @@
+# 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.

copernicus_mcp-0.1.2/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "copernicus-mcp"
+description = "MCP server for safe, validated, cost-aware access to Copernicus Earth observation data."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Ivan Kuznetsov" },
+    { name = "CliDyn" },
+]
+dynamic = ["version"]
+dependencies = [
+    "mcp>=1.27.0,<1.28",
+    "httpx>=0.27,<1",
+    "pydantic>=2.0,<3",
+    "pydantic-settings>=2.0,<3",
+    "pyyaml>=6,<7",
+    "typer>=0.12,<1",
+    "rich>=13,<14",
+    "aiosqlite>=0.20,<1",
+    "python-dateutil>=2.8,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=4",
+    "pytest-timeout>=2.3",
+    "ruff>=0.5",
+    "mypy>=1.10",
+]
+cmems = ["copernicusmarine>=2.4,<3"]
+all = ["copernicus-mcp[cmems]"]
+
+[project.scripts]
+copernicus-mcp = "copernicus_mcp.cli:app"
+
+[tool.hatch.version]
+path = "src/copernicus_mcp/version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/copernicus_mcp"]
+
+[tool.hatch.build.targets.sdist]
+# Ship ONLY the source tree, packaging metadata, README and LICENSE.
+# Internal docs, research notes, plans, spikes, IDE config and
+# example dotenv files do not belong on PyPI.
+include = [
+    "/src/copernicus_mcp/**",
+    "/pyproject.toml",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "W"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.11"
+ignore_missing_imports = true

copernicus_mcp-0.1.2/src/copernicus_mcp/__init__.py

@@ -0,0 +1,3 @@
+from copernicus_mcp.version import __version__
+
+__all__ = ["__version__"]

copernicus_mcp-0.1.2/src/copernicus_mcp/__main__.py

@@ -0,0 +1,12 @@
+"""Allow ``python -m copernicus_mcp ...`` to invoke the Typer CLI.
+
+The installed console script ``copernicus-mcp`` (defined in
+``pyproject.toml``) is the primary entrypoint; this module exists so
+tests and tooling that use ``-m`` (without relying on PATH) reach the
+same app.
+"""
+
+from copernicus_mcp.cli import app
+
+if __name__ == "__main__":
+    app()

copernicus_mcp-0.1.2/src/copernicus_mcp/auth/__init__.py

@@ -0,0 +1,17 @@
+from copernicus_mcp.auth.adapter import AuthAdapter
+from copernicus_mcp.auth.cmems import CmemsBasicAuthAdapter
+from copernicus_mcp.auth.resolver import (
+    CredentialResolver,
+    CredentialSource,
+    ResolvedCredentials,
+    SecretManagerProvider,
+)
+
+__all__ = [
+    "AuthAdapter",
+    "CmemsBasicAuthAdapter",
+    "CredentialResolver",
+    "CredentialSource",
+    "ResolvedCredentials",
+    "SecretManagerProvider",
+]

copernicus_mcp-0.1.2/src/copernicus_mcp/auth/adapter.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Protocol
+
+import httpx
+
+
+class AuthAdapter(Protocol):
+    """Backend-specific authorization handler.
+
+    Concrete adapters live next to their backend (e.g. ``CmemsBasicAuthAdapter``).
+    Implementations must not log credential values; ``credentials_summary``
+    is the only public introspection surface and returns ``<set>`` / ``<unset>``
+    placeholders only.
+
+    See ``research/08_auth_matrix.md`` §9.6 for the canonical protocol shape.
+    """
+
+    backend_id: str
+    supports_refresh: bool
+
+    async def apply_credentials(
+        self, request: httpx.Request
+    ) -> httpx.Request: ...
+
+    async def handle_unauthorized(self, response: httpx.Response) -> bool:
+        """Return ``True`` if a retry should be attempted after re-auth."""
+        ...
+
+    async def close(self) -> None: ...
+
+    def credentials_summary(self) -> Mapping[str, str]: ...

copernicus_mcp-0.1.2/src/copernicus_mcp/auth/cmems.py

@@ -0,0 +1,88 @@
+"""CMEMS basic-auth adapter.
+
+This module is the **only** in-process exit point for raw CMEMS credential
+values, via ``CmemsBasicAuthAdapter.get_username_password()``. The CMEMS
+backend layer calls that method during initialization to hand the values to
+the ``copernicusmarine`` toolbox; nothing else may.
+
+CLAUDE.md invariant #2: credentials live in ``CredentialResolver`` and
+``AuthAdapter`` instances only — never tool input/output, logs, cache keys,
+provenance records, or error records.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+
+import httpx
+
+from copernicus_mcp.auth.resolver import ResolvedCredentials
+
+_REDACTED_SUMMARY: Mapping[str, str] = MappingProxyType(
+    {"username": "<set>", "password": "<set>"}
+)
+
+
+class CmemsBasicAuthAdapter:
+    """Static-credential adapter for CMEMS.
+
+    The ``copernicusmarine`` toolbox performs HTTP-level auth itself, so
+    ``apply_credentials`` is a no-op and our ``httpx`` client never sees
+    these credentials. The backend layer pulls username/password via
+    ``get_username_password`` during construction and passes them to the
+    toolbox.
+    """
+
+    backend_id: str = "cmems"
+    supports_refresh: bool = False
+
+    def __init__(self, credentials: ResolvedCredentials) -> None:
+        if credentials.backend != "cmems":
+            # Do not echo the rejected backend value — defense in depth in
+            # case it is ever something secret-shaped.
+            raise ValueError(
+                "CmemsBasicAuthAdapter requires credentials for backend 'cmems'."
+            )
+        if credentials.source == "missing":
+            raise ValueError("CmemsBasicAuthAdapter requires resolved credentials.")
+        username = credentials.fields.get("username", "")
+        password = credentials.fields.get("password", "")
+        if not username or not password:
+            raise ValueError(
+                "CmemsBasicAuthAdapter requires non-empty 'username' and "
+                "'password' credential fields."
+            )
+        self._username = username
+        self._password = password
+        self._closed = False
+
+    async def apply_credentials(self, request: httpx.Request) -> httpx.Request:
+        # CMEMS toolbox handles HTTP-level auth itself; nothing to apply here.
+        return request
+
+    async def handle_unauthorized(self, response: httpx.Response) -> bool:
+        # Static basic auth has no refreshable state.
+        return False
+
+    async def close(self) -> None:
+        # Idempotent — nothing to release.
+        self._closed = True
+
+    def credentials_summary(self) -> Mapping[str, str]:
+        return _REDACTED_SUMMARY
+
+    def get_username_password(self) -> tuple[str, str]:
+        """Return raw ``(username, password)`` for the in-process backend layer.
+
+        SENSITIVE: this is the **only** authorised exit point for raw CMEMS
+        credentials. Must never be exposed through MCP tool results, logs,
+        cache keys, provenance, or error messages.
+        """
+        return self._username, self._password
+
+    def __repr__(self) -> str:
+        return (
+            f"CmemsBasicAuthAdapter(backend_id={self.backend_id!r}, "
+            f"supports_refresh={self.supports_refresh!r})"
+        )