hymnkeep 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,11 @@
+Copyright (c) 2026 R.J. Nestor. All rights reserved.
+
+You may install and run this program to work with a Hymnkeep community you
+belong to. You may not copy, change, publish, distribute, sublicense or sell
+it, or any part of it, except as this paragraph allows.
+
+THE PROGRAM IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM, OUT OF
+OR IN CONNECTION WITH THE PROGRAM OR ITS USE.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# hymnkeep
 
-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.
+Plan your Hymnkeep community from the command line, or let an AI app on your
+computer do it for you.
+
+## Set up
+
+You need [Node.js](https://nodejs.org) 20 or later, and a key from your
+community's Keys page in Hymnkeep (Settings, then Keys). Only owners and
+directors can make keys.
+
+```sh
+npm install -g hymnkeep
+hymnkeep login
+```
+
+`login` asks for your community's address (paste the address of any Hymnkeep
+page you have open) and the key, and keeps both on this computer.
+
+## Day to day
+
+```sh
+hymnkeep week                       # the next occasion: its music and who is on it
+hymnkeep week 2026-12-24            # a particular day
+hymnkeep occasions                  # the next six weeks
+hymnkeep find "gather us in"        # music, with page numbers and when it was last sung
+
+hymnkeep plan 2026-12-27            # plan a day from its templates
+hymnkeep put "Gathering Hymn" "O Come, All Ye Faithful" --day 2026-12-27
+hymnkeep put Psalm "Psalm 98" --at "Sun 8:00 AM" --preview
+hymnkeep add-slot "Communion Meditation" --at "Sun 8:00 AM"
+hymnkeep remove-slot Postlude --at Vigil
+
+hymnkeep assign "Karis Wolfe" --job Cantor --day 2026-12-27
+hymnkeep assign "Adult Choir" --at "Sun 11:00 AM"
+hymnkeep unassign "Karis Wolfe" --at Vigil
+hymnkeep copy --from "Sat 5:30 PM" --to "Sun 8:00 AM"
+```
+
+A command acts on every service of the day unless `--at` names some.
+`--preview` says what it would do and writes nothing. `--json` prints what
+Hymnkeep sent, for scripts.
+
+Everything else Hymnkeep can do is one call away: `hymnkeep api` lists the
+calls, and `hymnkeep api <name> key=value …` makes one.
+
+## In an AI app
+
+Add Hymnkeep as an MCP server, after `hymnkeep login`. In Claude Desktop,
+Settings, then Developer, then Edit Config:
+
+```json
+{
+    "mcpServers": {
+        "hymnkeep": { "command": "npx", "args": ["-y", "hymnkeep", "mcp"] }
+    }
+}
+```
+
+The app can then read your weekends, find music, plan days, put music in
+place, and assign musicians. Anything that changes your plans is marked as a
+change, so the app asks you first.
+
+## For scripts
+
+`HYMNKEEP_KEY` and `HYMNKEEP_COMMUNITY` in the environment take the place of
+`login`; `HYMNKEEP_URL` points it somewhere other than hymnkeep.com.
+
+## Keeping it in step with Hymnkeep
+
+`openapi.json` is Hymnkeep's own description of its API, copied from
+`api/openapi.json` in the Hymnkeep repository. When that file changes, copy it
+here and release a new version: `hymnkeep api` and the MCP server's
+`api_calls` read it as it ships.

