access-calibre 1.0.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# access-calibre
+
+> [!NOTE]
+> This package has been entirely vibe-coded by Junie in JetBrains IntelliJ and not human checked.
+
+A JavaScript library to connect to a local Calibre Content Server and grab portions of ebooks.
+
+## Installation
+
+```bash
+npm install access-calibre
+```
+
+## Usage
+
+You can use it as a library in your project:
+
+```javascript
+const CalibreClient = require('./src/client');
+
+const client = new CalibreClient('http://localhost:8080', 'username', 'password');
+
+async function example() {
+    // List libraries
+    const libraries = await client.getLibraries();
+    const libraryId = Object.keys(libraries)[0];
+
+    // List books
+    const books = await client.getBooks(libraryId);
+    
+    // Get EPUB contents
+    const bookId = books.book_ids[0];
+    const files = await client.getEpubContents(libraryId, bookId);
+    console.log('Files in EPUB:', files);
+
+    // Get a specific file (e.g., a chapter) from the EPUB
+    const html = await client.getEpubFile(libraryId, bookId, 'index_split_001.html');
+    console.log(html);
+}
+```
+
+## API
+
+### `new CalibreClient(baseUrl, username, password)`
+Initialize the client.
+
+### `client.getLibraries()`
+Returns an object containing information about available libraries.
+
+### `client.getBooks(libraryId, limit, offset)`
+Returns a list of book IDs and their metadata for the specified library.
+
+### `client.getBookMetadata(libraryId, bookId)`
+Returns detailed metadata for a specific book.
+
+### `client.downloadBook(libraryId, bookId, format)`
+Downloads the book in the specified format (e.g., 'EPUB', 'PDF') and returns a Buffer.
+
+### `client.getEpubContents(libraryId, bookId)`
+Returns a list of file paths inside the EPUB file.
+
+### `client.getTOC(libraryId, bookId)`
+Returns an array of `{ title, path }` objects representing the book's Table of Contents.
+
+### `client.getChapters(libraryId, bookId)`
+Returns an array of `{ title, path }` objects representing the book's chapters in their linear reading order (as defined in the EPUB spine).
+
+### `client.getEpubFile(libraryId, bookId, filePath, responseType)`
+Extracts a specific file from the EPUB and returns its content as a string (default) or Buffer (if `responseType` is `'buffer'`).
+
+## Scripts
+
+### `get-chapter.js`
+Extracts the XML/HTML content of a chapter to the console.
+```bash
+node get-chapter.js <book_id_or_title> <chapter_index_or_title>
+```
+
+### `render-chapter.js`
+Renders a specific page from a chapter to a PNG image using Playwright.
+```bash
+node render-chapter.js <book_id_or_title> <chapter_index_or_title> [output.png] [--page <number>]
+```
+- `--page <number>`: Optional. Specifies which page of the chapter to render (default is 1).
+- If no output filename is provided, it defaults to `chapter_render.png`.
+
+Note: You may need to run `npx playwright install chromium` before using this script.
+
+## MCP Server
+
+This library includes an MCP (Model Context Protocol) server that allows LLMs to interact with your Calibre library.
+
+### Tools Provided:
+- `list_libraries`: List available libraries.
+- `search_books`: Search for books by title or author across all libraries.
+- `list_books`: List all books in a library.
+- `list_chapters`: List the chapters of a book in reading order.
+- `get_chapter_content`: Retrieve the HTML content of a specific chapter.
+- `render_chapter_page`: Render a specific page of a chapter as a PNG image (useful for LLMs with vision capabilities). It also returns the total number of pages in the chapter.
+- `get_book_cover`: Retrieve the cover image of a book as a PNG image.
+- `get_epub_file`: Retrieve any file from the EPUB (e.g. CSS, images).
+
+### Configuration
+The MCP server can be configured via environment variables:
+- `CALIBRE_URL`: The URL of your Calibre Content Server (default: `http://[::1]:8080/`).
+- `CALIBRE_USERNAME`: Optional username for authentication.
+- `CALIBRE_PASSWORD`: Optional password for authentication.
+
+### Running the MCP Server
+
+#### Claude Desktop
+
+You can run the MCP server directly using `npx` (useful for Claude Desktop or other MCP clients):
+
+```bash
+npx access-calibre
+```
+
+#### LM Studio
+
+To use this MCP server in LM Studio:
+
+1. Open **LM Studio**.
+2. Click on the **Tools** icon (puzzle piece) in the left sidebar.
+3. Click **+ Add Tool**.
+4. Choose **MCP Server**.
+5. Give it a name (e.g., `access-calibre`).
+6. For **Command**, enter `npx`.
+7. For **Arguments**, enter `access-calibre`.
+8. Add any required environment variables (like `CALIBRE_URL`) in the **Environment Variables** section.
+9. Click **Add Tool**.
+
+Alternatively, you can add it to your `mcp-config.json` (usually found in `~/.lmstudio/mcp-config.json`):
+
+```json
+{
+  "mcpServers": {
+    "access-calibre": {
+      "command": "npx",
+      "args": ["access-calibre"],
+      "env": {
+        "CALIBRE_URL": "http://localhost:8080/"
+      }
+    }
+  }
+}
+```
+
+#### Local Installation
+
+```bash
+npm run start:mcp
+```
+
+Or directly via Node:
+```bash
+CALIBRE_URL=http://localhost:8080 node mcp-server.js
+```
+
+## Running Tests
+
+```bash
+npm test
+```

