mcp-open-library

MCP Open Library

AI アシスタントが書籍や著者の情報を検索できるようにする、Open Library API 用の Model Context Protocol（MCP）サーバーです。

概要

このプロジェクトは、AI アシスタントが Open Library を利用するためのツールを提供する MCP サーバーを実装しています。タイトル、著者、件名などのフィールドでカタログを検索したり、名前から著者を検索したり、Open Library キーを使って著者の詳細情報を取得したり、書籍の表紙や著者の写真の URL を取得したりできます。サーバーは Open Library の応答をそのまま返すのではなく、JSON 形式に整えたデータを返します。

機能

• 書籍検索：タイトル、著者、件名、場所、人名、出版社、ISBN で検索し、並べ替えやページ分割もできます（search_books）。
• タイトルによる書籍検索：タイトルを使って書籍を検索します（get_book_by_title）。
• 名前による著者検索：名前を使って著者を検索し、ページ分割できます（get_authors_by_name）。
• 著者の詳細情報取得：Open Library キーを使って特定の著者の詳細情報を取得します（get_author_info）。
• 著者の写真取得：Open Library ID（OLID）を使って著者の写真の URL を取得します（get_author_photo）。
• 書籍の表紙取得：各種識別子（ISBN、OCLC、LCCN、OLID、ID）を使って書籍の表紙画像の URL を取得します（get_book_cover）。
• ID による書籍情報取得：各種識別子（ISBN、LCCN、OCLC、OLID）を使って書籍の詳細情報を取得します（get_book_by_id）。

検索結果はページ分割されます。各検索ツールが返す結果は limit 件まで（デフォルトは 10 件、最大 50 件）で、合致した件数の合計である num_found も返します。offset（最大 1000）を指定してページを切り替えられます。表紙を取得する 2 つのツールは、画像が実際に存在するかを確認し、存在しない場合はその旨を伝えます。空のプレースホルダーに解決される URL を返すことはありません。

すべてのツールは読み取り専用の参照機能であり、readOnlyHint と openWorldHint アノテーションでそのことを示します。そのため、変更を伴う可能性があるツールに対してクライアントが表示する確認プロンプトを省略できる場合があります。これらはあくまでヒントです。MCP 仕様では、サーバーが信頼されていない限り、クライアントはアノテーションを信頼できないものとして扱うため、確認の方針はクライアントが決定します。API に接続できない場合や引数が拒否された場合などのエラーは、isError が付いたツールの結果として返されます。これにより、アシスタントは何が問題だったかを確認し、リクエスト全体が失敗するのではなく、次の呼び出しを修正できます。

インストール

クイックスタート

インストールやビルドは不要です。npx を使って MCP クライアントからパッケージを指定すると、初回実行時に取得されます。

{
  "mcpServers": {
    "mcp-open-library": {
      "command": "npx",
      "args": ["-y", "mcp-open-library"]
    }
  }
}

Claude Desktop では claude_desktop_config.json に設定します。他のクライアントでも同じ形式を使用します。クライアントを再起動すると、以下の 7 つのツールが利用可能になります。

MCP レジストリ

このサーバーは、v1.0.3 以降、公式 MCP レジストリに io.github.8enSmith/mcp-open-library として公開されています。レジストリに 対応したクライアントは、この名前でインストールできます。

公開されたリスティングを確認するには、次のようにします。

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.8enSmith/mcp-open-library"

手動インストール

# Clone the repository
git clone https://github.com/8enSmith/mcp-open-library.git
cd mcp-open-library

# Install dependencies
npm install

# Build the project
npm run build

使用方法

サーバーの実行

