stagebook-mcp 0.0.0-stage → 0.1.1

package/LICENSE.md

@@ -0,0 +1,91 @@
+Required Notice: Copyright Stagebook (https://stagebook.app.br)
+
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any product that competes with the software or any product the licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality through different kinds of interfaces or for different technical platforms.  Applications can compete with services, libraries with plugins, frameworks with development tools, and so on, even if they're written in different programming languages or for different computer architectures.  Goods and services compete even when provided free of charge.  If you market a product as a practical substitute for the software or another product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does not compete, but the licensor or any of its affiliates brings your product into competition by providing a new version of the software or another product using the software, you may continue using versions of the software available under these terms beforehand to provide your competing product, but not any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product or service that the licensor or any of its affiliates has stopped providing, unless the licensor includes a plain-text line beginning with `Licensor Line of Business:` with the software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of business developing the software or using the software to provide a product, the buyer can also enforce [Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+A **product** can be a good or service, or a combination of them.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all its affiliates.
+
+**Affiliates** means the other organizations than an organization has control over, is under the control of, or is under common control with.
+
+**Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# Stagebook MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English** · [Português (Brasil)](README.pt-BR.md)
+
+Lets AI assistants read and edit the songs and setlists on your Stagebook tablet: "build a 15-song setlist for Saturday
+without repeating artists", "move every Skank song down a half tone", "check the chords of Hazard", "import this page".
+It's a [Model Context Protocol](https://modelcontextprotocol.io) server that runs on your computer and talks to the
+tablet over the local network, through the same connection as **Settings → Edit on the computer**. Nothing goes to the
+internet, and the app itself doesn't change: what the assistant saves shows on the stage right away.
+
+Works with Claude Code, Claude Desktop and any assistant that runs local MCP servers (Cursor, VS Code with Copilot,
+Windsurf, Gemini CLI, OpenAI Codex CLI…).
+
+## What it can do
+
+| Area | Tools |
+|---|---|
+| Connection | `stagebook_connect` (finds the tablet and asks to come in), `stagebook_status` |
+| Songs | `list_songs` (filters: text, tag, key), `get_song`, `create_song`, `update_song`, `delete_song`, `transpose_song`, `set_capo` |
+| Import | `import_song` (pasted lyrics/chords in any common format, or a song page address) |
+| Backing tracks | `set_backing_track` (OGG, MP3 or WAV from this computer), `remove_backing_track` |
+| Setlists | `list_setlists`, `get_setlist`, `create_setlist`, `update_setlist`, `delete_setlist` |
+| Receiving | `receive_by_code` (the 3 words), `receive_create`, `band_inbox`, `band_sync`, `open_band_item` |
+| Backup | `restore_backup` (inspect a `.stagebook` file, add what's missing or replace the library) |
+
+Also **resources** (`stagebook://songs`, `stagebook://setlists`, `stagebook://songs/{id}` as ChordPro) and **prompts**
+(`build_setlist`, `fix_chords`, `transpose_for_singer`).
+
+Deleting, removing a track, emptying a setlist, replacing the library and restoring settings (they replace the
+tablet's stage look, pedals, USB audio interface and band) need `confirm: true`: the assistant has to ask you first.
+
+Files to send (backing tracks, backups) take a full path; `~` is your home folder. The tablet takes tracks up to
+200 MB and backups up to 1 GB. If the assistant gives up on a long call, the upload or restore stops too.
+
+## Install
+
+Needs [Node.js](https://nodejs.org) 20 or newer.
+
+```sh
+npx -y stagebook-mcp
+```
+
+That's the server: your assistant starts it by itself with the settings below (`npx` downloads it the first time and
+keeps it up to date), so there's nothing to run by hand.
+
+## Connect your assistant
+
+**Claude Code**
+
+```sh
+claude mcp add stagebook -- npx -y stagebook-mcp
+```
+
+**Claude Desktop** — Settings → Developer → Edit config (`claude_desktop_config.json`):
+
+```json
+{ "mcpServers": { "stagebook": { "command": "npx", "args": ["-y", "stagebook-mcp"] } } }
+```
+
+**Cursor** (`~/.cursor/mcp.json`) and **Windsurf** (`~/.codeium/windsurf/mcp_config.json`): the same `mcpServers` block.
+
+**VS Code** (`.vscode/mcp.json` in a project, or the user `mcp.json`):
+
+```json
+{ "servers": { "stagebook": { "type": "stdio", "command": "npx", "args": ["-y", "stagebook-mcp"] } } }
+```
+
+**Gemini CLI** (`~/.gemini/settings.json`): the same `mcpServers` block as Claude Desktop.
+
+**OpenAI Codex CLI** (`~/.codex/config.toml`):
+
+```toml
+[mcp_servers.stagebook]
+command = "npx"
+args = ["-y", "stagebook-mcp"]
+```
+
+ChatGPT's own app only connects to remote servers (over the internet), so it can't reach the tablet on your Wi-Fi.
+
+## First use
+
+1. On the tablet: open Stagebook and turn on **Settings → Edit on the computer**. It shows the address
+   (e.g. `http://192.168.0.10:8090`). The computer and the tablet must be on the same Wi-Fi.
+2. Ask the assistant to connect to Stagebook. It searches the network (or you give it the address) and the tablet shows
+   a request with a code. If more than one tablet with Stagebook answers (a band on the same Wi-Fi), it asks which
+   address is yours; if your tablet's address changed, it searches again.
+3. If the code matches, tap **Allow** on the tablet. The key is saved on this computer
+   (`~/.config/stagebook-mcp/config.json`, readable only by you); next time it connects without asking.
+
+The editor turns itself off on the tablet when unused: turn it on again when you want to use the assistant. The key
+lasts 90 days without use; **Settings → Edit on the computer → Authorized computers** removes it at any time.
+
+### Settings
+
+| Variable | What for |
+|---|---|
+| `STAGEBOOK_URL` | The tablet's address, skipping the search (e.g. `http://192.168.0.10:8090`). |
+| `STAGEBOOK_KEY` | A key instead of the saved one. |
+| `STAGEBOOK_CONFIG` | Another place for the saved address and key. |
+
+## If it doesn't connect
+
+- **"Stagebook wasn't found" / "Couldn't reach"**: the tablet's Stagebook must be open with **Settings → Edit on the
+  computer** on, on the same Wi-Fi as the computer (not a guest network). Pass the address shown there to the connect tool.
+- **On a Mac, "macOS blocked the connection"**: macOS asks before an app talks to devices on the local network. Open
+  **System Settings → Privacy & Security → Local Network** and turn on the app that runs the assistant (Claude, Terminal,
+  iTerm, Cursor, VS Code…), then restart that app.
+- **"No longer accepts this computer's key"**: it was removed on the tablet or went 90 days unused. Connect again.
+- **"Already showing a request, or one was just denied"**: answer the request on the tablet; after a Deny it waits
+  5 minutes before taking a new one.
+- **"Not found on the tablet, or that part is turned off"**: receiving by code needs the internet on, and the band
+  tools need the band on, in the tablet's Settings.
+
+## Privacy
+
+Everything stays on your network: the server talks only to the tablet. The assistant sees what its tools return
+(titles, artists, chords and, when it asks for them, the lyrics) and sends that to its AI provider like the rest of your
+conversation. Lyrics are copyrighted: the server tells the assistant not to reproduce them in full.
+
+## Development
+
+```sh
+git clone https://github.com/julianoAffonso/stagebook.git
+cd stagebook/mcp
+npm install
+npm test   # builds and runs the tests against a fake tablet
+```
+
+The tools are in `src/server.ts`; the calls to the tablet in `src/client.ts` (the same HTTP API as the computer editor's
+page, in the app's `data/web/`).

package/README.pt-BR.md

@@ -0,0 +1,133 @@
+# Stagebook MCP
+
+[English](README.md) · **Português (Brasil)**
+
+Deixa assistentes de IA lerem e editarem as músicas e os setlists do seu tablet com o Stagebook: "monta um setlist de
+15 músicas para sábado sem repetir artista", "passa todas as do Skank meio tom abaixo", "confere os acordes de Hazard",
+"importa esta página". É um servidor [Model Context Protocol](https://modelcontextprotocol.io) que roda no seu computador
+e conversa com o tablet pela rede local, pela mesma conexão de **Ajustes → Editar no computador**. Nada vai para a
+internet e o app não muda: o que o assistente salva aparece no palco na hora.
+
+Funciona com o Claude Code, o Claude Desktop e qualquer assistente que roda servidores MCP locais (Cursor, VS Code com
+Copilot, Windsurf, Gemini CLI, OpenAI Codex CLI…).
+
+## O que ele faz
+
+| Assunto | Ferramentas |
+|---|---|
+| Conexão | `stagebook_connect` (acha o tablet e pede para entrar), `stagebook_status` |
+| Músicas | `list_songs` (filtros: texto, tag, tom), `get_song`, `create_song`, `update_song`, `delete_song`, `transpose_song`, `set_capo` |
+| Importar | `import_song` (letra e cifra coladas em qualquer formato comum, ou o endereço de uma página) |
+| Backing tracks | `set_backing_track` (OGG, MP3 ou WAV do computador), `remove_backing_track` |
+| Setlists | `list_setlists`, `get_setlist`, `create_setlist`, `update_setlist`, `delete_setlist` |
+| Receber | `receive_by_code` (as 3 palavras), `receive_create`, `band_inbox`, `band_sync`, `open_band_item` |
+| Backup | `restore_backup` (ver o que um arquivo `.stagebook` tem, juntar o que falta ou substituir a biblioteca) |
+
+Tem também **recursos** (`stagebook://songs`, `stagebook://setlists`, `stagebook://songs/{id}` em ChordPro) e **roteiros
+prontos** (`build_setlist`, `fix_chords`, `transpose_for_singer`).
+
+Apagar, tirar uma faixa, esvaziar um setlist, substituir a biblioteca e restaurar os ajustes (eles substituem o visual
+do palco, os pedais, a interface de áudio USB e a banda do tablet) pedem `confirm: true`: o assistente precisa
+perguntar a você antes.
+
+Os arquivos a enviar (backing tracks, backups) vão com o caminho completo; `~` é a sua pasta pessoal. O tablet aceita
+faixas de até 200 MB e backups de até 1 GB. Se o assistente desistir de uma chamada longa, o envio ou a restauração
+param também.
+
+## Instalar
+
+Precisa do [Node.js](https://nodejs.org) 20 ou mais novo.
+
+```sh
+npx -y stagebook-mcp
+```
+
+Esse é o servidor: o assistente abre ele sozinho com os ajustes abaixo (o `npx` baixa da primeira vez e mantém
+atualizado), então não precisa rodar nada à mão.
+
+## Ligar no seu assistente
+
+**Claude Code**
+
+```sh
+claude mcp add stagebook -- npx -y stagebook-mcp
+```
+
+**Claude Desktop** — Configurações → Desenvolvedor → Editar configuração (`claude_desktop_config.json`):
+
+```json
+{ "mcpServers": { "stagebook": { "command": "npx", "args": ["-y", "stagebook-mcp"] } } }
+```
+
+**Cursor** (`~/.cursor/mcp.json`) e **Windsurf** (`~/.codeium/windsurf/mcp_config.json`): o mesmo bloco `mcpServers`.
+
+**VS Code** (`.vscode/mcp.json` num projeto, ou o `mcp.json` do usuário):
+
+```json
+{ "servers": { "stagebook": { "type": "stdio", "command": "npx", "args": ["-y", "stagebook-mcp"] } } }
+```
+
+**Gemini CLI** (`~/.gemini/settings.json`): o mesmo bloco `mcpServers` do Claude Desktop.
+
+**OpenAI Codex CLI** (`~/.codex/config.toml`):
+
+```toml
+[mcp_servers.stagebook]
+command = "npx"
+args = ["-y", "stagebook-mcp"]
+```
+
+O app do ChatGPT só se conecta a servidores remotos (pela internet), então não alcança o tablet no seu Wi-Fi.
+
+## Primeira vez
+
+1. No tablet: abra o Stagebook e ligue **Ajustes → Editar no computador**. Ele mostra o endereço
+   (ex.: `http://192.168.0.10:8090`). O computador e o tablet precisam estar no mesmo Wi-Fi.
+2. Peça ao assistente para conectar no Stagebook. Ele procura na rede (ou você passa o endereço) e o tablet mostra um
+   pedido com um código. Se mais de um tablet com o Stagebook responder (uma banda no mesmo Wi-Fi), ele pergunta qual
+   endereço é o seu; se o endereço do seu tablet mudou, ele procura de novo.
+3. Se o código bater, toque em **Permitir** no tablet. A chave fica guardada neste computador
+   (`~/.config/stagebook-mcp/config.json`, que só você lê); da próxima vez ele conecta sem perguntar.
+
+O editor desliga sozinho no tablet quando fica sem uso: ligue de novo quando quiser usar o assistente. A chave dura 90
+dias sem uso; **Ajustes → Editar no computador → Computadores autorizados** remove a qualquer hora.
+
+### Ajustes
+
+| Variável | Para quê |
+|---|---|
+| `STAGEBOOK_URL` | O endereço do tablet, sem procurar (ex.: `http://192.168.0.10:8090`). |
+| `STAGEBOOK_KEY` | Uma chave no lugar da guardada. |
+| `STAGEBOOK_CONFIG` | Outro lugar para o endereço e a chave guardados. |
+
+## Se não conectar
+
+- **"Stagebook wasn't found" / "Couldn't reach"**: o Stagebook precisa estar aberto no tablet, com **Ajustes → Editar no
+  computador** ligado, no mesmo Wi-Fi do computador (não numa rede de convidados). Passe ao assistente o endereço que
+  aparece ali.
+- **No Mac, "macOS blocked the connection"**: o macOS pergunta antes de um app conversar com aparelhos da rede local.
+  Abra **Ajustes do Sistema → Privacidade e Segurança → Rede Local** e ligue o app que roda o assistente (Claude,
+  Terminal, iTerm, Cursor, VS Code…). Depois reabra esse app.
+- **"No longer accepts this computer's key"**: a chave foi removida no tablet ou passou 90 dias sem uso. Conecte de novo.
+- **"Already showing a request, or one was just denied"**: responda o pedido no tablet; depois de um Negar, ele espera
+  5 minutos para aceitar outro.
+- **"Not found on the tablet, or that part is turned off"**: receber por código precisa da internet ligada, e as
+  ferramentas de banda precisam da banda ligada, nos Ajustes do tablet.
+
+## Privacidade
+
+Tudo fica na sua rede: o servidor só conversa com o tablet. O assistente vê o que as ferramentas devolvem (títulos,
+artistas, acordes e, quando ele pede, a letra) e manda isso para o provedor de IA dele, como o resto da conversa. Letras
+têm direito autoral: o servidor orienta o assistente a não reproduzi-las inteiras.
+
+## Para quem programa
+
+```sh
+git clone https://github.com/julianoAffonso/stagebook.git
+cd stagebook/mcp
+npm install
+npm test   # compila e roda os testes contra um tablet de mentira
+```
+
+As ferramentas ficam em `src/server.ts`; as chamadas ao tablet em `src/client.ts` (a mesma API HTTP da página do editor
+no computador, em `data/web/` no app).

package/dist/client.js

@@ -0,0 +1,277 @@
+// Talks to Stagebook's "Edit on the computer" server on the tablet: the same HTTP API its web page uses.
+// Every call carries the X-Stagebook header and, once approved on the tablet, the stagebook_key cookie.
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { networkInterfaces, homedir } from "node:os";
+import { dirname, join } from "node:path";
+export const COOKIE = "stagebook_key";
+const PORTS = [8090, 8091, 8092];
+/** Where the tablet's address and key are kept between sessions (or STAGEBOOK_CONFIG). */
+export function configPath() {
+    return process.env.STAGEBOOK_CONFIG ?? join(homedir(), ".config", "stagebook-mcp", "config.json");
+}
+export async function loadSaved() {
+    try {
+        return JSON.parse(await readFile(configPath(), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export async function save(s) {
+    await mkdir(dirname(configPath()), { recursive: true });
+    // the key gives access to the library: readable by this user only. The mode only applies when the file is created,
+    // so an existing one (or one at STAGEBOOK_CONFIG) is set again (audit 03/11)
+    await writeFile(configPath(), JSON.stringify(s, null, 2), { mode: 0o600 });
+    await chmod(configPath(), 0o600);
+}
+/** A problem the assistant should explain to the person, with what to do. */
+export class StagebookError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+export class StagebookClient {
+    url;
+    key;
+    timeoutMs;
+    constructor(url, key, timeoutMs = 15000) {
+        this.url = url;
+        this.key = key;
+        this.timeoutMs = timeoutMs;
+    }
+    static async fromEnv() {
+        const saved = await loadSaved();
+        return new StagebookClient(process.env.STAGEBOOK_URL ?? saved.url, process.env.STAGEBOOK_KEY ?? saved.key);
+    }
+    base() {
+        if (!this.url) {
+            throw new StagebookError("Stagebook's address isn't known yet. Open Stagebook on the tablet, turn on Settings → Edit on the computer, " +
+                "then use the connect tool (it finds the tablet on the network) or set STAGEBOOK_URL (e.g. http://192.168.0.10:8090).");
+        }
+        return this.url.replace(/\/+$/, "");
+    }
+    /** One API call. [body]: JSON object, raw bytes (uploads) or nothing. */
+    async call(method, path, body, opts = {}) {
+        const url = new URL(this.base() + path);
+        for (const [k, v] of Object.entries(opts.query ?? {}))
+            url.searchParams.set(k, v);
+        const headers = { "X-Stagebook": "1" };
+        if (opts.auth !== false) {
+            await this.awaitApproval();
+            if (!this.key)
+                throw new StagebookError("This computer isn't approved on the tablet yet: use the connect tool first.");
+            headers.Cookie = `${COOKIE}=${this.key}`;
+        }
+        let payload;
+        if (body instanceof Uint8Array) {
+            payload = body;
+            headers["Content-Type"] = "application/octet-stream";
+        }
+        else if (body !== undefined) {
+            payload = JSON.stringify(body);
+            headers["Content-Type"] = "application/json";
+        }
+        let res;
+        try {
+            const limit = AbortSignal.timeout(opts.timeoutMs ?? this.timeoutMs);
+            res = await fetch(url, { method, headers, body: payload, signal: opts.signal ? AbortSignal.any([limit, opts.signal]) : limit });
+        }
+        catch (e) {
+            if (opts.signal?.aborted)
+                throw new StagebookError("The call was cancelled.");
+            throw new StagebookError(unreachable(this.base(), e));
+        }
+        const text = await res.text();
+        let json = undefined;
+        if (text) {
+            try {
+                json = JSON.parse(text);
+            }
+            catch {
+                json = text;
+            }
+        }
+        if (res.status === 401) {
+            // the dead key goes: kept, the next call (after connecting again) sent it instead of waiting for Allow (audit 03/11)
+            if (opts.auth !== false)
+                this.key = undefined;
+            throw new StagebookError("The tablet no longer accepts this computer's key (removed, or 90 days unused): use the connect tool again.", 401);
+        }
+        if (res.status === 403)
+            throw new StagebookError("The tablet refused the call (forbidden).", 403);
+        // the tablet answers 429 to a new request while one is on its screen, and for 5 minutes after a Deny (this
+        // check sat in startPair, after the generic error had already been thrown: "HTTP 429"; audit 03/11)
+        if (res.status === 429) {
+            throw new StagebookError("The tablet is already showing a request, or one was just denied (it then waits 5 minutes): answer it there, or wait and connect again.", 429);
+        }
+        if (res.status >= 400 && res.status !== 404) {
+            const why = json && typeof json === "object" && json.error ? json.error : `HTTP ${res.status}`;
+            throw new StagebookError(problemText(why), res.status);
+        }
+        return { status: res.status, json, headers: res.headers };
+    }
+    async get(path) {
+        return this.send("GET", path);
+    }
+    async send(method, path, body, query, timeoutMs, signal) {
+        const r = await this.call(method, path, body, { query, timeoutMs, signal });
+        // the tablet answers 404 also for what is turned off there (internet, band): "not found" alone misled (audit 03/11)
+        if (r.status === 404)
+            throw new StagebookError("Not found on the tablet, or that part is turned off there (the internet or the band, in Settings).", 404);
+        return r.json;
+    }
+    /** The approval being waited for (pairing runs past the tool call: assistants give up on a call after ~60 s). */
+    pending;
+    pendingId;
+    /**
+     * Asks the tablet to let this computer in: Stagebook shows a request with a code. Returns the code at once; the wait
+     * for the person to tap Allow goes on in [pending] (up to [waitMs], the 2 minutes the tablet keeps a request), which
+     * saves the key when it comes.
+     */
+    async startPair(name, waitMs = 120000) {
+        // a new request replaces whatever key was loaded (another tablet, or one the tablet no longer accepts): the next
+        // call waits for this approval instead of sending the old key (audit 03/11)
+        this.key = undefined;
+        const asked = await this.call("POST", "/api/ask", { name }, { auth: false });
+        const { id, code } = asked.json ?? {};
+        if (!id)
+            throw new StagebookError("The tablet didn't accept the request.");
+        // connecting twice gets the same request back: one wait for it (two polled it, and the tablet hands the answer
+        // out once, so the other said "expired" even after Allow; audit 03/11)
+        if (this.pending && this.pendingId === String(id))
+            return String(code ?? "");
+        this.pendingId = String(id);
+        const p = this.waitApproval(String(id), waitMs).finally(() => {
+            if (this.pending === p) {
+                this.pending = undefined;
+                this.pendingId = undefined;
+            }
+        });
+        this.pending = p;
+        p.catch(() => { }); // a refusal is reported by the next call that waits on it
+        return String(code ?? "");
+    }
+    async waitApproval(id, waitMs) {
+        const until = Date.now() + waitMs;
+        while (Date.now() < until) {
+            let r;
+            try {
+                r = await this.call("GET", "/api/ask", undefined, { auth: false, query: { id } });
+            }
+            catch (e) {
+                if (e instanceof StagebookError && e.status === 403)
+                    throw new StagebookError("The request was denied on the tablet.");
+                throw e;
+            }
+            if (r.status === 200) {
+                const key = cookieValue(r.headers.get("set-cookie"));
+                if (!key)
+                    throw new StagebookError("Approved, but the tablet sent no key.");
+                this.key = key;
+                await save({ url: this.url, key });
+                return key;
+            }
+            if (r.status === 404)
+                throw new StagebookError("The request expired on the tablet: connect again.");
+            await new Promise((ok) => setTimeout(ok, 1500));
+        }
+        throw new StagebookError("Nobody tapped Allow on the tablet in 2 minutes: connect again.");
+    }
+    /**
+     * Waits a while for a pending approval before a call needs the key, within one tool call's time: 40 s plus the
+     * call's own 15 s stays under the ~60 s an assistant gives a tool.
+     */
+    async awaitApproval(maxMs = 40000) {
+        if (this.key || !this.pending)
+            return;
+        let timer;
+        const timeout = new Promise((ok) => { timer = setTimeout(ok, maxMs); });
+        try {
+            await Promise.race([this.pending.then(() => undefined), timeout]);
+        }
+        finally {
+            clearTimeout(timer); // otherwise it held the process 40 s after the approval came
+        }
+        if (!this.key)
+            throw new StagebookError("Still waiting for Allow on the tablet: tap it there, then try again.");
+    }
+    /** Pairs and waits for the approval (tests and scripts; tools use startPair). */
+    async pair(name, onCode, waitMs = 120000) {
+        onCode(await this.startPair(name, waitMs));
+        return this.pending;
+    }
+}
+/**
+ * Why the tablet couldn't be reached, in words. EHOSTUNREACH while the tablet answers a browser is usually macOS's
+ * Local Network privacy blocking the program that runs this server (Node), not the network.
+ */
+export function unreachable(base, e) {
+    const code = e?.cause?.code;
+    if (code === "EHOSTUNREACH" && process.platform === "darwin") {
+        return `macOS blocked the connection to ${base} (Local Network privacy). Open System Settings → Privacy & Security → ` +
+            "Local Network and turn on the app that runs this assistant (Claude, Terminal, Cursor, VS Code…), then restart it.";
+    }
+    return `Couldn't reach Stagebook at ${base}. Check that the tablet is on the same Wi-Fi, Stagebook is open and ` +
+        "Settings → Edit on the computer is on (it turns itself off when unused).";
+}
+/** The stagebook_key value in a Set-Cookie header. */
+export function cookieValue(setCookie) {
+    const m = setCookie?.match(new RegExp(`${COOKIE}=([^;]+)`));
+    return m?.[1];
+}
+/** The app's error codes, in words an assistant can pass on. */
+export function problemText(code) {
+    const known = {
+        title_empty: "The song needs a title.",
+        title_taken: "There's already a song with this title and artist.",
+        not_song: "That doesn't look like lyrics or chords (Stagebook keeps only song text).",
+        offline: "Stagebook has the internet or the band turned off (essential mode), or there's no connection.",
+        bad_address: "The address must start with http:// or https://.",
+        unreadable: "Couldn't read that page or file.",
+        not_found: "Not found.",
+        search_page: "That's a search page, not a song page: pass the song's own address.",
+        expired: "That expired: start again.",
+        format: "That file isn't an audio format Stagebook plays (OGG, MP3 or WAV).",
+    };
+    return known[code] ?? `The tablet answered: ${code}`;
+}
+/** Does Stagebook's editor answer at [base]? (Its page's strings: the editor is on and it is Stagebook.) */
+export async function answers(base, timeoutMs = 600) {
+    try {
+        const res = await fetch(base.replace(/\/+$/, "") + "/api/strings", { headers: { "X-Stagebook": "1" }, signal: AbortSignal.timeout(timeoutMs) });
+        return res.ok && (await res.text()).includes("{");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Looks for Stagebook on the local networks (every address of each /24 this computer is on, ports 8090-8092): the
+ * editor answers its page there while it's on. Returns every tablet that answers: on a band's Wi-Fi there can be
+ * several, and the request must not land on a bandmate's tablet (audit 03/11).
+ */
+export async function discoverAll(timeoutMs = 600) {
+    const prefixes = new Set();
+    for (const list of Object.values(networkInterfaces())) {
+        for (const a of list ?? []) {
+            if (a.family === "IPv4" && !a.internal && /^(10|172|192)\./.test(a.address))
+                prefixes.add(a.address.split(".").slice(0, 3).join("."));
+        }
+    }
+    const candidates = [];
+    for (const p of prefixes)
+        for (let i = 1; i < 255; i++)
+            for (const port of PORTS)
+                candidates.push(`http://${p}.${i}:${port}`);
+    const found = [];
+    // in batches, so a whole /24 doesn't open hundreds of sockets at once
+    for (let i = 0; i < candidates.length; i += 128) {
+        const batch = candidates.slice(i, i + 128);
+        const ok = await Promise.all(batch.map((u) => answers(u, timeoutMs)));
+        batch.forEach((u, k) => { if (ok[k])
+            found.push(u); });
+    }
+    return found;
+}

package/dist/index.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// Stagebook MCP server over stdio: what Claude Code, Claude Desktop, Cursor, VS Code, Gemini CLI, Codex and other MCP
+// clients start as a local command.
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StagebookClient } from "./client.js";
+import { buildServer } from "./server.js";
+const client = await StagebookClient.fromEnv();
+const server = buildServer(client);
+await server.connect(new StdioServerTransport());

package/dist/server.js

@@ -0,0 +1,399 @@
+// The MCP side: tools, resources and prompts over the tablet's API (client.ts). Every write goes through the same rules
+// as the app's editor (the tablet applies them), and the stage on the tablet follows right away.
+import { readFileSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join } from "node:path";
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { StagebookError, answers, discoverAll, save } from "./client.js";
+// the one in package.json (it ships beside dist/), so the two never disagree
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const text = (value) => ({ content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }] });
+// every tool answers a StagebookError as a readable message instead of failing the call. [signal]: the assistant gave up
+// on the call (it waits ~60 s); long calls pass it on, so an upload or a restore stops instead of finishing unseen
+// after the assistant was told it failed (audit 03/11)
+function safe(run) {
+    return async (args, extra) => {
+        try {
+            return await run(args, extra?.signal);
+        }
+        catch (e) {
+            const msg = e instanceof StagebookError ? e.message : `Unexpected error: ${e.message}`;
+            return { ...text(msg), isError: true };
+        }
+    };
+}
+/** A song for the assistant: without the lyrics unless asked (they are often long). */
+function songOut(s, withText) {
+    const { text: lyrics, ...rest } = s;
+    return withText ? s : { ...rest, lines: lyrics.split("\n").length, chords: chordsIn(lyrics) };
+}
+/** The distinct chords of a ChordPro text, in order of appearance. */
+export function chordsIn(chordpro) {
+    const seen = new Set();
+    for (const m of chordpro.matchAll(/\[([A-G][^\[\]\s]*)\]/g))
+        seen.add(m[1]);
+    return [...seen];
+}
+// the tablet's limits (WebEditorServer): a backing track as in the app, a backup with every track
+const TRACK_MAX = 200 * 1024 * 1024;
+const BACKUP_MAX = 1024 * 1024 * 1024;
+/**
+ * A file on this computer to send: `~` is the home folder, a relative path is refused (it would resolve against the
+ * assistant app's folder, not the person's), and one over the tablet's limit is refused here (the tablet closed the
+ * connection, which read as "Couldn't reach"). Read once: the copy into a new array held a backup twice (audit 03/11).
+ */
+export async function localFile(path, max) {
+    const full = path === "~" || path.startsWith("~/") ? join(homedir(), path.slice(1)) : path;
+    if (!isAbsolute(full))
+        throw new StagebookError(`Pass the file's full path (like /Users/name/Music/song.mp3 or ~/Music/song.mp3), not "${path}".`);
+    let size;
+    try {
+        size = (await stat(full)).size;
+    }
+    catch {
+        throw new StagebookError(`There's no file at ${full}.`);
+    }
+    if (size > max)
+        throw new StagebookError(`The file is ${Math.round(size / 1048576)} MB; the tablet takes up to ${Math.round(max / 1048576)} MB.`);
+    return readFile(full);
+}
+const norm = (s) => s.normalize("NFD").replace(/\p{Diacritic}/gu, "").toLowerCase();
+export function buildServer(client) {
+    const server = new McpServer({ name: "stagebook", version: VERSION }, {
+        instructions: "Stagebook is an Android app for lyrics, chords (ChordPro), setlists and backing tracks used live by musicians. " +
+            "These tools edit the library on the person's tablet over the local network; the stage updates right away. " +
+            "First use: call stagebook_connect (the person approves on the tablet). Song text is ChordPro: chords in brackets " +
+            "before the syllable ([G]Here I [D]go), sections as [Verse 1]/[Chorus] lines (Portuguese names work too) or " +
+            "{start_of_chorus}; key, capo and " +
+            "BPM are separate fields. Ask before deleting anything. Song lyrics are copyrighted: don't reproduce them in full " +
+            "to the person unless they ask for their own song.",
+    });
+    /**
+     * Transpose or capo: the tablet reworks the song's text with its own rules ([route]), then the song is saved with
+     * the new text, key and capo (the two tools were the same three calls).
+     */
+    async function rework(id, route, change) {
+        const cur = (await client.get(`/api/songs/${encodeURIComponent(id)}`));
+        const out = await client.send("POST", route, { text: cur.text, ...change, meta: { key: cur.key, capo: cur.capo } });
+        const key = out.meta?.key ?? cur.key;
+        const capo = out.meta?.capo ?? change.capo ?? cur.capo;
+        await client.send("PUT", `/api/songs/${encodeURIComponent(id)}`, { ...cur, text: out.text, key, capo });
+        return { cur, key: out.meta?.key, capo: out.meta?.capo };
+    }
+    // ---------- connection ----------
+    server.registerTool("stagebook_connect", {
+        title: "Connect to the Stagebook tablet",
+        description: "Finds Stagebook on the local network (or uses the given address) and asks the tablet to let this computer in. " +
+            "The tablet shows a request with a code: this tool returns at once with the code; tell the person and ask them to tap " +
+            "Allow on the tablet, then call stagebook_status, which waits for it. Needs Stagebook open with Settings → Edit on " +
+            "the computer turned on. The key is saved for next time.",
+        inputSchema: {
+            url: z.string().optional().describe("Address shown in Stagebook, e.g. http://192.168.0.10:8090. Omit to search the network."),
+            name: z.string().optional().describe("How this computer shows on the tablet (default: 'AI assistant')."),
+        },
+    }, safe(async ({ url, name }) => {
+        if (url)
+            client.url = url;
+        // no address given: the saved one if it still answers, otherwise search again (the tablet's address can change
+        // with the Wi-Fi; the saved one was used forever, audit 03/11)
+        else if (!client.url || !(await answers(client.url))) {
+            const found = await discoverAll();
+            if (found.length === 0) {
+                throw new StagebookError("Stagebook wasn't found on this network. On the tablet: open Stagebook and turn on Settings → Edit on the computer; " +
+                    "it shows the address to pass here. On a Mac, also check System Settings → Privacy & Security → Local Network " +
+                    "for the app that runs this assistant.");
+            }
+            if (found.length > 1) {
+                throw new StagebookError(`Stagebook answers on more than one tablet here: ${found.join(", ")}. Ask the person which address their tablet ` +
+                    "shows in Settings → Edit on the computer and pass it as url.");
+            }
+            client.url = found[0];
+        }
+        await save({ url: client.url, key: client.key });
+        const code = await client.startPair(name ?? "AI assistant");
+        return text(`Stagebook found at ${client.url}. The tablet now shows a request with the code ${code}: ask the person to check it ` +
+            "and tap Allow on the tablet. Then call stagebook_status (it waits for the approval); the key is saved for next time.");
+    }));
+    server.registerTool("stagebook_status", {
+        title: "Stagebook connection status",
+        description: "Checks the connection: the tablet's address, its name and how this computer is known there.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, safe(async () => {
+        const s = await client.get("/api/session");
+        return text({ url: client.url, device: s?.app, thisComputer: s?.name });
+    }));
+    // ---------- songs ----------
+    server.registerTool("list_songs", {
+        title: "List songs",
+        description: "The library's songs (id, title, artist, year, key, tags), in the app's order. Optional filters.",
+        inputSchema: {
+            query: z.string().optional().describe("Part of the title or artist (accents and case ignored)."),
+            tag: z.string().optional().describe("Only songs with this tag."),
+            key: z.string().optional().describe("Only songs in this key, e.g. G or Am."),
+        },
+        annotations: { readOnlyHint: true },
+    }, safe(async ({ query, tag, key }) => {
+        let songs = (await client.get("/api/songs"));
+        if (query)
+            songs = songs.filter((s) => norm(`${s.title} ${s.author}`).includes(norm(query)));
+        if (tag)
+            songs = songs.filter((s) => s.tags.some((t) => norm(t) === norm(tag)));
+        if (key)
+            songs = songs.filter((s) => s.key.toLowerCase() === key.toLowerCase());
+        return text({ count: songs.length, songs });
+    }));
+    server.registerTool("get_song", {
+        title: "Get a song",
+        description: "One song's details: title, artist, year, BPM, key, capo, tags, backing track and its chords. With include_text, the full ChordPro text.",
+        inputSchema: {
+            id: z.string(),
+            include_text: z.boolean().optional().describe("Also return the lyrics and chords (ChordPro). Default false."),
+        },
+        annotations: { readOnlyHint: true },
+    }, safe(async ({ id, include_text }) => text(songOut((await client.get(`/api/songs/${encodeURIComponent(id)}`)), !!include_text))));
+    const songFields = {
+        title: z.string().optional(),
+        author: z.string().optional().describe("Artist."),
+        year: z.string().optional(),
+        tempo: z.string().optional().describe("BPM, e.g. '120'."),
+        text: z.string().optional().describe("Lyrics and chords in ChordPro (chords above the lyrics are converted too)."),
+        key: z.string().optional().describe("The song's key, e.g. G."),
+        capo: z.number().int().min(0).max(12).optional(),
+        tags: z.array(z.string()).optional(),
+    };
+    server.registerTool("create_song", {
+        title: "Create a song",
+        description: "Adds a song to the library. Title and text are required; the tablet refuses a repeated title+artist or text that isn't a song.",
+        inputSchema: { ...songFields, title: z.string(), text: z.string() },
+    }, safe(async (a) => {
+        const r = await client.send("POST", "/api/songs", { title: a.title, author: a.author ?? "", year: a.year ?? "", tempo: a.tempo ?? "", text: a.text, key: a.key ?? "", capo: a.capo ?? 0, tags: a.tags ?? [] });
+        return text({ created: r?.id });
+    }));
+    server.registerTool("update_song", {
+        title: "Update a song",
+        description: "Changes some fields of a song; the others stay as they are.",
+        inputSchema: { id: z.string(), ...songFields },
+    }, safe(async ({ id, ...changes }) => {
+        const cur = (await client.get(`/api/songs/${encodeURIComponent(id)}`));
+        const next = { ...cur, ...Object.fromEntries(Object.entries(changes).filter(([, v]) => v !== undefined)) };
+        await client.send("PUT", `/api/songs/${encodeURIComponent(id)}`, next);
+        return text({ updated: id });
+    }));
+    server.registerTool("delete_song", {
+        title: "Delete a song",
+        description: "Deletes a song from the library (and its backing track). It can't be undone: ask the person first and pass confirm=true.",
+        inputSchema: { id: z.string(), confirm: z.literal(true).describe("Must be true: the person agreed to delete it.") },
+        annotations: { destructiveHint: true },
+    }, safe(async ({ id }) => {
+        await client.send("DELETE", `/api/songs/${encodeURIComponent(id)}`);
+        return text({ deleted: id });
+    }));
+    server.registerTool("transpose_song", {
+        title: "Transpose a song",
+        description: "Moves every chord of a song up or down by semitones (and the key with it), then saves.",
+        inputSchema: { id: z.string(), semitones: z.number().int().min(-11).max(11).describe("+2 = up a whole tone, -1 = down a half tone.") },
+    }, safe(async ({ id, semitones }) => {
+        const { cur, key } = await rework(id, "/api/transpose", { semitones });
+        return text({ id, from: cur.key, to: key });
+    }));
+    server.registerTool("set_capo", {
+        title: "Set a song's capo",
+        description: "Puts the capo on a fret (0 = none). Like the app: the chord shapes stay, and the song sounds higher.",
+        inputSchema: { id: z.string(), capo: z.number().int().min(0).max(12) },
+    }, safe(async ({ id, capo }) => {
+        const r = await rework(id, "/api/capo", { capo });
+        return text({ id, capo: r.capo ?? capo, key: r.key });
+    }));
+    server.registerTool("import_song", {
+        title: "Import a song",
+        description: "Turns pasted lyrics/chords (any common format, chords above the lyrics included) or a song page address into a " +
+            "Stagebook song, with the app's own importer. With save=true it's added to the library; otherwise it's returned to review.",
+        inputSchema: {
+            text: z.string().optional().describe("Pasted lyrics and chords."),
+            url: z.string().optional().describe("Address of a song page (needs the tablet's internet on)."),
+            title: z.string().optional().describe("Title when pasting text without one."),
+            with_tab: z.boolean().optional().describe("Keep tablature when the song has it (otherwise the tool asks)."),
+            save: z.boolean().optional().describe("Add it to the library right away. Default false."),
+        },
+    }, safe(async ({ text: pasted, url, title, with_tab, save: keep }, signal) => {
+        if (!pasted && !url)
+            throw new StagebookError("Pass the text or the page address.");
+        const r = await client.send("POST", "/api/import", { text: pasted ?? "", url: url ?? "", title: title ?? "", withTab: with_tab ?? null }, undefined, 60000, signal);
+        if (r?.status === "askTab")
+            return text("The song has tablature: call again with with_tab true (keep it) or false (chords only).");
+        if (!keep)
+            return text({ toReview: { title: r.title, author: r.author, year: r.year, tempo: r.tempo, key: r.key, capo: r.capo, chords: chordsIn(r.text ?? ""), text: r.text } });
+        const created = await client.send("POST", "/api/songs", { title: r.title, author: r.author, year: r.year, tempo: r.tempo, text: r.text, key: r.key, capo: r.capo, tags: [] });
+        return text({ created: created?.id, title: r.title, author: r.author });
+    }));
+    server.registerTool("set_backing_track", {
+        title: "Set a song's backing track",
+        description: "Uploads an audio file from this computer (OGG with any number of channels, MP3 or WAV) as the song's backing track, replacing any previous one.",
+        inputSchema: { id: z.string(), path: z.string().describe("Path of the audio file on this computer.") },
+    }, safe(async ({ id, path }, signal) => {
+        const bytes = await localFile(path, TRACK_MAX);
+        const r = await client.send("PUT", `/api/songs/${encodeURIComponent(id)}/track`, bytes, { name: basename(path) }, 300000, signal);
+        return text({ id, track: r?.trackName ?? basename(path) });
+    }));
+    server.registerTool("remove_backing_track", {
+        title: "Remove a song's backing track",
+        description: "Takes the backing track off a song (the audio file is deleted from the tablet). Ask first.",
+        inputSchema: { id: z.string(), confirm: z.literal(true) },
+        annotations: { destructiveHint: true },
+    }, safe(async ({ id }) => {
+        await client.send("DELETE", `/api/songs/${encodeURIComponent(id)}/track`);
+        return text({ id, track: null });
+    }));
+    // ---------- setlists ----------
+    server.registerTool("list_setlists", {
+        title: "List setlists",
+        description: "The setlists (id, name, number of songs).",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, safe(async () => text(await client.get("/api/sets"))));
+    server.registerTool("get_setlist", {
+        title: "Get a setlist",
+        description: "A setlist with its songs in order (a song deleted from the library shows with an empty title).",
+        inputSchema: { id: z.string() },
+        annotations: { readOnlyHint: true },
+    }, safe(async ({ id }) => text(await client.get(`/api/sets/${encodeURIComponent(id)}`))));
+    server.registerTool("create_setlist", {
+        title: "Create a setlist",
+        description: "Creates a setlist with these songs, in this order (song ids from list_songs). Without a name it's named after the date and time.",
+        inputSchema: { name: z.string().optional(), song_ids: z.array(z.string()).optional() },
+    }, safe(async ({ name, song_ids }) => text({ created: (await client.send("POST", "/api/sets", { name: name ?? "", items: song_ids ?? [] }))?.id })));
+    server.registerTool("update_setlist", {
+        title: "Update a setlist",
+        description: "Renames a setlist and/or replaces its songs (the full list, in order). Omitted fields stay. Emptying it (song_ids []) needs confirm=true.",
+        inputSchema: {
+            id: z.string(), name: z.string().optional(), song_ids: z.array(z.string()).optional(),
+            confirm: z.boolean().optional().describe("Required true to leave the setlist with no songs."),
+        },
+    }, safe(async ({ id, name, song_ids, confirm }) => {
+        const cur = await client.get(`/api/sets/${encodeURIComponent(id)}`);
+        // an empty list takes every song out: like deleting, it asks first (audit 03/11)
+        if (song_ids?.length === 0 && cur.songs.length > 0 && !confirm) {
+            throw new StagebookError(`This takes all ${cur.songs.length} songs out of "${cur.name}": ask the person and pass confirm=true.`);
+        }
+        await client.send("PUT", `/api/sets/${encodeURIComponent(id)}`, { name: name ?? cur.name, items: song_ids ?? cur.songs.map((s) => s.id) });
+        return text({ updated: id });
+    }));
+    server.registerTool("delete_setlist", {
+        title: "Delete a setlist",
+        description: "Deletes a setlist (its songs stay in the library). Ask first and pass confirm=true.",
+        inputSchema: { id: z.string(), confirm: z.literal(true) },
+        annotations: { destructiveHint: true },
+    }, safe(async ({ id }) => {
+        await client.send("DELETE", `/api/sets/${encodeURIComponent(id)}`);
+        return text({ deleted: id });
+    }));
+    // ---------- receiving and the band ----------
+    server.registerTool("receive_by_code", {
+        title: "Receive a setlist by its 3 words",
+        description: "Fetches what someone sent over the internet with Stagebook's 3-word code (e.g. 47-violao-lua) and returns the " +
+            "review: each song found in the library, new, or with candidates. Then call receive_create with the token.",
+        inputSchema: { code: z.string() },
+    }, safe(async ({ code }, signal) => text(await client.send("POST", "/api/receive", { code }, undefined, 60000, signal))));
+    server.registerTool("receive_create", {
+        title: "Create the received setlist",
+        description: "After receive_by_code or open_band_item: creates the setlist from the review's token. choices maps a row index " +
+            "to the chosen library song id where the review offered candidates.",
+        inputSchema: { token: z.string(), name: z.string().optional(), choices: z.record(z.string(), z.string()).optional() },
+    }, safe(async ({ token, name, choices }) => {
+        const r = await client.send("POST", "/api/receive/create", { token, name: name ?? "", choices: choices ?? {} });
+        return text({ setlist: r?.setlist });
+    }));
+    server.registerTool("band_inbox", {
+        title: "What the band sent",
+        description: "Setlists and songs band members sent to this tablet that weren't opened yet.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, safe(async () => text(await client.get("/api/band"))));
+    server.registerTool("band_sync", {
+        title: "Sync with the band",
+        description: "Asks the band (same Wi-Fi) and the internet inbox for anything new.",
+        inputSchema: {},
+    }, safe(async () => {
+        await client.send("POST", "/api/band/sync");
+        return text("Asked the band for anything new; check band_inbox in a few seconds.");
+    }));
+    server.registerTool("open_band_item", {
+        title: "Open something the band sent",
+        description: "Reviews an item from band_inbox (by id), like receive_by_code; then create it with receive_create.",
+        inputSchema: { id: z.string() },
+    }, safe(async ({ id }) => text(await client.send("POST", "/api/band/open", { code: id }))));
+    // ---------- backup ----------
+    server.registerTool("restore_backup", {
+        title: "Restore a backup file",
+        description: "Sends a .stagebook file from this computer to the tablet. Without parts it only inspects (what the file has). " +
+            "With parts (library, tracks, settings) it restores them: replace=true swaps the library for the file's, " +
+            "replace=false only adds the songs, setlists and tracks that are missing. Settings always replace the tablet's " +
+            "(stage look, pedals, USB audio interface, band). Replacing the library or restoring settings: ask first and pass confirm=true.",
+        inputSchema: {
+            path: z.string(),
+            parts: z.array(z.enum(["library", "tracks", "settings"])).optional(),
+            replace: z.boolean().optional(),
+            confirm: z.boolean().optional().describe("Required true with replace=true or with settings in parts."),
+        },
+        annotations: { destructiveHint: true },
+    }, safe(async ({ path, parts, replace, confirm }, signal) => {
+        const bytes = await localFile(path, BACKUP_MAX);
+        const info = await client.send("POST", "/api/backup/inspect", bytes, undefined, 600000, signal);
+        if (!parts?.length)
+            return text({ inspected: info });
+        if (replace && !confirm)
+            throw new StagebookError("Replacing swaps the whole library for the file's: ask the person and pass confirm=true.");
+        // the tablet's settings are always replaced by the file's, with replace or not (audit 03/11: it went without asking)
+        if (parts.includes("settings") && !confirm) {
+            throw new StagebookError("Restoring settings replaces the tablet's (stage look, pedals, USB audio interface, band): ask the person and pass confirm=true.");
+        }
+        // given up while the file went over: the restore doesn't start
+        if (signal?.aborted)
+            throw new StagebookError("The call was cancelled before restoring: nothing changed on the tablet.");
+        const r = await client.send("POST", "/api/backup/restore", { token: info.token, parts, replace: !!replace }, undefined, 600000, signal);
+        return text({ restored: parts, replace: !!replace, skipped: r?.skipped ?? 0 });
+    }));
+    // ---------- resources ----------
+    server.registerResource("songs", "stagebook://songs", { title: "Stagebook songs", description: "The library's songs (id, title, artist, year, key, tags).", mimeType: "application/json" }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(await client.get("/api/songs"), null, 2) }] }));
+    server.registerResource("setlists", "stagebook://setlists", { title: "Stagebook setlists", description: "The setlists (id, name, count).", mimeType: "application/json" }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(await client.get("/api/sets"), null, 2) }] }));
+    server.registerResource("song", new ResourceTemplate("stagebook://songs/{id}", { list: undefined }), { title: "A Stagebook song (ChordPro)", description: "One song as ChordPro, with its details as directives.", mimeType: "text/plain" }, async (uri, { id }) => {
+        const s = (await client.get(`/api/songs/${encodeURIComponent(String(id))}`));
+        const head = [`{title: ${s.title}}`, s.author && `{artist: ${s.author}}`, s.year && `{year: ${s.year}}`, s.key && `{key: ${s.key}}`, s.capo ? `{capo: ${s.capo}}` : "", s.tempo && `{tempo: ${s.tempo}}`].filter(Boolean);
+        return { contents: [{ uri: uri.href, mimeType: "text/plain", text: [...head, "", s.text].join("\n") }] };
+    });
+    // ---------- prompts ----------
+    server.registerPrompt("build_setlist", {
+        title: "Build a setlist",
+        description: "Picks songs from the library for a gig and creates the setlist.",
+        argsSchema: { occasion: z.string().describe("The gig: length, mood, audience…"), count: z.string().optional() },
+    }, ({ occasion, count }) => ({
+        messages: [{
+                role: "user",
+                content: { type: "text", text: `Build a Stagebook setlist for: ${occasion}. ${count ? `About ${count} songs. ` : ""}Use list_songs (and get_song for BPM/key when useful), balance energy and keys, avoid the same artist back to back, show me the list with a short reason, and create it with create_setlist after I agree.` },
+            }],
+    }));
+    server.registerPrompt("fix_chords", {
+        title: "Check a song's chords",
+        description: "Reviews a song's chords and sections and proposes fixes.",
+        argsSchema: { song: z.string().describe("Title or id.") },
+    }, ({ song }) => ({
+        messages: [{
+                role: "user",
+                content: { type: "text", text: `Find the Stagebook song "${song}" (list_songs), read it with get_song include_text, and check the chords (misplaced, wrong key, typos) and section titles. Propose the changes and only save with update_song after I agree.` },
+            }],
+    }));
+    server.registerPrompt("transpose_for_singer", {
+        title: "Transpose songs for a singer",
+        description: "Moves several songs to keys that suit a singer.",
+        argsSchema: { which: z.string().describe("Which songs (artist, tag, setlist…)."), range: z.string().describe("The singer's comfortable range or target keys.") },
+    }, ({ which, range }) => ({
+        messages: [{
+                role: "user",
+                content: { type: "text", text: `In Stagebook, for these songs: ${which}. The singer's range/target: ${range}. Propose a new key per song (with semitones), then transpose_song each one after I agree.` },
+            }],
+    }));
+    return server;
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "stagebook-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "MCP server for Stagebook: lets AI assistants (Claude Code, Claude Desktop, Cursor, VS Code, Gemini CLI, Codex…) read and edit the songs and setlists on your Stagebook tablet over the local network.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "author": "Juliano Affonso",
+  "homepage": "https://github.com/julianoAffonso/stagebook/tree/main/mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/julianoAffonso/stagebook.git",
+    "directory": "mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/julianoAffonso/stagebook/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "stagebook",
+    "setlist",
+    "chords",
+    "chordpro",
+    "lyrics",
+    "backing-track"
+  ],
+  "type": "module",
+  "bin": {
+    "stagebook-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test \"test/*.test.mjs\"",
+    "start": "node dist/index.js",
+    "prepack": "npm run build && cp ../LICENSE.md LICENSE.md",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}