Skip to main content
Glama

Stacks

Give your AI agent a library card.

Stacks is an MCP server that lets Claude, ChatGPT and other AI agents look things up at your public library: what's on the shelf, which branch is open, what's on this week. It reads the library's website live, every time you ask.

MCP TinyFish TypeScript Node

npm CI Canary License: MIT PRs welcome

Quick start · Tools · Architecture · Reliability · Configuration · Contributing

🧭 Open the interactive explorer Ten real questions that between them use all 14 tools, played step by step. No install and no key needed: it replays recorded results.

🟢 Product 01 See it work 02 Why it exists 03 Tools

🟠 How it works 04 How it works 05 How TinyFish is used 06 Breaks loudly 07 What comes back 08 The wait estimate

🟣 Build and run 09 Tech stack 10 Quick start 11 Contributing 12 Responsible use and limits

🎬 See it work

"I'm in Toronto. Is Project Hail Mary on the shelf anywhere, is that branch open now, and what's on there this week?"

To answer that, the agent makes five tool calls. Each one hands a real id to the next, so nothing is guessed along the way.

flowchart LR
  Q(["🧑 One question"]) --> A["find_library<br/>Toronto → tpl<br/><b>2.4 s</b>"]
  A --> B["search_catalog<br/>→ the book's id<br/><b>5.3 s</b>"]
  B --> C["check_availability<br/>→ on the shelf at 1 of 92 branches<br/><b>3.1 s</b>"]
  C --> D["get_branch<br/>→ open now, 09:00 to 20:30<br/><b>3.3 s</b>"]
  D --> E["list_events<br/>→ 39 events this week<br/><b>6.6 s</b>"]
  E --> R(["✅ One answer,<br/>every fact sourced"])

Those timings are from a real run against Toronto Public Library. The answer the agent could give: one copy is on the shelf at North York Central Library, which is open until 8:30 tonight and has 39 programs this week.

Related MCP server: libraryapi-mcp

🎯 Why it exists

Public libraries don't offer developers an API. Their catalogues, branch pages and event calendars are websites made for people. Stacks uses TinyFish to read those sites and gives the agent clean, structured data instead.

One server, many libraries

  • Works with BiblioCommons, the platform behind 200+ public library systems

  • 54 systems verified live: 33 in the US, 20 in Canada, 1 in New Zealand

  • Others are found on demand

Typed in, typed out

  • 14 tools, each with a defined input and output

  • Structured data, never a dump of a web page

  • Every answer says where it came from and when

Live, not indexed

  • Shelf status, hold queues, today's hours, this week's events

  • Read from the site at the moment you ask

  • No library card or login needed

Honest when it breaks

  • If a library changes its website, the tool says so and names what broke

  • "Nothing found" and "I can't tell" are never mixed up

  • A daily check catches changes early

Why not just let the agent search the web?

Web search in a chat app

Stacks

"Is it on the shelf at my branch?"

Can't see it. Shelf status loads after the page does and isn't in any search index

Each copy at each branch, with call number and due date

Freshness

Days or weeks old

Read when you ask

Follow-up steps

Guesses between steps

Passes real ids from one tool to the next

When the site changes

Confidently out of date

A clear error and a failing health check

🧰 Tools

Tool

What it does

TinyFish endpoint

Catalogue and availability

find_library

Turns a city or library name into a library id

Fetch, Search

search_catalog

Searches books, eBooks, audiobooks and DVDs

Browser

get_title

Full details for one title, and its other formats

Browser

check_availability

Which branches have a copy on the shelf right now

Browser

estimate_wait

How long you'd wait if you placed a hold today

Browser

Branches and events

list_branches

Branches with address, today's hours and distance

Browser

get_branch

One branch's weekly hours, closures and services

Browser

list_events

Programs, filtered by branch, date, audience and type

Browser

Policy questions and watches

ask_library

Open questions about services and policies

Search, Fetch, Agent

get_job_result

Collects the answer from a slow Agent run

Agent

watch_title

Watches a title and notices when availability changes

Monitor

list_watches

Your watches, with live availability on request

Monitor, Browser

cancel_watch

Removes a watch, with a preview option

Monitor

Diagnostics

health_check

Proves every tool still works, or says what broke

Fetch, Browser, Agent

Twelve of the fourteen only read. The two watch tools create and remove a watch, and are labelled that way for the client. Every input and output field is listed in docs/TOOLS.md.

