encode-toolkit 0.3.0b1__py3-none-any.whl

encode_connector/__init__.py

@@ -0,0 +1,4 @@
+"""ENCODE Project connector - MCP server and Python client."""
+
+__version__ = "0.2.1"
+__author__ = "Dr. Alex M. Mawla, PhD"

encode_connector/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m encode_connector"""
+
+from encode_connector.server.main import main
+
+main()

encode_connector/client/__init__.py

@@ -0,0 +1,6 @@
+"""ENCODE Project Python client library."""
+
+from encode_connector.client.auth import CredentialManager
+from encode_connector.client.encode_client import EncodeClient
+
+__all__ = ["EncodeClient", "CredentialManager"]

encode_connector/client/auth.py

@@ -0,0 +1,262 @@
+"""Secure credential management for ENCODE API authentication.
+
+Credentials are stored in the OS keyring (macOS Keychain, Linux Secret Service,
+Windows Credential Locker). Falls back to Fernet-encrypted file storage when
+keyring is unavailable.
+
+Credentials never appear in logs, error messages, or are sent anywhere
+except the ENCODE API over HTTPS.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import logging
+import os
+import platform
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def _get_machine_key(salt_path: Path | None = None) -> bytes:
+    """Derive a machine-specific encryption key for fallback file storage.
+
+    Uses PBKDF2 with a random salt stored alongside the credentials file.
+    The salt is generated once and reused for subsequent key derivations.
+    """
+    if salt_path is None:
+        salt_path = Path.home() / ".encode_connector" / ".salt"
+
+    # Generate or read the salt
+    if salt_path.exists():
+        salt = salt_path.read_bytes()
+    else:
+        salt_path.parent.mkdir(parents=True, exist_ok=True)
+        salt = os.urandom(32)
+        salt_path.write_bytes(salt)
+        salt_path.chmod(0o600)
+
+    # Combine machine-specific values as key material
+    import getpass
+
+    try:
+        login = getpass.getuser()
+    except (KeyError, OSError):
+        # getpass.getuser() raises KeyError in containers/CI where the user
+        # is not in the password database, or OSError in restricted environments
+        login = os.environ.get("USER", os.environ.get("USERNAME", "encode-user"))
+    material = f"{platform.node()}-{login}-encode-connector"
+
+    # Use PBKDF2 with 600,000 iterations (OWASP recommendation)
+    dk = hashlib.pbkdf2_hmac("sha256", material.encode(), salt, 600_000, dklen=32)
+    return base64.urlsafe_b64encode(dk)
+
+
+class CredentialManager:
+    """Manages ENCODE API credentials with secure storage.
+
+    Storage priority:
+    1. OS keyring (macOS Keychain, Linux Secret Service, Windows Credential Locker)
+    2. Fernet-encrypted file at ~/.encode_connector/credentials.enc
+    3. Environment variables (read-only, for initial setup)
+    """
+
+    SERVICE_NAME = "encode-connector"
+    _fallback_dir = Path.home() / ".encode_connector"
+    _fallback_file = _fallback_dir / "credentials.enc"
+
+    def __init__(self) -> None:
+        self._access_key: str | None = None
+        self._secret_key: str | None = None
+        self._keyring_available: bool | None = None
+
+    def _check_keyring(self) -> bool:
+        """Check if OS keyring is available."""
+        if self._keyring_available is not None:
+            return self._keyring_available
+        try:
+            import keyring
+            from keyring.errors import NoKeyringError
+
+            try:
+                # Test keyring access
+                keyring.get_password(self.SERVICE_NAME, "__test__")
+                self._keyring_available = True
+            except NoKeyringError:
+                self._keyring_available = False
+            except Exception:
+                self._keyring_available = False
+        except ImportError:
+            self._keyring_available = False
+
+        return self._keyring_available
+
+    def _read_from_keyring(self) -> tuple[str | None, str | None]:
+        """Read credentials from OS keyring."""
+        if not self._check_keyring():
+            return None, None
+        try:
+            import keyring
+
+            access_key = keyring.get_password(self.SERVICE_NAME, "access_key")
+            secret_key = keyring.get_password(self.SERVICE_NAME, "secret_key")
+            return access_key, secret_key
+        except Exception:
+            return None, None
+
+    def _write_to_keyring(self, access_key: str, secret_key: str) -> bool:
+        """Store credentials in OS keyring. Returns True on success."""
+        if not self._check_keyring():
+            return False
+        try:
+            import keyring
+
+            keyring.set_password(self.SERVICE_NAME, "access_key", access_key)
+            keyring.set_password(self.SERVICE_NAME, "secret_key", secret_key)
+            logger.info("Credentials stored in OS keyring")
+            return True
+        except Exception as e:
+            logger.warning("Failed to store credentials in keyring: %s", type(e).__name__)
+            return False
+
+    def _read_from_encrypted_file(self) -> tuple[str | None, str | None]:
+        """Read credentials from Fernet-encrypted file."""
+        if not self._fallback_file.exists():
+            return None, None
+        try:
+            from cryptography.fernet import Fernet
+
+            key = _get_machine_key()
+            f = Fernet(key)
+            data = f.decrypt(self._fallback_file.read_bytes()).decode()
+            parts = data.split("\n", 1)
+            if len(parts) == 2:
+                return parts[0], parts[1]
+        except Exception:
+            logger.warning("Failed to decrypt credential file")
+        return None, None
+
+    def _write_to_encrypted_file(self, access_key: str, secret_key: str) -> bool:
+        """Store credentials in Fernet-encrypted file."""
+        try:
+            from cryptography.fernet import Fernet
+
+            self._fallback_dir.mkdir(parents=True, exist_ok=True)
+            # Restrict directory permissions
+            self._fallback_dir.chmod(0o700)
+
+            key = _get_machine_key()
+            f = Fernet(key)
+            data = f"{access_key}\n{secret_key}"
+            encrypted = f.encrypt(data.encode())
+            self._fallback_file.write_bytes(encrypted)
+            # Restrict file permissions
+            self._fallback_file.chmod(0o600)
+            logger.info("Credentials stored in encrypted file")
+            return True
+        except Exception as e:
+            logger.warning("Failed to write encrypted credential file: %s", type(e).__name__)
+            return False
+
+    def _read_from_env(self) -> tuple[str | None, str | None]:
+        """Read credentials from environment variables."""
+        access_key = os.environ.get("ENCODE_ACCESS_KEY")
+        secret_key = os.environ.get("ENCODE_SECRET_KEY")
+        if access_key and secret_key:
+            return access_key, secret_key
+        return None, None
+
+    def get_credentials(self) -> tuple[str | None, str | None]:
+        """Get ENCODE API credentials from the most secure available source.
+
+        Checks in order: cache -> keyring -> encrypted file -> env vars.
+        If found in env vars, migrates to keyring/encrypted file for future use.
+
+        Returns:
+            Tuple of (access_key, secret_key), both None if no credentials found.
+        """
+        # Check cache first
+        if self._access_key and self._secret_key:
+            return self._access_key, self._secret_key
+
+        # Try keyring
+        access_key, secret_key = self._read_from_keyring()
+        if access_key and secret_key:
+            self._access_key = access_key
+            self._secret_key = secret_key
+            return access_key, secret_key
+
+        # Try encrypted file
+        access_key, secret_key = self._read_from_encrypted_file()
+        if access_key and secret_key:
+            self._access_key = access_key
+            self._secret_key = secret_key
+            return access_key, secret_key
+
+        # Try env vars (and migrate to secure storage)
+        access_key, secret_key = self._read_from_env()
+        if access_key and secret_key:
+            self._access_key = access_key
+            self._secret_key = secret_key
+            # Migrate to secure storage
+            self.store_credentials(access_key, secret_key)
+            return access_key, secret_key
+
+        return None, None
+
+    def store_credentials(self, access_key: str, secret_key: str) -> str:
+        """Store credentials in the most secure available storage.
+
+        Returns:
+            Description of where credentials were stored.
+        """
+        self._access_key = access_key
+        self._secret_key = secret_key
+
+        if self._write_to_keyring(access_key, secret_key):
+            return "OS keyring (macOS Keychain / Linux Secret Service / Windows Credential Locker)"
+
+        if self._write_to_encrypted_file(access_key, secret_key):
+            return f"Encrypted file ({self._fallback_file})"
+
+        return "Memory only (credentials will not persist across sessions)"
+
+    def clear_credentials(self) -> None:
+        """Remove all stored credentials."""
+        self._access_key = None
+        self._secret_key = None
+
+        # Clear keyring
+        if self._check_keyring():
+            try:
+                import keyring
+
+                keyring.delete_password(self.SERVICE_NAME, "access_key")
+                keyring.delete_password(self.SERVICE_NAME, "secret_key")
+            except Exception:
+                pass
+
+        # Clear encrypted file
+        if self._fallback_file.exists():
+            self._fallback_file.unlink()
+
+    @property
+    def has_credentials(self) -> bool:
+        """Check if credentials are available without revealing them."""
+        access_key, secret_key = self.get_credentials()
+        return bool(access_key and secret_key)
+
+    def get_auth_header(self) -> dict[str, str] | None:
+        """Get HTTP Basic auth header for ENCODE API.
+
+        Returns:
+            Dict with Authorization header, or None if no credentials.
+        """
+        access_key, secret_key = self.get_credentials()
+        if not access_key or not secret_key:
+            return None
+
+        token = base64.b64encode(f"{access_key}:{secret_key}".encode()).decode()
+        return {"Authorization": f"Basic {token}"}