1. node v22.23.4 を実行していることを確認します（新しいバージョンの node でもおそらく動作しますが、このテストではこのバージョンを使用しています）。nvm がインストールされている場合は、nvm use を実行します。
2. mcp-open-library のルートディレクトリで npm run build を実行します。
3. 次に npm run inspector を実行します。ビルド後、MCP_PROXY_AUTH_TOKEN クエリ文字列パラメーターが付いた URL をクリックして Inspector を開きます。
4. Inspector で「STDIO」トランスポートを選択します。
5. コマンドが「build/index.js」に設定されていることを確認します。
6. Inspector の「Connect」ボタンをクリックすると、サーバーに接続されます。
7. 右上のメニューバーで「Tools」をクリックします。
8. たとえば、get_book_by_title をクリックしてツールを実行してみます。
9. 本を検索します。たとえば、タイトル欄に「The Hobbit」と入力し、「Run Tool」をクリックします。すると、サーバーが本の詳細を返します。

MCP クライアントでの使用

このサーバーは Model Context Protocol を実装しているため、MCP 互換の AI アシスタントやクライアント（例：Claude Desktop）で使用できます。サーバーは次のツールを公開します。

• search_books：クエリ、タイトル、著者、主題、場所、人物、出版社、ISBN を任意に組み合わせてカタログを検索します
• get_book_by_title：タイトルで本の情報を検索します
• get_authors_by_name：名前で著者の情報を検索します
• get_author_info：Open Library Author Key を使って、特定の著者の詳細情報を取得します
• get_author_photo：Open Library Author ID（OLID）を使って、著者の写真の URL を取得します
• get_book_cover：特定の識別子（ISBN、OCLC、LCCN、OLID、ID）を使って、本の表紙画像の URL を取得します
• get_book_by_id：特定の識別子（ISBN、LCCN、OCLC、OLID）を使って、本の詳細情報を取得します

search_books の入力例：

{
  "author": "Ursula K. Le Guin",
  "subject": "fantasy",
  "sort": "old",
  "limit": 2
}

search_books の出力例：

{
  "num_found": 51,
  "offset": 0,
  "limit": 2,
  "results": [
    {
      "title": "A Wizard of Earthsea",
      "authors": ["Ursula K. Le Guin"],
      "first_publish_year": 1968,
      "open_library_work_key": "/works/OL59798W",
      "edition_count": 87,
      "author_keys": ["OL31353A"],
      "best_edition": {
        "edition_key": "OL5613890M"
      },
      "cover_url": "https://covers.openlibrary.org/b/id/13617691-M.jpg",
      "ratings_average": 3.95,
      "ebook_access": "borrowable"
    }
  ]
}

best_edition は、その作品の特定の版を表します。これは、クエリに対して Open Library が最適と評価した版であり、その版固有の識別子を持ちます。それ以外の検索結果で識別されるのは作品（open_library_work_key）であり、どのツールもこのキーを受け付けません。そのため、検索結果から具体的な本を取得するには、この方法を使います。

edition_key は OLID なので、get_book_by_id にそのまま渡すと、ISBN の全配列を含む版の完全なレコードを取得できます。

{ "idType": "olid", "idValue": "OL5613890M" }

その版について Open Library に ISBN が登録されていない場合、isbn_13／isbn_10 フィールドは省略されます。上記の例や検索結果のおよそ 3 分の 1 が該当します。一方、edition_key はほぼ常に存在します。版に同じ種類の ISBN が複数登録されている場合は、最初の ISBN が返されます。get_book_by_id はすべての ISBN を返します。

search_books ツールは、次のパラメーターを受け付けます。

• q、title、author、subject、place、person、publisher、isbn のいずれかを少なくとも 1 つ指定します。フィルターなしの検索はカタログ全体に一致するため、これらのいずれも指定しないリクエストは拒否されます。q には、subject:cyberpunk AND first_publish_year:[1980 TO 1990] のような自由形式の Solr クエリを指定します
• language：省略可能な 3 文字の MARC 言語コード（例：eng、fre）
• sort：省略可能な並べ替え順。new、old、random、key、rating、readinglog、want_to_read、currently_reading、already_read、title のいずれかを指定します。関連度順にする場合は省略します
• limit：省略可能。1～50。デフォルトは 10 です
• offset：省略可能。0～1000。デフォルトは 0 です

