libofcongress-mcp-server

---

概要

米国議会図書館のデジタルコレクション、Chronicling America の歴史的新聞、LC 件名標目を利用できます。資料や新聞ページを検索し、メタデータと OCR テキストの全文を読み、件名語を解決し、厳選されたコレクションを閲覧できます。

ツール

ツール	説明
libofcongress_search_items	キーワードに加えて、形式、日付範囲、件名、場所、コレクションのフィルターを使って LOC のデジタルコレクションを検索します。
libofcongress_get_item	特定の LOC デジタル資料の全メタデータ（出版事項、寄稿者、件名、権利、形式、デジタルリソース、およびページ分割されたページ一覧）を取得します。
libofcongress_search_newspapers	Chronicling America のコーパスから歴史的な新聞ページを検索し、各ページ冒頭の OCR テキストの抜粋を表示します。
libofcongress_get_newspaper_page	1 ページ分の全文とメタデータ（新聞ページ、または libofcongress_get_item で取得した書籍や原稿のページ）を取得するか、検索語の前後にある箇所のみを取得します。
libofcongress_search_subjects	Library of Congress Subject Headings（LCSH）をキーワードで検索します。
libofcongress_browse_collections	LOC が厳選したデジタルコレクションを一覧表示して閲覧します。必要に応じてキーワードで絞り込めます。

リソース

リソース	説明
libofcongress://item/{+item_id}	ID による LOC デジタルアイテムのメタデータ — アイテムのコンテキストをエージェントとの会話に挿入するための安定した URI です。

すべてのリソースデータは libofcongress_get_item からも取得できます。まず libofcongress_search_items を使ってアイテム ID を見つけてください。

機能リファレンス

libofcongress_search_items _ツール

• フィルター：8 種類の資料形式（photo、map、newspaper、manuscript、audio、film、book、notated-music）、包含的な年の範囲（date_start／date_end）、subject（libofcongress_search_subjects の LCSH 件名標目またはファセット用語）、場所、collection_slug（libofcongress_browse_collections から取得。format とは併用できません）。1 ページあたり最大 100 件です。より大きな limit（最大 1000）を指定した場合は、effectiveLimit と通知を付けて 100 件として返されます
• 各結果には、LOC の目録に記載されている date と is_item が含まれます。is_item は、libofcongress_get_item で ID を解決できる目録アイテムの場合は true、コレクション、展示／ガイドページ、新聞ページ、catalog.loc.gov のレコード、hdl.loc.gov の検索補助資料の場合は false です。後者の場合は url を開いてください
• include_facets: true を指定すると subject_facets と location_facets が追加されます（一致するすべての結果から取得した LOC の上位 10 件の用語と、それぞれのアイテム数）。検索のたびに処理が遅くなるため、デフォルトでは無効です。結果が 0 件の場合は、適用された件名用語と場所を通知に示します

---

libofcongress_get_item _ツール

• 検索結果の id（単一または複数セグメント。例：sn95047246/1935-09-05/ed-1）、LOC アイテムのリンク、または lccn.loc.gov のパーマリンクを受け取ります。それ以外の URL は、リクエストを行う前に invalid_item_id として拒否されます
• imprint、役割付きの寄稿者、LCSH の subject_headings、検索の subject フィルターで受け付けられる小文字の用語である subject_terms、注記、概要、言語、場所、プレーンテキスト形式の rights_information、物理的な説明、請求記号、旧 ID、形式、access_restricted を返します。上流データに存在しないフィールドは省略されます
• resources には各デジタルリソースのページ数、image、pdf、audio（MP3）が一覧表示されます。pages はデフォルトで一度に 50 ページを一覧表示します（page_offset、page_limit、page_total、next_page_offset。1 回の呼び出しで最大 100 ページまでです。より大きな page_limit（最大 1000）を指定した場合は、effectivePageLimit と通知を付けて 100 ページとして返されます）。各ページには、libofcongress_get_newspaper_page で読み取れる page_url と has_text が含まれます。include_files: true を指定すると、各ページのダウンロード URL が追加されます

---

libofcongress_search_newspapers _ツール

