spines

SPINES MCP Server

通过 Model Context Protocol，让 AI 助手访问 SPINES 图书收藏、阅读清单和书架数据。

功能

• 根据书架照片识别图书；同一书架的多张照片会合并为一个收藏
• 按书名、作者或 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	查看你的每日识别额度余额

写入工具

工具	描述
add_to_reading_list	将图书添加到阅读清单
remove_from_reading_list	从阅读清单中移除图书
recognize_bookshelf	根据一张或多张书架照片识别图书，并将其保存为收藏（会消耗额度）

工具详情

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"
}

• 照片数量限制： 使用普通密钥时，每个请求最多 4 张。同一本书出现在两张照片中时只会保留一次。
• 额度： 每张照片消耗一个额度；请求开始时至少需要一个额度。设置 SPINES_LLM_PROVIDER / SPINES_LLM_API_KEY 后，不会消耗额度。
• 优先使用 URL。 总大小超过 4 MB 的 Base64 照片无法放入同一个请求。
• 重复照片： SPINES 中已有的照片会导致整个请求失败（RECOGNIZE_IMAGE_DUPLICATE，并附上该照片的索引）。
• 耗时： 工具会等待服务器读取每张照片，然后持续轮询，直到图书匹配完成（最长 2 分钟）。匹配完成后会返回收藏；如果匹配仍在进行，或无法读取其状态，则会返回任务当前状态（含 job_id）。如果第一步超时（5 分钟），收藏仍可能已创建：请先检查 list_collections 再重试，因为重试会再次消耗额度。

资源

URI	描述
spines://collection/{id}	包含元数据的藏书集
spines://book/{id}	完整的图书详情
spines://persona/{id}	Persona 资料和藏书集
spines://reading-lists	用户的阅读列表

提示词

提示词	描述
analyze_shelf	分析藏书集中的主题和阅读模式
recommend_books	根据你的藏书获取推荐
compare_collections	比较两个藏书集的相似之处

故障排除

问题	解决方案
"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