get_book_by_title の入力例：

{
  "title": "The Hobbit",
  "limit": 1
}

get_book_by_title の出力例：

{
  "num_found": 224,
  "offset": 0,
  "limit": 1,
  "results": [
    {
      "title": "The Hobbit",
      "authors": ["J.R.R. Tolkien"],
      "first_publish_year": 1937,
      "open_library_work_key": "/works/OL27482W",
      "edition_count": 481,
      "author_keys": ["OL26320A"],
      "best_edition": {
        "edition_key": "OL51709286M",
        "isbn_13": "9780395520215",
        "isbn_10": "0395520215"
      },
      "cover_url": "https://covers.openlibrary.org/b/id/14627509-M.jpg",
      "ratings_average": 4.29,
      "ebook_access": "borrowable"
    }
  ]
}

get_authors_by_name の入力例：

{
  "name": "J. R. R. Tolkien",
  "limit": 2
}

get_authors_by_name の出力例：

各結果の key を get_author_info に渡すと、その著者の全レコードを取得できます。ここでは alternate_names を省略しています。

{
  "num_found": 2,
  "offset": 0,
  "limit": 2,
  "results": [
    {
      "key": "OL26320A",
      "name": "J.R.R. Tolkien",
      "alternate_names": ["John Ronald Reuel Tolkien", "Tolkien"],
      "birth_date": "3 January 1892",
      "top_work": "The Hobbit",
      "work_count": 355
    },
    {
      "key": "OL332676A",
      "name": "J. R. R. Tolkien Centenary Conference (1992 Keble College, Oxford)",
      "top_work": "Proceedings of the J.R.R. Tolkien Centenary Conference, 1992",
      "work_count": 2
    }
  ]
}

get_author_info の入力例：

{
  "author_key": "OL26320A"
}

get_author_info の出力例：

{
  "name": "J. R. R. Tolkien",
  "personal_name": "John Ronald Reuel Tolkien",
  "birth_date": "3 January 1892",
  "death_date": "2 September 1973",
  "bio": "John Ronald Reuel Tolkien (1892-1973) was a major scholar of the English language, specializing in Old and Middle English. He served as the Rawlinson and Bosworth Professor of Anglo-Saxon and later the Merton Professor of English Language and Literature at Oxford University.",
  "alternate_names": ["John Ronald Reuel Tolkien"],
  "photos": [6791763],
  "key": "/authors/OL26320A",
  "remote_ids": {
    "viaf": "95218067",
    "wikidata": "Q892"
  },
  "revision": 43,
  "last_modified": {
    "type": "/type/datetime",
    "value": "2023-02-12T05:50:22.881"
  }
}

get_author_photo の入力例：

{
  "olid": "OL26320A"
}

get_author_photo の出力例：

https://covers.openlibrary.org/a/olid/OL26320A-L.jpg

Open Library にその著者の写真がない場合、このツールは URL を返す代わりに、その旨を伝えます。

No author photo available for OLID OL99999999A.

get_book_cover の入力例：

{
  "key": "ISBN",
  "value": "9780547928227",
  "size": "L"
}

get_book_cover の出力例：

https://covers.openlibrary.org/b/isbn/9780547928227-L.jpg

著者の写真と同様に、表紙がない書籍の場合は URL の代わりにメッセージが返されます。

No cover image available for OLID OL00000000M.

get_book_cover ツールは、次のパラメーターを受け取ります。

• key：識別子の種類（ISBN、OCLC、LCCN、OLID、ID のいずれか）
• value：識別子の値
• size：任意の表紙サイズ（小は S、中は M、大は L。デフォルトは L）

get_book_by_id の入力例：

{
  "idType": "isbn",
  "idValue": "9780547928227"
}

