libofcongress-mcp-server

---

概述

美国国会图书馆（LOC）数字馆藏、Chronicling America 历史报纸和 LC 主题词。搜索条目和报纸页面，读取完整元数据和 OCR 文本，解析主题词，并浏览精选馆藏。

工具

工具	描述
libofcongress_search_items	按关键词搜索 LOC 数字馆藏，并可按格式、日期范围、主题、位置和馆藏筛选。
libofcongress_get_item	获取特定 LOC 数字条目的完整元数据，包括印记、贡献者、主题、权利、格式、数字资源及分页的页面列表。
libofcongress_search_newspapers	搜索 Chronicling America 语料库中的历史报纸页面，并提供每页开头 OCR 文本的摘录。
libofcongress_get_newspaper_page	获取一个页面的完整文本和元数据——报纸页面，或通过 libofcongress_get_item 获取的书籍或手稿页面；也可仅获取搜索词周围的段落。
libofcongress_search_subjects	按关键词搜索美国国会图书馆主题词（LCSH）。
libofcongress_browse_collections	列出并浏览 LOC 精选数字馆藏，也可按关键词筛选。

资源

资源	描述
libofcongress://item/{+item_id}	按 ID 获取 LOC 数字馆藏项目元数据——用于将项目上下文注入 Agent 对话的稳定 URI。

所有资源数据也可通过 libofcongress_get_item 获取。请先使用 libofcongress_search_items 查找项目 ID。

功能参考

libofcongress_search_items _工具

• 筛选条件：八种资料格式（photo、map、newspaper、manuscript、audio、film、book、notated-music）、包含起止年份的年份范围（date_start/date_end）、subject（来自 libofcongress_search_subjects 的 LCSH 标题或分面词）、地点，以及 collection_slug（来自 libofcongress_browse_collections，不能与 format 同时使用）；每页最多返回 100 条结果——较大的 limit（最多 1000）会按 100 条返回，并附带 effectiveLimit 和提示
• 每条结果都包含 LOC 编目的 date 和 is_item：对于可通过 libofcongress_get_item 解析其 id 的目录项目，值为 true；对于合集、展览／指南页面、报纸页面、catalog.loc.gov 记录和 hdl.loc.gov 查找工具，值为 false，应改为打开其 url
• include_facets: true 会添加 subject_facets 和 location_facets（LOC 在所有匹配项中排名前 10 的词条及各自的项目数）；默认关闭，因为这会减慢每次搜索。无结果时的提示会列出所应用的主题词和地点

---

libofcongress_get_item _工具

• 接受搜索结果的 id（简单 ID 或多段 ID，例如 sn95047246/1935-09-05/ed-1）、loc.gov 项目链接或 lccn.loc.gov 永久链接；其他 URL 均会在发起任何请求前被拒绝，并返回 invalid_item_id
• 返回 imprint、带角色的贡献者、LCSH subject_headings、subject_terms（搜索 subject 筛选条件接受的小写词条）、注释、摘要、语言、地点、纯文本形式的 rights_information、实体描述、索书号、曾用 ID、格式和 access_restricted；上游不存在的字段会省略
• resources 列出每项数字资源及其页数、image、pdf 和 audio（MP3）。pages 默认每次列出 50 页（page_offset、page_limit、page_total、next_page_offset；每次最多 100 页——较大的 page_limit（最多 1000）会按 100 页返回，并附带 effectivePageLimit 和提示），每页都包含 page_url 和 has_text，可通过 libofcongress_get_newspaper_page 读取。include_files: true 会添加每页的下载 URL

---

libofcongress_search_newspapers _工具

• 筛选条件：关键词、精确到日的包含起止日期范围（date_start/date_end 接受整数年份，或 YYYY、YYYY-MM、YYYY-MM-DD 格式的字符串）、美国州名（全称或邮政缩写），以及报纸标题（搜索结果中的确切 newspaper_title）；每页最多返回 100 条结果——较大的 limit（最多 1000）会按 100 条返回，并附带 effectiveLimit 和提示
• 每条结果都包含页面 OCR 文本开头约 500 个字符、states，以及可原样传给 libofcongress_get_newspaper_page 的 url
• 摘录取自页面开头，而非匹配内容附近；请将相同查询作为 match 传给 libofcongress_get_newspaper_page，以获取匹配内容附近的段落