encode_connector/client/constants.py

@@ -0,0 +1,348 @@
+"""ENCODE API constants, endpoints, and known filter values."""
+
+BASE_URL = "https://www.encodeproject.org"
+SEARCH_ENDPOINT = "/search/"
+
+
+# Rate limiting
+MAX_REQUESTS_PER_SECOND = 10
+DOWNLOAD_CONCURRENCY = 3
+
+# Request defaults
+DEFAULT_TIMEOUT = 30.0
+DOWNLOAD_TIMEOUT = 300.0
+DEFAULT_LIMIT = 25
+try:
+    import importlib.metadata
+
+    _version = importlib.metadata.version("encode-toolkit")
+except importlib.metadata.PackageNotFoundError:
+    _version = "0.3.0"
+USER_AGENT = f"encode-toolkit/{_version} (MCP; +https://github.com/ammawla/encode-toolkit)"
+
+# Keyring service name for credential storage
+KEYRING_SERVICE = "encode-connector"
+KEYRING_ACCESS_KEY = "access_key"
+KEYRING_SECRET_KEY = "secret_key"
+
+# -------------------------------------------------------------------
+# Known ENCODE filter values (for metadata/autocomplete)
+# -------------------------------------------------------------------
+
+ASSAY_TITLES = [
+    "Histone ChIP-seq",
+    "TF ChIP-seq",
+    "Control ChIP-seq",
+    "Mint-ChIP-seq",
+    "ATAC-seq",
+    "DNase-seq",
+    "RNA-seq",
+    "total RNA-seq",
+    "small RNA-seq",
+    "long read RNA-seq",
+    "microRNA-seq",
+    "polyA plus RNA-seq",
+    "polyA minus RNA-seq",
+    "single-cell RNA sequencing assay",
+    "CAGE",
+    "RAMPAGE",
+    "RRBS",
+    "WGBS",
+    "whole-genome shotgun bisulfite sequencing",
+    "Hi-C",
+    "intact Hi-C",
+    "in situ Hi-C",
+    "Micro-C",
+    "ChIA-PET",
+    "HiChIP",
+    "PLAC-seq",
+    "PRO-seq",
+    "GRO-seq",
+    "CUT&RUN",
+    "CUT&Tag",
+    "STARR-seq",
+    "MPRA",
+    "CRISPR screen",
+    "proliferation CRISPR screen",
+    "FlowFISH CRISPR screen",
+    "eCLIP",
+    "iCLIP",
+    "shRNA knockdown followed by RNA-seq",
+    "siRNA knockdown followed by RNA-seq",
+    "CRISPRi followed by RNA-seq",
+    "MeDIP-seq",
+    "MRE-seq",
+    "MNase-seq",
+    "5C",
+    "BruUV-seq",
+    "genetic modification followed by DNase-seq",
+    "long read sequencing assay",
+    "direct RNA-seq",
+    "Parse SPLiT-seq",
+    "SHARE-seq",
+    "10x multiome",
+    "single-nucleus ATAC-seq",
+    "single-nucleus RNA-seq",
+    "snATAC-seq",
+    "Repli-seq",
+    "Repli-chip",
+    "Switchgear",
+    "genotyping HTS",
+    "whole genome sequencing assay",
+]
+
+ORGANISMS = [
+    "Homo sapiens",
+    "Mus musculus",
+    "Drosophila melanogaster",
+    "Caenorhabditis elegans",
+    "Saccharomyces cerevisiae",
+]
+
+BIOSAMPLE_CLASSIFICATIONS = [
+    "tissue",
+    "cell line",
+    "primary cell",
+    "in vitro differentiated cells",
+    "organoid",
+    "whole organisms",
+    "single cell",
+    "induced pluripotent stem cell line",
+    "stem cell",
+]
+
+ORGAN_SLIMS = [
+    "adrenal gland",
+    "arterial blood vessel",
+    "bone element",
+    "bone marrow",
+    "brain",
+    "breast",
+    "bronchus",
+    "connective tissue",
+    "embryo",
+    "esophagus",
+    "extraembryonic component",
+    "eye",
+    "gonad",
+    "heart",
+    "intestine",
+    "kidney",
+    "large intestine",
+    "limb",
+    "liver",
+    "lung",
+    "lymph node",
+    "lymphoid tissue",
+    "mammary gland",
+    "mouth",
+    "musculature of body",
+    "nerve",
+    "nose",
+    "ovary",
+    "pancreas",
+    "penis",
+    "placenta",
+    "prostate gland",
+    "skeleton",
+    "skin of body",
+    "small intestine",
+    "spinal cord",
+    "spleen",
+    "stomach",
+    "testis",
+    "thymus",
+    "thyroid gland",
+    "tongue",
+    "tonsil",
+    "ureter",
+    "urinary bladder",
+    "uterus",
+    "vagina",
+    "vasculature",
+]
+
+FILE_FORMATS = [
+    "fastq",
+    "bam",
+    "bed",
+    "bigWig",
+    "bigBed",
+    "tsv",
+    "csv",
+    "tar",
+    "hic",
+    "tagAlign",
+    "bedpe",
+    "pairs",
+    "fasta",
+    "gff",
+    "gtf",
+    "idat",
+    "CEL",
+    "rcc",
+    "sra",
+    "csfasta",
+    "csqual",
+    "2bit",
+    "database",
+    "vcf",
+    "bigInteract",
+    "idx",
+    "dat",
+    "txt",
+]
+
+OUTPUT_TYPES = [
+    "reads",
+    "alignments",
+    "unfiltered alignments",
+    "transcriptome alignments",
+    "signal",
+    "signal of unique reads",
+    "signal of all reads",
+    "signal p-value",
+    "fold change over control",
+    "peaks",
+    "IDR thresholded peaks",
+    "conservative IDR thresholded peaks",
+    "optimal IDR thresholded peaks",
+    "pseudoreplicated peaks",
+    "replicated peaks",
+    "stable peaks",
+    "hotspots",
+    "narrowPeaks",
+    "broadPeaks",
+    "gappedPeaks",
+    "gene quantifications",
+    "transcript quantifications",
+    "exon quantifications",
+    "splice junctions",
+    "genome reference",
+    "genome index",
+    "transcriptome reference",
+    "transcriptome index",
+    "spike-in sequence",
+    "contact matrix",
+    "contact domains",
+    "topologically associated domains",
+    "chromatin interactions",
+    "DNA accessibility raw signal",
+    "DNA accessibility enrichment signal",
+    "methylation state at CpG",
+    "methylation state at CHG",
+    "methylation state at CHH",
+    "enrichment",
+    "FDR cut rate",
+    "element quantifications",
+    "guide quantifications",
+]
+
+OUTPUT_CATEGORIES = [
+    "raw data",
+    "alignment",
+    "signal",
+    "annotation",
+    "quantification",
+    "reference",
+    "quality metric",
+]
+
+FILE_STATUSES = [
+    "released",
+    "archived",
+    "in progress",
+    "revoked",
+    "deleted",
+    "content error",
+    "upload failed",
+]
+
+EXPERIMENT_STATUSES = [
+    "released",
+    "archived",
+    "revoked",
+    "deleted",
+    "replaced",
+    "in progress",
+    "submitted",
+    "preliminary",
+]
+
+ASSEMBLIES = [
+    "GRCh38",
+    "hg19",
+    "mm10",
+    "mm9",
+    "GRCm39",
+    "dm6",
+    "dm3",
+    "ce11",
+    "ce10",
+]
+
+LIFE_STAGES = [
+    "embryonic",
+    "postnatal",
+    "newborn",
+    "child",
+    "adolescent",
+    "adult",
+    "unknown",
+]
+
+REPLICATION_TYPES = [
+    "isogenic",
+    "anisogenic",
+    "unreplicated",
+]
+
+# Map of metadata_type to its values for the get_metadata tool
+METADATA_MAP = {
+    "assays": ASSAY_TITLES,
+    "organisms": ORGANISMS,
+    "organs": ORGAN_SLIMS,
+    "biosample_types": BIOSAMPLE_CLASSIFICATIONS,
+    "file_formats": FILE_FORMATS,
+    "output_types": OUTPUT_TYPES,
+    "output_categories": OUTPUT_CATEGORIES,
+    "assemblies": ASSEMBLIES,
+    "life_stages": LIFE_STAGES,
+    "replication_types": REPLICATION_TYPES,
+    "statuses": EXPERIMENT_STATUSES,
+    "file_statuses": FILE_STATUSES,
+}
+
+# ENCODE API parameter name mapping (user-friendly -> API param)
+EXPERIMENT_FILTER_MAP = {
+    "assay_title": "assay_title",
+    "organism": "replicates.library.biosample.donor.organism.scientific_name",
+    "organ": "biosample_ontology.organ_slims",
+    "biosample_type": "biosample_ontology.classification",
+    "biosample_term_name": "biosample_ontology.term_name",
+    "target": "target.label",
+    "status": "status",
+    "lab": "lab.title",
+    "award": "award.project",
+    "assembly": "assembly",
+    "replication_type": "replication_type",
+    "life_stage": "replicates.library.biosample.life_stage",
+    "sex": "replicates.library.biosample.sex",
+    "perturbed": "replicates.library.biosample.perturbed",
+    "treatment": "replicates.library.biosample.treatments.treatment_term_name",
+    "genetic_modification": "replicates.library.biosample.applied_modifications.category",
+    "date_released": "date_released",
+    "searchTerm": "searchTerm",
+}
+
+FILE_FILTER_MAP = {
+    "file_format": "file_format",
+    "file_type": "file_type",
+    "output_type": "output_type",
+    "output_category": "output_category",
+    "assembly": "assembly",
+    "status": "status",
+    "biological_replicates": "biological_replicates",
+    "preferred_default": "preferred_default",
+    "dataset": "dataset",
+}