package/dist/cli.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { HymnkeepError, Hymnkeep } from './client.js';
+import { communityFrom, forget, load, save } from './config.js';
+import { serve } from './mcp.js';
+import { call, operation, operations } from './operations.js';
+import * as tasks from './tasks.js';
+const program = new Command();
+program
+    .name('hymnkeep')
+    .description('Plan Hymnkeep from the command line, or serve it to an AI app with `hymnkeep mcp`.')
+    .option('--json', 'print what Hymnkeep sent, as JSON')
+    .showHelpAfterError();
+function api() {
+    const credentials = load();
+    if (!credentials) {
+        throw new Error('Not signed in. Run `hymnkeep login` first.');
+    }
+    return new Hymnkeep(credentials);
+}
+/** Prints a task's answer as sentences, or as JSON with --json. */
+async function run(task) {
+    const result = await task();
+    stdout.write(`${program.opts().json ? JSON.stringify(result.data, null, 2) : result.text}\n`);
+}
+const collect = (value, previous = []) => [...previous, value];
+/** Asks one question a line at a time, whether a person types the answers or a script pipes them. */
+function questions() {
+    const lines = createInterface({ input: stdin, terminal: stdin.isTTY })[Symbol.asyncIterator]();
+    return {
+        async ask(question) {
+            stdout.write(question);
+            const next = await lines.next();
+            if (next.done) {
+                throw new Error('No answer given.');
+            }
+            return next.value.trim();
+        },
+        close: () => void lines.return?.(),
+    };
+}
+program
+    .command('login')
+    .description('Keep a key from your Keys page, and the community it belongs to, on this computer.')
+    .action(async () => {
+    const ask = questions();
+    const where = communityFrom(await ask.ask("Your community's address in Hymnkeep (paste any page's address): "));
+    const key = await ask.ask('The key from your Keys page: ');
+    ask.close();
+    const credentials = { ...where, key };
+    const me = await tasks.whoami(new Hymnkeep(credentials));
+    save(credentials);
+    stdout.write(`Signed in. ${me.text}\n`);
+});
+program.command('logout').description('Forget the key kept on this computer.').action(() => {
+    forget();
+    stdout.write('Forgotten.\n');
+});
+program.command('whoami').description('Who this key is, and what it may do.').action(() => run(() => tasks.whoami(api())));
+program
+    .command('week')
+    .argument('[day]', 'a date (YYYY-MM-DD) or an occasion id; the next occasion if left out')
+    .description("An occasion's music, place by place, and who is on each service.")
+    .action((day) => run(() => tasks.show(api(), day)));
+program
+    .command('occasions')
+    .description('What is planned in a date range: six weeks from today if left out.')
+    .option('--from <date>')
+    .option('--to <date>')
+    .action((o) => run(() => tasks.occasions(api(), o.from, o.to)));
+program
+    .command('plan')
+    .argument('<date>', 'the day to plan, YYYY-MM-DD')
+    .description("Plan a day from its templates: shows what it would write and asks any question first.")
+    .option('--template <id>', 'a template to use; the ones the day ticks itself if left out', collect)
+    .option('--answer <key=value>', "an answer to one of the plan's questions", collect)
+    .option('--preview', 'show what it would write, and write nothing')
+    .option('--yes', 'write without asking')
+    .action(async (date, o) => {
+    const answers = Object.fromEntries((o.answer ?? []).map((a) => [a.slice(0, a.indexOf('=')), a.slice(a.indexOf('=') + 1)]));
+    const options = { date, templates: o.template, answers };
+    const look = await tasks.plan(api(), { ...options, preview: true });
+    if (o.preview || look.data.questions) {
+        stdout.write(`${program.opts().json ? JSON.stringify(look.data, null, 2) : look.text}\n`);
+        return;
+    }
+    if (!o.yes && stdin.isTTY) {
+        stdout.write(`${look.text.replace(/\n\nNothing written yet\.$/, '')}\n\n`);
+        const ask = questions();
+        const go = (await ask.ask('Write it? (y/N) ')).toLowerCase();
+        ask.close();
+        if (go !== 'y' && go !== 'yes') {
+            stdout.write('Nothing written.\n');
+            return;
+        }
+    }
+    await run(() => tasks.plan(api(), options));
+});
+program
+    .command('find')
+    .argument('<words...>', 'a title, a tune, a first line, a composer')
+    .description('Music in the library and the adopted hymnals.')
+    .option('--date <date>', 'page numbers as the books stand on this day')
+    .action((words, o) => run(() => tasks.find(api(), words.join(' '), o.date)));
+const where = (command) => command
+    .option('--day <day>', 'a date or an occasion id; the next occasion if left out')
+    .option('--at <service>', 'a service by its time or name ("Sun 8:00 AM", "Vigil"); every service if left out', collect);
+where(program
+    .command('put')
+    .argument('<slot>', 'the place, by name ("Gathering Hymn")')
+    .argument('<piece...>', 'the piece, by title or id')
+    .description('Put a piece in a place at every service named, replacing what the place held.')
+    .option('--both', 'where the place holds something else, sing both instead of replacing')
+    .option('--preview', 'say what it would do, and write nothing')).action((slot, piece, o) => run(() => tasks.put(api(), { when: o.day, slot, piece: piece.join(' '), services: o.at, both: o.both, preview: o.preview })));
+where(program.command('add-slot').argument('<slot>', 'a slot name').description('Add a slot, empty, to every service named.')).action((slot, o) => run(() => tasks.addSlot(api(), { when: o.day, slot, services: o.at })));
+where(program.command('remove-slot').argument('<slot>', 'a slot name').description('Take a slot off every service named.')).action((slot, o) => run(() => tasks.removeSlot(api(), { when: o.day, slot, services: o.at })));
+where(program
+    .command('assign')
+    .argument('<who...>', 'a person or an ensemble, by name')
+    .description('Assign a person to a job, or an ensemble, at every service named.')
+    .option('--job <job>', 'the job, for a person ("Cantor")')
+    .option('--both', 'where someone else does the job, keep them too instead of replacing them')
+    .option('--preview', 'say what it would do, and write nothing')).action((who, o) => run(() => tasks.assign(api(), { when: o.day, who: who.join(' '), job: o.job, services: o.at, both: o.both, preview: o.preview })));
+where(program
+    .command('unassign')
+    .argument('<who...>', 'a person or an ensemble, by name')
+    .description('Take a person or an ensemble off every service named.')
+    .option('--job <job>', 'only where they do this job')).action((who, o) => run(() => tasks.unassign(api(), { when: o.day, who: who.join(' '), job: o.job, services: o.at })));
+program
+    .command('copy')
+    .description("Copy one service's music onto another of the same day.")
+    .requiredOption('--from <service>')
+    .requiredOption('--to <service>')
+    .option('--day <day>', 'a date or an occasion id; the next occasion if left out')
+    .option('--replace', "replace the second service's music rather than adding after it")
+    .action((o) => run(() => tasks.copy(api(), { when: o.day, from: o.from, to: o.to, replace: o.replace })));
+program
+    .command('api')
+    .argument('[call]', 'a call by name; every call is listed if left out')
+    .argument('[params...]', 'name=value for each of its ids and fields')
+    .description('Any call the API offers, by name: the command-line door to everything.')
+    .option('--data <json>', 'the whole body of a write, as JSON')
+    .action(async (name, params, o) => {
+    if (!name) {
+        for (const op of operations()) {
+            stdout.write(`${op.id.padEnd(44)} ${op.method.padEnd(6)} ${op.summary.slice(0, 90)}\n`);
+        }
+        return;
+    }
+    const op = operation(name);
+    const values = o.data ? JSON.parse(o.data) : {};
+    for (const pair of params) {
+        const at = pair.indexOf('=');
+        values[pair.slice(0, at)] = pair.slice(at + 1);
+    }
+    stdout.write(`${JSON.stringify(await call(api(), op, values), null, 2)}\n`);
+});
+program
+    .command('mcp')
+    .description('Serve Hymnkeep to an AI app over standard input and output.')
+    .action(() => serve(api()));
+program.parseAsync().catch((error) => {
+    process.stderr.write(`${error instanceof HymnkeepError ? error.explain() : error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/client.js

@@ -0,0 +1,85 @@
+/** What Hymnkeep refused, in its own sentence, and the field-by-field reasons where it gave them. */
+export class HymnkeepError extends Error {
+    status;
+    errors;
+    constructor(message, status, errors = {}) {
+        super(message);
+        this.status = status;
+        this.errors = errors;
+    }
+    /** The message with each field's reason under it. */
+    explain() {
+        const reasons = Object.values(this.errors).flat();
+        return [this.message, ...reasons.filter((reason) => reason !== this.message).map((reason) => `  ${reason}`)].join('\n');
+    }
+}
+/** The community API, reached with one person's key in one community. */
+export class Hymnkeep {
+    credentials;
+    constructor(credentials) {
+        this.credentials = credentials;
+    }
+    get community() {
+        return this.credentials.community;
+    }
+    /** `path` is under `/api/p/{community}`, as `occasions` or `occasions/{id}`. */
+    async request(method, path, options = {}) {
+        const url = new URL(`${this.credentials.url}/api/p/${encodeURIComponent(this.credentials.community)}/${path.replace(/^\/+/, '')}`);
+        for (const [name, value] of Object.entries(options.query ?? {})) {
+            if (value === undefined || value === null) {
+                continue;
+            }
+            if (Array.isArray(value)) {
+                value.forEach((each) => url.searchParams.append(`${name}[]`, String(each)));
+            }
+            else {
+                url.searchParams.set(name, String(value));
+            }
+        }
+        const response = await fetch(url, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.credentials.key}`,
+                Accept: 'application/json',
+                ...(options.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                'User-Agent': 'hymnkeep-cli',
+            },
+            body: options.body === undefined ? undefined : JSON.stringify(options.body),
+        });
+        const text = await response.text();
+        const json = text === '' ? null : safeJson(text);
+        if (!response.ok) {
+            const body = (json ?? {});
+            throw new HymnkeepError(body.message || refusal(response.status), response.status, body.errors ?? {});
+        }
+        return json;
+    }
+    get(path, query) {
+        return this.request('GET', path, { query });
+    }
+    post(path, body) {
+        return this.request('POST', path, { body: body ?? {} });
+    }
+    patch(path, body) {
+        return this.request('PATCH', path, { body: body ?? {} });
+    }
+    delete(path) {
+        return this.request('DELETE', path);
+    }
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { message: text.slice(0, 300) };
+    }
+}
+function refusal(status) {
+    return ({
+        401: 'That key is not valid for this community.',
+        403: 'That key may not do this.',
+        404: 'Nothing with that id in this community.',
+        429: 'Too many calls at once. Wait a minute and try again.',
+    }[status] ?? `Hymnkeep answered ${status}.`);
+}

