Spines

io.github.SuperAgentic由 GitHub 帳號 SuperAgentic 發布v1.1.0更新於 Oct 24, 2026

Access book collections, reading lists, and bookshelf recognition from AI assistants.

已驗證STDIO僅桌面知識與記憶媒體與設計

概覽

AI 產生的概覽

把 AI 助理連接到 SPINES 書籍收藏,可搜尋書籍、瀏覽書櫃、管理閱讀清單,並從書櫃照片辨識書籍。

可以做什麼
  • 依書名、作者或 ISBN 搜尋書籍並查看書籍詳細資料
  • 瀏覽收藏、分類與人物檔案,找出常被擺在一起的書籍
  • 將書籍加入閱讀清單或從中移除
  • 從一張或多張書櫃照片辨識書籍並存成一個收藏
  • 查詢每日辨識額度餘額
  • 以資源形式提供收藏、書籍、人物檔案與閱讀清單,並提供書櫃分析、推薦與收藏比較提示詞
適用情境
適合已在使用 SPINES 書庫、希望助理協助查書、整理閱讀清單,或把實體書櫃照片轉成數位收藏並進行分析與推薦的情境。
執行需求
透過 npm 套件 @spines/mcp-server 在本機執行,需要 Node.js 18 以上版本,並在 Claude Desktop、VS Code 或 Cursor 等 MCP 用戶端中設定。需要 SPINES API 金鑰,放在 SPINES_API_KEY 環境變數中。選用設定:SPINES_API_URL、SPINES_DEBUG,以及 SPINES_LLM_PROVIDER 與 SPINES_LLM_API_KEY。需要能連線到 SPINES API 的網路。
安裝前請注意
API 金鑰是有效憑證,會存放在用戶端設定中,請妥善保管。recognize_bookshelf 每張照片消耗一個額度,逾時後重試可能再次消耗額度,重試前先查看收藏清單。它也會寫入資料:建立收藏並修改閱讀清單。以連結或 base64 送出的照片會傳給 SPINES,重複照片會導致整個請求失敗。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Spines,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

SPINES MCP Server

Access SPINES book collections, reading lists, and bookshelf data from AI assistants via the Model Context Protocol.

Features

  • Recognize books from photos of a bookshelf; several photos of one shelf become one collection
  • Search books by title, author, or ISBN
  • Browse and filter book collections
  • Manage reading lists (add and remove books)
  • Explore personas, categories, and books commonly shelved together
  • AI prompts for shelf analysis and book recommendations

Quick Start

Prerequisites

Installation

bash
npm install -g @spines/mcp-server

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Add to your MCP settings:

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

Environment Variables

VariableRequiredDefaultDescription
SPINES_API_KEYYes-Your API key
SPINES_API_URLNohttps://getspines.com/api/v1API base URL
SPINES_DEBUGNofalseVerbose logging to stderr
SPINES_LLM_PROVIDERNo-Bring your own LLM key for recognize_bookshelf; only gemini is accepted. Set together with SPINES_LLM_API_KEY
SPINES_LLM_API_KEYNo-Your provider API key. With both set, recognition uses your key and no SPINES credits

Tools

Read Tools

ToolDescription
search_booksSearch for books by title, author, or ISBN
get_book_detailsGet full details for a specific book
get_collectionGet a book collection with all its books
list_collectionsList your collections with optional filters
list_categoriesList all approved book categories
get_personaGet details about a persona
get_book_pairingsFind books commonly shelved together with a book (Shelfology)
check_creditsCheck your daily recognition credit balance

Write Tools

ToolDescription
add_to_reading_listAdd a book to a reading list
remove_from_reading_listRemove a book from a reading list
recognize_bookshelfRecognize books from one or more bookshelf photos and save them as a collection (uses credits)

Tool Details

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 cursorpersona_id?: string   - Filter by personacategory_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 forlimit?: number   - Max results (1-50, default 10)
check_credits
(no arguments)
add_to_reading_list
book_id: string      - The book to addlist_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 photoimage_base64?: string  - Base64-encoded single photoimages?: 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

Send either image_url / image_base64 or images, not both. Example:

json
{  "images": [    { "image_url": "https://example.com/shelf-left.jpg" },    { "image_url": "https://example.com/shelf-right.jpg" }  ],  "cover_index": 1,  "title": "Living room"}
  • Photo limit: 4 per request with a regular key. A book that appears on two photos is kept once.
  • Credits: each photo uses one credit; the request needs at least one to start. With SPINES_LLM_PROVIDER / SPINES_LLM_API_KEY set, no credits are used.
  • Prefer URLs. Base64 photos over 4 MB in total do not fit in one request.
  • Duplicates: a photo already in SPINES fails the whole request (RECOGNIZE_IMAGE_DUPLICATE, with the index of that photo).
  • Timing: the tool waits while the server reads every photo, then polls until book matching finishes (up to 2 minutes). It returns the finished collection, or the job's current status (with its job_id) if matching is still running or its status could not be read. If the first step times out (5 minutes), the collection may still be created: check list_collections before trying again, since a retry uses credits again.

Resources

URIDescription
spines://collection/{id}A book collection with metadata
spines://book/{id}Full book details
spines://persona/{id}Persona profile and collections
spines://reading-listsUser's reading lists

Prompts

PromptDescription
analyze_shelfAnalyze a collection for themes and reading patterns
recommend_booksGet recommendations based on your library
compare_collectionsCompare two collections for similarities

Troubleshooting

ProblemSolution
"SPINES_API_KEY is required"Set the env var in your MCP client config
401 errorsCheck your API key is valid and not expired
403 errorsYour key may lack required scopes
429 errorsRate limited — wait and retry
TIMEOUT from recognize_bookshelfThe server may still be working; check list_collections before resending
Tools not appearingRestart your MCP client

Development

bash
git clone https://github.com/GetSpines/mcp-servercd mcp-servernpm installnpm run buildnpm test

License

MIT

來源:README.md,提交 64fb770

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

3
  1. v1.1.0最新Oct 14, 2026
  2. v1.0.3Oct 14, 2026
  3. v1.0.2Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分