ncbi-datasets-mcp 0.1.0__tar.gz

ncbi_datasets_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,90 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Nightly at 06:00 UTC — runs integration tests against live NCBI API
+    - cron: "0 6 * * *"
+  workflow_dispatch:
+    inputs:
+      run_integration:
+        description: "Run integration tests against live NCBI API"
+        type: boolean
+        default: false
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+
+  unit-tests:
+    name: Unit tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Run unit tests
+        run: pytest tests/unit/ -v --tb=short
+
+  integration-tests:
+    name: Integration tests (live NCBI API)
+    runs-on: ubuntu-latest
+    # Only run on schedule or manual trigger — not on every push/PR
+    if: |
+      github.event_name == 'schedule' ||
+      github.event.inputs.run_integration == 'true'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Run integration tests
+        run: pytest -m integration -v --tb=short
+        env:
+          # Optional: add NCBI_API_KEY as a repo secret for higher rate limits
+          NCBI_API_KEY: ${{ secrets.NCBI_API_KEY }}
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: unit-tests
+    # Only publish on version tags pushed to main
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/project/ncbi-datasets-mcp/
+    permissions:
+      id-token: write  # Required for trusted publishing (no token needed)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

ncbi_datasets_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] — Initial release
+
+### Added
+- `ensure_cli` tool: detect and auto-install `datasets`/`dataformat` binaries from NCBI FTP
+- `genome_summary_by_taxon`: search genome assemblies by organism name or tax ID (REST)
+- `genome_summary_by_accession`: fetch metadata for known accessions (REST)
+- `genome_download_by_taxon`: download genome packages by taxon (CLI)
+- `genome_download_by_accession`: download genome packages by accession (CLI)
+- `rehydrate_genome_package`: fetch sequence files for dehydrated packages (CLI)
+- `dataformat_genome_tsv`: convert genome JSONL data reports to TSV (CLI)
+- `taxonomy_summary`: get lineage, rank, and names for a taxon (REST)
+- `taxonomy_download`: download taxonomy packages (CLI)
+- Desktop Extension manifest (`.mcpb`) with `NCBI_AUTO_INSTALL=true` default
+- `scripts/gen_enums.py` to regenerate enums from the live NCBI OpenAPI spec
+- `scripts/build_mcpb.py` to produce a distributable `.mcpb` bundle
+- GitHub Actions CI: lint, unit test matrix (Python 3.10–3.12), nightly integration tests, PyPI trusted publish on tag

ncbi_datasets_mcp-0.1.0/LICENSE

@@ -0,0 +1 @@
+MIT License