package/dist/config.js

@@ -0,0 +1,73 @@
+import { execFileSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { dirname, join } from 'node:path';
+export const DEFAULT_URL = 'https://hymnkeep.com';
+const SERVICE = 'hymnkeep';
+function file() {
+    const base = platform() === 'win32' ? (process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming')) : (process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'));
+    return join(base, 'hymnkeep', 'credentials.json');
+}
+/** macOS keeps the key in the login keychain; elsewhere a file only its owner can read. */
+const keychain = () => platform() === 'darwin' && process.env.HYMNKEEP_NO_KEYCHAIN === undefined;
+/**
+ * The community's slug from what a person pastes: the slug itself, or the
+ * address of any Hymnkeep page in it ("https://hymnkeep.com/p/st-lukes/plan").
+ */
+export function communityFrom(text) {
+    const trimmed = text.trim();
+    const match = trimmed.match(/^(https?:\/\/[^/]+)\/p\/([^/?#]+)/);
+    if (match) {
+        return { url: match[1], community: decodeURIComponent(match[2]) };
+    }
+    return { url: DEFAULT_URL, community: trimmed.replace(/^\/+|\/+$/g, '') };
+}
+export function load() {
+    if (process.env.HYMNKEEP_KEY && process.env.HYMNKEEP_COMMUNITY) {
+        return {
+            url: process.env.HYMNKEEP_URL ?? DEFAULT_URL,
+            community: process.env.HYMNKEEP_COMMUNITY,
+            key: process.env.HYMNKEEP_KEY,
+        };
+    }
+    if (!existsSync(file())) {
+        return null;
+    }
+    const saved = JSON.parse(readFileSync(file(), 'utf8'));
+    if (!saved.community) {
+        return null;
+    }
+    const key = keychain() ? readKeychain(saved.community) : saved.key;
+    return key ? { url: process.env.HYMNKEEP_URL ?? saved.url ?? DEFAULT_URL, community: saved.community, key } : null;
+}
+export function save(credentials) {
+    mkdirSync(dirname(file()), { recursive: true });
+    if (keychain()) {
+        execFileSync('security', ['add-generic-password', '-U', '-s', SERVICE, '-a', credentials.community, '-w', credentials.key]);
+        writeFileSync(file(), JSON.stringify({ url: credentials.url, community: credentials.community }, null, 2));
+    }
+    else {
+        writeFileSync(file(), JSON.stringify(credentials, null, 2), { mode: 0o600 });
+        chmodSync(file(), 0o600);
+    }
+}
+export function forget() {
+    const saved = load();
+    if (saved && keychain()) {
+        try {
+            execFileSync('security', ['delete-generic-password', '-s', SERVICE, '-a', saved.community], { stdio: 'ignore' });
+        }
+        catch {
+            // Already gone.
+        }
+    }
+    rmSync(file(), { force: true });
+}
+function readKeychain(account) {
+    try {
+        return execFileSync('security', ['find-generic-password', '-s', SERVICE, '-a', account, '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    }
+    catch {
+        return null;
+    }
+}

package/dist/mcp.js

@@ -0,0 +1,112 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { HymnkeepError } from './client.js';
+import { call, operation, operations } from './operations.js';
+import * as tasks from './tasks.js';
+const day = z.string().optional().describe('A date (YYYY-MM-DD) or an occasion id. The next occasion if left out.');
+const at = z.array(z.string()).optional().describe('Services by their time or name ("Sun 8:00 AM", "Vigil"). Every service of the day if left out.');
+const preview = z.boolean().optional().describe('True to see what would happen without writing. Use it first, and show the person.');
+const READ = { readOnlyHint: true, openWorldHint: false };
+const WRITE = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
+const REMOVE = { readOnlyHint: false, destructiveHint: true, openWorldHint: false };
+const INSTRUCTIONS = `Hymnkeep plans the music and musicians of a community's services.
+An occasion is a day (a Sunday, a feast); it has services (the Saturday vigil, Sunday 8:00, 11:00), each with places (slots) holding one piece each, and people assigned to jobs.
+Start with "week" to see a day. A tool that writes has a preview: use it first, tell the person what will change, and write only once they agree.
+Name services as Hymnkeep does ("Sun 8:00 AM"), never as "Mass".
+For anything the day-to-day tools do not cover, "api_calls" lists every call and "api_call" makes one.`;
+/** A task's answer as a tool's reply, its sentences first, with what was sent behind them. */
+async function reply(task) {
+    try {
+        const result = await task();
+        return { content: [{ type: 'text', text: result.text }, { type: 'text', text: JSON.stringify(result.data) }] };
+    }
+    catch (error) {
+        const text = error instanceof HymnkeepError ? error.explain() : error instanceof Error ? error.message : String(error);
+        return { isError: true, content: [{ type: 'text', text }] };
+    }
+}
+export function build(api) {
+    const server = new McpServer({ name: 'hymnkeep', version: '0.1.0' }, { instructions: INSTRUCTIONS });
+    server.registerTool('whoami', { description: 'Who this key is: the community, the person, their role, and whether it may write.', annotations: READ }, () => reply(() => tasks.whoami(api)));
+    server.registerTool('week', { description: "An occasion's services, its music place by place (where services differ, each one's), and who is on each service.", inputSchema: { day }, annotations: READ }, ({ day: when }) => reply(() => tasks.show(api, when)));
+    server.registerTool('occasions', {
+        description: 'What is planned in a date range. Six weeks from today if left out.',
+        inputSchema: { from: z.string().optional(), to: z.string().optional() },
+        annotations: READ,
+    }, ({ from, to }) => reply(() => tasks.occasions(api, from, to)));
+    server.registerTool('find_music', {
+        description: 'Music in the library and the adopted hymnals, by title, tune, first line or composer, with page numbers and when it was last sung.',
+        inputSchema: { query: z.string(), date: z.string().optional().describe('Page numbers as the books stand on this day.') },
+        annotations: READ,
+    }, ({ query, date }) => reply(() => tasks.find(api, query, date)));
+    server.registerTool('plan_day', {
+        description: 'Plan a day from its templates. With preview true it says what it would write and lists any question the templates raise; answer each by its key in answers and call again. With preview false it writes.',
+        inputSchema: {
+            date: z.string().describe('YYYY-MM-DD'),
+            templates: z.array(z.string()).optional().describe('Template ids. The ones the day ticks itself if left out.'),
+            answers: z.record(z.string(), z.string()).optional().describe("Each question's key and the chosen option's value."),
+            preview,
+        },
+        annotations: WRITE,
+    }, ({ date, templates, answers, preview: look }) => reply(() => tasks.plan(api, { date, templates, answers, preview: look })));
+    server.registerTool('put_music', {
+        description: 'Put a piece in a place (slot) at the services named, replacing what the place held there, or singing both. A service without the place is given it.',
+        inputSchema: {
+            day,
+            slot: z.string().describe('The place, by name ("Gathering Hymn").'),
+            piece: z.string().describe('The piece, by title or id. find_music first when unsure.'),
+            services: at,
+            both: z.boolean().optional().describe('Where the place holds something else, sing both instead of replacing.'),
+            preview,
+        },
+        annotations: WRITE,
+    }, ({ day: when, slot, piece, services, both, preview: look }) => reply(() => tasks.put(api, { when, slot, piece, services, both, preview: look })));
+    server.registerTool('add_slot', {
+        description: 'Add a slot, empty, to the services named, at the end of each one\'s list.',
+        inputSchema: { day, slot: z.string().describe("A slot name from the community's list."), services: at },
+        annotations: WRITE,
+    }, ({ day: when, slot, services }) => reply(() => tasks.addSlot(api, { when, slot, services })));
+    server.registerTool('remove_slot', { description: 'Take a slot, and whatever is in it, off the services named.', inputSchema: { day, slot: z.string(), services: at }, annotations: REMOVE }, ({ day: when, slot, services }) => reply(() => tasks.removeSlot(api, { when, slot, services })));
+    server.registerTool('assign_musician', {
+        description: 'Assign a person to a job, or an ensemble, at the services named. Where someone else does that job, they are replaced unless both is true.',
+        inputSchema: {
+            day,
+            who: z.string().describe('A person or an ensemble, by name.'),
+            job: z.string().optional().describe('The job, for a person ("Cantor", "Organist").'),
+            services: at,
+            both: z.boolean().optional(),
+            preview,
+        },
+        annotations: WRITE,
+    }, ({ day: when, who, job, services, both, preview: look }) => reply(() => tasks.assign(api, { when, who, job, services, both, preview: look })));
+    server.registerTool('unassign_musician', { description: 'Take a person or an ensemble off the services named.', inputSchema: { day, who: z.string(), job: z.string().optional(), services: at }, annotations: REMOVE }, ({ day: when, who, job, services }) => reply(() => tasks.unassign(api, { when, who, job, services })));
+    server.registerTool('copy_music', {
+        description: "Copy one service's music onto another of the same day, after what it has, or replacing it.",
+        inputSchema: { day, from: z.string(), to: z.string(), replace: z.boolean().optional() },
+        annotations: WRITE,
+    }, ({ day: when, from, to, replace }) => reply(() => tasks.copy(api, { when, from, to, replace })));
+    server.registerTool('api_calls', {
+        description: 'Every call the Hymnkeep API offers, by name, for what the other tools do not cover. Filter by words in the name or summary.',
+        inputSchema: { search: z.string().optional() },
+        annotations: READ,
+    }, ({ search }) => reply(async () => {
+        const found = operations().filter((op) => !search || `${op.id} ${op.summary}`.toLowerCase().includes(search.toLowerCase()));
+        return {
+            data: found.map(({ id, method, path, summary, pathParams, queryParams, body }) => ({ id, method, path, summary, pathParams, queryParams, body })),
+            text: found.map((op) => `${op.id} (${op.method} ${op.path}): ${op.summary}`).join('\n') || 'No call matches.',
+        };
+    }));
+    server.registerTool('api_call', {
+        description: 'Make one API call by name (see api_calls), with its ids and fields in params. A call whose method is not GET writes: say what it will change first.',
+        inputSchema: { name: z.string(), params: z.record(z.string(), z.unknown()).optional() },
+        annotations: WRITE,
+    }, ({ name, params }) => reply(async () => {
+        const data = await call(api, operation(name), params ?? {});
+        return { data, text: `${name} done.` };
+    }));
+    return server;
+}
+export async function serve(api) {
+    await build(api).connect(new StdioServerTransport());
+}

package/dist/operations.js

@@ -0,0 +1,52 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const PREFIX = '/api/p/{community}';
+let cached = null;
+/** Every call, read from the description that ships beside the program. */
+export function operations() {
+    if (cached) {
+        return cached;
+    }
+    const here = dirname(fileURLToPath(import.meta.url));
+    const document = JSON.parse(readFileSync(join(here, '..', 'openapi.json'), 'utf8'));
+    cached = Object.entries(document.paths).flatMap(([path, methods]) => Object.entries(methods).map(([method, op]) => ({
+        id: op.operationId,
+        method: method.toUpperCase(),
+        path: path.slice(PREFIX.length).replace(/^\//, ''),
+        summary: op.summary,
+        tag: op.tags[0] ?? '',
+        pathParams: (op.parameters ?? []).filter((p) => p.in === 'path' && p.name !== 'community').map((p) => p.name),
+        queryParams: (op.parameters ?? []).filter((p) => p.in === 'query').map((p) => ({ name: p.name.replace(/\[\]$/, ''), required: p.required, schema: p.schema })),
+        body: op.requestBody?.content['application/json'].schema ?? null,
+        writes: method !== 'get',
+    })));
+    return cached;
+}
+export function operation(id) {
+    const found = operations().find((op) => op.id === id);
+    if (!found) {
+        throw new Error(`No call named "${id}". \`hymnkeep api\` lists them.`);
+    }
+    return found;
+}
+/**
+ * Makes one call: the path's ids from `params`, the rest as the query of a
+ * read or the body of a write.
+ */
+export async function call(api, op, params) {
+    const rest = { ...params };
+    let path = op.path;
+    for (const name of op.pathParams) {
+        const value = rest[name];
+        if (value === undefined || value === null || value === '') {
+            throw new Error(`"${op.id}" needs ${name}.`);
+        }
+        path = path.replace(`{${name}}`, encodeURIComponent(String(value)));
+        delete rest[name];
+    }
+    if (!op.writes || op.method === 'DELETE') {
+        return api.request(op.method, path, { query: rest });
+    }
+    return api.request(op.method, path, { body: rest });
+}