• フィルター：キーワード、日単位まで指定できる包含的な日付範囲（date_start／date_end には整数の年、または YYYY、YYYY-MM、YYYY-MM-DD 形式の文字列を指定）、米国の州（正式名称または郵便番号）、新聞のタイトル（検索結果の正確な newspaper_title）。1 ページあたり最大 100 件です。より大きな limit（最大 1000）を指定した場合は、effectiveLimit と通知を付けて 100 件として返されます
• 各結果には、ページの 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 も返します（item_id を libofcongress_get_item に渡すと、そのアイテムのページ一覧を取得できます）。ocr_available: false は画像のみのページを示します。結果が空の場合は、テキストサービスから応答がなかった（再試行してください）、本文をテキストとして読み取れなかった、またはページが空白であることを notice で説明します
• match は検索語の周辺の文章のみを返します。検索に使用したクエリを渡してください。空白で区切られた単語は個別の検索語として扱われ、二重引用符で囲まれた範囲は1つのフレーズとして、大文字と小文字を区別せずに照合されます。matches には各出現箇所の前後約300文字を含む文章が最大10件格納され、match_count はすべての出現箇所を数えます。ocr_text は空になります。一致がなかった場合や、一部の出現箇所が文章の範囲外にある場合は notice で通知されます

---

libofcongress_search_subjects _ツール

• キーワードクエリを受け付け、1回の呼び出しにつき最大50件を返します（デフォルトは10件です。limit を大きくして最大1000にすると、最大50件が返され、notice が付きます）。正式な LCSH の label と、変わらない LOC の uri を返します。一致が完全なものが先に表示されます
• label をそのまま libofcongress_search_items の subject フィルターに渡してください。一部分の単語（aerial photog など）の場合は、その語で始まる見出しにフォールバックします

---

libofcongress_browse_collections _ツール

• コレクション名と説明に対する任意のキーワードフィルターを受け付けます。1ページにつき最大100件のコレクションを返します。より大きな limit（最大1000）を指定した場合は、100件のページとして返され、effectiveLimit と notice が付きます
• 各コレクションには、libofcongress_search_items の collection_slug に使用する slug が含まれます（タイトルから導出するのではなく、loc.gov のルートから取得します）。item_count は概数であり、LOC が提供していない場合は省略されます

---

libofcongress://item/{+item_id} _リソース

• libofcongress_get_item と同じレコードを application/json として返します。最初の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 トレーシングに対応した構造化ロギングを備えています。

Library of Congress 固有の機能：

• www.loc.gov の前段にリクエストキューを設置しています。呼び出しは到着順に開始され、開始間隔は少なくとも LOC_REQUEST_DELAY_MS（デフォルトは 3100ms、約 19 リクエスト／分）です。LOC の 1 分あたり 20 件の上限を超えることはありません。時間内に開始できない呼び出しは、retryAfter を伴う server_busy として失敗します
• レート制限への対応：429 が返ると LOC による 1 時間のブロックが発生し、解除されるまでリクエストを送信せずに呼び出しが失敗します（再試行は行いません）。JSON の代わりに Cloudflare チャレンジまたは HTML ページが返された場合は、retryAfter: 60 を伴う upstream_unavailable として失敗します。libofcongress_search_subjects（id.loc.gov）は影響を受けません
• ツール呼び出しごとに 50 秒の予算が設定されており、キュー待ち、再試行、OCR の取得を含みます。そのため、アップストリームの応答が遅い場合は request_timed_out として失敗します。それ以外のアップストリームエラー（接続切断、5xx または 403、空または途中で切れたレスポンス本文）は、再試行のヒントを伴う upstream_unavailable として失敗します
• 結果の末尾を超えたページや取得上限を超えたページは、エラーではなく通知付きの空の結果を返します
• 新聞の OCR は加工せずに返されます。19 世紀のページや劣化したページでは、文字化けしたテキストが含まれる場合があります

エージェントに適した出力：

• 結果が空の場合、適用したフィルターを反映した復旧のヒントを含む notice が返されます
• すべての検索レスポンスには、LOC の約 100,000 件の取得上限を適用したページネーションの状態（total、page、pages、has_next）が含まれます
• 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 Linked Data エンドポイントは公開されています。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	20 req/min のレート制限を超えないようにするための、LOC API リクエスト間の遅延時間（ミリ秒）です。	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 instrumentation（スパン、メトリクス、完了ログ）を有効にします。	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 ツールが 6 つあります。
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 を参照してください。