ncbi_datasets_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: ncbi-datasets-mcp
+Version: 0.1.0
+Summary: MCP server for NCBI Datasets — search metadata and download genomic data
+Author-email: John Torcivia <jtorcivia@gmail.com>
+License: MIT License
+License-File: LICENSE
+Keywords: bioinformatics,datasets,genomics,mcp,ncbi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.9.0
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: tenacity>=8.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ncbi-datasets-mcp
+NOTE: This is not affiliated with NCBI or NCBI Datasets, this is a user provided tool.
+
+An MCP server that gives Claude access to [NCBI Datasets v2](https://www.ncbi.nlm.nih.gov/datasets/docs/v2/) — search genome assembly metadata, retrieve taxonomy records, and download data packages without leaving your conversation.
+
+## Tools
+
+| Tool | Transport | Description |
+|------|-----------|-------------|
+| `ensure_cli` | — | Install the NCBI CLI tools (run once, or set `NCBI_AUTO_INSTALL=true`) |
+| `genome_summary_by_taxon` | REST | Search genome assemblies by organism name or tax ID |
+| `genome_summary_by_accession` | REST | Fetch assembly metadata for known accessions |
+| `genome_download_by_taxon` | CLI | Download a genome package by taxon |
+| `genome_download_by_accession` | CLI | Download a genome package by accession |
+| `rehydrate_genome_package` | CLI | Fetch sequence files for a dehydrated package |
+| `dataformat_genome_tsv` | CLI | Convert a genome JSONL data report to TSV |
+| `taxonomy_summary` | REST | Get lineage, rank, and names for a taxon |
+| `taxonomy_download` | CLI | Download a taxonomy package |
+
+## Installation
+
+### Option 1 — Desktop Extension (recommended for Claude Desktop users)
+
+1. Download `ncbi-datasets.mcpb` from the [Releases](../../releases) page.
+2. Double-click the file and click **Install** in Claude Desktop.
+3. Optionally enter your [NCBI API key](https://www.ncbi.nlm.nih.gov/account/) and download directory.
+
+The NCBI CLI tools are downloaded automatically on first use (`NCBI_AUTO_INSTALL=true` is set by default in the extension).
+
+### Option 2 — JSON config (Claude Desktop / Claude Code)
+
+Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ncbi-datasets": {
+      "command": "uvx",
+      "args": ["ncbi-datasets-mcp"],
+      "env": {
+        "NCBI_API_KEY": "your_key_here",
+        "NCBI_DOWNLOAD_DIR": "/path/to/downloads",
+        "NCBI_AUTO_INSTALL": "true"
+      }
+    }
+  }
+}
+```
+
+Requires [uv](https://docs.astral.sh/uv/getting-started/installation/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`).
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NCBI_API_KEY` | *(none)* | NCBI API key — raises rate limit to 10 req/s |
+| `NCBI_DOWNLOAD_DIR` | `~/Downloads/ncbi_datasets` | Default download location |
+| `NCBI_AUTO_INSTALL` | `false` | Auto-install CLI tools on startup |
+| `NCBI_MAX_RESULTS` | `20` | Cap for summary tool result counts |
+| `NCBI_REQUEST_TIMEOUT` | `300` | Seconds before a download times out |
+| `NCBI_CLI_PATH` | *(auto)* | Override path to `datasets` binary |
+| `NCBI_DATAFORMAT_PATH` | *(auto)* | Override path to `dataformat` binary |
+
+## Development
+
+```bash
+# Install with dev extras
+pip install -e ".[dev]"
+
+# Run unit tests
+pytest
+
+# Run all tests including live network calls
+pytest -m integration
+
+# Regenerate enums from the current NCBI OpenAPI spec
+python scripts/gen_enums.py
+
+# Run the server locally (stdio transport)
+ncbi-datasets-mcp
+```
+
+## Architecture
+
+```
+src/ncbi_datasets_mcp/
+  server.py           FastMCP app — tool registrations only
+  config.py           Pydantic-settings env config
+  cli/
+    locator.py        Find datasets/dataformat (config → PATH → cache)
+    installer.py      Download binaries from NCBI FTP
+    runner.py         Async subprocess wrapper
+  rest/
+    client.py         httpx client for metadata/summary endpoints
+  domains/
+    _generated_enums.py  Vendored enums from OpenAPI spec
+    common.py         Shared utilities (output dir, filename sanitising)
+    genome.py         Genome CLI arg builders + response shaping
+    taxonomy.py       Taxonomy CLI arg builders
+  models/
+    responses.py      Shared DownloadResult dataclass
+```
+
+Summary tools (no file I/O) → REST API.  
+Download and format-conversion tools → NCBI CLI binaries.
+
+## Cite
+
+If you use NCBI Datasets in your research, please cite:
+> NCBI Datasets. National Center for Biotechnology Information. https://www.ncbi.nlm.nih.gov/datasets/
+
+## License
+
+MIT

ncbi_datasets_mcp-0.1.0/README.md

@@ -0,0 +1,114 @@
+# ncbi-datasets-mcp
+NOTE: This is not affiliated with NCBI or NCBI Datasets, this is a user provided tool.
+
+An MCP server that gives Claude access to [NCBI Datasets v2](https://www.ncbi.nlm.nih.gov/datasets/docs/v2/) — search genome assembly metadata, retrieve taxonomy records, and download data packages without leaving your conversation.
+
+## Tools
+
+| Tool | Transport | Description |
+|------|-----------|-------------|
+| `ensure_cli` | — | Install the NCBI CLI tools (run once, or set `NCBI_AUTO_INSTALL=true`) |
+| `genome_summary_by_taxon` | REST | Search genome assemblies by organism name or tax ID |
+| `genome_summary_by_accession` | REST | Fetch assembly metadata for known accessions |
+| `genome_download_by_taxon` | CLI | Download a genome package by taxon |
+| `genome_download_by_accession` | CLI | Download a genome package by accession |
+| `rehydrate_genome_package` | CLI | Fetch sequence files for a dehydrated package |
+| `dataformat_genome_tsv` | CLI | Convert a genome JSONL data report to TSV |
+| `taxonomy_summary` | REST | Get lineage, rank, and names for a taxon |
+| `taxonomy_download` | CLI | Download a taxonomy package |
+
+## Installation
+
+### Option 1 — Desktop Extension (recommended for Claude Desktop users)
+
+1. Download `ncbi-datasets.mcpb` from the [Releases](../../releases) page.
+2. Double-click the file and click **Install** in Claude Desktop.
+3. Optionally enter your [NCBI API key](https://www.ncbi.nlm.nih.gov/account/) and download directory.
+
+The NCBI CLI tools are downloaded automatically on first use (`NCBI_AUTO_INSTALL=true` is set by default in the extension).
+
+### Option 2 — JSON config (Claude Desktop / Claude Code)
+
+Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ncbi-datasets": {
+      "command": "uvx",
+      "args": ["ncbi-datasets-mcp"],
+      "env": {
+        "NCBI_API_KEY": "your_key_here",
+        "NCBI_DOWNLOAD_DIR": "/path/to/downloads",
+        "NCBI_AUTO_INSTALL": "true"
+      }
+    }
+  }
+}
+```
+
+Requires [uv](https://docs.astral.sh/uv/getting-started/installation/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`).
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NCBI_API_KEY` | *(none)* | NCBI API key — raises rate limit to 10 req/s |
+| `NCBI_DOWNLOAD_DIR` | `~/Downloads/ncbi_datasets` | Default download location |
+| `NCBI_AUTO_INSTALL` | `false` | Auto-install CLI tools on startup |
+| `NCBI_MAX_RESULTS` | `20` | Cap for summary tool result counts |
+| `NCBI_REQUEST_TIMEOUT` | `300` | Seconds before a download times out |
+| `NCBI_CLI_PATH` | *(auto)* | Override path to `datasets` binary |
+| `NCBI_DATAFORMAT_PATH` | *(auto)* | Override path to `dataformat` binary |
+
+## Development
+
+```bash
+# Install with dev extras
+pip install -e ".[dev]"
+
+# Run unit tests
+pytest
+
+# Run all tests including live network calls
+pytest -m integration
+
+# Regenerate enums from the current NCBI OpenAPI spec
+python scripts/gen_enums.py
+
+# Run the server locally (stdio transport)
+ncbi-datasets-mcp
+```
+
+## Architecture
+
+```
+src/ncbi_datasets_mcp/
+  server.py           FastMCP app — tool registrations only
+  config.py           Pydantic-settings env config
+  cli/
+    locator.py        Find datasets/dataformat (config → PATH → cache)
+    installer.py      Download binaries from NCBI FTP
+    runner.py         Async subprocess wrapper
+  rest/
+    client.py         httpx client for metadata/summary endpoints
+  domains/
+    _generated_enums.py  Vendored enums from OpenAPI spec
+    common.py         Shared utilities (output dir, filename sanitising)
+    genome.py         Genome CLI arg builders + response shaping
+    taxonomy.py       Taxonomy CLI arg builders
+  models/
+    responses.py      Shared DownloadResult dataclass
+```
+
+Summary tools (no file I/O) → REST API.  
+Download and format-conversion tools → NCBI CLI binaries.
+
+## Cite
+
+If you use NCBI Datasets in your research, please cite:
+> NCBI Datasets. National Center for Biotechnology Information. https://www.ncbi.nlm.nih.gov/datasets/
+
+## License
+
+MIT

ncbi_datasets_mcp-0.1.0/build_mcpb.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Build ncbi-datasets.mcpb — a Claude Desktop Extension bundle.
+
+The .mcpb is a ZIP archive containing manifest.json plus any bundled assets.
+For this Python server, the manifest points to `uvx ncbi-datasets-mcp`, so
+the archive only needs the manifest (and optional icon). The Python package
+itself is fetched from PyPI by uvx at install time.
+
+Usage:
+    python scripts/build_mcpb.py [--version VERSION] [--out DIR]
+
+Requires: an icon at assets/icon.png (optional but recommended for the registry)
+"""
+
+import argparse
+import json
+import shutil
+import sys
+import zipfile
+from pathlib import Path
+
+ROOT = Path(__file__).parent.parent
+
+
+def load_manifest() -> dict:
+    manifest_path = ROOT / "manifest.json"
+    with manifest_path.open() as fh:
+        return json.load(fh)
+
+
+def sync_version(manifest: dict, version: str) -> dict:
+    """Keep manifest version in sync with pyproject.toml version."""
+    manifest = manifest.copy()
+    manifest["version"] = version
+    return manifest
+
+
+def build(version: str | None, out_dir: Path) -> Path:
+    manifest = load_manifest()
+
+    if version:
+        manifest = sync_version(manifest, version)
+    else:
+        version = manifest.get("version", "0.0.0")
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    bundle_path = out_dir / f"ncbi-datasets-{version}.mcpb"
+
+    with zipfile.ZipFile(bundle_path, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        # manifest.json is the only required file
+        zf.writestr("manifest.json", json.dumps(manifest, indent=2))
+
+        # Optional icon
+        icon_path = ROOT / "assets" / "icon.png"
+        if icon_path.exists():
+            zf.write(icon_path, "icon.png")
+            print(f"  + icon.png")
+        else:
+            print(
+                "  (no assets/icon.png found — bundle will work but won't show an icon)",
+                file=sys.stderr,
+            )
+
+    size_kb = bundle_path.stat().st_size // 1024
+    print(f"Built {bundle_path} ({size_kb} KB)")
+    return bundle_path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Build ncbi-datasets.mcpb")
+    parser.add_argument("--version", help="Override version (default: from manifest.json)")
+    parser.add_argument("--out", default="dist", help="Output directory (default: dist/)")
+    args = parser.parse_args()
+
+    bundle_path = build(version=args.version, out_dir=Path(args.out))
+    print(f"\nTo install: double-click {bundle_path.name} in Finder/Explorer")
+    print(f"Or: open Claude Desktop → Settings → Extensions → Install from file")
+
+
+if __name__ == "__main__":
+    main()

ncbi_datasets_mcp-0.1.0/ci.yml

@@ -0,0 +1,90 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Nightly at 06:00 UTC — runs integration tests against live NCBI API
+    - cron: "0 6 * * *"
+  workflow_dispatch:
+    inputs:
+      run_integration:
+        description: "Run integration tests against live NCBI API"
+        type: boolean
+        default: false
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+
+  unit-tests:
+    name: Unit tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Run unit tests
+        run: pytest tests/unit/ -v --tb=short
+
+  integration-tests:
+    name: Integration tests (live NCBI API)
+    runs-on: ubuntu-latest
+    # Only run on schedule or manual trigger — not on every push/PR
+    if: |
+      github.event_name == 'schedule' ||
+      github.event.inputs.run_integration == 'true'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Run integration tests
+        run: pytest -m integration -v --tb=short
+        env:
+          # Optional: add NCBI_API_KEY as a repo secret for higher rate limits
+          NCBI_API_KEY: ${{ secrets.NCBI_API_KEY }}
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: unit-tests
+    # Only publish on version tags pushed to main
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/project/ncbi-datasets-mcp/
+    permissions:
+      id-token: write  # Required for trusted publishing (no token needed)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

ncbi_datasets_mcp-0.1.0/installer.py

@@ -0,0 +1,110 @@
+"""Download the NCBI datasets/dataformat CLI binaries for the current platform.
+
+Binaries are single static files published by NCBI at predictable FTP URLs:
+  https://ftp.ncbi.nlm.nih.gov/pub/datasets/command-line/v2/{platform}/{binary}
+"""
+
+import asyncio
+import platform
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+
+from ncbi_datasets_mcp.cli.locator import CLIBinaries, _exe, get_install_dir
+
+FTP_BASE = "https://ftp.ncbi.nlm.nih.gov/pub/datasets/command-line/v2"
+
+# Maps (system, machine) → NCBI FTP platform path
+_PLATFORM_MAP: dict[tuple[str, str], str] = {
+    ("Linux", "x86_64"): "linux-amd64",
+    ("Linux", "aarch64"): "linux-arm64",
+    ("Linux", "armv7l"): "linux-arm",
+    ("Darwin", "x86_64"): "mac",
+    ("Darwin", "arm64"): "mac",   # Universal binary covers Apple Silicon
+    ("Windows", "AMD64"): "win64",
+    ("Windows", "x86_64"): "win64",
+}
+
+
+@dataclass
+class InstallResult:
+    success: bool
+    datasets_path: Path | None = None
+    dataformat_path: Path | None = None
+    version: str | None = None
+    message: str = ""
+
+
+def detect_platform() -> str:
+    """Return the NCBI FTP sub-path for the current OS/arch, or raise."""
+    system = platform.system()
+    machine = platform.machine()
+    key = (system, machine)
+    if key in _PLATFORM_MAP:
+        return _PLATFORM_MAP[key]
+    raise RuntimeError(
+        f"Unsupported platform: {system}/{machine}. "
+        "Install manually: "
+        "https://www.ncbi.nlm.nih.gov/datasets/docs/v2/command-line-tools/download-and-install/"
+    )
+
+
+async def _download_binary(url: str, dest: Path, client: httpx.AsyncClient) -> None:
+    """Stream a binary from *url* to *dest*, then mark it executable."""
+    async with client.stream("GET", url) as response:
+        response.raise_for_status()
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        with dest.open("wb") as fh:
+            async for chunk in response.aiter_bytes(chunk_size=65_536):
+                fh.write(chunk)
+
+    if platform.system() != "Windows":
+        dest.chmod(dest.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+
+
+async def install_cli() -> InstallResult:
+    """Download both binaries into the managed cache dir and verify them."""
+    try:
+        platform_path = detect_platform()
+    except RuntimeError as exc:
+        return InstallResult(success=False, message=str(exc))
+
+    install_dir = get_install_dir()
+    datasets_dest = install_dir / _exe("datasets")
+    dataformat_dest = install_dir / _exe("dataformat")
+
+    datasets_url = f"{FTP_BASE}/{platform_path}/{_exe('datasets')}"
+    dataformat_url = f"{FTP_BASE}/{platform_path}/{_exe('dataformat')}"
+
+    async with httpx.AsyncClient(follow_redirects=True, timeout=120.0) as client:
+        try:
+            await _download_binary(datasets_url, datasets_dest, client)
+            await _download_binary(dataformat_url, dataformat_dest, client)
+        except httpx.HTTPError as exc:
+            return InstallResult(success=False, message=f"Download failed: {exc}")
+
+    # Smoke-test: run --version on the freshly installed binary
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            str(datasets_dest),
+            "--version",
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=15.0)
+        version = stdout.decode().strip()
+    except Exception as exc:
+        return InstallResult(
+            success=False,
+            message=f"Binary installed but verification failed: {exc}",
+        )
+
+    return InstallResult(
+        success=True,
+        datasets_path=datasets_dest,
+        dataformat_path=dataformat_dest,
+        version=version,
+        message=f"Installed {version} → {install_dir}",
+    )