---

libofcongress_get_newspaper_page _工具

• 接受来自 libofcongress_search_newspapers 结果的 url，或来自 libofcongress_get_item 的 pages[].page_url（报纸、书籍和手稿页面均可），以及 Chronicling America 页面链接；如果链接未指向某个具体页面、来自其他主机，或路径或 sp 格式错误，则会在发起任何请求前以 invalid_page_url 拒绝
• 将页面文本作为 ocr_text 返回，并包含 newspaper_title、date、place_of_publication、states、edition、sequence、segment_count、item_title 和 item_id（将其传给 libofcongress_get_item 以列出该项目的页面）。ocr_available: false 表示这是仅有图像的页面；如果结果为空，notice 会说明原因：文本服务未响应（请重试）、无法将正文读取为文本，或页面为空白
• match 仅返回包含某个词语的上下文段落——请传入你搜索时使用的查询词。空格分隔的词语会被视为不同的词，双引号括起来的部分则视为一个短语，匹配时不区分大小写。matches 最多包含 10 段，每个匹配项前后约 300 个字符；match_count 统计所有匹配项，ocr_text 为空；如果没有匹配项，或部分匹配项不在返回的上下文段落中，notice 会予以说明

---

libofcongress_search_subjects _工具

• 关键词查询，每次调用最多返回 50 条结果（默认 10 条；将 limit 设为更大的值，最多 1000，会返回最多 50 条并附带提示）；返回授权的 LCSH label 和稳定的 LOC uri，完全匹配的结果优先
• 将标签原样传入 libofcongress_search_items 的 subject 过滤器。对于部分词语（例如 aerial photog），会回退到查找以该词语开头的主题标题

---

libofcongress_browse_collections _工具

• 可按合集名称和描述进行可选关键词过滤；每页最多显示 100 个合集——如果 limit 更大（最多 1000），则以 100 个合集为一页返回，并附带 effectiveLimit 和提示
• 每个合集都带有一个 slug，用于 libofcongress_search_items 的 collection_slug（取自 loc.gov 路由，无法根据标题推导）；item_count 为近似值，如果 LOC 未提供则会省略

---

libofcongress://item/{+item_id} _资源

• 以 application/json 格式返回与 libofcongress_get_item 相同的记录，包含前 50 个页面但不含文件；next_page_offset 标记了 libofcongress_get_item 的 page_offset 后续读取位置
• item_id 来自 libofcongress_search_items 结果中的 id；任何非项目 ID 都会以 invalid_item_id 拒绝。包含多个路径段的报纸 ID 会保留斜杠（libofcongress://item/sn95047246/1935-09-05/ed-1）

特性

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并提供结构化日志记录和可选的 OpenTelemetry 跟踪。

美国国会图书馆专属功能：

• 在 www.loc.gov 前设置请求队列：调用按到达顺序开始，间隔至少为 LOC_REQUEST_DELAY_MS（默认 3100ms，约 19 次请求/分钟），且绝不超过 LOC 每分钟 20 次的限制。无法及时开始的调用会失败并返回 server_busy，同时附带 retryAfter
• 速率限制处理：收到 429 响应会触发 LOC 的 1 小时封锁；封锁解除前，调用会直接失败，不会发送任何请求（且不会重试）。如果遇到 Cloudflare 验证挑战，或返回的不是 JSON 而是 HTML 页面，则会失败并返回 upstream_unavailable，同时附带 retryAfter: 60。libofcongress_search_subjects（id.loc.gov）不受影响
• 每次工具调用的 50 秒时限涵盖队列等待、重试和 OCR 获取；因此，上游响应缓慢时会失败并返回 request_timed_out。其他上游故障（连接中断、5xx 或 403、响应正文为空或被截断）会失败并返回 upstream_unavailable，同时附带重试提示
• 超出结果范围或检索上限的页面会返回带有提示的空结果，而不是错误
• 报纸 OCR 内容按原样提供；19 世纪或质量较差的页面可能包含乱码