🏗 How it works

flowchart TB
  client(["🤖 MCP client<br/>Claude · ChatGPT · Cursor"])

  subgraph S["⚙️ Stacks · Node + TypeScript"]
    direction TB
    tool["Tool layer<br/>checks the input · shapes the output"]
    adapter["Library adapter<br/>knows which page to load and how to read it"]
    core["Cache · pacing · job ids · typed errors"]
    web["web.ts<br/>the only code that touches the network"]
    tool --> adapter --> core --> web
  end

  subgraph TF["🐟 TinyFish"]
    search["Search"]
    fetch["Fetch"]
    browser["Browser"]
    agent["Agent"]
    monitor["Monitor"]
  end

  site(("🏛 Library website"))
  ci["⏰ Daily canary<br/>GitHub Actions"]

  client <-->|"stdio or HTTP"| tool
  web --> search & fetch & browser & agent & monitor
  search & fetch & browser & agent & monitor --> site
  ci -->|"health check"| adapter

A call comes in from the client and passes through four layers. The tool layer checks the arguments. The adapter knows which library page answers the question. The core decides whether a recent answer can be reused and keeps requests to one site spaced out. Then web.ts asks TinyFish to do the actual reading. On the way back, the page data is checked against a contract before it is turned into the answer.

Layer

What it is responsible for

Code

Transport

Talking MCP over stdio or HTTP, and deciding whose TinyFish key a request uses

src/index.ts, src/http.ts

Tools

The 14 tools

src/tools/

Adapter

Everything specific to one library platform

src/adapters/bibliocommons/

Core

Cache, pacing, jobs, errors

src/core/

Health

Live checks that each tool still works

src/health/

There is no database. Stacks writes nothing to disk and keeps no user data. Recent answers sit in memory for a few minutes (5 for availability, 10 for search, 30 for events, 60 for branches) and are gone on restart. Watches and slow jobs are kept by TinyFish, so they survive a restart without Stacks storing anything.

sequenceDiagram
  autonumber
  actor C as 🤖 MCP client
  participant T as Tool layer
  participant A as Adapter
  participant K as Cache
  participant B as TinyFish Browser
  participant L as 🏛 Library site

  C->>T: check_availability for one title
  Note over T: arguments checked
  T->>A: get this title
  A->>K: read in the last 5 minutes?
  alt yes
    K-->>A: stored answer, in a few milliseconds
  else no
    A->>B: open the title's page
    B->>L: load it, without images or fonts
    L-->>B: the page and its availability data
    B-->>A: page data
    Note over A: contract check, then parse
    A->>K: keep for 5 minutes
  end
  A-->>T: typed result and its source
  T-->>C: the answer

The interactive explorer plays this same path with real data. More detail is in docs/ARCHITECTURE.md.

🐟 How TinyFish is used

Every network call Stacks makes goes through TinyFish. Nothing is canned, and there is no other scraping code. All five endpoints have a real job, chosen for what each is good at.

flowchart TB
  call(["🤖 MCP tool call"]) --> zod["Input checked against the tool's schema"]
  zod -- "page data" --> cache{"Cache:<br/>read recently?"}
  zod -- "everything else" --> OTHER

  cache -- "miss" --> pace["Pacing<br/>750 ms per host · 4 pages at once"]
  pace --> BR["🖥 <b>Browser</b><br/>catalogue, titles, branches, events"]
  BR --> contract{"contracts.ts:<br/>do the fields match?"}
  contract -- "yes" --> parse["Parser<br/>page data → public shapes"]
  contract -- "no" --> err["🚨 SITE_CHANGED<br/>with broken_fields"]

  subgraph OTHER["The other four TinyFish endpoints"]
    direction LR
    FE["📄 <b>Fetch</b><br/>is it live?<br/>page landmarks"]
    SE["🔎 <b>Search</b><br/>find a library<br/>or a page"]
    AG["🧭 <b>Agent</b><br/>open questions<br/>fallback, diagnosis"]
    MO["🔔 <b>Monitor</b><br/>watches"]
  end

  cache -- "hit" --> out(["✅ Typed answer and its source"])
  parse --> out
  OTHER --> out

Page reads through Browser are the ones that are cached, paced and checked against the contract. The other four endpoints return to the tool that called them. The interactive walkthrough plays this route step by step for ten real questions.

