spines

SPINES MCP サーバー

Model Context Protocol を通じて、AI アシスタントから SPINES の書籍コレクション、読書リスト、書棚データにアクセスできます。

機能

• 書棚の写真から本を認識します。同じ書棚の写真を複数枚送ると、1 つのコレクションになります
• タイトル、著者、ISBN で本を検索します
• 書籍コレクションを表示し、絞り込みます
• 読書リストを管理します（本の追加と削除）
• ペルソナ、カテゴリー、一緒に書棚に並べられることの多い本を調べます
• 書棚の分析や本のおすすめに使える AI プロンプト

クイックスタート

前提条件

• Node.js 18+
• SPINES API キー（こちらから取得）

インストール

npm install -g @spines/mcp-server

設定

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "spines": {
      "command": "npx",
      "args": ["-y", "@spines/mcp-server"],
      "env": {
        "SPINES_API_KEY": "gtspn_live_your_key_here"
      }
    }
  }
}

VS Code / Cursor

MCP の設定に追加します。

{
  "spines": {
    "command": "npx",
    "args": ["-y", "@spines/mcp-server"],
    "env": {
      "SPINES_API_KEY": "gtspn_live_your_key_here"
    }
  }
}

環境変数

変数	必須	デフォルト	説明
SPINES_API_KEY	はい	-	API キー
SPINES_API_URL	いいえ	https://getspines.com/api/v1	API のベース URL
SPINES_DEBUG	いいえ	false	stderr への詳細なログ出力
SPINES_LLM_PROVIDER	いいえ	-	recognize_bookshelf 用に独自の LLM キーを使用します。受け付ける値は gemini のみです。SPINES_LLM_API_KEY と合わせて設定してください
SPINES_LLM_API_KEY	いいえ	-	プロバイダーの API キーです。両方設定すると、認識に独自のキーを使用し、SPINES クレジットを消費しません

ツール

読み取りツール

ツール	説明
search_books	タイトル、著者、ISBN で本を検索します
get_book_details	特定の本の詳細情報を取得します
get_collection	すべての本を含む書籍コレクションを取得します
list_collections	オプションのフィルターを指定して、コレクションの一覧を取得します
list_categories	承認済みの書籍カテゴリーをすべて一覧表示します
get_persona	ペルソナの詳細情報を取得します
get_book_pairings	ある本と一緒に書棚に並べられることの多い本を探します（Shelfology）
check_credits	1 日あたりの認識クレジット残高を確認します

書き込みツール

ツール	説明
add_to_reading_list	本を読書リストに追加します
remove_from_reading_list	本を読書リストから削除します
recognize_bookshelf	1 枚以上の書棚写真から本を認識し、コレクションとして保存します（クレジットを使用）

ツールの詳細

search_books

query: string    - Search query (title, author, or ISBN)
limit?: number   - Max results (1-50, default 10)

get_book_details

book_id: string  - The book's unique ID

get_collection

collection_id: string  - The collection's unique ID

list_collections

limit?: number        - Max results (1-50, default 20)
cursor?: string       - Pagination cursor
persona_id?: string   - Filter by persona
category_id?: string  - Filter by category

list_categories

(no arguments)

get_persona

persona_id: string  - The persona's unique ID

get_book_pairings

book_id: string  - The book to find pairings for
limit?: number   - Max results (1-50, default 10)

check_credits

(no arguments)

add_to_reading_list

book_id: string      - The book to add
list_name?: string   - List name (default: "want_to_read")

remove_from_reading_list

entry_id: string     - The reading list entry ID to remove

recognize_bookshelf

image_url?: string     - URL of a single photo
image_base64?: string  - Base64-encoded single photo
images?: array         - Several photos of one bookshelf, saved as ONE collection;
                         each entry is { image_url } or { image_base64 }
cover_index?: number   - Zero-based index into images of the cover photo (default 0)
title?: string         - Title for the new collection

image_url / image_base64 または images のいずれかを指定してください。両方は指定しないでください。例：

{
  "images": [
    { "image_url": "https://example.com/shelf-left.jpg" },
    { "image_url": "https://example.com/shelf-right.jpg" }
  ],
  "cover_index": 1,
  "title": "Living room"
}

• 写真の上限： 通常のキーでは、1 回のリクエストにつき 4 枚までです。2 枚の写真に写っている本は 1 冊として扱われます。
• クレジット： 写真 1 枚につき 1 クレジットを使用します。リクエストの開始には、少なくとも 1 クレジットが必要です。SPINES_LLM_PROVIDER / SPINES_LLM_API_KEY を設定した場合、クレジットは消費されません。
• URL を推奨します。 合計 4 MB を超える Base64 写真は、1 回のリクエストに収まりません。
• 重複： SPINES にすでに登録されている写真があると、リクエスト全体が失敗します（RECOGNIZE_IMAGE_DUPLICATE と、その写真のインデックスが返されます）。
• 処理時間： このツールは、サーバーがすべての写真を読み取る間待機し、その後、本の照合が完了するまでポーリングします（最長 2 分）。照合が完了すると、完成したコレクションを返します。照合がまだ進行中の場合、またはステータスを読み取れなかった場合は、ジョブの現在のステータス（job_id を含む）を返します。最初の手順でタイムアウトした場合（5 分）、コレクションが作成されている可能性があります。再試行すると再びクレジットを使用するため、再試行する前に list_collections を確認してください。

リソース

URI	説明
spines://collection/{id}	メタデータを含む書籍コレクション
spines://book/{id}	書籍の詳細情報
spines://persona/{id}	ペルソナのプロフィールとコレクション
spines://reading-lists	ユーザーの読書リスト

プロンプト

プロンプト	説明
analyze_shelf	コレクションのテーマと読書パターンを分析します
recommend_books	ライブラリに基づいておすすめを取得します
compare_collections	2つのコレクションの類似点を比較します

トラブルシューティング

問題	解決方法
"SPINES_API_KEY is required"	MCP クライアントの設定で環境変数を設定してください
401 エラー	API キーが有効で、有効期限が切れていないことを確認してください
403 エラー	キーに必要なスコープがない可能性があります
429 エラー	レート制限に達しました — 待ってから再試行してください
recognize_bookshelf の TIMEOUT	サーバーはまだ処理中の可能性があります。再送信する前に list_collections を確認してください
ツールが表示されない	MCP クライアントを再起動してください

開発

git clone https://github.com/GetSpines/mcp-server
cd mcp-server
npm install
npm run build
npm test

ライセンス

MIT