book-downloader-mcp-server/README.md

MCP server to search and download books using Anna's Archive API

# Book Downloader MCP Server

This MCP (Model Context Protocol) server allows you to search for books using Anna's Archive API and download them directly to your computer's Downloads folder.

**Note:** This tool uses the Anna's Archive API via RapidAPI to provide a more reliable and consistent experience compared to web scraping methods.

## Prerequisites

*   Node.js (v16 or higher recommended)
*   npm (comes with Node.js)

## MCP Configuration

To use this server with an LLM or other MCP-compatible client, register it with the following configuration. This setup will automatically download and run the server in a temporary environment without requiring a manual global installation:

```json
{
  "mcpServers": {
    "book-downloader": {
      "command": "sh",
      "args": [
        "-c",
        "cd $(mktemp -d) && npm install book-downloader-mcp-server && npx book-downloader-mcp-server-cli"
      ]
      // "env": {} // Add environment variables here if your server needs them in the future
    }
  }
}
```

**Explanation of the command:**

*   `sh -c "..."`: Executes the provided string as a shell command.
*   `cd $(mktemp -d)`: Creates a unique temporary directory and changes the current directory into it. This keeps the installation isolated.
*   `npm install book-downloader-mcp-server`: Installs your package (and its dependencies) into this temporary directory.
*   `npx book-downloader-mcp-server-cli`: Executes the command-line interface (`book-downloader-mcp-server-cli`) that was made available by installing your package. `npx` handles finding and running the binary.

This ensures the MCP client always uses the latest version of `book-downloader-mcp-server` available on npm each time it starts (or according to `npm install`'s caching behavior for subsequent runs within the same client session if the temp directory isn't cleared immediately).

## Available Tools

### `searchAndDownloadBook`

Searches for books using Anna's Archive API and attempts to download them in the preferred format to your system's default Downloads folder.

**Parameters:**

*   `query` (string, required): The search term for the book. This can be the book's title, author, ISBN, or other relevant keywords.
    *   Example: `"The Hitchhiker's Guide to the Galaxy"`
*   `format` (string, optional): The preferred book format. Accepts 'PDF', 'EPUB', 'MOBI', 'AZW3', or 'any'. Defaults to 'any' if not specified.
    *   Example: `"epub"`
*   `category` (string, optional): Book categories to search. Options include 'fiction', 'nonfiction', 'comic', 'magazine', 'musicalscore', 'other', 'unknown'. Defaults to 'fiction, nonfiction'.
    *   Example: `"fiction, comic"`
*   `limit` (number, optional): Maximum number of search results to return. Defaults to 10.
    *   Example: `20`
*   `bookIndex` (number, optional): If provided, selects the book at this index from search results.
    *   Example: `0`

**Example Usage (conceptual, depends on your LLM/client):**
`LLM, please use the book-downloader to find 'Sapiens by Yuval Noah Harari' and download it as an EPUB.`

This would translate to an MCP tool call like:
`searchAndDownloadBook({ query: "Sapiens by Yuval Noah Harari", format: "epub" })`

## How it Works (Briefly)

1.  The `searchAndDownloadBook` tool receives a query and optional parameters.
2.  It constructs an API request to Anna's Archive API via RapidAPI.
3.  It processes the search results and presents a list of matching books if no specific book index is provided.
4.  When a book is selected (either automatically or by the user providing a book index), it fetches additional book information and initiates the download.
5.  The book content is streamed to a file in your OS's default Downloads folder.

**Important Notes:**

*   **Reliability:** This tool uses the Anna's Archive API which provides a more reliable and consistent experience compared to web scraping methods.
*   **Download Location:** Books are saved to your operating system's standard Downloads folder (e.g., `~/Downloads` on macOS/Linux, `C:\Users\YourUser\Downloads` on Windows).
*   **Error Handling:** Comprehensive error handling is in place to handle various API response scenarios.
*   **API Key:** The tool uses a RapidAPI key to access the Anna's Archive API.