# Reported issues for protein-mcp-server

Pod holds 23 of 54 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [protein-mcp-server](/mcp/protein-mcp-server).

## Most discussed

### feat(search): add retrieval for bounded RCSB result sets

### Use case

`protein_search_structures`, `protein_find_similar` with `by: "sequence"`, and `protein_track_ligands` with `mode: "structures_with_ligand"` expose `totalCount` but accept only `limit`. A caller cannot request a later RCSB page without leaving the server.

### Proposed behavior

Add an optional `start` input to those three RCSB-backed result modes. `start` is a zero-based result offset, defaults to `0`, and combines with the existing `limit` (1–100). The name matches RCSB Search AP

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/41) · 2026-08-17 · closed · 2 comments

### feat(protein_analyze_collection): disclose combined cross-tab bucket size

### Use case

`protein_analyze_collection` applies the same `bucket_limit` cap independently to the parent dimension and to the nested cross-tab child, so a two-dimension `group_by` can return up to `cap²` buckets. At the default cap of 50 that is up to 2,500 buckets in one response; at the maximum it is larger still.

Each position honestly discloses its own truncation — the parent dimension carries `truncated`, and so does each child — so nothing is hidden from a caller who inspects every leve

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/36) · 2026-08-17 · closed · 2 comments

### bug(protein_analyze_collection): group_by accepts the same dimension twice

### Server version

0.4.2

### mcp-ts-core version

^0.11.5

### Runtime

Bun

### Runtime version

Bun 1.3.14

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`protein_analyze_collection` accepts the same dimension twice in `group_by`. `{"group_by": ["method", "method"]}` passes schema validation and reaches `buildFacetSpec('method', interval, 'method')`, which builds a method facet nested inside itself and sends that to RCSB.

Verified live against RCSB, the self-ne

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/30) · 2026-08-16 · closed · 2 comments

### feat(facets): nested cross-tab child is single-valued, not an array

### Use case

The facet output schema advertises `buckets[].children` as an unbounded array of nested dimensions, but no code path can produce more than one element. Three independent bounds enforce that:

- `FacetSpec.child` (`src/services/rcsb/rcsb-service.ts`) is a single optional spec, not a list.
- `toRcsbFacet` requests exactly one nested facet: `if (spec.child) facet.facets = [toRcsbFacet(spec.child)]`.
- `normalizeBuckets` reads only index 0 of the upstream response and wraps the result 

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/28) · 2026-08-16 · closed · 2 comments

### enhancement(protein_track_ligands): structures_with_ligand score is a constant; sort is undocumented

`protein_track_ligands` mode `structures_with_ligand` returns a `score` on every entry that carries no signal, and an ordering that isn't stated.

### Observed

`{ mode: "structures_with_ligand", comp_id: "HEM", limit: 8 }` → every row scores `1.00`, ordered by PDB ID ascending (`101M, 102M, 103M …` — myoglobins ahead of any hemoglobin). Containment is boolean (an entry either has the component or doesn't), so RCSB's relevance score is uniform and the column is noise; the PDB-ascending order is 

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/19) · 2026-07-03 · closed · 2 comments

### enhancement(protein_find_similar): sequence hits return entity IDs that don't chain into other tools

`protein_find_similar` emits a different hit-ID format per mode, and the `by:"sequence"` format doesn't match the bare entry IDs the rest of the server uses — so feeding a sequence hit into `protein_get_structure` requires the caller to strip a suffix.

### Observed

- `by:"sequence"` → polymer-entity IDs like `1A00_1` (raw mmseqs2 `h.id`).
- `by:"structure"` → bare entry IDs (`1A00`) or UniProt accessions (`h.pdbId ?? h.uniprotAccession`).
- `protein_search_structures` and `protein_get_structur

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/18) · 2026-07-03 · closed · 2 comments

### enhancement(protein_track_ligands): find_ligand buries the canonical component for common names

`protein_track_ligands` mode `find_ligand` relays RCSB's chemical-name search ranking unchanged, which sorts by name-string match. For a common query the canonical component sinks below near-namesakes, and a `find_ligand → structures_with_ligand` chain on the top hit then silently resolves the wrong ligand.

### Observed

`{ mode: "find_ligand", query: "heme", limit: 10 }` ranks `HEM` (protoporphyrin IX + Fe — the heme of hemoglobin, myoglobin, cytochromes) **last of ten**, below `HEC`, `HEA`, `

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/17) · 2026-07-03 · closed · 2 comments

### bug(protein_get_structure): best_available returns one coordinate format where experimental returns three

### Server version

0.3.0

### mcp-ts-core version

0.10.10

### Runtime

Bun

### Runtime version

Bun 1.3.x

### Transport

stdio

### Description

