# Reported issues for libofcongress-mcp-server

Pod holds 21 of 40 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 [libofcongress-mcp-server](/mcp/libofcongress-mcp-server).

## Most discussed

### bug(loc_get_item,loc_get_newspaper_page): internal LOC API URL with query params leaked in not-found error messages

Not-found errors from `libofcongress_get_item`, `libofcongress_get_newspaper_page`, and the `libofcongress://item/{item_id}` resource expose the full internal LOC API URL — including query parameters like `?fo=json&at=item,resources,related_items` — in `data.url`. The same leak occurs in `serviceUnavailable` errors when the LOC API returns an HTML body instead of JSON (rate-limited or maintenance page).

### Steps to reproduce

1. Call `libofcongress_get_item` with input: `{ "item_id": "TOTALLY_

[Read the thread](https://github.com/cyanheads/libofcongress-mcp-server/issues/1) · 2026-05-24 · closed · 6 comments

### bug(loc_get_item): format() truncates related_items at 5 without indicating truncation — parity gap with structuredContent

### Server version

0.1.0

### mcp-ts-core version

0.9.9

### Runtime

Node.js

### Runtime version

Node v25.9.0

### Transport

HTTP (Streamable HTTP)

### Description

`libofcongress_get_item`'s `format()` caps both `related_items` and `resource_links` at 5 entries in `content[]`. Originally this was a silent drop (see comments below); a first fix added an "… and N more" overflow note to both blocks. **Reopened:** disclosure isn't the same as access. An overflow count tells a `content[]`-onl

[Read the thread](https://github.com/cyanheads/libofcongress-mcp-server/issues/7) · 2026-05-24 · closed · 5 comments

### bug(search_subjects): returns non-LCSH authority records

### Server version

0.2.10

### mcp-ts-core version

^0.10.9

### Runtime

Bun

### Runtime version

Bun 1.3.11

### Transport

HTTP

### Description

`libofcongress_search_subjects` is described as returning Library of Congress Subject Headings for use as the `subject` filter in `libofcongress_search`, but the live endpoint response includes name-authority and children-subject records ahead of real subject headings. That can send callers to labels that are not LCSH subject headings and may not 

[Read the thread](https://github.com/cyanheads/libofcongress-mcp-server/issues/25) · 2026-06-27 · closed · 3 comments

### feat(get_item): expose research-critical metadata currently discarded

`libofcongress_get_item` describes itself as returning the full metadata record, but normalization drops several high-value fields already present in the requested `item` payload. The gap is most consequential for summaries, catalog identifiers, language/location context, and access restrictions.

## Proposal

Expand the existing output with a curated set of research-critical fields rather than forwarding raw LOC JSON: `summary`, `languages`, `locations`, `call_number`, `former_ids`, `original_f

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

### feat(search): add collection_slug to complete the browse-to-search workflow

`libofcongress_browse_collections` returns stable collection slugs, but no MCP tool can use them to search inside that collection. The design documentation already describes the slug as a `libofcongress_search` input, while the actual search schema has no collection/part-of filter.

## Proposal

Add an optional `collection_slug` parameter to `libofcongress_search`. When present, route the existing query/filter/pagination shape through the corresponding collection endpoint so browse results becom

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

### bug(item-resource): slash-separated item IDs cannot be read

### Server version

0.2.12

### mcp-ts-core version

0.10.14

### Runtime

Bun 1.3.14

### Transport

HTTP

### Description

The `libofcongress://item/{item_id}` resource claims to return the same record as `libofcongress_get_item`, but it cannot address slash-separated item IDs returned by search. The tool succeeds for these IDs; the resource fails for both raw and percent-encoded URI forms.

Related: #24

### Steps to reproduce

1. Call `libofcongress_get_item` with `{ "item_id": "sn83025842/1

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

### feat(error-handling): route rate-limit throws through ctx.fail() to engage contract-correlation machinery

The `LocApiService` throws `rateLimited()` factory errors directly from `checkRateLimit()` (line 130) and `fetch()` (line 157) in `src/services/loc-api/loc-api-service.ts`. All five tool handlers declare a `rate_limit_exceeded` error contract entry, but those throws originate inside the service layer — not via `ctx.fail('rate_limit_exceeded', ...)` in each handler's catch block. As a result, the framework's contract-correlation machinery is bypassed: `data.reason` is manually populated in the fa

[Read the thread](https://github.com/cyanheads/libofcongress-mcp-server/issues/22) · 2026-05-29 · closed · 2 comments

### bug(search): empty_results contract entry declared but never thrown on 4 search tools

### Server version

0.2.5

### mcp-ts-core version

^0.9.16

### Runtime

Bun

### Transport

stdio

### Description

Four search tools declare an `errors[]` contract entry for `empty_results` with code `JsonRpcErrorCode.NotFound`, but none of them ever throw it. All four handlers return a structured success response with `items: []` (or `subjects: []`) plus `enrichment.notice` carrying recovery guidance. The contract entry is dead code — `data.reason` is never `'empty_results'`, and `JsonRpcErr

