Skip to content

About

Faster calibre query downloads, based on meilisearch.

Topics

calibrefastmeilisearch

Resources

Readme
MIT license
Activity

Stars

4 stars

Watchers

2 watching

Forks

1 fork
Report repository
BranchesTags

Repository files navigation

Calibre-API

基于 MeiliSearch 搭建的 Calibre 书籍管理系统，支持搜索、下载、预览和智能交互。

✨ 核心特性

📚 书籍管理

  • 使用 Calibre Content Server 作为数据来源
  • MeiliSearch 提供快速全文搜索和语义搜索
  • 支持书籍元数据的 CRUD 操作
  • 在线元数据获取和补全
  • 封面图片和文件下载

🤖 AI 智能交互（MCP 支持）

  • MCP (Model Context Protocol) 集成 - 与 AI 助手无缝交互
  • 自然语言操作 - 通过对话管理书籍
  • 智能推荐 - AI 驱动的书籍推荐
  • 双模式部署 - 支持集成模式和独立模式
  • 详细参数说明 - 为所有 API 接口提供完整的参数文档

🎨 现代化前端

  • 两套前端实现:
    • Next.js 15 + Shadcn/UI (推荐，现代化设计)
      • React 19 + TypeScript 5
      • Tailwind CSS 4 + Glassmorphism
      • Vercel AI SDK 流式对话
      • react-reader EPUB 阅读器
      • 10 个完整页面（首页、书籍列表、详情、阅读器、搜索、对话、设置、任务、出版社、元数据管理）
    • Vue.js 3 + Element Plus (旧版，稳定维护)
  • 响应式设计 - 支持桌面端和移动端
  • 暗黑模式 - 自动适配系统主题

🔧 开发特性

  • RESTful API 接口
  • Docker 容器化部署
  • 多平台二进制发布
  • 完整的 CI/CD 流程
  • 静态文件托管（支持 Vue/Next.js）

📚 文档导航

开发指南:

用户文档 (docs/ 目录):

前端开发:

🚀 快速开始

运行模式

1. HTTP API 模式（默认）

# 构建和运行
make build
./calibre-api

2. MCP 智能交互模式

# 使用命令行参数
./calibre-api --mcp

# 使用环境变量
MCP_MODE=true ./calibre-api

# 使用配置文件
# 在 config.yaml 中设置 mcp.enabled: true
./calibre-api

🤖 AI 助手集成

配置 Claude Desktop 或其他 MCP 客户端：

{
  "mcpServers": {
    "calibre-api": {
      "command": "/path/to/calibre-api",
      "args": ["--mcp"]
    }
  }
}

现在您可以通过自然语言与 AI 助手交互：

  • "搜索关于机器学习的书籍"
  • "帮我更新书籍 ID 123 的元数据"
  • "推荐几本随机书籍"
  • "根据 ISBN 获取书籍信息"

📖 API 接口