package/index.js

@@ -0,0 +1,4 @@
+const CalibreClient = require('./src/client');
+
+module.exports = CalibreClient;
+

package/mcp-server.js

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListToolsRequestSchema,
+  McpError,
+} = require("@modelcontextprotocol/sdk/types.js");
+const CalibreClient = require("./index");
+
+const CALIBRE_URL = process.env.CALIBRE_URL || "http://[::1]:8080/";
+const CALIBRE_USERNAME = process.env.CALIBRE_USERNAME || null;
+const CALIBRE_PASSWORD = process.env.CALIBRE_PASSWORD || null;
+
+const client = new CalibreClient(CALIBRE_URL, CALIBRE_USERNAME, CALIBRE_PASSWORD);
+
+const server = new Server(
+  {
+    name: "calibre-reader",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "list_libraries",
+        description: "List available Calibre libraries",
+        inputSchema: {
+          type: "object",
+          properties: {
+            // Some MCP clients/LLMs struggle with empty properties
+            _config: {
+              type: "object",
+              description: "Optional configuration (unused)",
+            },
+          },
+          required: [],
+        },
+      },
+      {
+        name: "search_books",
+        description: "Search for books across all libraries by title or author fragment",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description: "Title or author fragment to search for",
+            },
+          },
+          required: ["query"],
+        },
+      },
+      {
+        name: "list_books",
+        description: "List books in a specific library",
+        inputSchema: {
+          type: "object",
+          properties: {
+            libraryId: {
+              type: "string",
+              description: "The ID of the library",
+            },
+            limit: {
+              type: "number",
+              description: "Maximum number of books to return (default 100)",
+            },
+            offset: {
+              type: "number",
+              description: "Offset for pagination (default 0)",
+            },
+          },
+          required: ["libraryId"],
+        },
+      },
+      {
+        name: "list_chapters",
+        description: "List chapters (reading order) of a specific book",
+        inputSchema: {
+          type: "object",
+          properties: {
+            libraryId: {
+              type: "string",
+              description: "The ID of the library",
+            },
+            bookId: {
+              type: "number",
+              description: "The ID of the book",
+            },
+          },
+          required: ["libraryId", "bookId"],
+        },
+      },
+      {
+        name: "get_chapter_content",
+        description: "Get the HTML content of a specific chapter",
+        inputSchema: {
+          type: "object",
+          properties: {
+            libraryId: {
+              type: "string",
+              description: "The ID of the library",
+            },
+            bookId: {
+              type: "number",
+              description: "The ID of the book",
+            },
+            path: {
+              type: "string",
+              description: "The internal file path of the chapter (from list_chapters)",
+            },
+          },
+          required: ["libraryId", "bookId", "path"],
+        },
+      },
+      {
+        name: "render_chapter_page",
+        description: "Render a specific page of a chapter as a PNG image",
+        inputSchema: {
+          type: "object",
+          properties: {
+            libraryId: {
+              type: "string",
+              description: "The ID of the library",
+            },
+            bookId: {
+              type: "number",
+              description: "The ID of the book",
+            },
+            path: {
+              type: "string",
+              description: "The internal file path of the chapter (from list_chapters)",
+            },
+            page: {
+              type: "number",
+              description: "The page number to render (default 1)",
+            },
+          },
+          required: ["libraryId", "bookId", "path"],
+        },
+      },
+      {
+        name: "get_book_cover",
+        description: "Get the cover image of a book as a PNG",
+        inputSchema: {
+          type: "object",
+          properties: {
+            libraryId: {
+              type: "string",
+              description: "The ID of the library",
+            },
+            bookId: {
+              type: "number",
+              description: "The ID of the book",
+            },
+          },
+          required: ["libraryId", "bookId"],
+        },
+      },
+      {
+        name: "get_epub_file",
+        description: "Retrieve any file from the EPUB (e.g. CSS, images)",
+        inputSchema: {
+          type: "object",
+          properties: {
+            libraryId: {
+              type: "string",
+              description: "The ID of the library",
+            },
+            bookId: {
+              type: "number",
+              description: "The ID of the book",
+            },
+            path: {
+              type: "string",
+              description: "The internal file path in the EPUB",
+            },
+          },
+          required: ["libraryId", "bookId", "path"],
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "list_libraries": {
+        const libraries = await client.getLibraries();
+        return {
+          content: [{ type: "text", text: JSON.stringify(libraries, null, 2) }],
+        };
+      }
+
+      case "search_books": {
+        if (!args.query) {
+          throw new McpError(ErrorCode.InvalidParams, "Query is required");
+        }
+        const query = args.query.toLowerCase();
+        const libraries = await client.getLibraries();
+        const results = [];
+
+        for (const libraryId of Object.keys(libraries)) {
+          const books = await client.getBooks(libraryId);
+          if (Array.isArray(books)) {
+            for (const book of books) {
+              const title = (book.title || "").toLowerCase();
+              const authors = Array.isArray(book.authors) 
+                ? book.authors.join(", ").toLowerCase() 
+                : (book.authors || "").toLowerCase();
+              
+              if (title.includes(query) || authors.includes(query)) {
+                results.push({
+                  libraryId,
+                  libraryName: libraries[libraryId],
+                  bookId: book.id || book.application_id,
+                  title: book.title,
+                  authors: book.authors
+                });
+              }
+            }
+          }
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+      }
+
+      case "list_books": {
+        if (!args.libraryId) {
+          throw new McpError(ErrorCode.InvalidParams, "libraryId is required");
+        }
+        const books = await client.getBooks(args.libraryId, args.limit || 100, args.offset || 0);
+        return {
+          content: [{ type: "text", text: JSON.stringify(books, null, 2) }],
+        };
+      }
+
+      case "list_chapters": {
+        if (!args.libraryId || !args.bookId) {
+          throw new McpError(ErrorCode.InvalidParams, "libraryId and bookId are required");
+        }
+        const chapters = await client.getChapters(args.libraryId, args.bookId);
+        return {
+          content: [{ type: "text", text: JSON.stringify(chapters, null, 2) }],
+        };
+      }
+
+      case "get_chapter_content": {
+        if (!args.libraryId || !args.bookId || !args.path) {
+          throw new McpError(ErrorCode.InvalidParams, "libraryId, bookId and path are required");
+        }
+        const content = await client.getEpubFile(args.libraryId, args.bookId, args.path);
+        return {
+          content: [{ type: "text", text: content }],
+        };
+      }
+      
+      case "render_chapter_page": {
+        if (!args.libraryId || !args.bookId || !args.path) {
+          throw new McpError(ErrorCode.InvalidParams, "libraryId, bookId and path are required");
+        }
+        const { buffer, totalPages } = await client.renderChapterPage(
+          args.libraryId,
+          args.bookId,
+          args.path,
+          args.page || 1
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Page ${args.page || 1} of ${totalPages}`,
+            },
+            {
+              type: "image",
+              data: buffer.toString("base64"),
+              mimeType: "image/png",
+            },
+          ],
+        };
+      }
+
+      case "get_book_cover": {
+        if (!args.libraryId || !args.bookId) {
+          throw new McpError(ErrorCode.InvalidParams, "libraryId and bookId are required");
+        }
+        const buffer = await client.getBookCover(args.libraryId, args.bookId);
+        return {
+          content: [
+            {
+              type: "image",
+              data: buffer.toString("base64"),
+              mimeType: "image/png",
+            },
+            {
+              type: "text",
+              text: `Cover image for book ID ${args.bookId} in library ${args.libraryId}`,
+            }
+          ],
+        };
+      }
+
+      case "get_epub_file": {
+        if (!args.libraryId || !args.bookId || !args.path) {
+          throw new McpError(ErrorCode.InvalidParams, "libraryId, bookId and path are required");
+        }
+        
+        const isImage = /\.(png|jpe?g|gif|webp)$/i.test(args.path);
+        const responseType = isImage ? 'buffer' : 'text';
+        
+        const content = await client.getEpubFile(args.libraryId, args.bookId, args.path, responseType);
+        
+        if (isImage) {
+          const mimeType = args.path.toLowerCase().endsWith('.png') ? 'image/png' : 'image/jpeg';
+          return {
+            content: [
+              {
+                type: "image",
+                data: content.toString("base64"),
+                mimeType: mimeType,
+              },
+            ],
+          };
+        }
+        
+        return {
+          content: [{ type: "text", text: content }],
+        };
+      }
+
+      default:
+        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    if (error instanceof McpError) {
+      throw error;
+    }
+    return {
+      content: [{ type: "text", text: `Error: ${error.message}` }],
+      isError: true,
+    };
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Calibre Reader MCP server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Server error:", error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "access-calibre",
+  "version": "1.0.0",
+  "description": "A JavaScript library and MCP server to connect to a local Calibre Content Server and grab portions of ebooks.",
+  "main": "index.js",
+  "bin": {
+    "access-calibre": "./mcp-server.js"
+  },
+  "files": [
+    "index.js",
+    "mcp-server.js",
+    "src",
+    "README.md",
+
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "jest",
+    "start:mcp": "node mcp-server.js"
+  },
+  "keywords": ["mcp", "calibre", "llm", "book", "books"],
+  "author": "kybernetikos <me@kybernetikos.com>",
+  "license": "MIT",
+  "type": "commonjs",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "adm-zip": "^0.5.16",
+    "axios": "^1.13.4",
+    "chromium": "^3.0.3",
+    "playwright-core": "^1.58.1"
+  },
+  "devDependencies": {
+    "jest": "^30.2.0",
+    "nock": "^14.0.10"
+  }
+}

package/src/client.js

@@ -0,0 +1,375 @@
+const axios = require('axios');
+const AdmZip = require('adm-zip');
+const { chromium } = require('playwright-core');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+class CalibreClient {
+    constructor(baseUrl, username = null, password = null) {
+        this.baseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+        this.auth = (username && password) ? { username, password } : null;
+        this.client = axios.create({
+            baseURL: this.baseUrl,
+            auth: this.auth
+        });
+    }
+
+    /**
+     * Get a list of libraries available on the server.
+     */
+    async getLibraries() {
+        const response = await this.client.get('/interface-data/init');
+        return response.data.library_info || response.data.library_map || {};
+    }
+
+    /**
+     * Get books from a specific library.
+     * @param {string} libraryId 
+     * @param {number} limit 
+     * @param {number} offset 
+     */
+    async getBooks(libraryId, limit = 100, offset = 0) {
+        // Calibre's JSON API often uses /ajax/books/
+        const response = await this.client.get(`/ajax/books/${libraryId}`, {
+            params: {
+                num: limit,
+                start: offset
+            }
+        });
+        
+        // Some versions of Calibre return an object with book IDs as keys, 
+        // others return an object with a 'books' array.
+        // We try to normalize this to an array of books.
+        if (response.data && response.data.books) {
+            return response.data.books;
+        } else if (response.data && typeof response.data === 'object') {
+            const values = Object.values(response.data);
+            const books = values.filter(item => typeof item === 'object' && item !== null && (item.id !== undefined || item.application_id !== undefined));
+            
+            if (books.length > 0) {
+                return books;
+            }
+        }
+        return response.data;
+    }
+
+    /**
+     * Get detailed metadata for a specific book.
+     */
+    async getBookMetadata(libraryId, bookId) {
+        const response = await this.client.get(`/ajax/book/${bookId}/${libraryId}`);
+        return response.data;
+    }
+
+    /**
+     * Get the formats available for a book.
+     */
+    async getBookFormats(libraryId, bookId) {
+        const metadata = await this.getBookMetadata(libraryId, bookId);
+        return metadata.formats;
+    }
+
+    /**
+     * Download a specific format of a book.
+     * Note: This returns a Buffer.
+     */
+    async downloadBook(libraryId, bookId, format) {
+        const url = `/get/${format}/${bookId}/${libraryId}`;
+        const response = await this.client.get(url, { responseType: 'arraybuffer' });
+        return Buffer.from(response.data);
+    }
+
+    /**
+     * Get the cover image of a book.
+     * Returns a Buffer.
+     */
+    async getBookCover(libraryId, bookId) {
+        const url = `/get/cover/${bookId}/${libraryId}`;
+        const response = await this.client.get(url, { responseType: 'arraybuffer' });
+        return Buffer.from(response.data);
+    }
+
+    /**
+     * Get a list of files inside an EPUB book.
+     */
+    async getEpubContents(libraryId, bookId) {
+        const buffer = await this.getEpubBuffer(libraryId, bookId);
+        const zip = new AdmZip(buffer);
+        return zip.getEntries().map(entry => entry.entryName);
+    }
+
+    /**
+     * Extract a specific file from an EPUB.
+     * Returns the content as a string or Buffer depending on the format.
+     */
+    async getEpubFile(libraryId, bookId, filePath, responseType = 'text') {
+        const buffer = await this.getEpubBuffer(libraryId, bookId);
+        const zip = new AdmZip(buffer);
+        const entry = zip.getEntry(filePath);
+        if (!entry) throw new Error(`File ${filePath} not found in EPUB`);
+        
+        if (responseType === 'buffer') {
+            return entry.getData();
+        }
+        return zip.readAsText(entry);
+    }
+    /**
+     * Get a Buffer of the entire EPUB file.
+     */
+    async getEpubBuffer(libraryId, bookId) {
+        const formats = await this.getBookFormats(libraryId, bookId);
+        const epubFormat = formats.find(f => f.toUpperCase() === 'EPUB');
+        if (!epubFormat) throw new Error(`Book ${bookId} does not have an EPUB format`);
+
+        return await this.downloadBook(libraryId, bookId, epubFormat);
+    }
+
+    /**
+     * Parse Manifest
+     */
+    _parseManifest(opfXml, opfDir) {
+        const manifest = {};
+        const itemRegex = /<item\s+[^>]*href\s*=\s*"([^"]+)"[^>]*id\s*=\s*"([^"]+)"|<item\s+[^>]*id\s*=\s*"([^"]+)"[^>]*href\s*=\s*"([^"]+)"/gi;
+        let itemMatch;
+        while ((itemMatch = itemRegex.exec(opfXml)) !== null) {
+            const id = itemMatch[2] || itemMatch[3];
+            const href = itemMatch[1] || itemMatch[4];
+            // Decode URI components in href (e.g. %20 to space)
+            let decodedHref = href;
+            try {
+                decodedHref = decodeURIComponent(href);
+            } catch (e) {
+                // Ignore decoding errors
+            }
+            manifest[id] = this._normalizePath(opfDir + decodedHref);
+        }
+        return manifest;
+    }
+
+    /**
+     * Normalize path (remove ./ and handle ../)
+     */
+    _normalizePath(filePath) {
+        // Simple normalization for internal EPUB paths
+        const parts = filePath.split('/');
+        const stack = [];
+        for (const part of parts) {
+            if (part === '.' || part === '') continue;
+            if (part === '..') {
+                if (stack.length > 0) stack.pop();
+            } else {
+                stack.push(part);
+            }
+        }
+        return stack.join('/');
+    }
+
+    /**
+     * Build chapters list
+     */
+    async getChapters(libraryId, bookId) {
+        const buffer = await this.getEpubBuffer(libraryId, bookId);
+        const zip = new AdmZip(buffer);
+
+        // 1. Find the OPF file
+        const containerEntry = zip.getEntry('META-INF/container.xml');
+        if (!containerEntry) throw new Error('EPUB missing META-INF/container.xml');
+        const containerXml = zip.readAsText(containerEntry);
+        const fullPathMatch = containerXml.match(/full-path="([^"]+)"/);
+        if (!fullPathMatch) throw new Error('Could not find root file in container.xml');
+        const opfPath = fullPathMatch[1];
+        const opfDir = opfPath.includes('/') ? opfPath.substring(0, opfPath.lastIndexOf('/') + 1) : '';
+
+        const opfEntry = zip.getEntry(opfPath);
+        if (!opfEntry) throw new Error(`Could not find OPF file at ${opfPath}`);
+        const opfXml = zip.readAsText(opfEntry);
+
+        // 2. Parse Manifest
+        const manifest = this._parseManifest(opfXml, opfDir);
+
+        // 3. Parse Spine
+        const spine = [];
+        const itemrefRegex = /<itemref\s+[^>]*idref\s*=\s*"([^"]+)"/gi;
+        let itemrefMatch;
+        while ((itemrefMatch = itemrefRegex.exec(opfXml)) !== null) {
+            const idref = itemrefMatch[1];
+            if (manifest[idref]) {
+                spine.push(manifest[idref]);
+            }
+        }
+
+        // 4. Get TOC for titles
+        const toc = await this.getTOC(libraryId, bookId);
+        const tocMap = {};
+        toc.forEach(item => {
+            const normalizedPath = this._normalizePath(item.path);
+            if (!tocMap[normalizedPath]) {
+                tocMap[normalizedPath] = item.title;
+            }
+        });
+
+        // 5. Build chapters list
+        return spine.map(chapterPath => ({
+            title: tocMap[chapterPath] || 'No heading',
+            path: chapterPath
+        }));
+    }
+
+    /**
+     * Renders a specific page of a chapter to a PNG Buffer.
+     */
+    async renderChapterPage(libraryId, bookId, chapterPath, pageNumber = 1, width = 800, height = 1000) {
+        const epubBuffer = await this.getEpubBuffer(libraryId, bookId);
+        const zip = new AdmZip(epubBuffer);
+        
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'calibre-render-'));
+        
+        try {
+            // Only extract the requested chapter and its immediate dependencies if possible?
+            // Actually, EPUBs often have CSS/images in other directories.
+            // Extracting all is safer for rendering, but let's ensure we only extract once if possible.
+            zip.extractAllTo(tempDir, true);
+            
+            const htmlPath = path.join(tempDir, chapterPath);
+            if (!fs.existsSync(htmlPath)) {
+                // Try to find it if path is relative or slightly different
+                throw new Error(`Extracted chapter file not found at expected path: ${chapterPath}`);
+            }
+            
+            const browser = await chromium.launch({
+                args: ['--disable-web-security'] // Allow loading local files
+            });
+            try {
+                const page = await browser.newPage();
+                await page.setViewportSize({ width, height });
+                
+                // Use a proper file:// URL
+                const fileUrl = `file://${path.resolve(htmlPath)}`;
+                await page.goto(fileUrl, { waitUntil: 'networkidle' });
+                
+                const totalPages = await page.evaluate((h) => {
+                    return Math.ceil(document.documentElement.scrollHeight / h) || 1;
+                }, height);
+
+                if (pageNumber > 1) {
+                    await page.evaluate(({ n, h }) => {
+                        window.scrollTo(0, (n - 1) * h);
+                    }, { n: pageNumber, h: height });
+                    
+                    // Give it a moment to scroll and render
+                    await new Promise(resolve => setTimeout(resolve, 500));
+                }
+                
+                const screenshotBuffer = await page.screenshot({ fullPage: false });
+                return {
+                    buffer: screenshotBuffer,
+                    totalPages: totalPages
+                };
+            } finally {
+                await browser.close();
+            }
+        } finally {
+            try {
+                if (fs.existsSync(tempDir)) {
+                    fs.rmSync(tempDir, { recursive: true, force: true });
+                }
+            } catch (err) {
+                console.error(`Failed to clean up temp directory ${tempDir}: ${err.message}`);
+            }
+        }
+    }
+
+    /**
+     * Get the Table of Contents (TOC) from an EPUB.
+     * Returns an array of { title, path } objects.
+     */
+    async getTOC(libraryId, bookId) {
+        const buffer = await this.getEpubBuffer(libraryId, bookId);
+        const zip = new AdmZip(buffer);
+        const entries = zip.getEntries();
+
+        // 1. Find the OPF file to find the TOC file
+        const containerEntry = zip.getEntry('META-INF/container.xml');
+        if (!containerEntry) throw new Error('EPUB missing META-INF/container.xml');
+        const containerXml = zip.readAsText(containerEntry);
+        const fullPathMatch = containerXml.match(/full-path="([^"]+)"/);
+        if (!fullPathMatch) throw new Error('Could not find root file in container.xml');
+        const opfPath = fullPathMatch[1];
+        const opfDir = opfPath.includes('/') ? opfPath.substring(0, opfPath.lastIndexOf('/') + 1) : '';
+
+        const opfEntry = zip.getEntry(opfPath);
+        if (!opfEntry) throw new Error(`Could not find OPF file at ${opfPath}`);
+        const opfXml = zip.readAsText(opfEntry);
+
+        // Try to find TOC in NCX (EPUB 2) or Nav (EPUB 3)
+        // Check for NCX first
+        const ncxMatch = opfXml.match(/id="([^"]+)"[^>]+media-type="application\/x-dtbncx\+xml"/i) || 
+                         opfXml.match(/media-type="application\/x-dtbncx\+xml"[^>]+id="([^"]+)"/i);
+        
+        let toc = [];
+
+        if (ncxMatch) {
+            const ncxId = ncxMatch[1];
+            const ncxHrefMatch = opfXml.match(new RegExp(`id="${ncxId}"[^>]+href="([^"]+)"`)) ||
+                                 opfXml.match(new RegExp(`href="([^"]+)"[^>]+id="${ncxId}"`));
+            if (ncxHrefMatch) {
+                const ncxPath = opfDir + ncxHrefMatch[1];
+                const ncxEntry = zip.getEntry(ncxPath);
+                if (ncxEntry) {
+                    const ncxXml = zip.readAsText(ncxEntry);
+                    // Very basic NCX parsing using regex
+                    const navPointRegex = /<navPoint[^>]*>[\s\S]*?<navLabel>[\s\S]*?<text>([\s\S]*?)<\/text>[\s\S]*?<\/navLabel>[\s\S]*?<content src="([^"]+)"/g;
+                    let match;
+                    while ((match = navPointRegex.exec(ncxXml)) !== null) {
+                        let label = match[1].trim();
+                        let href = match[2];
+                        // remove anchors
+                        if (href.includes('#')) href = href.split('#')[0];
+                        
+                        const fullPath = this._normalizePath(opfDir + href);
+                        // Avoid duplicates if multiple navPoints point to same file, but keep first (usually better label)
+                        if (!toc.find(t => t.path === fullPath)) {
+                            toc.push({
+                                title: label,
+                                path: fullPath
+                            });
+                        }
+                    }
+                }
+            }
+        }
+
+        // If no TOC found yet, try EPUB 3 Nav
+        if (toc.length === 0) {
+            const navMatch = opfXml.match(/properties="[^"]*nav[^"]*"[^>]+href="([^"]+)"/i) ||
+                             opfXml.match(/href="([^"]+)"[^>]+properties="[^"]*nav[^"]*"/i);
+            if (navMatch) {
+                const navPath = this._normalizePath(opfDir + navMatch[1]);
+                const navEntry = zip.getEntry(navPath);
+                if (navEntry) {
+                    const navXml = zip.readAsText(navEntry);
+                    // Very basic Nav parsing
+                    const linkRegex = /<a[^>]+href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/g;
+                    let match;
+                    while ((match = linkRegex.exec(navXml)) !== null) {
+                        let href = match[1];
+                        if (href.includes('#')) href = href.split('#')[0];
+                        const fullPath = this._normalizePath(opfDir + href);
+                        const label = match[2].replace(/<[^>]+>/g, '').trim();
+                        if (!toc.find(t => t.path === fullPath)) {
+                            toc.push({
+                                title: label,
+                                path: fullPath
+                            });
+                        }
+                    }
+                }
+            }
+        }
+
+        return toc;
+    }
+}
+
+module.exports = CalibreClient;