[Read the thread](https://github.com/cyanheads/libofcongress-mcp-server/issues/21) · 2026-05-29 · closed · 2 comments

## Most recent

### bug(errors): item_not_found and page_not_found reach the client with no recovery hint

### Server version

0.2.16

### mcp-ts-core version

0.10.14

### Runtime

Bun

### Runtime version

Bun 1.3.x

### Transport

HTTP

### Description

The `item_not_found` and `page_not_found` contract entries declare useful `recovery` metadata, but neither throw site passes `{ recovery: { hint } }`, so nothing reaches the wire. Both re-throw the service's message verbatim, and on a 404 that message is the generic `notFound('LOC resource not found')` raised inside `fetchJson` — it never names the

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

### feat(get_newspaper_page): request at=item,resource so newspaper_title, state, and edition stop coming back empty

### Use case

`libofcongress_get_newspaper_page` declares `newspaper_title`, `state`, and `edition` in its output schema, and never populates any of them. The request asks LOC for `?fo=json&at=resource`, and that projection returns exactly seven keys — `fulltext_file`, `iiif_manifest_url`, `image`, `pdf`, `segment_count`, `url`, `word_coordinates`. The `title`, `date_issued`, `part_of`, and `sequence` the handler reads are all `null` there, so `state` and `edition` are always absent and `part_of

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

### bug(search_subjects): count is the suggest endpoint's record tally, not the LOC item count it is described as

### Server version

0.2.16

### mcp-ts-core version

0.10.14

### Runtime

Bun

### Runtime version

Bun 1.3.x

### Transport

HTTP

### Description

`libofcongress_search_subjects` describes `count` as "Approximate number of LOC items carrying this heading." It is parsed from the third array of the id.loc.gov `/suggest/` OpenSearch response, which carries a per-suggestion description string — `"1 result"`, `"2 results"` — counting matching *authority records*, not catalogued items. `parseInt` r

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

### bug(pagination): LOC 404s out-of-range pages, so recovery guidance is skipped and a valid collection_slug is reported missing

### Server version

0.2.16

### mcp-ts-core version

0.10.14

### Runtime

Bun

### Runtime version

Bun 1.3.x

### Transport

HTTP

### Description

`fetchSearchJson` treats only HTTP 400 and 520 as "page out of range" (`allowStatus: [400, 520]` → `null` → the `pages: 0` sentinel handlers key their recovery notice on). LOC actually answers a past-the-end page with **404** on every endpoint except `/search/`:

| Endpoint | Out-of-range status | Result today |
|:---|:---|:---|
| `/search/` (no `f

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

### bug(get_item): object-form item.related_items violates the output schema and fails the call

### Server version

0.2.16

### mcp-ts-core version

0.10.14

### Runtime

Bun

### Runtime version

Bun 1.3.x

### Transport

HTTP

### Description

`libofcongress_get_item` fails outright for any item whose `item.related_items` entries are objects rather than strings. `RawLocItemResponse` types the field as `string[]` and `getItem` spreads it straight into the normalized `related_items: string[]`:

```ts
relatedItems.push(...(item.related_items ?? []));
```

LOC returns objects (`{ title, url 

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

### bug(tests): LOC_REQUEST_DELAY_MS override is a no-op, so the mocked suite sleeps ~137s

### Server version

0.2.12

### mcp-ts-core version

0.10.14

### Runtime

Bun

### Runtime version

Bun 1.3.14

### Transport

stdio

### Description

`bun run test` takes ~137s. The same suite with `LOC_REQUEST_DELAY_MS=0` in the environment takes ~975ms — a ~140x difference on a suite that mocks `fetch` and never reaches the network. The suite already tries to disable pacing per test, but the override never takes effect.

The cause is an ordering/caching interaction:

- `getServerConfig()` me

[Read the thread](https://github.com/cyanheads/libofcongress-mcp-server/issues/38) · 2026-07-16 · closed · 1 comment

### bug(browse_collections): returned slugs do not match LOC collection routes

### Server version

0.2.12

### mcp-ts-core version

0.10.14

### Runtime

Bun 1.3.14

### Transport

HTTP

### Description

`libofcongress_browse_collections` describes `slug` as the identifier within loc.gov collection URLs, but the extractor only matches URLs ending immediately after `/collections/<slug>/`. Current LOC results end in `/about-this-collection/`, so the regex misses and fabricates a title-derived fallback that often is not a valid route.

### Steps to reproduce

1. Call `libofco

[Read the thread](https://github.com/cyanheads/libofcongress-mcp-server/issues/37) · 2026-07-16 · closed · 1 comment

### bug(search): advertised pagination extends past the LOC 100,000-result ceiling

### Server version

0.2.12

### mcp-ts-core version

0.10.14

### Runtime

Bun 1.3.14

### Transport

HTTP

### Description

`libofcongress_search` computes `pages` and `has_next` from the full upstream total, but LOC stops serving deep pages after roughly 100,000 results. The tool therefore advertises page numbers that cannot be retrieved, then misclassifies the cap response as an ordinary out-of-range request.

Related: #4

### Steps to reproduce

1. Call `libofcongress_search` with `{ "query"

[Read the thread](https://github.com/cyanheads/libofcongress-mcp-server/issues/33) · 2026-07-16 · closed · 1 comment

### bug(browse_collections): discards upstream collection item counts

### Server version

0.2.12

### mcp-ts-core version

0.10.14

### Runtime

Bun 1.3.14

### Transport

HTTP

### Description

`libofcongress_browse_collections` advertises `collections[].item_count` and says it returns collection item counts, but the service never populates the field even when the LOC collections response provides a top-level numeric `count` for every tested result.

### Steps to reproduce

1. Call `libofcongress_browse_collections` with `{ "limit": 2, "page": 1 }`.
2. Observe th

[Read the thread](https://github.com/cyanheads/libofcongress-mcp-server/issues/32) · 2026-07-16 · closed · 1 comment

### bug(response-parity): content and structuredContent diverge on success metadata

### Server version

0.2.12

### mcp-ts-core version

0.10.14

### Runtime

Bun 1.3.14

### Transport

HTTP

### Description

Two success paths expose different facts depending on whether a client consumes `structuredContent` or `content[]`.

1. `libofcongress_search` always returns `items[].is_item`, but `format()` only emits a message when the value is `false`. For the live result `sn83025842/1884-05-22/ed-1`, structured clients see `is_item: true`; text-only clients receive no positive discrim

[Read the thread](https://github.com/cyanheads/libofcongress-mcp-server/issues/31) · 2026-07-16 · closed · 1 comment

### bug(loc-api-service): bare fetch has no retry or timeout, so transient network drops fail the tool call

### Server version

0.2.12

### mcp-ts-core version

0.10.14

### Runtime

Bun

### Runtime version

Bun 1.3.x

### Transport

stdio

### Description

`LocApiService.fetch()` calls global `fetch()` directly (`src/services/loc-api/loc-api-service.ts:159`), passing only `ctx.signal`. It uses neither `withRetry` nor `fetchWithTimeout` from `@cyanheads/mcp-ts-core/utils` — `withRetry` appears nowhere in `src/`. `LcLinkedDataService` has the same gap (`src/services/lc-linked-data/lc-linked-data-servi

[Read the thread](https://github.com/cyanheads/libofcongress-mcp-server/issues/30) · 2026-07-15 · closed · 1 comment

### feat(get_newspaper_page): derive basic metadata from page_url

`libofcongress_get_newspaper_page` returns full OCR text now, but `date` and `sequence` remain absent for normal URLs even though both values are already present in the required `page_url`.

Related: #17

## Proposal

Derive low-risk metadata directly from the LOC newspaper page URL when the `?fo=json&at=resource` endpoint omits it. For URLs like `https://www.loc.gov/resource/sn82014248/1912-04-18/ed-1/?sp=12&q=titanic`, the tool can return `date: "1912-04-18"` from the path and `sequence: 12` f

[Read the thread](https://github.com/cyanheads/libofcongress-mcp-server/issues/28) · 2026-06-27 · closed · 1 comment

### bug(browse_collections): empty results report mismatched totalCount

### Server version

0.2.10

### mcp-ts-core version

^0.10.9

### Runtime

Bun

### Runtime version

Bun 1.3.11

### Transport

HTTP

### Description

`libofcongress_browse_collections` can return empty `collections` with `total: 0` while enrichment reports `totalCount: 1`. The enrichment schema says `totalCount` mirrors `output.total`, so structured clients receive contradictory counts for the same response.

### Steps to reproduce

1. Call `libofcongress_browse_collections` with `{ "query": "z

[Read the thread](https://github.com/cyanheads/libofcongress-mcp-server/issues/27) · 2026-06-27 · closed · 1 comment

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