UniProt MCP Server

Instructions

Implementation Reference

• src/uniprot_mcp/server.py:107-130 (handler)

  The handler function for the 'fetch_entry' tool, registered via @mcp.tool(). Fetches UniProt entry JSON, handles missing entries with a stub, and parses to Entry model.

  @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)

• src/uniprot_mcp/models/domain.py:61-96 (schema)

  Pydantic BaseModel defining the output schema Entry returned by the fetch_entry tool.

  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/adapters/parsers.py:232-260 (helper)

  Helper function parse_entry that transforms raw UniProt JSON into the structured Entry model, invoked by the fetch_entry handler.

  def parse_entry(js: dict[str, Any]) -> Entry:
      """Convert a UniProt entry payload into the Entry model."""
  
      accession = js.get("primaryAccession") or js.get("accession")
      if not accession:
          raise ValueError("UniProt entry payload missing primary accession.")
  
      entry_type = js.get("entryType") or ""
      xrefs, go_terms = _extract_xrefs(js)
  
      entry = Entry(
          accession=str(accession),
          id=js.get("uniProtkbId") or js.get("id"),
          reviewed=entry_type.startswith("UniProtKB reviewed"),
          protein_name=_extract_protein_name(js),
          gene_symbols=_extract_gene_symbols(js),
          organism=(js.get("organism") or {}).get("scientificName")
          if isinstance(js.get("organism"), dict)
          else None,
          taxonomy_id=_to_int_or_none((js.get("organism") or {}).get("taxonId"))
          if isinstance(js.get("organism"), dict)
          else None,
          sequence=_extract_sequence(js),
          features=_extract_features(js),
          go=_extract_go(js) or go_terms,
          xrefs=xrefs,
          raw_payload=js,
      )
      return entry

• src/uniprot_mcp/server.py:70-79 (helper)

  Internal helper _load_entry used by fetch_entry to fetch and normalize the raw JSON payload from UniProt API.

  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)