For an experimental pick, `source: "best_available"` and `source: "experimental"` resolve to the same PDB entry but expose different coordinate URLs. `fetchExperimental` builds all three formats from the entry ID (`coordinateUrls: { cif, pdb, bcif }` via `rcsb.coordinateFileUrl`), whereas `fetchBest` derives a single URL from the 3D-Beacons `modelU

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/16) · 2026-07-03 · closed · 2 comments

## Most recent

### bug(protein_search_structures): sequence-only controls are silently ignored

### Server version

0.5.3

### mcp-ts-core version

^0.12.3

### Runtime

Bun

### Runtime version

Bun 1.4.0 / Node v26.5.0

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`protein_search_structures` accepts `min_identity` and `max_evalue` without `sequence`, then silently runs the non-sequence query. A malformed workflow therefore looks filtered even though neither threshold affects the result.

### Steps to reproduce

1. Call `protein_search_structures` with `{ "q

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/56) · 2026-08-31 · open · 0 comments

### bug(protein_analyze_collection): zero-match scopes omit the declared notice

### Server version

0.5.3

### mcp-ts-core version

^0.12.3

### Runtime

Bun

### Runtime version

Bun 1.4.0 / Node v26.5.0

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`protein_analyze_collection` returns an empty success for a zero-match scope without the empty-scope advisory declared by its enrichment contract. The result is technically distinguishable through `total: 0`, but it gives no recovery guidance.

### Steps to reproduce

1. Call `protein_analyze_coll

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/54) · 2026-08-31 · open · 0 comments

### docs(tools): make catalog descriptions caller-facing

The MCP catalog mixes user-facing contracts with implementation mechanics and audience assumptions. Examples include `protein_analyze_collection` describing a single upstream call and "no row pull," `protein_compare_structures` describing its internal fanout/concurrency cap, and an output field saying it lets "an agent" cite a structure.

Related: #38

## Proposal

Keep provider identity, limits, partial-success behavior, and resume semantics. Remove API-call counts, internal routing/fanout deta

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/55) · 2026-08-31 · open · 0 comments

### bug(protein_find_similar): completed Foldseek results have no retrieval path

### Server version

0.5.3

### mcp-ts-core version

^0.12.3

### Runtime

Bun

### Runtime version

Bun 1.4.0 / Node v26.5.0

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`protein_find_similar` silently slices completed Foldseek results to `limit`. The response has no total, truncation flag, offset, or reusable completed-job ticket, so hits beyond that cap cannot be retrieved through the server.

Related: #41

### Steps to reproduce

1. Call `protein_find_similar` 

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/53) · 2026-08-31 · open · 0 comments

### bug(protein_search_structures): truncated facets omit recovery guidance

### Server version

0.5.3

### mcp-ts-core version

^0.12.3

### Runtime

Bun

### Runtime version

Bun 1.4.0 / Node v26.5.0

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`protein_search_structures` marks a capped facet as `truncated: true`, but its enrichment omits the promised truncation advisory and gives no route to the remaining buckets.

Related: #13, #41

### Steps to reproduce

1. Call `protein_search_structures` with `{ "query": "kinase", "facets": ["organ

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/52) · 2026-08-31 · open · 0 comments

### bug(protein_analyze_collection): interval is silently ignored for incompatible dimensions

### Server version

0.5.3

### mcp-ts-core version

^0.12.3

### Runtime

Bun

### Runtime version

Bun 1.4.0 / Node v26.5.0

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`protein_analyze_collection.interval` is accepted for every `group_by` shape, but it only reaches the top-level facet when that facet is a histogram. A terms-only call silently drops it, and a numeric/date child in a cross-tab keeps its default interval.

Related: #15

### Steps to reproduce

1. C

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/51) · 2026-08-31 · open · 0 comments

### bug(protein_track_ligands): formula queries run as name searches

### Server version

0.5.3

### mcp-ts-core version

^0.12.3

### Runtime

Bun

### Runtime version

Bun 1.4.0 / Node v26.5.0

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`protein_track_ligands` advertises `find_ligand.query` as a chemical name or formula, but formula input is handled as a name search. A caller can receive chemically unrelated component IDs with no indication that the declared formula path was not applied.

Related: #17

### Steps to reproduce

1. 

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/50) · 2026-08-31 · open · 0 comments

### bug(rcsb): surface GraphQL errors returned with partial data

### Server version

0.5.2

### mcp-ts-core version

^0.12.3

### Runtime

Bun / Node.js

### Runtime version

Bun ≥1.3.0 / Node ≥24.0.0

### Transport

