scigantic-mcp 0.1.0__tar.gz

scigantic_mcp-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+MIT No Attribution
+
+Copyright Scigantic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

scigantic_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: scigantic-mcp
+Version: 0.1.0
+Summary: MCP server for the Scigantic catalog of public scientific data archives, with LLM-ready schema cards
+Author: Scigantic
+License: MIT-0
+Project-URL: Homepage, https://scigantic.com
+Project-URL: Documentation, https://scigantic.com/blog/scigantic-mcp-server
+Keywords: mcp,model-context-protocol,datasets,open-data,schema-card,bioinformatics,earth-observation
+Classifier: License :: OSI Approved :: MIT No Attribution License (MIT-0)
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<3,>=2
+Requires-Dist: httpx>=0.27
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Dynamic: license-file
+
+# scigantic-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes the
+**Scigantic catalog of public scientific data archives** to any MCP client.
+
+It is built to drop into **[Kiro for Life Sciences](https://github.com/aws-samples/sample-kiro-power-life-sciences)**
+alongside its domain database servers. Where each Kiro server wraps one domain's
+APIs (genomics, proteomics, structural, …), Scigantic is the **cross-domain
+launchpad**: 5,000+ curated public archives spanning every domain, each with an
+LLM-ready **schema card** (file format, columns, sample rows/headers, inlined
+READMEs/data dictionaries, and a copy-paste starter cell) so an agent can
+understand a dataset's structure *before* downloading anything.
+
+It is **discovery-only and zero-config** — every tool calls public, read-only
+Scigantic endpoints, so there is no API key to set up.
+
+Requires Python 3.10+ and MCP SDK 2.x.
+
+> **Prefer the hosted server if your client speaks HTTP.** Scigantic also runs a
+> remote MCP server at `https://api.scigantic.com/mcp` (no auth, nothing to
+> install, and it carries two extra tools):
+> `claude mcp add --transport http scigantic https://api.scigantic.com/mcp`.
+> This package exists for clients that launch **stdio** servers, such as Kiro.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `search_archives(query, category?, limit?)` | Natural-language search across the whole catalog. |
+| `get_archive(id)` | Full metadata for one archive. |
+| `get_schema_card(id)` | The compact schema card — the fastest way to learn a dataset's structure. |
+| `get_data_access(id, language?)` | How to load the dataset in **your own** environment: storage location + copy-paste code snippets. |
+| `list_archive_files(id, limit?)` | A sample of the files/objects in the archive. |
+
+## Prompts (guided workflows)
+
+These surface as slash commands in Claude Code (`/mcp__scigantic__<name>`):
+
+| Prompt | What it does |
+|--------|--------------|
+| `explore_dataset(topic)` | Search → inspect schema cards → recommend the best dataset → offer load code. |
+| `start_analysis(archive_id, goal?)` | Pull schema card + data-access snippet for an archive and outline an analysis plan. |
+
+## Install & register in Kiro
+
+Add an entry under `mcpServers` in `~/.kiro/settings/mcp.json`.
+
+**Option A — `uvx` (zero-install, recommended):**
+
+```json
+{
+  "mcpServers": {
+    "scigantic": {
+      "command": "uvx",
+      "args": ["scigantic-mcp"]
+    }
+  }
+}
+```
+
+**Option B — install into a venv (matches the Kiro servers' own mcp.json form):**
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install scigantic-mcp                 # or: pip install /path/to/scigantic-mcp
+```
+
+```json
+{
+  "mcpServers": {
+    "scigantic": {
+      "command": "/path/to/.venv/bin/scigantic-mcp",
+      "env": {
+        "SCIGANTIC_API_URL": "https://api.scigantic.com"
+      }
+    }
+  }
+}
+```
+
+Works the same in Claude Desktop / Claude Code (`claude mcp add scigantic -- uvx scigantic-mcp`)
+or any MCP client that launches stdio servers.
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `SCIGANTIC_API_URL` | `https://api.scigantic.com` | API base (set to `https://staging-api.scigantic.com` for staging). |
+| `SCIGANTIC_API_ORIGIN` | `https://scigantic.com` | Origin header → selects the public (default) catalog tenant. |
+
+## Develop & test
+
+The tool/client layer has no `mcp` dependency, so those tests run on any Python
+with `httpx` and need no network (mocked transport):
+
+```bash
+python3 tests/test_tools.py     # or: pytest
+```
+
+`tests/test_server_import.py` covers the wiring layer — that the server module
+imports, and that the registered tools and prompts are the expected set. It needs
+the `mcp` SDK installed (Python ≥ 3.10) and is skipped otherwise:
+
+```bash
+pip install -e '.[test]' && pytest
+```
+
+Keep it that way: the tool tests skip `server.py` on purpose, so an SDK breaking
+change is invisible to them. All 12 passed while the server could not import at
+all under SDK 2.x, which is what `test_server_import.py` now guards against.
+
+## Roadmap
+
+- **Richer discovery for agents** — structured tool outputs and MCP *resources*
+  (attach an archive + its schema card as durable context).
+- Upstream inclusion as `life-sciences-scigantic` in `aws-samples/sample-kiro-power-life-sciences`
+  (see `docs/kiro-upstream-pr.md`).
+- **Hosted compute is intentionally not exposed here.** Scigantic's notebooks are
+  interactive (a JupyterLab URL a human opens); handing an external agent that URL
+  is a dead end. The agent-to-agent path is `get_data_access` — the caller runs the
+  analysis in its own environment. Letting Scigantic *execute code for* an agent
+  (run against an ephemeral kernel with the dataset mounted, return outputs) is a
+  separate capability the platform would need to build first.
+
+## License
+
+MIT-0.

scigantic_mcp-0.1.0/README.md

@@ -0,0 +1,127 @@
+# scigantic-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes the
+**Scigantic catalog of public scientific data archives** to any MCP client.
+
+It is built to drop into **[Kiro for Life Sciences](https://github.com/aws-samples/sample-kiro-power-life-sciences)**
+alongside its domain database servers. Where each Kiro server wraps one domain's
+APIs (genomics, proteomics, structural, …), Scigantic is the **cross-domain
+launchpad**: 5,000+ curated public archives spanning every domain, each with an
+LLM-ready **schema card** (file format, columns, sample rows/headers, inlined
+READMEs/data dictionaries, and a copy-paste starter cell) so an agent can
+understand a dataset's structure *before* downloading anything.
+
+It is **discovery-only and zero-config** — every tool calls public, read-only
+Scigantic endpoints, so there is no API key to set up.
+
+Requires Python 3.10+ and MCP SDK 2.x.
+
+> **Prefer the hosted server if your client speaks HTTP.** Scigantic also runs a
+> remote MCP server at `https://api.scigantic.com/mcp` (no auth, nothing to
+> install, and it carries two extra tools):
+> `claude mcp add --transport http scigantic https://api.scigantic.com/mcp`.
+> This package exists for clients that launch **stdio** servers, such as Kiro.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `search_archives(query, category?, limit?)` | Natural-language search across the whole catalog. |
+| `get_archive(id)` | Full metadata for one archive. |
+| `get_schema_card(id)` | The compact schema card — the fastest way to learn a dataset's structure. |
+| `get_data_access(id, language?)` | How to load the dataset in **your own** environment: storage location + copy-paste code snippets. |
+| `list_archive_files(id, limit?)` | A sample of the files/objects in the archive. |
+
+## Prompts (guided workflows)
+
+These surface as slash commands in Claude Code (`/mcp__scigantic__<name>`):
+
+| Prompt | What it does |
+|--------|--------------|
+| `explore_dataset(topic)` | Search → inspect schema cards → recommend the best dataset → offer load code. |
+| `start_analysis(archive_id, goal?)` | Pull schema card + data-access snippet for an archive and outline an analysis plan. |
+
+## Install & register in Kiro
+
+Add an entry under `mcpServers` in `~/.kiro/settings/mcp.json`.
+
+**Option A — `uvx` (zero-install, recommended):**
+
+```json
+{
+  "mcpServers": {
+    "scigantic": {
+      "command": "uvx",
+      "args": ["scigantic-mcp"]
+    }
+  }
+}
+```
+
+**Option B — install into a venv (matches the Kiro servers' own mcp.json form):**
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install scigantic-mcp                 # or: pip install /path/to/scigantic-mcp
+```
+
+```json
+{
+  "mcpServers": {
+    "scigantic": {
+      "command": "/path/to/.venv/bin/scigantic-mcp",
+      "env": {
+        "SCIGANTIC_API_URL": "https://api.scigantic.com"
+      }
+    }
+  }
+}
+```
+
+Works the same in Claude Desktop / Claude Code (`claude mcp add scigantic -- uvx scigantic-mcp`)
+or any MCP client that launches stdio servers.
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `SCIGANTIC_API_URL` | `https://api.scigantic.com` | API base (set to `https://staging-api.scigantic.com` for staging). |
+| `SCIGANTIC_API_ORIGIN` | `https://scigantic.com` | Origin header → selects the public (default) catalog tenant. |
+
+## Develop & test
+
+The tool/client layer has no `mcp` dependency, so those tests run on any Python
+with `httpx` and need no network (mocked transport):
+
+```bash
+python3 tests/test_tools.py     # or: pytest
+```
+
+`tests/test_server_import.py` covers the wiring layer — that the server module
+imports, and that the registered tools and prompts are the expected set. It needs
+the `mcp` SDK installed (Python ≥ 3.10) and is skipped otherwise:
+
+```bash
+pip install -e '.[test]' && pytest
+```
+
+Keep it that way: the tool tests skip `server.py` on purpose, so an SDK breaking
+change is invisible to them. All 12 passed while the server could not import at
+all under SDK 2.x, which is what `test_server_import.py` now guards against.
+
+## Roadmap
+
+- **Richer discovery for agents** — structured tool outputs and MCP *resources*
+  (attach an archive + its schema card as durable context).
+- Upstream inclusion as `life-sciences-scigantic` in `aws-samples/sample-kiro-power-life-sciences`
+  (see `docs/kiro-upstream-pr.md`).
+- **Hosted compute is intentionally not exposed here.** Scigantic's notebooks are
+  interactive (a JupyterLab URL a human opens); handing an external agent that URL
+  is a dead end. The agent-to-agent path is `get_data_access` — the caller runs the
+  analysis in its own environment. Letting Scigantic *execute code for* an agent
+  (run against an ephemeral kernel with the dataset mounted, return outputs) is a
+  separate capability the platform would need to build first.
+
+## License
+
+MIT-0.

scigantic_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scigantic-mcp"
+version = "0.1.0"
+description = "MCP server for the Scigantic catalog of public scientific data archives, with LLM-ready schema cards"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT-0" }
+authors = [{ name = "Scigantic" }]
+keywords = ["mcp", "model-context-protocol", "datasets", "open-data", "schema-card", "bioinformatics", "earth-observation"]
+classifiers = [
+  "License :: OSI Approved :: MIT No Attribution License (MIT-0)",
+  "Programming Language :: Python :: 3",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering",
+]
+
+# mcp 2.0 removed `mcp.server.fastmcp`, so an open-ended floor silently installs
+# an SDK this package cannot import. Both bounds are load-bearing.
+dependencies = [
+  "mcp>=2,<3",
+  "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://scigantic.com"
+Documentation = "https://scigantic.com/blog/scigantic-mcp-server"
+
+[project.optional-dependencies]
+test = ["pytest>=7", "pytest-asyncio>=0.23"]
+
+# Console-script entry point. This is the binary Kiro launches from mcp.json
+# (e.g. "command": "/path/to/.venv/bin/scigantic-mcp") and what `uvx scigantic-mcp`
+# resolves to.
+[project.scripts]
+scigantic-mcp = "scigantic_mcp.server:main"
+
+[tool.setuptools]
+packages = ["scigantic_mcp"]

scigantic_mcp-0.1.0/scigantic_mcp/__init__.py

@@ -0,0 +1,9 @@
+"""Scigantic MCP server — public scientific-data catalog as MCP tools.
+
+Built to drop into Kiro for Life Sciences (and any MCP client) alongside the
+domain database servers. Where those servers each wrap one domain's APIs,
+Scigantic is the cross-domain launchpad: 5,000+ curated public archives with
+LLM-ready schema cards, searchable in one place.
+"""
+
+__version__ = "0.1.0"

scigantic_mcp-0.1.0/scigantic_mcp/client.py

@@ -0,0 +1,124 @@
+"""Async HTTP client for the public Scigantic API.
+
+Deliberately mirrors the shape of Kiro's `life-sciences-common` base
+(async httpx client, exponential backoff on 429/5xx/timeout, a small error
+taxonomy) so this connector can either run standalone (self-serve install) or
+be adapted to inherit `BaseLifeSciencesServer` for the aws-samples monorepo.
+
+Only public, unauthenticated, read-only endpoints are used here.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any, Dict, Optional
+
+import httpx
+
+DEFAULT_BASE_URL = "https://api.scigantic.com"
+# The API derives its (default) tenant from the request Origin; pinning it to
+# scigantic.com keeps this connector on the main public catalog.
+DEFAULT_ORIGIN = "https://scigantic.com"
+USER_AGENT = "scigantic-mcp/0.1 (+https://scigantic.com)"
+
+_RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+
+
+class ScigateApiError(Exception):
+    """Base class for Scigantic API errors."""
+
+
+class RateLimitError(ScigateApiError):
+    """429 Too Many Requests after retries were exhausted."""
+
+
+class AuthenticationError(ScigateApiError):
+    """401/403 — should not happen on public endpoints, surfaced for clarity."""
+
+
+class NotFoundError(ScigateApiError):
+    """404 — archive/paper/resource does not exist."""
+
+
+class ScigateClient:
+    """Thin retrying JSON client over the public Scigantic REST API."""
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        origin: Optional[str] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+        max_retries: int = 3,
+        timeout: float = 20.0,
+    ) -> None:
+        self.base_url = (base_url or os.environ.get("SCIGANTIC_API_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.origin = origin or os.environ.get("SCIGANTIC_API_ORIGIN") or DEFAULT_ORIGIN
+        self.max_retries = max_retries
+        self._timeout = timeout
+        # Allow an injected client (tests use httpx.MockTransport); otherwise lazily build one.
+        self._client = http_client
+        self._owns_client = http_client is None
+
+    def _headers(self) -> Dict[str, str]:
+        return {"Origin": self.origin, "User-Agent": USER_AGENT, "Accept": "application/json"}
+
+    async def _ensure_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(base_url=self.base_url, timeout=self._timeout)
+        return self._client
+
+    async def aclose(self) -> None:
+        if self._client is not None and self._owns_client:
+            await self._client.aclose()
+            self._client = None
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        client = await self._ensure_client()
+        last_exc: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                resp = await client.request(method, path, headers=self._headers(), **kwargs)
+            except (httpx.TimeoutException, httpx.TransportError) as exc:
+                last_exc = exc
+                if attempt < self.max_retries:
+                    await asyncio.sleep(self._backoff(attempt))
+                    continue
+                raise ScigateApiError(f"{method} {path} failed: {exc}") from exc
+
+            if resp.status_code in _RETRYABLE_STATUS and attempt < self.max_retries:
+                await asyncio.sleep(self._backoff(attempt))
+                continue
+
+            return self._handle_response(method, path, resp)
+
+        # Only reached if every attempt raised a transport error.
+        raise ScigateApiError(f"{method} {path} failed after retries: {last_exc}")
+
+    @staticmethod
+    def _backoff(attempt: int) -> float:
+        # 0.5s, 1s, 2s — capped exponential backoff.
+        return min(0.5 * (2 ** attempt), 4.0)
+
+    @staticmethod
+    def _handle_response(method: str, path: str, resp: httpx.Response) -> Any:
+        status = resp.status_code
+        if status == 404:
+            raise NotFoundError(f"{path} not found")
+        if status in (401, 403):
+            raise AuthenticationError(f"{path} requires authentication ({status})")
+        if status == 429:
+            raise RateLimitError(f"{path} rate-limited (429)")
+        if status >= 400:
+            raise ScigateApiError(f"{method} {path} -> HTTP {status}: {resp.text[:200]}")
+        try:
+            return resp.json()
+        except ValueError as exc:
+            raise ScigateApiError(f"{path} returned non-JSON body") from exc
+
+    async def get_json(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        clean = {k: v for k, v in (params or {}).items() if v is not None}
+        return await self._request("GET", path, params=clean)
+
+    async def post_json(self, path: str, body: Optional[Dict[str, Any]] = None) -> Any:
+        return await self._request("POST", path, json=body or {})

scigantic_mcp-0.1.0/scigantic_mcp/server.py

@@ -0,0 +1,150 @@
+"""Stdio MCP server exposing the Scigantic catalog to MCP clients (Kiro, etc.).
+
+Thin wiring layer: each tool delegates to scigantic_mcp.tools (which is what the
+tests exercise). Run via the `scigantic-mcp` console script or `uvx scigantic-mcp`.
+
+Built on `MCPServer` from the MCP Python SDK 2.x. SDK 1.x's `FastMCP` was removed
+in 2.0 (`mcp.server.fastmcp` no longer exists), which is why pyproject pins
+`mcp>=2,<3` rather than an open-ended floor.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from mcp.server import MCPServer
+
+from . import __version__, tools
+from .client import ScigateClient
+
+mcp = MCPServer(
+    "scigantic",
+    title="Scigantic",
+    version=__version__,
+    website_url="https://scigantic.com",
+    instructions=(
+        "Scigantic is a cross-domain catalog of public scientific data archives. "
+        "Unlike single-domain database servers, it spans genomics, proteomics, structural "
+        "biology, imaging, earth observation and more, and ships an LLM-ready 'schema card' "
+        "for each dataset. Use search_archives to find datasets across domains, then "
+        "get_schema_card to understand structure before analysis."
+    ),
+)
+
+# Single shared client for the process lifetime (stdio server = one process).
+_client: Optional[ScigateClient] = None
+
+
+def _get_client() -> ScigateClient:
+    global _client
+    if _client is None:
+        _client = ScigateClient()
+    return _client
+
+
+@mcp.tool()
+async def search_archives(query: str, category: Optional[str] = None, limit: int = 10) -> str:
+    """Search the Scigantic catalog of public scientific data archives by natural-language query.
+
+    Returns ranked matches with id, title, category and a short summary across all domains.
+    Follow up with get_schema_card to understand a match's structure.
+
+    Args:
+        query: Natural-language search, e.g. "single-cell RNA-seq of human cortex".
+        category: Optional category filter, e.g. "Genomics & Bioinformatics" (comma-separate for several).
+        limit: Max results (default 10, max 50).
+    """
+    return await tools.search_archives(_get_client(), query=query, category=category, limit=limit)
+
+
+@mcp.tool()
+async def get_archive(id: str) -> str:
+    """Get full metadata for one archive by id, including whether a schema card exists.
+
+    Args:
+        id: Archive id from search_archives.
+    """
+    return await tools.get_archive(_get_client(), id=id)
+
+
+@mcp.tool()
+async def get_schema_card(id: str) -> str:
+    """Get the compact schema card for an archive: file format, columns, sample rows/headers,
+    sidecar docs (READMEs/data dictionaries) and a copy-paste starter cell.
+
+    This is the fastest way to understand a dataset's structure without downloading it.
+
+    Args:
+        id: Archive id from search_archives.
+    """
+    return await tools.get_schema_card(_get_client(), id=id)
+
+
+@mcp.tool()
+async def list_archive_files(id: str, limit: int = 50) -> str:
+    """List a sample of the files/objects in an archive's storage.
+
+    Args:
+        id: Archive id from search_archives.
+        limit: Max entries (default 50, max 200).
+    """
+    return await tools.list_archive_files(_get_client(), id=id, limit=limit)
+
+
+@mcp.tool()
+async def get_data_access(id: str, language: Optional[str] = None) -> str:
+    """Get how to load a dataset in YOUR OWN environment: storage location plus copy-paste
+    code snippets (from the dataset's schema card, or generated as a fallback).
+
+    Use this after finding a dataset when you want to run analysis where you are, rather
+    than in a hosted notebook.
+
+    Args:
+        id: Archive id from search_archives.
+        language: Optional filter for the snippet language (e.g. "datasets", "s3fs", "gcsfs").
+    """
+    return await tools.get_data_access(_get_client(), id=id, language=language)
+
+
+# ---------------------------------------------------------------------------
+# Prompts — guided workflows. In Claude Code these surface as slash commands
+# (/mcp__scigantic__explore_dataset, /mcp__scigantic__start_analysis).
+# ---------------------------------------------------------------------------
+
+
+@mcp.prompt()
+def explore_dataset(topic: str) -> str:
+    """Find and understand a Scigantic dataset on a topic, end to end."""
+    return (
+        f"Find and understand a Scigantic dataset about: {topic}\n\n"
+        f'1. Use search_archives to find candidate datasets for "{topic}".\n'
+        "2. For the 1-2 most relevant results, call get_schema_card to understand structure "
+        "(format, columns, sample rows/headers, sidecar docs).\n"
+        "3. Summarize what's available and recommend the best fit, citing its archive id.\n"
+        "4. If I want to use it, call get_data_access to give me copy-paste code to load it in this environment."
+    )
+
+
+@mcp.prompt()
+def start_analysis(archive_id: str, goal: str = "") -> str:
+    """Set up analysis of a specific Scigantic archive in your own environment."""
+    goal = (goal or "").strip()
+    return (
+        f"Help me start analyzing the Scigantic archive {archive_id}."
+        + (f" My goal: {goal}." if goal else "")
+        + "\n\n"
+        f"1. Call get_archive and get_schema_card for {archive_id} to understand the dataset.\n"
+        "2. Call get_data_access to get the code to load it in this environment.\n"
+        "3. Propose a concrete analysis plan and the initial code to load and explore the data"
+        + (f", working toward: {goal}" if goal else "")
+        + "."
+    )
+
+
+def main() -> None:
+    """Console-script entry point — runs the MCP server over stdio."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

scigantic_mcp-0.1.0/scigantic_mcp/tools.py

@@ -0,0 +1,209 @@
+"""Tool implementations for the Scigantic MCP server.
+
+Pure async functions that take a ScigateClient and return formatted text. Kept
+free of any `mcp` import so they can be unit-tested under any Python with a
+mocked httpx transport; server.py wires them into the MCP server.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+from .client import NotFoundError, ScigateApiError, ScigateClient
+
+
+def _source_url(a: Dict[str, Any]) -> str:
+    return a.get("sourceUrl") or a.get("websiteUrl") or a.get("huggingFaceUrl") or "n/a"
+
+
+def _summary(a: Dict[str, Any]) -> str:
+    return (a.get("summary") or a.get("description") or "").strip()
+
+
+async def search_archives(
+    client: ScigateClient,
+    query: str,
+    category: Optional[str] = None,
+    limit: int = 10,
+) -> str:
+    query = (query or "").strip()
+    if not query:
+        return "Error: query is required."
+    limit = max(1, min(int(limit or 10), 50))
+    try:
+        resp = await client.get_json(
+            "/api/archives", {"search": query, "category": category, "limit": str(limit)}
+        )
+    except ScigateApiError as exc:
+        return f"Search failed: {exc}"
+
+    data: List[Dict[str, Any]] = resp.get("data") or []
+    rows = data[:limit]
+    if not rows:
+        return f'No archives matched "{query}".'
+
+    lines = [f"Found {len(rows)} archive(s) for \"{query}\":\n"]
+    for i, a in enumerate(rows, 1):
+        lines.append(
+            f"{i}. {a.get('title', 'Untitled')}  [id: {a.get('id')}]\n"
+            f"   {a.get('category') or 'Uncategorized'}"
+            f"{' · ' + a['cloudProvider'] if a.get('cloudProvider') else ''}\n"
+            f"   {_summary(a)[:200]}\n"
+            f"   source: {_source_url(a)}"
+        )
+    lines.append("\nNext: call get_schema_card(id) to see a dataset's structure before using it.")
+    return "\n".join(lines)
+
+
+async def get_archive(client: ScigateClient, id: str) -> str:
+    id = (id or "").strip()
+    if not id:
+        return "Error: id is required."
+    try:
+        resp = await client.get_json(f"/api/archives/{id}")
+    except NotFoundError:
+        return f"Archive {id} not found."
+    except ScigateApiError as exc:
+        return f"Could not fetch archive {id}: {exc}"
+
+    a = resp.get("data") or {}
+    has_card = bool(a.get("schemaCard"))
+    storage = a.get("cloudProvider") or "?"
+    if a.get("bucketName"):
+        storage += " · " + a["bucketName"] + ("/" + a["bucketPrefix"] if a.get("bucketPrefix") else "")
+    return (
+        f"{a.get('title', 'Untitled')}  [id: {a.get('id')}]\n"
+        f"Category: {a.get('category') or 'Uncategorized'}\n"
+        f"License: {a.get('license') or 'n/a'}\n"
+        f"Storage: {storage}\n"
+        f"Source: {_source_url(a)}\n\n"
+        f"{a.get('description') or _summary(a)}\n"
+        + ("\n(A schema card is available — call get_schema_card for structure details.)" if has_card else "")
+    )
+
+
+async def get_schema_card(client: ScigateClient, id: str) -> str:
+    id = (id or "").strip()
+    if not id:
+        return "Error: id is required."
+    try:
+        resp = await client.get_json(f"/api/archives/{id}")
+    except NotFoundError:
+        return f"Archive {id} not found."
+    except ScigateApiError as exc:
+        return f"Could not fetch archive {id}: {exc}"
+
+    a = resp.get("data") or {}
+    card = a.get("schemaCard")
+    if not card:
+        return f"No schema card has been generated for \"{a.get('title') or id}\" yet."
+    return (
+        f"Schema card for {a.get('title')} [id: {id}] — file format, columns, "
+        f"sample rows/headers, sidecar docs, and a starter cell:\n\n"
+        + json.dumps(card, indent=2, ensure_ascii=False)
+    )
+
+
+async def list_archive_files(client: ScigateClient, id: str, limit: int = 50) -> str:
+    id = (id or "").strip()
+    if not id:
+        return "Error: id is required."
+    limit = max(1, min(int(limit or 50), 200))
+    try:
+        resp = await client.get_json(f"/api/archives/{id}/files")
+    except NotFoundError:
+        return f"Archive {id} not found."
+    except ScigateApiError as exc:
+        return f"Could not list files for {id}: {exc}"
+
+    data = resp.get("data") or {}
+    files = data.get("files") if isinstance(data, dict) else data
+    files = files or []
+    shown = files[:limit]
+    if not shown:
+        return "No files listed (the bucket may be private, empty, or list-restricted)."
+
+    def fmt(f: Any) -> str:
+        if isinstance(f, str):
+            return f
+        name = f.get("name") or f.get("key") or "?"
+        return f"{name}" + (f" ({f['size']} bytes)" if f.get("size") is not None else "")
+
+    header = f"{len(shown)} file(s)" + (" (truncated)" if len(files) > len(shown) else "") + ":\n"
+    return header + "\n".join(fmt(f) for f in shown)
+
+
+def _fallback_snippet(a: Dict[str, Any]) -> str:
+    """Best-effort load snippet for archives without a schema card's accessHints."""
+    provider = (a.get("cloudProvider") or "").lower()
+    bucket = a.get("bucketName") or ""
+    prefix = a.get("bucketPrefix") or ""
+    region = a.get("region") or ""
+    public = (a.get("bucketAccessType") or "") == "public"
+    path = bucket + (("/" + prefix) if prefix else "")
+    if provider in ("huggingface", "hf"):
+        return f'from datasets import load_dataset\nds = load_dataset("{bucket}")'
+    if provider in ("gcp", "gcs"):
+        tok = "token='anon'" if public else "token='google_default'"
+        return f"import gcsfs\nfs = gcsfs.GCSFileSystem({tok})\nfs.ls('{path}')[:20]"
+    if provider in ("aws", "s3"):
+        anon = "anon=True" if public else "anon=False"
+        note = f"  # region: {region}" if region else ""
+        return f"import s3fs\nfs = s3fs.S3FileSystem({anon}){note}\nfs.ls('{path}')[:20]"
+    if provider in ("api", "postgres"):
+        return f"# Accessed via {provider}; see source: {_source_url(a)}"
+    return f"# See source for access details: {_source_url(a)}"
+
+
+async def get_data_access(client: ScigateClient, id: str, language: Optional[str] = None) -> str:
+    """Return how to load this dataset in *your own* environment: storage location plus
+    copy-paste code snippets (from the dataset's schema card, or generated as a fallback).
+    """
+    id = (id or "").strip()
+    if not id:
+        return "Error: id is required."
+    try:
+        resp = await client.get_json(f"/api/archives/{id}")
+    except NotFoundError:
+        return f"Archive {id} not found."
+    except ScigateApiError as exc:
+        return f"Could not fetch archive {id}: {exc}"
+
+    a = resp.get("data") or {}
+    card = a.get("schemaCard") or {}
+    hints: List[Dict[str, Any]] = card.get("accessHints") or []
+    if language:
+        lang = language.lower()
+        hints = [h for h in hints if lang in (h.get("language") or "").lower()] or hints
+
+    storage = a.get("cloudProvider") or "?"
+    if a.get("bucketName"):
+        storage += " · " + a["bucketName"] + ("/" + a["bucketPrefix"] if a.get("bucketPrefix") else "")
+    if a.get("region"):
+        storage += f"  (region: {a['region']})"
+
+    out = [
+        f"How to access \"{a.get('title') or id}\" in your own environment:\n",
+        f"Storage: {storage}",
+        f"Access: {a.get('bucketAccessType') or 'unknown'}",
+        f"Source: {_source_url(a)}",
+        "",
+        "Load it:",
+    ]
+    if hints:
+        for h in hints:
+            out.append(f"\n# {h.get('language') or 'snippet'}\n{h.get('snippet') or ''}")
+    else:
+        out.append(f"\n# generated (no schema-card hints for this archive)\n{_fallback_snippet(a)}")
+    if card.get("starterCell"):
+        out.append("\n# worked example (starter cell)\n" + card["starterCell"])
+    return "\n".join(out)
+
+
+# NOTE: a `lookup_paper` tool (paper -> linked archives) was dropped before the
+# first PyPI release. The backing endpoint, /api/papers/lookup, is arXiv-only:
+# it resolves bare arXiv ids and free-text keywords, but not DOIs, "arXiv:"-
+# prefixed ids, or titles of papers that are not on arXiv — while the tool
+# description advertised all four. Re-add it here once the backend resolves
+# DOIs/titles, so the tool description can be true.

scigantic_mcp-0.1.0/scigantic_mcp.egg-info/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: scigantic-mcp
+Version: 0.1.0
+Summary: MCP server for the Scigantic catalog of public scientific data archives, with LLM-ready schema cards
+Author: Scigantic
+License: MIT-0
+Project-URL: Homepage, https://scigantic.com
+Project-URL: Documentation, https://scigantic.com/blog/scigantic-mcp-server
+Keywords: mcp,model-context-protocol,datasets,open-data,schema-card,bioinformatics,earth-observation
+Classifier: License :: OSI Approved :: MIT No Attribution License (MIT-0)
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<3,>=2
+Requires-Dist: httpx>=0.27
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Dynamic: license-file
+
+# scigantic-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes the
+**Scigantic catalog of public scientific data archives** to any MCP client.
+
+It is built to drop into **[Kiro for Life Sciences](https://github.com/aws-samples/sample-kiro-power-life-sciences)**
+alongside its domain database servers. Where each Kiro server wraps one domain's
+APIs (genomics, proteomics, structural, …), Scigantic is the **cross-domain
+launchpad**: 5,000+ curated public archives spanning every domain, each with an
+LLM-ready **schema card** (file format, columns, sample rows/headers, inlined
+READMEs/data dictionaries, and a copy-paste starter cell) so an agent can
+understand a dataset's structure *before* downloading anything.
+
+It is **discovery-only and zero-config** — every tool calls public, read-only
+Scigantic endpoints, so there is no API key to set up.
+
+Requires Python 3.10+ and MCP SDK 2.x.
+
+> **Prefer the hosted server if your client speaks HTTP.** Scigantic also runs a
+> remote MCP server at `https://api.scigantic.com/mcp` (no auth, nothing to
+> install, and it carries two extra tools):
+> `claude mcp add --transport http scigantic https://api.scigantic.com/mcp`.
+> This package exists for clients that launch **stdio** servers, such as Kiro.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `search_archives(query, category?, limit?)` | Natural-language search across the whole catalog. |
+| `get_archive(id)` | Full metadata for one archive. |
+| `get_schema_card(id)` | The compact schema card — the fastest way to learn a dataset's structure. |
+| `get_data_access(id, language?)` | How to load the dataset in **your own** environment: storage location + copy-paste code snippets. |
+| `list_archive_files(id, limit?)` | A sample of the files/objects in the archive. |
+
+## Prompts (guided workflows)
+
+These surface as slash commands in Claude Code (`/mcp__scigantic__<name>`):
+
+| Prompt | What it does |
+|--------|--------------|
+| `explore_dataset(topic)` | Search → inspect schema cards → recommend the best dataset → offer load code. |
+| `start_analysis(archive_id, goal?)` | Pull schema card + data-access snippet for an archive and outline an analysis plan. |
+
+## Install & register in Kiro
+
+Add an entry under `mcpServers` in `~/.kiro/settings/mcp.json`.
+
+**Option A — `uvx` (zero-install, recommended):**
+
+```json
+{
+  "mcpServers": {
+    "scigantic": {
+      "command": "uvx",
+      "args": ["scigantic-mcp"]
+    }
+  }
+}
+```
+
+**Option B — install into a venv (matches the Kiro servers' own mcp.json form):**
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install scigantic-mcp                 # or: pip install /path/to/scigantic-mcp
+```
+
+```json
+{
+  "mcpServers": {
+    "scigantic": {
+      "command": "/path/to/.venv/bin/scigantic-mcp",
+      "env": {
+        "SCIGANTIC_API_URL": "https://api.scigantic.com"
+      }
+    }
+  }
+}
+```
+
+Works the same in Claude Desktop / Claude Code (`claude mcp add scigantic -- uvx scigantic-mcp`)
+or any MCP client that launches stdio servers.
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `SCIGANTIC_API_URL` | `https://api.scigantic.com` | API base (set to `https://staging-api.scigantic.com` for staging). |
+| `SCIGANTIC_API_ORIGIN` | `https://scigantic.com` | Origin header → selects the public (default) catalog tenant. |
+
+## Develop & test
+
+The tool/client layer has no `mcp` dependency, so those tests run on any Python
+with `httpx` and need no network (mocked transport):
+
+```bash
+python3 tests/test_tools.py     # or: pytest
+```
+
+`tests/test_server_import.py` covers the wiring layer — that the server module
+imports, and that the registered tools and prompts are the expected set. It needs
+the `mcp` SDK installed (Python ≥ 3.10) and is skipped otherwise:
+
+```bash
+pip install -e '.[test]' && pytest
+```
+
+Keep it that way: the tool tests skip `server.py` on purpose, so an SDK breaking
+change is invisible to them. All 12 passed while the server could not import at
+all under SDK 2.x, which is what `test_server_import.py` now guards against.
+
+## Roadmap
+
+- **Richer discovery for agents** — structured tool outputs and MCP *resources*
+  (attach an archive + its schema card as durable context).
+- Upstream inclusion as `life-sciences-scigantic` in `aws-samples/sample-kiro-power-life-sciences`
+  (see `docs/kiro-upstream-pr.md`).
+- **Hosted compute is intentionally not exposed here.** Scigantic's notebooks are
+  interactive (a JupyterLab URL a human opens); handing an external agent that URL
+  is a dead end. The agent-to-agent path is `get_data_access` — the caller runs the
+  analysis in its own environment. Letting Scigantic *execute code for* an agent
+  (run against an ephemeral kernel with the dataset mounted, return outputs) is a
+  separate capability the platform would need to build first.
+
+## License
+
+MIT-0.

scigantic_mcp-0.1.0/scigantic_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+scigantic_mcp/__init__.py
+scigantic_mcp/client.py
+scigantic_mcp/server.py
+scigantic_mcp/tools.py
+scigantic_mcp.egg-info/PKG-INFO
+scigantic_mcp.egg-info/SOURCES.txt
+scigantic_mcp.egg-info/dependency_links.txt
+scigantic_mcp.egg-info/entry_points.txt
+scigantic_mcp.egg-info/requires.txt
+scigantic_mcp.egg-info/top_level.txt
+tests/test_server_import.py
+tests/test_tools.py

scigantic_mcp-0.1.0/scigantic_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

scigantic_mcp-0.1.0/scigantic_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scigantic-mcp = scigantic_mcp.server:main

scigantic_mcp-0.1.0/scigantic_mcp.egg-info/requires.txt

@@ -0,0 +1,6 @@
+mcp<3,>=2
+httpx>=0.27
+
+[test]
+pytest>=7
+pytest-asyncio>=0.23

scigantic_mcp-0.1.0/scigantic_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+scigantic_mcp

scigantic_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scigantic_mcp-0.1.0/tests/test_server_import.py

@@ -0,0 +1,67 @@
+"""Smoke test for the server wiring layer — needs the mcp SDK.
+
+This exists because tests/test_tools.py deliberately imports only .tools/.client
+so it can run offline on any Python. That left server.py with ZERO coverage, and
+it is exactly where the SDK contract lives: when SDK 2.0 removed
+`mcp.server.fastmcp`, every tool test still passed while the server crashed on
+import. Anything that would break `uvx scigantic-mcp` at startup belongs here.
+
+Skipped automatically when mcp is not installed (e.g. Python < 3.10).
+"""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+pytest.importorskip("mcp", reason="mcp SDK not installed (needs Python >= 3.10)")
+
+EXPECTED_TOOLS = {
+    "search_archives",
+    "get_archive",
+    "get_schema_card",
+    "list_archive_files",
+    "get_data_access",
+}
+EXPECTED_PROMPTS = {"explore_dataset", "start_analysis"}
+
+
+def test_server_module_imports():
+    """The import that SDK 2.0 broke. Guards the console-script entry point."""
+    from scigantic_mcp import server
+
+    assert callable(server.main)
+
+
+def test_registered_tools_match_expected():
+    import asyncio
+
+    from scigantic_mcp import server
+
+    names = {t.name for t in asyncio.run(_list(server.mcp.list_tools()))}
+    assert names == EXPECTED_TOOLS
+
+
+def test_registered_prompts_match_expected():
+    import asyncio
+
+    from scigantic_mcp import server
+
+    names = {p.name for p in asyncio.run(_list(server.mcp.list_prompts()))}
+    assert names == EXPECTED_PROMPTS
+
+
+def test_server_reports_package_version():
+    """MCPServer takes an explicit version; SDK 1.x's FastMCP reported the SDK's."""
+    from scigantic_mcp import __version__, server
+
+    assert server.mcp.version == __version__
+
+
+async def _list(maybe_awaitable):
+    """list_tools()/list_prompts() are sync in some SDK builds, async in others."""
+    import inspect
+
+    return await maybe_awaitable if inspect.isawaitable(maybe_awaitable) else maybe_awaitable

scigantic_mcp-0.1.0/tests/test_tools.py

@@ -0,0 +1,216 @@
+"""Offline tests for the Scigantic MCP tool layer.
+
+Uses httpx.MockTransport so nothing hits the network. Each test wraps its async
+body in asyncio.run(), so it runs under plain `pytest` without pytest-asyncio,
+and the file is also directly executable: `python3 tests/test_tools.py`.
+
+Note: these import scigantic_mcp.tools / .client only — NOT .server — so they
+run on any Python with httpx, independent of the mcp SDK (which needs 3.10+).
+"""
+
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+import httpx
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from scigantic_mcp import tools  # noqa: E402
+from scigantic_mcp.client import NotFoundError, ScigateClient  # noqa: E402
+
+
+def make_client(handler) -> ScigateClient:
+    transport = httpx.MockTransport(handler)
+    http = httpx.AsyncClient(transport=transport, base_url="https://api.test")
+    return ScigateClient(base_url="https://api.test", http_client=http)
+
+
+# --- fixtures: canned API responses keyed by (method, path) -----------------
+
+ARCHIVE_WITH_CARD = {
+    "id": "a1",
+    "title": "Test Archive",
+    "category": "Genomics & Bioinformatics",
+    "cloudProvider": "huggingface",
+    "license": "CC-BY-4.0",
+    "summary": "A tiny test dataset",
+    "description": "Longer description of the test dataset.",
+    "websiteUrl": "https://example.org/a1",
+    "bucketName": "test-bucket",
+    "region": "us-east-1",
+    "bucketAccessType": "public",
+    "schemaCard": {
+        "format": "parquet",
+        "columns": [{"name": "gene", "type": "string"}],
+        "accessHints": [{"language": "python-datasets", "snippet": "from datasets import load_dataset\nds = load_dataset(\"test-bucket\")"}],
+        "starterCell": "import pandas as pd  # worked example",
+    },
+}
+
+HF_NO_CARD = {
+    "id": "hfnocard",
+    "title": "HF No Card",
+    "cloudProvider": "huggingface",
+    "bucketName": "org/dataset",
+    "bucketAccessType": "public",
+}
+
+
+def default_handler(request: httpx.Request) -> httpx.Response:
+    path = request.url.path
+    method = request.method
+    if method == "GET" and path == "/api/archives":
+        return httpx.Response(200, json={"success": True, "count": 1, "data": [ARCHIVE_WITH_CARD]})
+    if method == "GET" and path == "/api/archives/a1":
+        return httpx.Response(200, json={"success": True, "data": ARCHIVE_WITH_CARD})
+    if method == "GET" and path == "/api/archives/nocard":
+        return httpx.Response(200, json={"success": True, "data": {"id": "nocard", "title": "No Card"}})
+    if method == "GET" and path == "/api/archives/hfnocard":
+        return httpx.Response(200, json={"success": True, "data": HF_NO_CARD})
+    if method == "GET" and path == "/api/archives/missing":
+        return httpx.Response(404, json={"error": {"message": "not found"}})
+    if method == "GET" and path == "/api/archives/a1/files":
+        return httpx.Response(200, json={"success": True, "data": {"files": [
+            {"name": "data.parquet", "size": 1024}, {"name": "README.md", "size": 50}]}})
+    return httpx.Response(404, json={"error": {"message": "unmapped"}})
+
+
+# --- tests -------------------------------------------------------------------
+
+def test_search_archives_formats_results():
+    async def body():
+        c = make_client(default_handler)
+        out = await tools.search_archives(c, query="genomics", limit=5)
+        assert "Test Archive" in out
+        assert "id: a1" in out
+        assert "https://example.org/a1" in out  # falls back to websiteUrl
+        await c.aclose()
+    asyncio.run(body())
+
+
+def test_search_requires_query():
+    async def body():
+        c = make_client(default_handler)
+        assert "query is required" in await tools.search_archives(c, query="  ")
+        await c.aclose()
+    asyncio.run(body())
+
+
+def test_get_archive_notes_schema_card():
+    async def body():
+        c = make_client(default_handler)
+        out = await tools.get_archive(c, id="a1")
+        assert "CC-BY-4.0" in out
+        assert "schema card is available" in out
+        await c.aclose()
+    asyncio.run(body())
+
+
+def test_get_archive_404():
+    async def body():
+        c = make_client(default_handler)
+        assert "not found" in (await tools.get_archive(c, id="missing")).lower()
+        await c.aclose()
+    asyncio.run(body())
+
+
+def test_get_schema_card_present_and_absent():
+    async def body():
+        c = make_client(default_handler)
+        present = await tools.get_schema_card(c, id="a1")
+        assert "parquet" in present
+        assert json.loads(present[present.index("{"):])  # the JSON body parses
+        absent = await tools.get_schema_card(c, id="nocard")
+        assert "No schema card" in absent
+        await c.aclose()
+    asyncio.run(body())
+
+
+def test_list_archive_files():
+    async def body():
+        c = make_client(default_handler)
+        out = await tools.list_archive_files(c, id="a1")
+        assert "data.parquet (1024 bytes)" in out
+        await c.aclose()
+    asyncio.run(body())
+
+
+def test_get_data_access_uses_schema_card_hints():
+    async def body():
+        c = make_client(default_handler)
+        out = await tools.get_data_access(c, id="a1")
+        assert "test-bucket" in out
+        assert "load_dataset" in out          # the card's accessHint snippet
+        assert "worked example" in out         # the starterCell
+        assert "region: us-east-1" in out
+        await c.aclose()
+    asyncio.run(body())
+
+
+def test_get_data_access_filters_by_language():
+    async def body():
+        c = make_client(default_handler)
+        out = await tools.get_data_access(c, id="a1", language="datasets")
+        assert "load_dataset" in out
+        await c.aclose()
+    asyncio.run(body())
+
+
+def test_get_data_access_fallback_when_no_card():
+    async def body():
+        c = make_client(default_handler)
+        out = await tools.get_data_access(c, id="hfnocard")
+        assert "generated (no schema-card hints" in out
+        assert 'load_dataset("org/dataset")' in out  # HF fallback
+        await c.aclose()
+    asyncio.run(body())
+
+
+def test_client_retries_on_503_then_succeeds():
+    calls = {"n": 0}
+
+    def flaky(request: httpx.Request) -> httpx.Response:
+        if request.url.path == "/api/archives":
+            calls["n"] += 1
+            if calls["n"] == 1:
+                return httpx.Response(503, json={"error": {"message": "try later"}})
+            return httpx.Response(200, json={"success": True, "data": [ARCHIVE_WITH_CARD]})
+        return httpx.Response(404)
+
+    async def body():
+        c = make_client(flaky)
+        c.max_retries = 2
+        out = await tools.search_archives(c, query="genomics")
+        assert "Test Archive" in out
+        assert calls["n"] == 2  # one retry happened
+        await c.aclose()
+    asyncio.run(body())
+
+
+def test_client_raises_notfound():
+    async def body():
+        c = make_client(default_handler)
+        raised = False
+        try:
+            await c.get_json("/api/archives/missing")
+        except NotFoundError:
+            raised = True
+        assert raised
+        await c.aclose()
+    asyncio.run(body())
+
+
+if __name__ == "__main__":
+    failures = 0
+    for name, fn in sorted(globals().items()):
+        if name.startswith("test_") and callable(fn):
+            try:
+                fn()
+                print(f"PASS {name}")
+            except Exception as exc:  # noqa: BLE001
+                failures += 1
+                print(f"FAIL {name}: {exc}")
+    print(f"\n{'OK' if failures == 0 else 'FAILURES: ' + str(failures)}")
+    sys.exit(1 if failures else 0)