Near Fine MCP

Search for a book across every bookseller Near Fine covers for the buyer's country (AbeBooks and eBay sites everywhere, plus World of Books, ThriftBooks, Better World Books, Books-A-Million, Casa del Libro, Hugendubel, preigu, Booklooker, Leslibraires.fr, Rarewaves, Ex Libris, Librairie Mollat, Boekwinkeltjes.nl, Standaard Boekhandel, Managementboek, Dubray Books, Malliaris-Paideia, Indigo, Kinokuniya, Daunt Books, Paper Cavalier, Lets Buy Books, Bookshop.org, LoveReading, BookKind, Chapters Bookstore, Harry Hartog, Book Grocer, Whitcoulls, Bokkilden, Bog & idé, Suomalainen Kirjakauppa, Booky.fi, Bookbot, Świat Książki, Matras, Luxor, Kosmas, IBS, Libraccio, Libreria Universitaria, Agapea, Label Emmaüs, Gandhi, Porrúa, Livraria da Travessa, Martins Fontes, Librería de la U, Ibero Librerías, Contrapunto, Maruzen Junkudo, BookOff, Kyobo, Yes24, Book Outlet, Livrenpoche, Buybook, Exclusive Books, Readers Warehouse, Wordsworth Books, Graffiti Books, Popular, MPH, BookXcess, National Book Store, Bookazine, Atlantic Books, Kitabay, Liberty Books, Tecni-Ciencia, Librairie Club, Books Upstairs, Nexus, Czytam.pl, Americanas, Livrarias Curitiba, Kel Ediciones and SBS Librerías where they ship, and Apple Books ebooks and audiobooks; shops' ebooks and audiobook downloads only in their own country). Pass an ISBN-10 or ISBN-13 for an exact edition, or title and author keywords. The query can also carry a price cap, as in "under $40" or "max 30 €" (in the buyer's currency when it names none), and ask for a first edition, a signed copy, a dust jacket, a hardcover or a paperback, as in "wolf hall signed first edition under £200", or for an ebook or audiobook alone. Offers over the cap, counting known shipping, and offers in other formats than the one asked for are left out; criteria reports what was read. Returns offers sorted cheapest first, each with title, seller, condition (new, used, ebook or audiobook), price and shipping in the seller's currency, the same in the buyer's currency when it differs, and the URL to buy. Shipping is left out where the shop doesn't publish it. Each offer may carry a match from 0 to 1: how sure a decision model is that the listing is the book searched for rather than a study guide, summary, adaptation or another book that shares a word. Below about 0.2 it rarely is. When the query asks for attributes, each offer carries verdicts: true where the decision model, reading the listing and any filter the bookseller applied, confirms the listing claims it, false where it doesn't, and left out where unjudged. Also reports which sources answered, failed or timed out, an amazon_url that opens the same search on the buyer's Amazon site, and a search_url that opens it on Near Fine, where the buyer can set an alert and get an email when a new listing turns up with everything the query asks for. A search takes a few seconds.

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "description": "ISBN-10, ISBN-13 (hyphens and spaces allowed) or title and author keywords, optionally with a price cap and attributes such as \"first edition under $40\""
    },
    "country": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$",
      "description": "Country the buyer is in, as an ISO 3166-1 alpha-2 code such as US, GB or DE. Defaults to US."
    }
  }
}

{
  "readOnlyHint": true,
  "openWorldHint": true,
  "idempotentHint": true,
  "destructiveHint": false
}

List the bookseller catalogs Near Fine searches, each with the countries it serves. Pass a country to see only the sources that serve buyers there.

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "country": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$",
      "description": "Only list sources serving buyers in this country (ISO 3166-1 alpha-2)"
    }
  }
}

{
  "readOnlyHint": true,
  "openWorldHint": false,
  "idempotentHint": true,
  "destructiveHint": false
}

Set an alert on a search for the person. The first time, they sign in to Near Fine. Near Fine checks the alert for six months and emails them when a new listing turns up with everything the query asks for, such as a first edition, a signed copy or a price cap. On the Pro plan the alert keeps watching after a find and emails again when newer listings turn up; on other plans it stops after one email. The query reads as search_books reads it. Listings there already never count: the alert stays pending until its first check has noted them. Setting an alert that's already set keeps it as it is. Returns the alert, with its status and its link on Near Fine, and the person's plan: how many alerts it allows, how many are in use and how often each is checked. A full plan comes back as an error; paid plans, at plans_url, have more.

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "query",
    "country"
  ],
  "properties": {
    "query": {
      "type": "string",
      "description": "ISBN or title and author keywords, with anything the person wants beyond the book, as in \"wolf hall signed first edition under £200\""
    },
    "country": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$",
      "description": "Country the book has to reach, as an ISO 3166-1 alpha-2 code such as US, GB or DE"
    }
  }
}

{
  "readOnlyHint": false,
  "openWorldHint": false,
  "idempotentHint": true,
  "destructiveHint": false
}

List the person's alerts on Near Fine. The first time, they sign in. Finds come first, then alerts being checked, then the rest, newest first. Each has its id, query, country, status, when it was set, last checked and runs until, a link to it on Near Fine, how many times it has emailed a find and when it last did, and, once it has found a listing, the cheapest it last found: its title, seller, condition, price and shipping in the person's currency, and the URL to buy it. Statuses: pending (noting what's listed already), live (watching, as a Pro alert stays after a find), found (emailed a find and stopped), ended (the person got the book or stopped it), expired (ran its six months) and paused (the plan has room for fewer alerts). Also returns the person's plan.

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "readOnlyHint": true,
  "openWorldHint": false,
  "idempotentHint": true,
  "destructiveHint": false
}

Cancel one of the person's alerts on Near Fine by its id, from list_alerts or set_alert, deleting it as its Delete button on Near Fine does. The first time, they sign in. Returns the cancelled alert and the person's plan.

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "The alert’s id"
    }
  }
}

{
  "readOnlyHint": false,
  "openWorldHint": false,
  "idempotentHint": true,
  "destructiveHint": true
}