便于 Agent 使用的输出：

• 空结果会包含 notice，其中提供恢复提示并回显已应用的筛选条件
• 每个搜索响应都包含分页状态（total、page、pages、has_next），结果最多达到 LOC 约 100,000 条的检索上限
• ocr_available 和 is_item 允许调用方无需解析文本即可进行分支处理
• 每个类型化错误都附带恢复提示

快速开始

公共托管实例

公共实例位于 https://libofcongress.caseyjhand.com/mcp，无需安装。通过 Streamable HTTP 将任意 MCP 客户端指向该实例：

{
  "mcpServers": {
    "libofcongress-mcp-server": {
      "type": "streamable-http",
      "url": "https://libofcongress.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "libofcongress-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/libofcongress-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_SESSION_MODE": "stateless",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 npx（无需 Bun）：

{
  "mcpServers": {
    "libofcongress-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/libofcongress-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_SESSION_MODE": "stateless",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可以使用 Docker：

{
  "mcpServers": {
    "libofcongress-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "MCP_SESSION_MODE=stateless",
        "ghcr.io/cyanheads/libofcongress-mcp-server:latest"
      ]
    }
  }
}

如需使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置要求

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥——LOC JSON API 和 LC 关联数据端点均开放。LOC 建议设置描述性 LOC_USER_AGENT，以便礼貌访问。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/libofcongress-mcp-server.git

2. 进入目录：

cd libofcongress-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env if you want to set LOC_USER_AGENT or LOC_REQUEST_DELAY_MS

配置

所有配置都会在启动时通过 src/config/server-config.ts 中的 Zod 架构进行验证。

变量	说明	默认值
LOC_USER_AGENT	随 LOC API 请求发送的 User-Agent 请求头。LOC 建议使用描述性值，以便礼貌访问。	libofcongress-mcp-server/0.5.1
LOC_REQUEST_DELAY_MS	LOC API 请求之间的延迟时间（毫秒），以遵守每分钟 20 次请求的速率限制。	3100
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_SESSION_MODE	HTTP 会话模式。此服务明确采用无状态模式。	stateless
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用参数和结果，按键名进行脱敏，并限制为 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES 字节（默认 16384）。自由格式值中的机密不会被脱敏。	false
STORAGE_PROVIDER_TYPE	存储后端。	in-memory
OTEL_ENABLED	启用 OpenTelemetry 检测（追踪、指标、完成日志）。	false

请参阅 .env.example 查看所有可选覆盖项。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t libofcongress-mcp-server .
docker run --rm -p 3010:3010 libofcongress-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/libofcongress-mcp-server。默认会安装 OpenTelemetry 对等依赖项 — 构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点 — 注册工具和资源，并初始化服务。
src/config	服务专用环境变量解析（LOC_USER_AGENT、LOC_REQUEST_DELAY_MS）。
src/mcp-server/tools	工具定义（*.tool.ts）— 六个 LOC 工具。
src/mcp-server/resources	资源定义 — libofcongress://item/{+item_id}。
src/services/loc-api	封装 www.loc.gov 的 LocApiService — 搜索、获取条目、页面文本、馆藏浏览器。
src/services/lc-linked-data	封装 id.loc.gov 的 LcLinkedDataService — LCSH 主题标题建议。
tests/	与 src/ 目录结构对应的单元测试和集成测试。

开发指南

请参阅 CLAUDE.md 了解开发指南和架构规则。简要来说：

• 处理器抛出异常，框架负责捕获 — 工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围的日志，使用 ctx.state 存储租户范围的数据
• 通过 src/index.ts 中的数组注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；切勿编造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。