Tools

Six tools for protein-first research over UniProt — discovery search is the entry point, uniprot_map_ids is the bridge that turns any sibling identifier into a UniProtKB accession, and the rest fetch curated records, proteomes, taxonomy, and sequences:

uniprot_search_proteins

Search UniProtKB and return curated protein records — the discovery entry point.

• text_search for plain language (the 80% case) or query for full Lucene field syntax (gene, organism_id, keyword, go, reviewed, protein_name, family, length, existence, accession) — exactly one
• reviewed defaults to true (Swiss-Prot only) so the agent isn't drowned in TrEMBL predictions; set false to include them
• organism_id convenience filter ANDed onto the query
• Optional facets for server-side count breakdowns (e.g. reviewed, model_organism)
• Forward cursor pagination (UniProtKB has no offset paging); totalResults and the effective query echoed back
• Every hit carries reviewed, annotationScore, and proteinExistence so curation quality is weighable

uniprot_get_entry

Fetch full curated UniProtKB entries by accession in batch — this tool does not search.

• Batch up to 20 accessions in one round trip
• Sectioned record: function, catalytic activity, cofactors, subcellular location, disease, PTMs, natural variants, isoforms, domains, GO terms, keywords, cross-references
• Partial-success output — resolved entries in succeeded[], unknown/withdrawn ones in failed[]; the whole batch never aborts on one bad accession
• fields trims the upstream projection; identity and provenance fields are always retained
• A single oversized record returns kind: "outline" (a section listing) instead of overflowing context — re-call the same accession with sections: [...] to pull only what's needed
• Accessions come from uniprot_search_proteins or uniprot_map_ids; strip any -N isoform suffix first

uniprot_map_ids

Translate identifiers across databases via UniProt's ID-mapping service — the bridge from any sibling server's identifier into a UniProtKB accession.

• from_db / to_db are validated enums (e.g. Gene_Name, Ensembl, RefSeq_Protein, ChEMBL, PDB, GeneID, UniProtKB_AC-ID) so an unsupported pair fails before the upstream call
• Target UniProtKB-Swiss-Prot for reviewed accessions only (the usual intent), or UniProtKB / UniProtKB_AC-ID to include unreviewed TrEMBL
• The job runs asynchronously; the tool submits it and polls within a budget. A running job returns status: "running" with a ticket — pass that ticket alone to poll the same job
• A completed call returns status: "finished" with one upstream page (up to 500 mappings). If continuation is present, pass it alone to fetch the next completed page without polling or re-submitting; its absence marks the terminal page
• Pair a gene-symbol from_db with tax_id to disambiguate species
• unmappedIds is populated only from UniProt's failedIds, so identifiers UniProt normalizes in successful result rows are not misclassified as failures

uniprot_get_proteome

Fetch the reference proteome for an organism by UPID or NCBI taxon ID — provide exactly one.

• Metadata inline: proteome type, total protein count, BUSCO completeness (score, complete/fragmented/missing counts, lineage dataset), genome assembly accession
• The protein set is opt-in via include_proteins (it is large — human is ~147,506) and returns a capped page with a forward cursor and truncation disclosure
• Narrow the protein list with the query filter (UniProtKB Lucene syntax) for a subset
• Resolve an organism name to a taxon ID first with uniprot_get_taxonomy

uniprot_get_taxonomy

Resolve a taxonomy record by NCBI taxon ID or scientific name — provide exactly one.

• Returns scientific and common name, mnemonic, rank, parent, and the full lineage (root → near ancestor)
• include_children fetches the immediate child taxa via a follow-up search (not inline on the record)
• Turns an organism name into the taxon ID that uniprot_search_proteins (organism_id) and uniprot_get_proteome (taxon_id) expect

uniprot_get_sequence

Fetch the canonical amino-acid sequence (FASTA) for an accession — the cheap, sequence-only path (for the full functional record use uniprot_get_entry).

• Returns the canonical sequence with its length and parsed FASTA header
• include_isoforms also returns the alternatively-spliced isoform sequences
• Accessions come from uniprot_search_proteins or uniprot_map_ids; strip any -N isoform suffix first

Resources and prompts

All resource data is also reachable via tools — tool-only clients lose nothing. UniProtKB is far too large to enumerate, so there is no resource list(); discovery is uniprot_search_proteins's job.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

UniProt-specific: