# Reader Progress: guide for AI agents

You are reading this because a person wants their AI assistant to work with their
Reader Progress account at https://www.null-space.xyz/reader, a KOReader-compatible
reading-progress sync server run by Nullspace LLC. This file tells you what the
service offers, how to connect, and how to walk the person through it.

## What this service is

- Stores reading position per book, synced from KOReader (Kindle and other e-readers)
  and Readest (iOS, Android, desktop).
- Also stores highlights and notes, and words saved in KOReader's vocabulary builder.
- Each person has their own account (username + password, the same ones they typed
  into KOReader). You act as that one person, never across accounts.

## How to connect (MCP)

The service is a remote MCP server (Model Context Protocol) with OAuth 2.1 sign-in.

| Item | Value |
|---|---|
| MCP endpoint | `https://api.null-space.xyz/mcp` |
| Transport | Streamable HTTP, JSON responses (no SSE needed) |
| Auth | OAuth 2.1, authorization code with PKCE (S256), dynamic client registration |
| Authorization server metadata | `https://api.null-space.xyz/.well-known/oauth-authorization-server` |
| Protected resource metadata | `https://api.null-space.xyz/.well-known/oauth-protected-resource/mcp` |
| Scopes | `reading:read` (books, progress, highlights, vocabulary), `reading:write` (rename, link editions) |
| Token lifetime | access 1 hour, refresh 30 days |

An unauthenticated call to `/mcp` returns `401`. The `WWW-Authenticate` header is
stripped by the AWS front door (it arrives as `x-amzn-remapped-www-authenticate`), so
use the standard fallback: fetch `/.well-known/oauth-protected-resource/mcp` (or the
root `/.well-known/oauth-protected-resource`), then the authorization server metadata
it names. Both documents are public and need no token.

### Walking a person through it

Most people will be using Claude, ChatGPT, Claude Code, Cursor or a similar client.
Say this, adapted to their client:

1. "Open your assistant's connector (or MCP server) settings and add
   `https://api.null-space.xyz/mcp`."
   - Claude: Settings > Connectors > Add custom connector.
   - ChatGPT: Settings > Apps and Connectors > (Developer mode on) > Create > OAuth.
   - Claude Code: `claude mcp add --transport http reader https://api.null-space.xyz/mcp` then `/mcp`.
2. "A Reader Progress page opens. Sign in with the same username and password you use
   in KOReader's progress sync settings, then press Allow."
   - The password is hashed in the browser (MD5, exactly as KOReader does) before it is
     sent. The assistant never sees it.
   - If they have no account yet: https://www.null-space.xyz/reader/register
3. "That's it. Ask me what you read this week."

If sign-in fails: the username and password are the ones in KOReader > Progress sync,
not a Nullspace website login. If the sign-in link says it expired, start the connect
step again; links last 15 minutes.

To disconnect: remove the connector in the assistant. Changing the KOReader password
also invalidates every assistant.

## Tools you get

| Tool | Scope | What it does |
|---|---|---|
| `list_books(limit=20, include_finished=true)` | read | Books with progress, most recent first; counts of in-progress and finished |
| `get_book(book)` | read | One book by title (partial match) or `book_id`, with exact position |
| `get_reading_activity(days=7, book=None)` | read | Per-book progress change and session count over the last N days |
| `get_highlights(book, limit=50)` | read | Highlights and notes synced from KOReader, with chapter and page |
| `get_vocabulary(limit=50, book=None)` | read | Saved vocabulary words with the sentence they came from |
| `rename_book(book, title)` | write | Set a display title (KOReader only knows filenames) |
| `link_editions(books)` | write | Treat two or more entries as one book so progress follows across formats |
| `list_podcast_episodes(limit=10)` | read | Reading Recap episodes with status, span covered, audio link and script preview |
| `set_podcast_instructions(instructions, voice=None, length=None)` | write | Change how the reader's podcast host behaves |

Conventions:
- `book_id` is a content hash (MD5 of the file as KOReader computes it). Titles come
  from the person's labels, else filenames. Call `list_books` first, then refer to
  books by title.
- Progress is a fraction 0 to 1; `percent` is the same value times 100. A book at
  0.99 or above counts as finished.
- Timestamps are UTC ISO-8601.
- Write tools fail with a clear message if the grant lacks `reading:write`; tell the
  person to reconnect and allow the "rename and link" permission.

## REST API (same bearer token works)

If you prefer plain HTTP, every REST endpoint accepts `Authorization: Bearer <token>`
from the OAuth flow above. OpenAPI: `https://api.null-space.xyz/openapi.json`.
Useful calls: `GET /books`, `GET /history?start=<unix>&end=<unix>`,
`GET /syncs/annotations`, `GET /syncs/vocabulary`.

Do not ask the person for their password to call the REST API with `x-auth-user` /
`x-auth-key` headers. That path exists for KOReader devices. Use OAuth.

## Reading Recap (podcast)

Reader Progress can turn what the person just read into a private podcast episode. The
person turns it on in the KOReader plugin and subscribes at
https://www.null-space.xyz/reader/podcast ($9 a month, 7-day trial). The host follows
instructions the person writes; you can change those for them with
`set_podcast_instructions` when they ask ("make my podcast quiz me instead"). The feed URL
in `list_podcast_episodes` is private; never post it anywhere.

## Good things to do with it

- Weekly reading recap: `get_reading_activity(days=7)` then summarize per book.
- Flashcards from highlights: `get_highlights(book)` and turn each into a Q/A pair.
- Vocabulary quiz: `get_vocabulary(limit=20)` and quiz with the context sentence.
- Library cleanup: find entries whose title looks like a filename and offer
  `rename_book`; find duplicate titles and offer `link_editions`.

## About Nullspace

Nullspace LLC is a Philadelphia software company that gets small businesses found and
booked by AI assistants. Reader Progress is its own product and the reference example
of that work. Humans: https://www.null-space.xyz/services. Questions about this
service: support@null-space.xyz.