get_book_by_id の出力例：

{
  "title": "The Hobbit",
  "authors": [
    "J. R. R. Tolkien"
  ],
  "publishers": [
    "Houghton Mifflin Harcourt"
  ],
  "publish_date": "October 21, 2012",
  "number_of_pages": 300,
  "isbn_13": [
    "9780547928227"
  ],
  "isbn_10": [
    "054792822X"
  ],
  "oclc": [
    "794607877"
  ],
  "olid": [
    "OL25380781M"
  ],
  "open_library_edition_key": "/books/OL25380781M",
  "open_library_work_key": "/works/OL45883W",
  "cover_url": "https://covers.openlibrary.org/b/id/8231496-M.jpg",
  "info_url": "https://openlibrary.org/books/OL25380781M/The_Hobbit",
  "preview_url": "https://archive.org/details/hobbit00tolkien"
}

get_book_by_id ツールは、次のパラメーターを受け取ります。

• idType：識別子の種類（isbn、lccn、oclc、olid のいずれか）
• idValue：識別子の値

このツールを Claude Desktop で使用する例はこちらをご覧ください。

Docker

この MCP サーバーは Docker を使用してテストできます。まず、次を実行します。

docker build -t mcp-open-library .
docker run -p 8080:8080 mcp-open-library

その後、たとえばインスペクターを使って、Docker 内で実行中のサーバーをテストできます。

npm run inspector http://localhost:8080

開発

プロジェクト構成

• src/index.ts - MCP サーバー。HTTP クライアントを構築し、ツールレジストリの両方のリクエストハンドラーを実行します
• src/index.test.ts - 公開されているツールスキーマのスナップショットを含む、サーバーの配線に関するテスト
• src/tools/<tool-name>/ - ツールごとのディレクトリ。それぞれに index.ts（ハンドラー、Zod 引数スキーマ、および ToolDefinition）、index.test.ts、そして複雑な API レスポンスを扱うツールの場合は、そのレスポンス形式を記述した types.ts が含まれます
• src/tools/registry.ts - サーバーが公開するものをまとめた唯一のリストである TOOLS 配列
• src/tools/types.ts - ToolDefinition と ToolHandler のコントラクト
• src/utils/ - 共通処理：http.ts（API および表紙用の Axios クライアント）、errors.ts（引数の解析とエラー結果）、results.ts、schema.ts（Zod → JSON Schema）、search.ts（共通の検索投影とページングスキーマ）、covers.ts
• scripts/ - リリース自動化（sync-server-json.mjs、promote-changelog.mjs、assert-release-consistency.mjs）とそのテスト

ツールの入力コントラクトは、Zod スキーマとして一度だけ宣言します。MCP クライアントに表示される JSON Schema は toInputSchema によって生成されるため、両者にずれが生じることはありません。フィールドの説明は、Zod スキーマの .describe() から取得されます。.refine() の制約は変換時に削除されるため、フィールド間のルールはツールの description にも記載する必要があります。そうしないと、クライアントには伝わりません。

ツールを追加するには、そのディレクトリを作成し、src/tools/registry.ts の TOOLS にエントリーを1つ追加します。src/index.test.ts はこの配列から期待値を導出するため、テストでの変更はスキーマスナップショットの更新のみです（npx vitest run -u）。

利用可能なスクリプト

• npm run build - TypeScript コードをビルドします
• npm run watch - 変更を監視して再ビルドします
• npm test - テストスイートをウォッチモードで実行します
• npm run test:precommit - テストスイートを一度実行して終了します
• npm run lint / npm run lint:fix - ESLint で src と scripts をリントします
• npm run format - Prettier でコードをフォーマットします
• npm run inspector - MCP Inspector をサーバーに対して実行します

テストの実行

npm test を実行すると、Vitest がウォッチモードで起動します。

npm test

