# Knihobot MCP — Unofficial

An unofficial, read-only [Model Context Protocol](https://modelcontextprotocol.io/)
server, independently developed as an interoperability and convenience layer for
end-user queries against publicly available information in the
[Knihobot.cz](https://knihobot.cz/) book catalog.

It lets MCP clients search the catalog, inspect a specific physical copy, compare
copies of the same edition, and retrieve Knihobot recommendations. It does not sign
in to or access customer accounts, carts, orders, authentication-protected data, or
private data.

> [!WARNING]
> Knihobot does not publicly document the API used by this project. Endpoints and
> response formats may change or access may be restricted without notice, causing
> this server to stop working. This project is not affiliated with, sponsored by,
> or endorsed by Knihobot.

## Features

- Search by title, author, ISBN, and catalog filters
- Inspect live prices, availability, metadata, and copy images
- Compare currently available copies of an edition
- Retrieve catalog suggestions and recommendations
- Validate upstream responses before exposing structured MCP output
- Limit concurrency and cache repeated requests

## Requirements

- Node.js 20 or later
- npm

## Installation

```bash
git clone https://github.com/birosrichard/knihobot-mcp
cd knihobot-mcp
npm ci
npm run build
```

## MCP client configuration

Add the server to your MCP client configuration. Replace the path with the absolute
path to the cloned repository:

```json
{
  "mcpServers": {
    "knihobot": {
      "command": "node",
      "args": ["/absolute/path/to/knihobot-mcp/dist/index.js"]
    }
  }
}
```

The server uses the stdio transport. Diagnostic messages are written to stderr so
they do not corrupt MCP messages on stdout.

## Tools

- `search_books` searches for titles, authors, ISBNs, and other text. It supports
  pages 1–20 plus availability, language, author, publisher, category, condition,
  binding, year, and price filters.
- `suggest_books` returns matching books, authors, publishers, categories, labels,
  and series.
- `get_book_detail` returns metadata and live sale information for one physical
  copy. It accepts `titleId` and `bookId` from search or suggestion results.
- `list_available_copies` lists physical copies currently offered for an
  `editionId`.
- `get_recommendations` returns recommended books for an `editionId`.

Knihobot's catalog model uses `titleId` for a language-specific title group,
`editionId` for an edition, and `bookId` for a physical copy offered for sale.
These are upstream implementation details and may change.

## Configuration

The server works without credentials. The following environment variables are
optional:

- `KNIHOBOT_BASE_URL`: API origin; defaults to `https://knihobot.cz`
- `KNIHOBOT_TIMEOUT_MS`: request timeout in milliseconds; defaults to `10000`
- `KNIHOBOT_CACHE_TTL_MS`: cache lifetime in milliseconds; defaults to `60000`
  and cannot exceed `300000`
- `KNIHOBOT_MAX_CONCURRENT`: maximum concurrent upstream requests; defaults to
  `2` and cannot exceed `4`

The server reads these values from its process environment; it does not load a
`.env` file. All numeric values must be positive integers.

## Example prompts

- "Find Czech editions of Dune under 500 CZK."
- "Show all available copies of this edition and compare their prices."
- "Recommend books related to this edition."

## Development

```bash
npm ci
npm run dev
npm run check
```

`npm run check` compiles the TypeScript project and runs the test suite. Tests use
mocked HTTP responses and do not require access to Knihobot.

## Responsible use and limitations

This project is an independent interoperability tool. It does not replicate or
redistribute the Knihobot catalog and does not maintain a persistent copy of
Knihobot's database. It provides no bulk catalog export; its bounded, short-lived
in-memory cache exists only to reduce repeated identical requests.

Use reasonable request rates and comply with Knihobot's website terms,
`robots.txt` where technically applicable, and applicable law. Do not use this
project to circumvent authentication, CAPTCHA, rate limits, bot protection,
Cloudflare protections, or any other technical access control. If Knihobot denies
or challenges a request, the server reports the restriction instead of attempting
to bypass it.

Catalog data, prices, stock levels, images, recommendations, trademarks, and other
upstream content remain subject to the rights of their respective owners and may
become stale immediately after a tool call. Do not rely on this project as a
guaranteed or supported commercial API.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

The project's source code is licensed under the [ISC License](LICENSE). The ISC
License applies only to this project's source code. Upstream product data, images,
trademarks, and other content remain subject to the rights of their respective
owners.