Endpoint

Why this one

What it does in Stacks

Fetch

Quick and cheap when plain text is enough

Confirms a catalogue is live, checks page landmarks in the health check, and picks the Agent's starting page

Browser

Library pages build their data with JavaScript, so plain text misses it

Reads search results, titles, shelf status, branches and events. One browser session stays warm between calls

Search

Finds pages nobody listed in advance

Finds libraries outside the built-in list, and the right page for an open question

Agent

Can navigate and reason

Answers open questions from the library's own site, and explains what changed when a page breaks

Monitor

Runs without anyone asking

Re-reads a title's page on a schedule for watch_title

Fetch and Agent, in more detail. Fetch is the first line of defence: the health check uses it to confirm each page still has the sections Stacks expects, before spending time on anything slower. The Agent gets the work that needs judgment. ask_library sends it to browse the library's own website and come back with an answer and the pages it read. When a fast tool hits a changed page, an Agent run is also started to read it the slow way. That fallback is best-effort: in testing it returned data in about half the runs, and a run that reads nothing is reported as failed, never as an empty answer.

An Agent run can take longer than a chat app will wait for one tool. So those tools wait under a minute and then hand back a job id, which the agent uses to collect the answer when it's ready.

🚨 Breaks loudly

Websites change. A tool that quietly returns an empty list is worse than one that fails, because the agent will tell someone "there are no copies" when the truth is "I can't tell". Stacks is built so that can't happen.

flowchart TD
  P["Page requested"] --> R{"Did it load?"}
  R -- "no such library" --> E1["UNKNOWN_LIBRARY"]
  R -- "refused" --> E2["SITE_BLOCKED"]
  R -- "site is down" --> E3["SITE_UNAVAILABLE"]
  R -- "too slow" --> E5["UPSTREAM_TIMEOUT"]
  R -- yes --> C{"Does the page data match<br/>what Stacks expects?"}
  C -- no --> SC["🚨 SITE_CHANGED<br/>names the broken fields"]
  C -- yes --> Z{"Did the site find anything?"}
  Z -- no --> OK0["✅ A normal empty result"]
  Z -- yes --> OK["✅ Typed data and its source"]

Five things make this work:

  • A contract for every page. One file lists exactly which fields Stacks depends on, and every page read is checked against it. If the library renames or removes one, the tool stops with SITE_CHANGED and lists the fields in broken_fields. Every tool fails this way; none returns less data.

  • A fallback where it helps most. On SITE_CHANGED, search_catalog and check_availability also start a best-effort Agent run and put its fallback_job_id in the error. The other tools fail without one.

  • A health check anyone can run. It runs known-good queries against a library and reports each tool as passing or failing. The agent can run it too, in the middle of a conversation.

  • A daily canary. GitHub Actions runs that health check against three libraries every day and opens an issue when one fails.

  • Tests that fake a site change. Recorded pages are deliberately damaged, and each tool has to fail with the right error. These run on every push.

Stacks health check: tpl
Healthy: 9 passed, 0 warning(s), 0 skipped.

  [PASS] locations page is reachable and intact  (fetch)
  [PASS] events page is reachable and intact  (fetch)
  [PASS] search page is reachable and intact  (fetch)
  [PASS] search_catalog returns typed results  (browser)
         367 results; first: "Harry Potter and the Philosopher's Stone" (Book)
  [PASS] search_catalog tells 'no results' apart from 'broken'  (browser)
  [PASS] check_availability returns copy-level data  (browser)
  [PASS] list_branches returns branches with hours  (browser)
         101 branches; 64 open now
  [PASS] list_events returns typed events  (browser)
         5980 upcoming events; 6 audiences, 27 event types
  [PASS] platform version  (browser)
         BiblioCommons 9.38.3 (the verified version)

Code

Meaning

INVALID_INPUT

The arguments were wrong

UNKNOWN_LIBRARY

No such library on this platform

NOT_FOUND

The library has no record of that title, branch or event

NOT_SUPPORTED

This library doesn't run that part of the platform

SITE_CHANGED

The website no longer matches what Stacks expects

SITE_UNAVAILABLE

The library's website returned a server error

SITE_BLOCKED

The website refused the request

UPSTREAM_TIMEOUT

The website or TinyFish took too long

RATE_LIMITED

Too many requests

TINYFISH_ERROR