1回だけ実行する場合（プリコミットフックと CI で実行される方法）は、次を使用します。

npm run test:precommit

ファイルまたはテストケースを1つだけ実行するには、次を使用します。

npx vitest run src/tools/get-book-by-id/index.test.ts
npx vitest run -t "should return book details when given a valid OLID"

リリース

リリースは自動化されています。v* タグをプッシュすると、 publish-mcp.yml が実行され、チェックの実行、npm へのパッケージの公開、MCP Registry への新しいバージョンの登録を行い、その後、そのバージョンの CHANGELOG.md のセクションをリリースノートとして GitHub Release を作成します。npm とレジストリはどちらも GitHub OIDC で認証するため、公開用のシークレットを管理する必要はありません。

package.json の version が唯一の信頼できる情報源です。version ライフサイクルフックによって npm version がそこから他のすべてを導出するため、リリースは次の1つのコマンドで行えます。

npm version patch   # or minor / major
git push --follow-tags

このコマンド1つで package.json のバージョンを更新し、それに合わせて server.json を書き換え、変更履歴の ## [Unreleased] 見出しを新しいバージョンと本日の日付に更新して、それらすべてを1つのタグのもとでコミットします。

実行する前に、次の2点を確認してください。

• まず変更履歴の項目を記述してください。 作業をマージする際、CHANGELOG.md の ## [Unreleased] 見出しの下に記述します。この見出しがない場合、npm version はリリースを行わずに失敗します。失敗した場合は、git restore --source=HEAD --staged --worktree package.json package-lock.json server.json で部分的なバージョン更新を取り消してください。
• 作業ツリーはクリーンな状態である必要があります。また、npm version の実行中にコミット前フック（lint + 全テストスイート）が実行されます。

CI は公開前に、タグ、package.json、server.json、CHANGELOG.md の内容がすべて一致していることを再確認します。詳しくは scripts/assert-release-consistency.mjs を参照してください。同じチェックは、これらのファイルを変更するプルリクエストでも実行されます。

npm version は再試行用のコマンドではありません

新しいタグが出力された時点で、コミットとタグが作成され、ローカルでのリリースは完了しています。次の手順は git push --follow-tags であり、npm version を再度実行することではありません。2回目の実行では次のバージョンが試されますが、最初の実行で消費された ## [Unreleased] 見出しがないため失敗します。この失敗は安全な設計ですが、package.json、package-lock.json、server.json のバージョンは更新されたまま、コミットされずに残ります。次のコマンドで元に戻してください。

git restore --source=HEAD --staged --worktree package.json package-lock.json server.json

公開ワークフローが失敗した場合

Actions タブからジョブを再実行して効果があるのは、一時的な障害の場合だけです。GitHub はタグが指すコミット時点のワークフローを実行するため、ワークフロー自体または server.json の不具合は再実行では修正できません。修正は、タグが指すコミットに含める必要があります。

ワークフローが npm の手順に到達するまで、何も公開されません。その前に失敗した場合は、バージョンがまだ未使用のため、タグを移動できます。

# fix the problem on main and commit it first
VERSION="$(node -p "require('./package.json').version")"

git push origin ":v${VERSION}"            # delete the remote tag e.g. git push origin :v1.0.3
git tag -d "v${VERSION}"                  # delete it locally
git tag -a "v${VERSION}" -m "${VERSION}"  # re-tag at the fixed commit
git push origin "v${VERSION}"

修正コミットでは package.json のバージョンを同じバージョンのままにする必要があります。そうでない場合、整合性チェックでタグが拒否されます。npm への公開がすでに完了している場合は、そのバージョンを再利用しないでください。リリースは変更できません。代わりに次のパッチバージョンに上げてください。npm の手順にはガードがあるため、再実行時にはすでに成功した処理はスキップされます。

貢献

貢献を歓迎します。お気軽にプルリクエストを送信してください。

謝辞

• Open Library API
• Model Context Protocol