https://github.com/jianyun8023/calibre-api

Faster calibre query downloads, based on meilisearch.
https://github.com/jianyun8023/calibre-api

calibre fast meilisearch

Last synced: 2 months ago
JSON representation

Faster calibre query downloads, based on meilisearch.

• Host: GitHub
• URL: https://github.com/jianyun8023/calibre-api
• Owner: jianyun8023
• License: mit
• Created: 2022-08-05T05:45:52.000Z (over 3 years ago)
• Default Branch: main
• Last Pushed: 2026-01-16T06:53:40.000Z (2 months ago)
• Last Synced: 2026-01-16T18:51:37.292Z (2 months ago)
• Topics: calibre, fast, meilisearch
• Language: TypeScript
• Homepage:
• Size: 21.8 MB
• Stars: 4
• Watchers: 2
• Forks: 1
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE
  • Agents: AGENTS.md

Awesome Lists containing this project

README

          
# Calibre-API

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

## ✨ 核心特性

### 📚 书籍管理

- 使用 Calibre Content Server 作为数据来源

- Qdrant 增强查询响应速度

- 支持书籍元数据的 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）

## 📚 文档导航

**开发指南**:

- [AGENTS.md](./AGENTS.md) - AI 助手快速参考

- [CHANGELOG.md](./CHANGELOG.md) - 版本变更历史

**用户文档** (`docs/` 目录):

- [快速开始](./docs/QUICK_START.md) - 部署和配置指南

- [API 文档](./docs/API_DOCUMENTATION.md) - RESTful API 参考

- [系统架构](./docs/ARCHITECTURE.md) - 系统架构设计

- [开发指南](./docs/DEVELOPMENT_GUIDE.md) - 代码规范和开发流程

- [代码结构](./docs/CODE_STRUCTURE.md) - 项目目录说明

- [MCP 指南](./docs/MCP_README.md) - MCP 协议集成和使用

- [MCP Inspector](./docs/features/MCP_INSPECTOR_GUIDE.md) - MCP 工具测试指南

- [Qdrant 配置](./docs/QDRANT_COLLECTION_SETUP.md) - 向量数据库设置

**前端开发**:

- [Next.js 前端](./web-next/README.md) - Next.js 15 + Shadcn/UI (推荐)

## 🚀 快速开始

### 运行模式

#### 1. HTTP API 模式（默认）

```bash

# 构建和运行

make build

./calibre-api

```

#### 2. MCP 智能交互模式

```bash

# 使用命令行参数

./calibre-api --mcp

# 使用环境变量

MCP_MODE=true ./calibre-api

# 使用配置文件

# 在 config.yaml 中设置 mcp.enabled: true

./calibre-api

```

### 🤖 AI 助手集成

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

```json

{

  "mcpServers": {

    "calibre-api": {

      "command": "/path/to/calibre-api",

      "args": ["--mcp"]

    }

  }

}

```

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

- *"搜索关于机器学习的书籍"*

- *"帮我更新书籍 ID 123 的元数据"*

- *"推荐几本随机书籍"*

- *"根据 ISBN 获取书籍信息"*

## 📖 API 接口

```text

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 指南](docs/MCP_README.md)

## 🔨 构建和部署

### 本地构建

```bash

# 构建主程序（包含 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 配置，支持前后端分离部署：

```bash

# 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

```

**服务访问**:

- 前端 (Next.js): http://localhost:3000

- 后端 API (Go): http://localhost:8080

- Qdrant 管理界面: http://localhost:6333/dashboard (使用 --profile qdrant 时)

**架构说明**:

- `calibre-api`: Go 后端服务，提供 RESTful API

- `calibre-web`: Next.js 前端服务，提供现代化 UI

- `qdrant`: 可选的向量数据库服务（使用 profile 启用）

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

详细的部署指南请参考：[快速开始](./docs/QUICK_START.md)

#### 手动 Docker 部署

```bash

# 构建后端镜像

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](https://github.com/jianyun8023/calibre-api/releases) 页面下载预构建的二进制文件：

- `calibre-api-*` - 主程序（包含 MCP 功能）

- `calibre-mcp-server-*` - 独立 MCP 服务器

## 配置

### 配置文件

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

- `/etc/calibre-api/config.yaml`

- `$HOME/.calibre-api`

- `./config.yaml`

配置内容

```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:

  doubanurl: https://api.douban.com

# 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)

```bash

# 基础配置

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_DOUBANURL=http://your-douban-api

# MCP 配置

CALIBRE_MCP_ENABLED=false

MCP_MODE=true                    # 快速启用 MCP 模式

```

#### 前端环境变量 (calibre-web)

```bash

# 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` 访问后端

- 详细配置说明请参考 [快速开始](./docs/QUICK_START.md)

## 适配阅读书源

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

```json

{

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

  }

}

```

## 📚 文档

- **[快速开始指南](docs/QUICK_START.md)** - 详细的设置和部署指南

- **[MCP 使用文档](docs/MCP_README.md)** - AI 助手集成的完整说明

- **[API 参考](docs/API_DOCUMENTATION.md)** - RESTful API 接口文档

## 🎯 使用场景

### 1. 个人书库管理

- 通过 Web 界面管理和搜索书籍

- 下载和预览书籍内容

- 元数据编辑和补全

### 2. AI 智能助手

- 自然语言搜索书籍

- AI 驱动的阅读推荐

- 智能元数据处理

### 3. 书源集成

- 作为阅读 APP 的书源

- API 接口供第三方应用调用

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License