GET    /api/get/cover/:id            --> 获取书籍封面
GET    /api/download/book/:id             --> 下载书籍文件
GET    /api/read/:id/toc             --> 获取书籍目录（包含元信息、目录和地址）
GET    /api/read/:id/file/*path      --> 读取书籍中的文件
GET    /api/book/:id                 --> 获取书籍信息
GET    /api/search                   --> 搜索书籍
POST   /api/search                   --> 搜索书籍
GET    /api/recently                 --> 最近更新的书籍
GET    /api/random                   --> 随机书籍推荐
GET    /api/publisher                --> 获取出版社列表
GET    /api/metadata/isbn/:isbn      --> 根据 ISBN 获取元数据
GET    /api/metadata/search          --> 搜索在线元数据
POST   /api/book/:id/update          --> 更新书籍元数据
POST   /api/book/:id/delete          --> 删除书籍
POST   /api/index/update             --> 更新搜索索引
POST   /api/index/switch             --> 切换搜索索引

接口

MCP 参数说明改进

本项目对 gin-mcp 包进行了增强，为所有 API 接口提供了详细的参数说明。这使得 AI 助手能够更好地理解和使用这些接口。

改进内容

  1. 参数结构体定义 - 在 internal/calibre/schemas.go 中定义了所有接口的参数结构体
  2. jsonschema 标签 - 为每个参数添加了详细的描述和约束
  3. 自动注册 - 在启动时自动为所有接口注册参数模式

示例对比

改进前：

参数：q (string)
参数：limit (number)
参数：offset (number)

改进后：

参数：q (string, required) - 搜索关键词
参数：limit (number, 1-100, default=20) - 每页结果数量
参数：offset (number, >=0, default=0) - 结果偏移量
参数：filter (string, optional) - 过滤条件
参数：sort (string, optional) - 排序字段

使用方法

  1. 启动服务器：./calibre-api
  2. 在 MCP 客户端（如 Cursor）中连接到 http://localhost:8080/mcp
  3. 所有 API 工具都会包含详细的参数说明

详细文档请参考：MCP 指南

🔨 构建和部署

本地构建

# 构建主程序（包含 MCP 功能）
make build

# 构建独立 MCP 服务器
make build-mcp

# 构建所有版本  
make build-all

# 直接使用 Go 构建
go build -o calibre-api .
go build -o calibre-mcp-server ./cmd/mcp-server

Docker 部署

使用 Docker Compose（推荐）

项目提供了完整的 Docker Compose 配置，支持前后端分离部署：

# 1. 基础部署（前端 + 后端）
docker-compose up -d

# 2. 完整部署（包含 Qdrant 向量数据库）
docker-compose --profile qdrant up -d

# 3. 查看服务状态
docker-compose ps

# 4. 查看日志
docker-compose logs -f

# 5. 停止服务
docker-compose down

服务访问:

架构说明:

  • calibre-api: Go 后端服务，提供 RESTful API
  • calibre-web: Next.js 前端服务，提供现代化 UI
  • qdrant: 可选的向量数据库服务（使用 profile 启用）

前端通过 Docker 内部网络访问后端，环境变量 API_BASE_URL=http://calibre-api:8080 配置了服务间通信（代理会自动拼接 /api/:path* 路径）。

详细的部署指南请参考：快速开始

手动 Docker 部署

# 构建后端镜像
docker build -t calibre-api:latest -f Dockerfile .

# 构建前端镜像
docker build -t calibre-web:latest -f web-next/Dockerfile ./web-next

# 运行后端容器
docker run -d -p 8080:8080 \
  -e CALIBRE_CONTENT_SERVER=https://lib.pve.icu \
  -v calibre_data:/data \
  calibre-api:latest

# 运行前端容器
docker run -d -p 3000:3000 \
  -e API_BASE_URL=http://calibre-api:8080 \
  --link calibre-api \
  calibre-web:latest

预构建二进制

从 Releases 页面下载预构建的二进制文件：

  • calibre-api-* - 主程序（包含 MCP 功能）
  • calibre-mcp-server-* - 独立 MCP 服务器

配置

配置文件

配置文件会按优先级从下面查找:

  • /etc/calibre-api/config.yaml
  • $HOME/.calibre-api
  • ./config.yaml

配置内容

address: :8080
debug: false
staticDir: "/app/static"
tmpDir: ".files"

# Calibre Content Server 配置
content:
  server: https://lib.pve.icu

# Qdrant 搜索引擎配置
qdrant:
  url: http://localhost:6333
  collection: books
  timeout: 30

# 元数据服务配置
metadata:
  doubanmode: local  # "local"（本地爬虫，推荐）或 "http"（HTTP 服务）
  doubanurl: http://your-douban-api:8085  # HTTP 模式时需要，local 模式可省略
  # doubanconfig:  # local 模式可选配置，以下为默认值，通常不需要修改
  #   baseurl: https://book.douban.com/
  #   searchurl: https://www.douban.com/search?cat={searchType}&q={searchText}
  #   isbnurl: https://book.douban.com/isbn/{isbn}/
  #   detailurl: https://book.douban.com/subject/{id}/

# MCP 服务器配置
mcp:
  enabled: false                        # 是否默认启用 MCP 模式
  server_name: "calibre-mcp-server"     # MCP 服务器名称
  version: "1.1.0"                      # MCP 服务器版本  
  base_url: "http://localhost:8080"     # API 基础 URL
  timeout: 30                           # API 请求超时时间（秒）

环境变量

环境变量优先于配置文件，可以使用环境变量覆盖配置文件中的参数

后端环境变量 (calibre-api)

# 基础配置
CALIBRE_ADDRESS=:8080
CALIBRE_DEBUG=false
CALIBRE_TMPDIR=/tmp
CALIBRE_SEARCH_INDEX=books

# Calibre Content Server（必需）
CALIBRE_CONTENT_SERVER=https://your-calibre-server.com

# Qdrant 配置（可选，启用向量搜索时配置）
CALIBRE_QDRANT_URL=http://qdrant:6333
CALIBRE_QDRANT_API_KEY=your-api-key

# OpenAI 配置（可选，启用 AI 功能时配置）
OPENAI_API_KEY=sk-your-api-key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4

# 元数据服务
CALIBRE_METADATA_DOUBANMODE=local  # 或 "http"
CALIBRE_METADATA_DOUBANURL=http://your-douban-api  # HTTP 模式时需要

# MCP 配置
CALIBRE_MCP_ENABLED=false
MCP_MODE=true                    # 快速启用 MCP 模式

前端环境变量 (calibre-web)

# API 配置（必需）
# Docker Compose 环境使用服务名（基础 URL，不包含路径）
API_BASE_URL=http://calibre-api:8080

# 本地开发环境使用 localhost
# API_BASE_URL=http://localhost:8080

# Node.js 配置
NODE_ENV=production
PORT=3000
TZ=Asia/Shanghai

重要提示:

  • Docker Compose 环境中，前端使用 http://calibre-api:8080 访问后端（Docker 服务名）
  • 本地开发环境中，前端使用 http://localhost:8080 访问后端
  • 详细配置说明请参考 快速开始

适配阅读书源

支持添加书源的APP可以使用下面配置，将本服务引入

{
  "bookSourceUrl": "http://localhost:8080",
  "bookSourceType": 0,
  "bookSourceName": "calibre书库",
  "bookSourceGroup": "calibre",
  "bookSourceComment": "",
  "loginUrl": "",
  "loginUi": "",
  "loginCheckJs": "",
  "concurrentRate": "",
  "header": "",
  "bookUrlPattern": "",
  "searchUrl": "search?q={{key}}&sort=id:desc",
  "exploreUrl": "",
  "enabled": true,
  "enabledExplore": false,
  "weight": 0,
  "customOrder": 0,
  "lastUpdateTime": 1661322926750,
  "ruleSearch": {
    "bookList": "$.hits",
    "name": "$.title",
    "author": "$.authors",
    "intro": "$.comments",
    "coverUrl": "/get/cover/{{$.id}}.jpg",
    "bookUrl": "/book/{{$.id}}"
  },
  "ruleExplore": {},
  "ruleBookInfo": {
    "name": "$.title",
    "author": "$.authors",
    "intro": "$.comments",
    "coverUrl": "/get/cover/{{$.id}}.jpg",
    "tocUrl": "/read/{{$.id}}/toc"
  },
  "ruleToc": {
    "chapterList": "$.points",
    "chapterName": "$.text",
    "chapterUrl": "$.content.src"
  },
  "ruleContent": {
    "content": "//body"
  }
}

📚 文档

🎯 使用场景

1. 个人书库管理

  • 通过 Web 界面管理和搜索书籍
  • 下载和预览书籍内容
  • 元数据编辑和补全

2. AI 智能助手

  • 自然语言搜索书籍
  • AI 驱动的阅读推荐
  • 智能元数据处理

3. 书源集成

  • 作为阅读 APP 的书源
  • API 接口供第三方应用调用

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

About

Faster calibre query downloads, based on meilisearch.

Topics

calibrefastmeilisearch

Resources

Readme
MIT license
Activity

Stars

4 stars

Watchers

2 watching

Forks

1 fork
Report repository

Releases

Packages

Used by

Contributors

Languages