# Reknihy 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
[Reknihy.cz](https://reknihy.cz/) book catalog.

The server primarily uses Reknihy's public WooCommerce Store API and a publicly
accessible catalog endpoint used to resolve author taxonomy data. It does not
require an account or API key and does not access customer accounts, carts,
orders, authentication-protected data, or private data.

> [!IMPORTANT]
> This project is not affiliated with, sponsored by, or endorsed by Reknihy.cz.
> The upstream API may change, restrict access, or return incomplete catalog data
> at any time, which may cause this server to stop working.

## Features

- Search by title, author, ISBN, or other catalog text
- Filter by availability, category, and price
- Sort and paginate catalog results
- Retrieve product details and exact ISBN matches
- Browse categories that can be reused as search filters
- Return normalized prices, stock information, images, and product links

## Requirements

- Node.js 20 or later
- npm

## Installation

```bash
git clone https://github.com/birosrichard/reknihy-mcp
cd reknihy-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": {
    "reknihy": {
      "command": "node",
      "args": ["/absolute/path/to/reknihy-mcp/dist/index.js"]
    }
  }
}
```

The server communicates over stdio. Rebuild and restart it after changing the
source code.

## Tools

- `search_books` searches the public catalog and returns price, availability, ISBN,
  image, category, and product URL data. It supports pages 1–20, stock and category
  filters, exact author filtering, price limits, and sorting.
- `get_book` retrieves a product by the numeric ID returned from `search_books`.
- `find_book_by_isbn` normalizes an ISBN-10 or ISBN-13 and returns an exact catalog
  match when available.
- `list_categories` lists public product categories that can be passed back to
  `search_books`, with pages limited to 1–20.

All tools are declared read-only, non-destructive, and idempotent.

## Configuration

The following environment variables are optional:

- `REKNIHY_BASE_URL`: API origin; defaults to `https://reknihy.cz`
- `REKNIHY_TIMEOUT_MS`: request timeout in milliseconds; defaults to `15000`
- `REKNIHY_CACHE_TTL_MS`: cache lifetime in milliseconds; defaults to `60000`
  and cannot exceed `300000`
- `REKNIHY_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 in-stock books by Karel Čapek under 250 CZK."
- "Look up this ISBN and summarize the listing."
- "List history categories and search the most relevant one."

## 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 Reknihy.

## Responsible use and limitations

This project does not provide a bulk catalog export and does not intentionally
replicate or maintain a persistent copy of Reknihy's catalog or database. Its
bounded, short-lived in-memory cache exists only to reduce repeated identical
requests.

Use reasonable request rates and comply with Reknihy'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 Reknihy denies or challenges
a request, the server reports the restriction instead of attempting to bypass it.

The implementation is limited to public catalog API paths selected to avoid areas
known to be disallowed by `robots.txt`. Because `robots.txt` and upstream behavior
can change—and the file may itself be unavailable behind a security challenge—users
should verify its current contents where applicable. This project does not treat
`robots.txt` as an authorization mechanism and does not work around access
restrictions to inspect it.

Catalog data, prices, stock levels, images, trademarks, and other upstream content
remain subject to the rights of their respective owners and may become stale
immediately after a tool call. This project is not a supported commercial API and
does not guarantee catalog completeness.

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