Search LOC digital collections, browse Chronicling America newspapers with full OCR text, and look up LC Subject Headings via MCP. STDIO or Streamable HTTP.\n
\n\n[](https://github.com/cyanheads/libofcongress-mcp-server/releases/latest/download/libofcongress-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=libofcongress-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvbGlib2Zjb25ncmVzcy1tY3Atc2VydmVyIl19) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22libofcongress-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Flibofcongress-mcp-server%22%5D%7D)\n\n[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n
\n\n---\n\n## Tools\n\nSix tools covering the Library of Congress digital holdings — general search with format/date/subject/location filters, full item retrieval, Chronicling America newspaper search with OCR, single-page full-text fetch, LCSH subject heading lookup, and curated collection browsing:\n\n| Tool | Description |\n|:-----|:------------|\n| `libofcongress_search` | Search LOC digital collections by keyword with optional format, date range, subject heading, geographic location, and collection filters. Returns item summaries with IDs for follow-up retrieval. |\n| `libofcongress_get_item` | Retrieve full metadata for a specific LOC item — contributors, subjects, summary, languages, locations, rights, physical description, call number, formats, access restrictions, resource links (TIFF/JPEG/PDF), and related items. |\n| `libofcongress_search_newspapers` | Search historical newspaper pages in the Chronicling America corpus. Returns pages with OCR text excerpts (~500 chars), publication title, date, state, and the URL needed for `libofcongress_get_newspaper_page`. |\n| `libofcongress_get_newspaper_page` | Retrieve the full OCR text of a specific newspaper page. Pass the `url` field from a `libofcongress_search_newspapers` result. Returns `ocr_available: false` when the page has no digitized text. |\n| `libofcongress_search_subjects` | Search Library of Congress Subject Headings (LCSH) by keyword. Returns controlled-vocabulary labels and URIs — use the label as the `subject` filter in `libofcongress_search`. |\n| `libofcongress_browse_collections` | List and browse LOC curated digital collections with descriptions, item counts, and slugs. Optionally filter by keyword. |\n\n### `libofcongress_search`\n\nSearch the LOC digital collections with full-text keyword matching and facet filters.\n\n- Eight material formats: `photo`, `map`, `newspaper`, `manuscript`, `audio`, `film`, `book`, `notated-music`\n- Date range filtering by year (inclusive start and end)\n- Subject heading filter — use `libofcongress_search_subjects` first to get the exact LCSH spelling\n- Geographic location filter (e.g., `\"oklahoma\"`, `\"washington d.c.\"`)\n- `collection_slug` scopes the search to one curated collection — pass a slug from `libofcongress_browse_collections`. Mutually exclusive with `format` (each selects a different LOC endpoint); an unknown slug returns `collection_not_found`\n- Pagination up to 100 results per page — `pages`/`has_next` respect LOC's ~100,000-item retrieval ceiling (a notice discloses how to reach the rest: partition by date, subject, or location); real results on a page beyond the reported total are always returned, never discarded\n- Empty results include a `notice` field with recovery hints — echoes the applied filters\n- Each result carries `is_item` — `true` for catalog items whose `id` resolves via `libofcongress_get_item`, `false` for non-item results (collections, exhibit/guide pages, newspaper pages); open their `url` instead\n\n---\n\n### `libofcongress_get_item`\n\nRetrieve the full metadata record for a specific LOC digital item.\n\n- Returns contributors, LCSH subject headings, rights information, physical/technical description, and cataloger notes\n- Also returns `summary`, `languages`, `locations`, `call_number` (shelf location for requesting the physical original), `former_ids`, `original_formats`, `online_formats`, and `access_restricted` — all sourced from the same upstream response, no extra request\n- `resource_links` contains URLs to downloadable digital files (TIFF, JPEG, PDF) for items with digital surrogates\n- `related_items` lists IDs of related LOC items for follow-up retrieval\n- `resource_links` and `related_items` render in full in both `structuredContent` and `content[]` — no truncation, so `content[]`-only clients see every value\n- Deduplicates resource links from nested `files[]` arrays\n- Accepts multi-segment item IDs verbatim (e.g. newspaper pages `sn95047246/1935-09-05/ed-1`); returned `url` is always an absolute `https://` URL\n- Fields absent upstream are omitted rather than filled — a sparse record stays sparse\n\n---\n\n### `libofcongress_search_newspapers`\n\nSearch historical newspaper pages in the Chronicling America corpus via the LOC `/newspapers/` endpoint.\n\n- OCR text excerpts (~500 chars) returned inline for relevance assessment without a second hop\n- Filters: keyword, date range, US state (full state name), newspaper publication title (partial match)\n- Returns the `url` field needed by `libofcongress_get_newspaper_page` — do not construct these URLs manually\n- OCR quality varies by digitization batch and era; 19th-century and degraded materials may contain garbled text\n- Empty results include a `notice` with recovery suggestions (broaden date, try different keywords, historical OCR caveat)\n\n---\n\n### `libofcongress_get_newspaper_page`\n\nRetrieve the full OCR text and metadata for a specific newspaper page.\n\n- Accepts the `url` field from a `libofcongress_search_newspapers` result — validates the URL prefix before any outbound request\n- Fetches JSON from the LOC text-services endpoint (`tile.loc.gov`) and reads plain text from the `full_text` field\n- `ocr_available: false` when the page has no digitized text (image-only batch) — not an error, a data property\n- When `ocr_available` is `true` but the text service returns nothing, a notice discloses the retrieval miss on both response surfaces — distinct from a genuinely image-only page\n- Strips echoed `q=` params from fulltext URLs to avoid tile.loc.gov 404s (known LOC API quirk)\n\n---\n\n### `libofcongress_search_subjects`\n\nSearch Library of Congress Subject Headings (LCSH) via `id.loc.gov`.\n\n- Returns standardized labels and stable LOC URIs for subjects matching the keyword\n- `count` field indicates approximate number of LOC items carrying that heading (when available)\n- Use the returned `label` exactly in the `libofcongress_search` `subject` filter — LCSH uses inverted forms (\"Photography, Aerial\", \"World War, 1939-1945\") that differ from natural language\n- Draws from the id.loc.gov suggest endpoint's full 50-candidate pool (not scaled to `limit`) and filters to true LCSH headings, so a heading ranked below name-authority records isn't reported as a false empty; when that ranked pool — rather than a lack of coverage — yields an empty or short result, the response discloses it with a recovery hint\n\n---\n\n### `libofcongress_browse_collections`\n\nList and browse LOC curated digital collections.\n\n- Returns collection `slug` — pass it to `libofcongress_search` as `collection_slug` to search inside that collection\n- Slugs come from the collection's loc.gov route, not its title — `\"Aaron Copland Collection\"` lives at `aaron-copland`, so they aren't guessable\n- Optional keyword filter by collection name/description\n- Item counts are approximate; omitted when the API doesn't provide them\n- Pagination supported up to 100 collections per page\n\n## Resource\n\n| Type | Name | Description |\n|:-----|:-----|:------------|\n| Resource | `libofcongress://item/{+item_id}` | LOC digital item metadata by ID. Stable URI for injecting item context into agent conversations. Returns the same full record as `libofcongress_get_item`. |\n\nAll resource data is also reachable via `libofcongress_get_item`. Use `libofcongress_search` to discover item IDs first.\n\nWrite the item ID with its slashes intact — `libofcongress://item/sn95047246/1935-09-05/ed-1` is the canonical form for a multi-segment newspaper ID. Percent-encoded slashes (`%2F`) also resolve.\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool and resource definitions — single file per primitive, framework handles registration and validation\n- Unified error handling — handlers throw, framework catches, classifies, and formats\n- Pluggable auth: `none`, `jwt`, `oauth`\n- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`\n- Structured logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports\n\nLOC-specific:\n\n- Module-level rate-limit enforcement: 20 req/min limit; 429 responses trigger a 1-hour block with per-minute countdown in error messages\n- Configurable pacing delay (default 3100ms, ~19 req/min) applied before every outbound LOC API request\n- HTML-response detection guards against silent rate-limit proxy pages that return 200 with HTML\n- Out-of-range page handling: LOC returns HTTP 400 or 520 for page numbers beyond the result set — treated as empty rather than errors\n- Transient-fault resilience: network drops and timeouts retry with backoff behind a 30s per-request timeout ceiling; the 429 rate-limit path is never retried, since a retry would deepen LOC's 1-hour block\n- JSON OCR extraction for newspaper text — reads the `full_text` field from LOC text-services responses\n- Two-service architecture: `LocApiService` for `www.loc.gov` and `LcLinkedDataService` for `id.loc.gov`\n\nAgent-friendly output:\n\n- Empty results always include a `notice` field with recovery hints — echoes the applied filters and suggests how to broaden\n- Pagination status on every search response: `total`, `page`, `pages`, `has_next` — capped at LOC's ~100,000-item retrieval ceiling, with a notice disclosing how to page past it\n- `ocr_available` discriminator on newspaper page results so callers can branch on data availability without parsing text\n- Recovery hints on all error contracts — actionable next steps for the agent on every failure mode\n\n## Getting started\n\nAdd the following to your MCP client configuration file.\n\n```json\n{\n \"mcpServers\": {\n \"libofcongress-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/libofcongress-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_SESSION_MODE\": \"stateless\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"libofcongress-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/libofcongress-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_SESSION_MODE\": \"stateless\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"libofcongress-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n \"-e\", \"MCP_SESSION_MODE=stateless\",\n \"ghcr.io/cyanheads/libofcongress-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\n### Prerequisites\n\n- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).\n- No API key required — the LOC JSON API and LC Linked Data endpoints are open. LOC recommends a descriptive `LOC_USER_AGENT` for polite access.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/libofcongress-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd libofcongress-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment:**\n\n```sh\ncp .env.example .env\n# edit .env if you want to set LOC_USER_AGENT or LOC_REQUEST_DELAY_MS\n```\n\n## Configuration\n\nAll configuration is validated at startup via Zod schemas in `src/config/server-config.ts`.\n\n| Variable | Description | Default |\n|:---------|:------------|:--------|\n| `LOC_USER_AGENT` | User-Agent header sent with LOC API requests. LOC recommends a descriptive value for polite access. | `libofcongress-mcp-server/0.2.17` |\n| `LOC_REQUEST_DELAY_MS` | Delay in milliseconds between LOC API requests to stay under the 20 req/min rate limit. | `3100` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_SESSION_MODE` | HTTP session mode. This server is explicitly stateless. | `stateless` |\n| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |\n| `LOGS_DIR` | Directory for log files (Node.js only). | `/logs` |\n| `STORAGE_PROVIDER_TYPE` | Storage backend. | `in-memory` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) (spans, metrics, completion logs). | `false` |\n\nSee [`.env.example`](./.env.example) for the full list of optional overrides.\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n ```sh\n # One-time build\n bun run rebuild\n\n # Run the built server\n bun run start:stdio\n # or\n bun run start:http\n ```\n\n- **Run checks and tests:**\n\n ```sh\n bun run devcheck # Lint, format, typecheck, security\n bun run test # Vitest test suite\n bun run lint:mcp # Validate MCP definitions against spec\n ```\n\n### Docker\n\n```sh\ndocker build -t libofcongress-mcp-server .\ndocker run --rm -p 3010:3010 libofcongress-mcp-server\n```\n\nThe Dockerfile defaults to HTTP transport and logs to `/var/log/libofcongress-mcp-server`.\n\n## Project structure\n\n| Directory | Purpose |\n|:----------|:--------|\n| `src/index.ts` | `createApp()` entry point — registers tools, resource, and initializes services. |\n| `src/config` | Server-specific environment variable parsing (`LOC_USER_AGENT`, `LOC_REQUEST_DELAY_MS`). |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`) — six LOC tools. |\n| `src/mcp-server/resources` | Resource definitions — `libofcongress://item/{+item_id}`. |\n| `src/services/loc-api` | `LocApiService` wrapping `www.loc.gov` — search, item fetch, newspaper page, collection browser. |\n| `src/services/lc-linked-data` | `LcLinkedDataService` wrapping `id.loc.gov` — LCSH subject heading suggest. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n\n## Development guide\n\nSee [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage\n- Register new tools and resources via the arrays in `src/index.ts`\n- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE) for details.\n",
"bytes": 17070,
"sha": "326a9a7f8442ac67c33ced4084d5799616b5e7d2d5cddd573e581a71933211a8",
"repo_slug": "cyanheads/libofcongress-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_libofcongress_mcp_se_fb75d5b6/readme"
}