TinyFish returned an error

CONFIG_ERROR

Stacks isn't set up correctly

JOB_FAILED

A background Agent run failed

Every error carries a code, a message and a hint that says what to do next.

🧬 What comes back

Tools return the same shapes whichever library you ask, so an agent learns them once. A title has an availability summary. Asking for more detail gives a list of branches, and each branch lists its copies with a status, call number and due date.

Every result also carries a source: which TinyFish endpoints read it, from which page, whether it came from the short cache, and when it was read. An answer can always be traced back.

erDiagram
  LIBRARY ||--o{ TITLE : "search_catalog"
  LIBRARY ||--o{ BRANCH : "list_branches"
  LIBRARY ||--o{ EVENT : "list_events"
  TITLE ||--|| AVAILABILITY : has
  TITLE ||--o{ BRANCH_AVAILABILITY : "check_availability"
  BRANCH_AVAILABILITY ||--o{ COPY : holds
  TITLE ||--o| WATCH : "watch_title"

  LIBRARY {
    string library_id
    string name
    string city
    string country
  }
  TITLE {
    string title_id
    string title
    string authors
    string format
    int year
  }
  AVAILABILITY {
    string status
    int total_copies
    int available_copies
    int holds
  }
  BRANCH_AVAILABILITY {
    string branch_name
    int copies_total
    int copies_on_shelf
    date next_due_date
  }
  COPY {
    string status
    string call_number
    date due_date
  }
  BRANCH {
    string name
    string address
    boolean open_now
  }
  EVENT {
    string title
    datetime start
    string branch_name
    boolean registration_required
  }
  WATCH {
    string watch_id
    string status
    string schedule_cron
  }

The full list of fields is in docs/TOOLS.md.

🧮 The wait estimate

estimate_wait answers "if I place a hold today, how long until I get it?" Library sites don't say, so Stacks works it out from what they do show, and labels the result as an estimate.

The idea is simple. Copies come back one at a time, and each returning copy goes to the next person in the queue. So Stacks works out which returning copy would be yours, and how many times the queue has to go all the way round before your turn.

It uses four things read live from the title's page: the number of holds $h$, the number of copies that can be borrowed $n$, the days until each copy is back $r_1 \le r_2 \le \dots \le r_n$ (its due date plus 3 days for transit and pickup), and the loan period $\ell$ (21 days unless you say otherwise).

$$p = h + 1 \qquad c = \ell + 3$$

$$\text{likely wait} = r_{,((p-1) \bmod n)+1} + \left\lfloor \frac{p-1}{n} \right\rfloor \cdot c$$

Here $p$ is your place in the queue and $c$ is one full lending cycle. The answer comes with a range, from 0.6 times the likely wait to 1.4 times plus 3 days, because people return books early and renew them.

Say a library has two copies, due back in 4 and 10 days, with 5 holds and a 21-day loan. These numbers are made up for illustration.

Step

Value

Days until each copy is ready

7 and 13

Your place in the queue

5 + 1 = 6

One lending cycle

21 + 3 = 24 days

Which copy is yours

the second one, ready in 13 days

Full rounds before your turn

2

Likely wait

13 + 2 × 24 = 61 days

Range

37 to 88 days

If a copy is on the shelf, the wait is zero and the result names the branches. If nothing can be borrowed, there is no estimate and the result says why.

🧱 Tech stack

Area

Choice

Why

Language

TypeScript 5.7, strict

One schema definition gives types, validation and documentation

Runtime

Node.js 20 or newer

Runs anywhere npx does

Protocol

MCP SDK 1.32

stdio for local apps, HTTP for remote ones, from one codebase

Web access

TinyFish SDK 0.11

Search, Fetch, Browser, Agent and Monitor

Browser control

playwright-core, connected remotely

Drives TinyFish's browser. Nothing is installed locally

Schemas

Zod 4

Checks every input and every page read

Database

None

Nothing is stored on disk

Tests

Vitest, 86 tests

Run offline against recorded pages

CI

GitHub Actions, Node 20 and 22

Lint, type check, tests with a coverage floor, build

Packaging

npm, a Claude Desktop bundle, Docker

npx or one click locally, a container for remote hosting

Testing happens at three levels. Offline tests run on every push with no network and no key. A live end-to-end run calls every core tool against three real libraries. And the daily canary keeps checking after release.

🚀 Quick start

You need two things: Node 20 or newer, and a TinyFish API key. Then pick your app below.

Download stacks.mcpb from the latest release and double-click it. Claude Desktop shows the Stacks icon, asks for your TinyFish key in a settings box, and installs it. There is no config file to edit.

Open Settings → Developer → Edit Config, add this, and restart Claude:

{
  "mcpServers": {
    "stacks": {
      "command": "npx",
      "args": ["-y", "stacks-mcp"],
      "env": { "TINYFISH_API_KEY": "your-key" }
    }
  }
}
claude mcp add stacks -e TINYFISH_API_KEY=your-key -- npx -y stacks-mcp

Use the same command, arguments and key as the hand-edited Claude Desktop block above.

ChatGPT reaches MCP servers over HTTPS, so Stacks has to run on a host in HTTP mode:

TINYFISH_API_KEY=your-key STACKS_HTTP_TOKEN=choose-a-secret npx -y stacks-mcp --http

Your MCP address is https://<your-host>/mcp/<your-secret>. In ChatGPT, go to Settings → Connectors → Advanced → Developer mode and add a connector with that address and no authentication. The included render.yaml and Dockerfile deploy it on Render's free tier.

Two rules apply when the server is reachable from outside this machine, as it is in Docker (HOST=0.0.0.0):

  • A server key needs a token. With TINYFISH_API_KEY set and no STACKS_HTTP_TOKEN, Stacks refuses to start. Otherwise anyone who found the address could spend your TinyFish credits.

  • GET /healthz is the health probe. It answers 200 with the status, version and uptime, needs no token and makes no TinyFish call. render.yaml already points at it.

git clone https://github.com/VivekSalwan2000/stacks-mcp.git
cd stacks-mcp
npm install
cp .env.example .env        # then put your TinyFish key in .env
npm run build
npm run e2e                 # calls every core tool against three live libraries

Variable

Default

Purpose

TINYFISH_API_KEY

required

Your TinyFish key

STACKS_DEFAULT_LIBRARY

none

The library to use when a call doesn't name one

STACKS_PROXY

auto

off, auto (retry through a proxy if blocked), tinyfish, or a country code

STACKS_AGENT_WAIT_MS

40000

How long Agent tools wait before handing back a job id

STACKS_HTTP_TOKEN

none

The secret HTTP mode asks for before it uses the server's own key

PORT

3000

Port for HTTP mode

HOST

see below

Address HTTP mode listens on

STACKS_LOG

on

Set to off to silence the log line written to stderr for each tool call

In HTTP mode, a caller can send their own TinyFish key and use their own credits. Otherwise the server uses its key, but only for callers who present the token. With no token set, the server listens on this machine only and turns away requests from other websites, so it is safe to run locally and can't be reached from outside.

If HOST is anything other than this machine (the Docker image uses 0.0.0.0) and the server has its own key, STACKS_HTTP_TOKEN is required: Stacks refuses to start without it. GET /healthz answers 200 with the status, version and uptime, needs no token and makes no TinyFish call.

Each tool call writes one JSON line to stderr: the tool, how long it took, whether the answer came from the cache, and the error code if it failed. It never contains what was searched for, results or keys.

Prompts to try

Each of these makes the agent chain several tools. Swap in your own city and titles.

Try

Tools it uses

I'm in Toronto. Is Project Hail Mary on the shelf anywhere right now, and how late is that branch open today?

find_library → search_catalog → check_availability → get_branch

How long would I wait for Dune at Vancouver Public Library? Compare the print book, the eBook and the audiobook.

search_catalog → get_title → estimate_wait

What's on for kids at Chicago Public Library this Saturday that doesn't need registration?

list_events, filtered by date and audience

I don't live in Toronto. Can I still get a library card, and what does it cost?

ask_library → get_job_result

Every copy of Atomic Habits is out at Toronto Public Library. Watch it for me and tell me what you set up.

search_catalog → watch_title → list_watches

🤝 Contributing

Contributions are welcome, and the project is laid out so they can be small.

I want to…

Where to start

Add my library to the list

One line in scripts/registry-candidates.json, then run the registry refresh

Fix a tool after a site change

Usually a few lines in the contract and the parser, plus a newly recorded page

Support another library platform

docs/ADDING_AN_ADAPTER.md. The tools, schemas and health check are reused

Report how my library behaves

A library compatibility report, whether it worked or not

Report a security problem

SECURITY.md, privately

Every pull request runs lint, a type check, the tests and a build. Start with CONTRIBUTING.md; the code of conduct and changelog are short.

On the roadmap: adapters for Aspen Discovery and Koha, a nearest_copy tool that combines shelf status with distance and opening hours, branch-level watches, and opt-in account actions such as placing holds.

🌱 Responsible use and limits

Stacks is a guest on library websites and behaves like one.

  • It only reads. It never logs in, places holds, signs up for events or submits forms, and it handles no personal data.

  • It reads on demand. A page is loaded when someone asks a question. Nothing is crawled.

  • It treads lightly. Answers are reused for a few minutes, requests to one site are spaced out, and images, fonts and stylesheets are never downloaded.

  • It stays on public pages, the same ones any visitor would open.

  • Staff-only details stay private. Page data sometimes includes internal notes. Stacks reads only the fields it needs, and a test checks the rest never appears in an answer.

What it can't do yet:

  • Only BiblioCommons libraries. Other platforms need an adapter.

  • No account actions. Placing a hold or renewing needs a login.

  • Some libraries block automated browsers. New York Public Library does today. Stacks reports that plainly instead of guessing.

  • Not every library runs every feature. Seattle keeps its events and branch pages elsewhere, so those two tools say "not supported" there.


Built for the TinyFish Student Bounty, Drop 002 · Site to MCP

MIT licensed · by Vivek Salwan

Stacks is an independent open-source project. It is not affiliated with or endorsed by BiblioCommons or any library.

Available Tools

14 tools
ask_libraryAsk about a library's servicesA
Read-onlyIdempotent

Answer an open-ended question about a library's services, policies or facilities by having a TinyFish Agent browse the library's own website. Use it for things the other tools do not cover, e.g. 'How do I get a card as a non-resident?', 'Can I book a study room at North York Central?', 'What are the overdue fines?'. Much slower than the other tools: a full answer usually takes 1 to 3 minutes. This call waits about 40 seconds; if the Agent is still working it returns status 'running' with a job_id, and you call get_job_result with that id until it is done.

Inputs: question (required), library. Returns: found, answer, job_id, source, +4 more

cancel_watchCancel a watchA
Destructive

Stop and permanently delete a watch created with watch_title. TinyFish stops re-checking the title and sends no more notifications. Only watches made by Stacks can be cancelled; get the watch_id from list_watches. Set dry_run to see which watch would be cancelled without cancelling it, for example to confirm with the user first.

Inputs: watch_id (required), dry_run. Returns: title, source, dry_run, library, +3 more

check_availabilityCheck availability by branchA
Read-onlyIdempotent

Live, copy-level availability for one title: which branches have it on the shelf right now, call numbers, and due dates for checked-out copies. Branches with a copy on the shelf are listed first.

Inputs: title_id (required), limit, branch, library, +1 more. Returns: title, format, source, library, +6 more

estimate_waitEstimate the wait for a titleA
Read-onlyIdempotent

Estimate how long you would wait if you placed a hold today, from the live hold queue, copy count and due dates. Also lists other formats of the same work with a shorter queue. This is an estimate computed by Stacks, not a figure published by the library.

Inputs: title_id (required), library, loan_days. Returns: basis, holds, title, format, +8 more

find_libraryFind a libraryA
Read-onlyIdempotent

Find the public library system for a city or library name and get its library_id. Call this first: every other tool needs the library_id. Covers library systems whose catalogue runs on BiblioCommons (e.g. Toronto, Vancouver, Chicago, Seattle, San Francisco, Boston, Ottawa, Calgary).

Inputs: query (required). Returns: note, source, matches

get_branchGet branch detailsB
Read-onlyIdempotent

Everything about one branch: weekly hours, whether it is open now, upcoming holiday closures, services and facilities (meeting rooms, printing, makerspaces), accessibility, parking and directions.

Inputs: branch (required), library. Returns: branch, source, library

get_job_resultGet the result of a running jobA
Read-onlyIdempotent

Fetch the result of a slow TinyFish Agent run that another Stacks tool started (a job_id from ask_library, a fallback_job_id from an error, or a diagnosis_job_id from health_check). If status is still 'running', wait about 15 seconds and call again.

Inputs: job_id (required). Returns: kind, error, job_id, result, +3 more

get_titleGet title detailsB
Read-onlyIdempotent

Full details for one title: description, contributors, publisher, ISBNs, subjects, series, and every other format the library holds it in.

Inputs: title_id (required), library. Returns: title, source, library

health_checkCheck that the tools still workA
Read-onlyIdempotent

Run live checks against a library's website to confirm every Stacks tool still works, and report exactly what broke if the site changed. Checks page landmarks (TinyFish Fetch) and the data contract of each tool using known-good queries (TinyFish Browser). Set deep to also start a TinyFish Agent that inspects a failing page and explains what changed. Takes about 20 to 40 seconds. Run this when a tool returns SITE_CHANGED.

Inputs: deep, library. Returns: checks, healthy, library, summary, +6 more

list_branchesList branchesA
Read-onlyIdempotent

List a library system's branches with address, phone, today's hours and whether each is open right now. Pass coordinates to sort by distance. Use get_branch for a branch's full weekly hours and services.

Inputs: limit, library, open_now, name_contains, +2 more. Returns: total, source, library, branches

list_eventsList events and programsA
Read-onlyIdempotent

Find events and programs at a library: storytimes, book clubs, classes, author talks. Filter by branch, date range, audience (e.g. kids, teens, adults) and type. Returns typed events with local start and end times and whether registration is required.

Inputs: page, limit, query, branch, +5 more. Returns: page, pages, total, events, +3 more

list_watchesList watchesA
Read-onlyIdempotent

List the title watches created with watch_title. Set check_now to also read each title's live availability, so you can tell the user whether a copy is available yet.

Inputs: check_now. Returns: source, watches

search_catalogSearch the catalogueA
Read-onlyIdempotent

Search a library's catalogue for books, eBooks, audiobooks, DVDs and more. Returns typed titles with live availability counts and hold queues. Use the title_id of a result with check_availability to see which branches have a copy on the shelf.

Inputs: query (required), page, format, library, +2 more. Returns: page, pages, query, total, +4 more

watch_titleWatch a title for availabilityA

Create a standing watch on a title using TinyFish Monitor. TinyFish re-reads the title's page on a schedule and detects when its availability changes (for example a copy comes back on the shelf). Notifications go to the webhook you pass, or to the alerts set up in the TinyFish dashboard. Use list_watches to see watches and their current availability.

Inputs: title_id (required), library, check_every, webhook_url. Returns: watch, source, already_existed, availability_at_creation

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 14 tools

    Disambiguation4/5

    Most tools have clearly distinct targets: list_branches vs get_branch, list_events, find_library, ask_library, and the watch trio (watch/list/cancel) are unambiguous. The main soft spot is the cluster around a single title — search_catalog, get_title, check_availability and estimate_wait all return title-level data and partially overlap (e.g. get_title and estimate_wait both list other formats), though the descriptions do a good job of drawing the lines and pointing to each other.

    Naming Consistency4/5

    Almost everything follows a clean snake_case verb_noun pattern (get_branch, list_branches, list_events, find_library, search_catalog, check_availability, get_title, watch_title, cancel_watch, get_job_result). The only real deviations are health_check (noun_noun) and the slightly softer ask_library/estimate_wait, which are still readable and consistent with the rest.

    Tool Count5/5

    14 tools is well within a healthy range and each one maps to a distinct capability: library lookup, branches, events, catalogue search, title detail, availability, wait estimation, a slow-agent fallback pair (ask_library/get_job_result), watch lifecycle, and diagnostics. Nothing feels padded or missing at the count level.

    Completeness3/5

    Discovery, branches, events, availability, alerts and a self-diagnostic path are all covered, and ask_library backstops policy questions. However the surface is read-only where the domain implies action: you can estimate a hold wait but there is no way to place or cancel a hold, and there are no account tools (my loans, holds, renewals), which are core library workflows. Also no get_event detail for individual events.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI coding agents with a live web search tool that returns extracted, answer-ready text from web pages. Enables real-time information retrieval without any local installation or maintenance.
      4 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to access US public library data from the federal IMLS Public Libraries Survey, including proximity searches, library system profiles, and statewide statistics.
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to search a curated catalog of practical AI books and retrieve book records, topics, reading paths, free chapters, glossary definitions, and verified claim citations. It also supports checking claims and generating citations from the catalog’s published free material.
      MIT