hardcover-mcp python.instructions.md

Python Coding Conventions

General Instructions

• Readability first. Write code that is easy to read and reason about. Clever one-liners are acceptable only when they do not obscure intent.
• State intent in comments. For non-trivial logic — especially GraphQL query construction, mutation side-effects, and caching — add a comment explaining why, not just what.
• Fail loud, fail early. Validate inputs at function boundaries. Never silently swallow bad data or fall back to a default that hides a bug.
• Keep functions focused. A function should do one thing. If a function needs a multi-step comment header (# --- 1. ..., # --- 2. ...), consider whether any step deserves its own function.
• Async by default. All I/O-bound functions (API calls, network) must be async. Keep sync helpers for pure data formatting.

Type Hints

• Use union syntax: X | Y and X | None (Python 3.10+, PEP 604), not Optional[X] or Union[X, Y].
• Annotate all function signatures with parameter and return types.
• Use list[int] / dict[str, float] (lowercase built-ins, Python 3.9+, PEP 585), not List / Dict from typing.
• Do not use from __future__ import annotations. The project targets Python 3.14; the import is a no-op and adds noise.

Docstrings

• Follow NumPy docstring style for all public functions and classes.
• Private helpers (prefixed _) require at minimum a one-line summary docstring.
• Always document: what the input data shape/convention is, and what the output represents.

async def handle_search_books(arguments: dict[str, Any]) -> list[TextContent]:
    """
    Search Hardcover for books matching a query string.

    Parameters
    ----------
    arguments : dict[str, Any]
        Tool arguments. Required key: ``query`` (str).
        Optional: ``per_page`` (int, default 10, max 25), ``page`` (int, default 1).

    Returns
    -------
    list[TextContent]
        Single-element list with JSON-formatted search results.
    """