fetch_entry
Retrieve structured protein data from UniProtKB database using accession numbers to access detailed entry information, sequences, and annotations.
Instructions
Return a structured UniProt entry.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| accession | Yes | ||
| fields | No | ||
| version | No |
Implementation Reference
- src/uniprot_mcp/server.py:107-130 (handler)MCP tool handler for 'fetch_entry'. Validates input, loads entry data via _load_entry, parses to Entry model or returns minimal empty Entry if not found.@mcp.tool() # type: ignore[misc] async def fetch_entry( accession: str, fields: list[str] | None = None, version: str | None = None, ) -> Entry: """Return a structured UniProt entry.""" if version is not None: raise ValueError( "Versioned entries are only available as flatfiles. " "Use fetch_entry_flatfile(accession, version) for historical versions." ) normalized, payload = await _load_entry(accession, fields=fields) if not payload: return Entry( accession=normalized, reviewed=False, gene_symbols=[], features=[], go=[], xrefs=[], ) return parse_entry(payload)
- Pydantic BaseModel defining the structured output type (Entry) returned by the fetch_entry tool, including fields like accession, reviewed status, features, GO annotations, etc.class Entry(BaseModel): """Normalized UniProtKB entry.""" model_config = ConfigDict(protected_namespaces=()) accession: str = Field(description="Primary accession identifier.") id: str | None = Field(default=None, description="UniProt entry name/ID.") reviewed: bool = Field(description="True for Swiss-Prot, False for TrEMBL.") protein_name: str | None = Field( default=None, description="Recommended protein name where available." ) gene_symbols: list[str] = Field( default_factory=list, description="Canonical gene symbols associated with the entry." ) organism: str | None = Field( default=None, description="Scientific name of the source organism." ) taxonomy_id: int | None = Field( default=None, description="NCBI taxonomy identifier for the organism." ) sequence: Sequence | None = Field( default=None, description="Protein sequence metadata when available." ) features: list[Feature] = Field( default_factory=list, description="Annotated sequence features." ) go: list[GOAnnotation] = Field( default_factory=list, description="Gene Ontology annotations extracted from the entry." ) xrefs: list[XRef] = Field( default_factory=list, description="Cross-references to external databases." ) raw_payload: dict[str, object] | None = Field( default=None, description="Original UniProt payload for debugging or future enrichment.", )
- src/uniprot_mcp/server.py:70-79 (helper)Private helper in server.py that normalizes accession, fetches raw JSON payload using fetch_entry_json from UniProtClient.async def _load_entry( accession: str, *, fields: Iterable[str] | None = None, ) -> tuple[str, dict[str, Any]]: normalized = _validate_accession(accession) async with new_client() as client: payload = await fetch_entry_json(client, normalized, fields=fields) return normalized, cast(dict[str, Any], payload)
- Low-level async function to fetch raw JSON entry from UniProt REST API, with retry logic, field/version params support, returns empty dict on 404/204.async def fetch_entry_json( client: httpx.AsyncClient, accession: str, *, fields: Iterable[str] | None = None, version: str | None = None, ) -> dict[str, Any]: """Return the UniProt entry payload for the provided accession.""" params: dict[str, Any] = {} if fields: params["fields"] = ",".join(fields) if version: params["version"] = version async with _SEMAPHORE: response = await client.get( f"/uniprotkb/{accession}", params=params or None, ) if response.status_code == 404: return {} if response.status_code == 204: return {} if response.status_code >= 400: if response.status_code in RETRYABLE_STATUS: response.raise_for_status() else: try: response.raise_for_status() except httpx.HTTPStatusError as exc: raise UniProtClientError(str(exc)) from exc return _ensure_dict(response.json())