stdio / HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`RcsbService.graphql()` returns `body.data` before inspecting `body.errors`. A GraphQL response carrying both fields is therefore treated as a complete success even when the upstream reports field-level failures. Callers cannot distinguish metadata omitted because it is genuinel

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/48) · 2026-08-30 · open · 1 comment

### bug(protein_analyze_collection): declared unknown_dimension error is unreachable and describes a different condition than it guards

`protein_analyze_collection` advertises an `unknown_dimension` error reason in its `outputSchema`, but no input can produce it, and the condition the code guards is not the condition the contract documents.

## The declared contract

`src/mcp-server/tools/definitions/analyze-collection.tool.ts`:

```
{
  reason: 'unknown_dimension',
  code: JsonRpcErrorCode.InvalidParams,
  when: 'A group_by value is outside the supported dimension set.',
  recovery: 'Use a supported dimension: method, organism,

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/47) · 2026-08-25 · open · 0 comments

### bug(protein_get_annotations): missing uniprot and pdb_id surfaces as no_uniprot_mapping NotFound instead of a validation error

### Server version

0.5.1

### mcp-ts-core version

^0.11.5

### Runtime

Bun

### Runtime version

Bun 1.3.x

### Transport

http

### Description

`protein_get_annotations` takes `uniprot` or `pdb_id`, both optional, with no schema-level one-of constraint. When neither is supplied the handler falls through to the post-resolution `!accession` check in `get-annotations.tool.ts` and throws `no_uniprot_mapping` (`-32001` NotFound) with the message "Provide a UniProt accession, or a PDB ID with a m

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/46) · 2026-08-22 · open · 0 comments

### feat(structure metadata): expose chain namespaces through existing surfaces

### Use case

`protein_compare_structures` takes `structures[].chain` as a `label_asym_id`, and no surface on this server emits a `label_asym_id`. `pdb://{entry_id}` exposes author chains only (`polymerEntities[].chains` is populated from `auth_asym_ids`), and `protein_get_structure` exposes no chain metadata at all. For any entry where the two namespaces differ, a per-chain alignment cannot be set up without leaving the server to look the mapping up.

In RCSB entry `6QNR`, polymer entity `6QNR_

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/45) · 2026-08-17 · open · 0 comments

### bug(protein_find_similar): sequence metadata enrichment silently stops at 50 hits

### Server version

0.5.2

### mcp-ts-core version

^0.12.3

### Runtime

Bun

### Runtime version

Bun 1.4.0 / Node v26.5.0

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`protein_find_similar` with `by: "sequence"` passes `facetBucketCap` to `runSequence()`. That configuration belongs only to `protein_analyze_collection`, but `runSequence()` uses it to slice de-duplicated PDB entry IDs before its one batched `getEntries()` call. With the default cap of 50 and `lim

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/44) · 2026-08-17 · closed · 1 comment

### bug(protein_get_structure): capped batches lose the cap warning and original count

### Server version

0.5.1

### mcp-ts-core version

^0.11.5

### Runtime

Bun

### Runtime version

Bun 1.3.14 / Node v26.5.0

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`protein_get_structure` writes three independent advisories — batch cap, coordinate overflow, and partial failure — to `ctx.enrich.notice`, which is last-write-wins in the framework (`enrich.notice` assigns `store.values.notice = text`). The handler calls it in that order, so a partial failure er

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/43) · 2026-08-17 · open · 0 comments

### bug(protein_get_structure): coordinate inlining bypasses the response budget

### Server version

0.5.1

### mcp-ts-core version

^0.11.5

### Runtime

Bun

### Runtime version

Bun 1.3.14 / Node v26.5.0

### Transport

HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

Two defects in `protein_get_structure`'s coordinate inlining, both in the same block.

**1. A single coordinate file bypasses the overflow guard entirely.** The guard fires only when `withCoords.length > 1`, so one file inlines at any size. `4HHB.cif` is 772,198 bytes — 32× the 24,000-byte `DEFAU

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/42) · 2026-08-17 · open · 0 comments

### bug(protein_search_structures): method and resolution filters cannot stand alone

### Server version

0.5.2

### mcp-ts-core version

^0.12.3

### Runtime

Bun / Node.js

### Runtime version

Bun ≥1.3.0 / Node ≥24.0.0

### Transport

stdio / HTTP (Streamable HTTP)

### OS

macOS 26.1

### Description

`protein_search_structures` rejects method-only and resolution-only requests before they reach RCSB. Its `no_criteria` guard recognizes only `query`, `sequence`, and `organism`, although the handler maps `method` and `max_resolution` into `StructureSearchParams` and `buildQuery(

[Read the thread](https://github.com/cyanheads/protein-mcp-server/issues/40) · 2026-08-17 · closed · 1 comment

The remaining reports are on [the project's issue tracker](https://github.com/cyanheads/protein-mcp-server/issues).