funoteka 0.1.0

package/dist/junk/rule.js

@@ -0,0 +1,93 @@
+/**
+ * What in the collection is not a record.
+ *
+ * The contract asks for a junk filter — a label, a hiding, a switch, and an
+ * allow/block edit — and never a deletion (requirements:47 §11). This module is
+ * the label: the one place that decides whether a folder is a record, so the
+ * scan that writes the label and the command that re-derives it after a hand
+ * edit cannot come to two answers.
+ *
+ * **The rule is about the folder, not about the music.** Nothing here reads a
+ * title, a tag, a bitrate or an artist, and that is deliberate: a rule that
+ * judged the music would be this server deciding taste, and the collection is
+ * the operator's. What it judges is whether the folder is a folder of music at
+ * all — which is a question about the disk, and has an answer.
+ */
+/**
+ * How many files a record may hold that are neither the music nor the paperwork.
+ *
+ * A record folder holds audio, the artwork that came with it, and the notes —
+ * a cue, an `.nfo`, a `.log`. Everything else is `kind = 'other'`. Measured on
+ * the live collection, the albums that *are* records hold at most **four** of
+ * those: an enhanced CD's data track (`AUTORUN.INF`, `OSC.EXE`, `LINKIN.MOV`,
+ * `JACKET01.00J` — the sixteen Linkin Park and Cure pressings that carry one)
+ * and a `foo_dr.txt` beside a rip.
+ */
+export const STRANGERS_FLOOR = 5;
+/**
+ * How far the music may be outnumbered before the folder stops being about it.
+ *
+ * **The count alone was not enough, and the live check is what said so.** With a
+ * bare floor of five the rule hid `Standalone-Music Access Virus TI` — one demo
+ * track, a Virus TI patch bank (`.lib`, `.mid`, `.syx`), a readme and a patch
+ * list, which is a single with its patch data and not a dumping ground. The
+ * floor separates a record's paperwork from a rubbish heap; it does not
+ * separate *a record with unusual paperwork* from a heap, and no count can,
+ * because a heap has no ceiling.
+ *
+ * What separates them is the shape, and it is the same measurement read twice:
+
+ * | folder | not music | music | ratio |
+ * |---|---|---|---|
+ * | `Downloads` (the root itself) | 199 | 9 | 22.1 |
+ * | `Telegram Desktop` | 98 | 7 | 14.0 |
+ * | `Standalone-Music Access Virus TI` | 6 | 1 | 6.0 |
+ * | every record in the collection | ≤ 4 | ≥ 1 | ≤ 1.0 |
+ *
+ * A record's companions scale with the record; a dumping ground accumulates with
+ * no relation to the music that happens to be in it. Ten is the number that
+ * falls between 6.0 and 14.0, and the *statement* is what makes the position
+ * defensible rather than the arithmetic: **a folder holding ten files that are
+ * not music for every one that is is not a folder of music.**
+ *
+ * The two conditions are kept together and not folded into the ratio alone: a
+ * single track beside eleven stray files is a ratio of eleven, and calling that
+ * a dumping ground on the strength of one song is the sort of guess this rule
+ * exists to avoid.
+ */
+export const STRANGERS_PER_SONG = 10;
+/** The files of a folder that are neither the music nor the paperwork. */
+export function strangers(files) {
+    return files.filter((file) => file.kind === 'other').length;
+}
+/** The files of a folder that are music. */
+export function songs(files) {
+    return files.filter((file) => file.kind === 'audio').length;
+}
+/**
+ * Whether a folder is a record, and why not.
+ *
+ * The mark wins where there is one. That is the whole of the allow/block edit:
+ * `trust` on a folder the rule would hide, `junk` on one it would keep — and the
+ * reason it carries says which of the two happened, because a hidden album that
+ * cannot say why is a hidden album nobody can argue with.
+ *
+ * The reason states both numbers rather than only the one that tripped the rule.
+ * A reader checking the filter's work is asking "was this folder mostly not
+ * music", and `6 against 1` answers it where `6 files that are not music` leaves
+ * them to guess at the denominator — the guess being the thing this rule was
+ * wrong about once already.
+ */
+export function junkReason(files, mark) {
+    if (mark === 'trust')
+        return null;
+    if (mark === 'junk')
+        return 'marked junk by hand';
+    const strangers_ = strangers(files);
+    if (strangers_ < STRANGERS_FLOOR)
+        return null;
+    const songs_ = songs(files);
+    if (strangers_ <= STRANGERS_PER_SONG * songs_)
+        return null;
+    return `${strangers_} files that are not music, against ${songs_} that are`;
+}

package/dist/mcp/client.js

@@ -0,0 +1,48 @@
+/**
+ * The admin API, called over HTTP, by an MCP server that is a process of its own.
+ *
+ * This is the client the stdio transport uses: an agent starts `funoteka mcp`,
+ * and every tool call it makes leaves this process as one authenticated HTTP
+ * request to the admin port. That is the design rather than a shortcut — the
+ * gate, the audit line, the lockout and the refusal sentences all belong to that
+ * port, and a second path into the same work would be a second place for them to
+ * be forgotten.
+ *
+ * The token is a bearer header and never a query parameter, for the reason the
+ * admin surface keeps saying: a query string is what ends up in a log line.
+ */
+export function adminClient(url, token) {
+    return async (method, path, body, idempotencyKey) => {
+        const response = await fetch(new URL(path, url), {
+            method,
+            headers: {
+                authorization: `Bearer ${token}`,
+                // **The retry key, which this client used to drop on the floor.** The
+                // tool layer hands it over as a fourth argument and an implementation
+                // that ignores one is not a type error — so an agent calling over stdio
+                // got no idempotency at all while the HTTP transport had it, which is
+                // the half that would never have been noticed.
+                ...(idempotencyKey === undefined ? {} : { 'idempotency-key': idempotencyKey }),
+                ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        const text = await response.text();
+        return { status: response.status, body: parse(text) };
+    };
+}
+/**
+ * A body, parsed if it is JSON.
+ *
+ * A route that answers with something else — the inventory dump is text — is
+ * still an answer, and a client that threw on it would report a working route as
+ * a transport failure. What comes back is the text under a name that says so.
+ */
+function parse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { text };
+    }
+}

package/dist/mcp/server.js

@@ -0,0 +1,175 @@
+import { SERVER_VERSION } from "../api/envelope.js";
+import { IDEMPOTENCY_ARGUMENT, TOOLS, callTool, mutatingTool } from "./tools.js";
+/**
+ * The protocol itself: JSON-RPC 2.0, four methods, and no dependencies.
+ *
+ * MCP over stdio is a line-delimited exchange — one JSON object per line, in
+ * both directions — and over HTTP it is a POST carrying one. Neither needs a
+ * library: the protocol this server has to speak is `initialize`, `tools/list`
+ * and `tools/call`, and a project that carries no dependencies to serve music is
+ * not going to carry one to answer three questions.
+ *
+ * **What is deliberately missing, and would be the next thing.** Prompts,
+ * resources, sampling, notifications the server originates, SSE streaming, and
+ * sessions. None of them is needed by an agent that wants to operate a music
+ * server, and every one of them is a surface with its own security story — this
+ * file says so rather than leaving a reader to guess whether it was forgotten.
+ */
+/**
+ * The protocol revision this server speaks.
+ *
+ * **It answers with its own name, and not the client's.** An earlier version
+ * echoed whatever non-empty string the client sent, which reads as agreement
+ * with a revision this server has never implemented — and a client that then
+ * used a feature of that revision would be talking to a server that had agreed
+ * to something it does not do. A client that cannot work with this one says so,
+ * which is the outcome worth having.
+ */
+export const PROTOCOL_VERSION = '2025-06-18';
+/**
+ * One message in, one message out — or nothing at all, for a notification.
+ *
+ * Nothing is the correct answer to a notification and it is not the same as an
+ * error: `notifications/initialized` is a client telling this server it is
+ * ready, and a server that replied would be talking when it was spoken to.
+ */
+export async function handleMessage(client, message) {
+    if (message === null || typeof message !== 'object') {
+        return { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'not a JSON-RPC message' } };
+    }
+    const { id = null, method, params = {} } = message;
+    if (typeof method !== 'string') {
+        return { jsonrpc: '2.0', id, error: { code: -32600, message: 'no method' } };
+    }
+    // A notification has no id, and nothing comes back for one.
+    const notification = message.id === undefined;
+    switch (method) {
+        case 'initialize': {
+            return reply(id, {
+                protocolVersion: PROTOCOL_VERSION,
+                capabilities: { tools: {} },
+                serverInfo: { name: 'funoteka', version: SERVER_VERSION },
+                instructions: 'Operates a funoteka music server. Reads are safe and cheap; funoteka_scan_start reads the disk and runs as a separate process, and funoteka_roots_remove and funoteka_restore change the library. Every call goes through the admin API and is audited there.',
+            });
+        }
+        case 'notifications/initialized':
+        case 'notifications/cancelled':
+            return null;
+        case 'ping':
+            return reply(id, {});
+        case 'tools/list':
+            return reply(id, {
+                tools: TOOLS.map((tool) => ({
+                    name: tool.name,
+                    description: tool.description,
+                    // A tool that changes something is offered the retry key; a read has
+                    // nothing to retry and is not told about one.
+                    inputSchema: mutatingTool(tool)
+                        ? {
+                            ...tool.inputSchema,
+                            properties: {
+                                ...tool.inputSchema.properties,
+                                ...IDEMPOTENCY_ARGUMENT,
+                            },
+                        }
+                        : tool.inputSchema,
+                })),
+            });
+        case 'tools/call': {
+            const name = params.name;
+            if (typeof name !== 'string') {
+                return { jsonrpc: '2.0', id, error: { code: -32602, message: 'tools/call needs a name' } };
+            }
+            const args = (params.arguments ?? {});
+            const called = await callTool(client, name, args);
+            if (!called.ok) {
+                // An unknown tool, a missing argument, or an admin API that is not
+                // answering: there is no result to report, so this is a protocol error
+                // rather than a tool that answered.
+                return { jsonrpc: '2.0', id, error: { code: -32602, message: called.error } };
+            }
+            return reply(id, {
+                content: [{ type: 'text', text: called.text }],
+                // **A refusal is content, not an error.** A scan refused because one is
+                // already running is an answer from the right tool, and an agent that
+                // saw a protocol error would reach for a different tool instead of
+                // reading what the server said. `isError` is the protocol's own way of
+                // saying "this is an answer, and it is not good news".
+                isError: called.refused,
+            });
+        }
+        default:
+            // Notifications for methods this server does not implement are dropped, as
+            // the specification asks; anything else is a method error.
+            if (notification)
+                return null;
+            return { jsonrpc: '2.0', id, error: { code: -32601, message: `no such method: ${method}` } };
+    }
+}
+function reply(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+/**
+ * The stdio loop: read lines, answer lines.
+ *
+ * **A line that is not JSON is answered, not fatal.** The caller here is an
+ * agent's transport, and a server that exited on one malformed line would look
+ * to it like a server that died — the failure would be investigated in the wrong
+ * place. One error message back, and the loop keeps reading.
+ *
+ * Nothing is written to stdout except protocol messages: an agent reads that
+ * stream as the protocol, and a stray `console.log` (of ours or of anything we
+ * import) would be a message it could not parse.
+ */
+export function serveStdio(client, input = process.stdin, output = process.stdout) {
+    let buffer = '';
+    const write = (message) => {
+        output.write(`${JSON.stringify(message)}\n`);
+    };
+    /**
+     * **One message at a time, in the order they arrived.**
+     *
+     * JSON-RPC does not require this — every answer carries the id of the question
+     * it belongs to, and a client is entitled to match them up however they come
+     * back. It is done anyway because the cost is a promise chain and what it buys
+     * is that a client which reads its answers in order is not surprised. The
+     * first version of this loop fired each message off as it arrived, and a
+     * garbled line's answer overtook a `initialize` that was waiting on an HTTP
+     * call — legal, and exactly the kind of thing that gets diagnosed in the wrong
+     * place.
+     */
+    let queue = Promise.resolve();
+    return new Promise((resolve) => {
+        input.setEncoding?.('utf8');
+        input.on('data', (chunk) => {
+            buffer += chunk;
+            // One message per line, and a partial line waits for the rest of itself —
+            // a JSON object split across two chunks is ordinary, not an error.
+            let newline = buffer.indexOf('\n');
+            while (newline !== -1) {
+                const line = buffer.slice(0, newline).trim();
+                buffer = buffer.slice(newline + 1);
+                if (line !== '') {
+                    queue = queue.then(() => deliver(client, line, write));
+                }
+                newline = buffer.indexOf('\n');
+            }
+        });
+        input.on('end', () => {
+            void queue.then(() => resolve());
+        });
+    });
+}
+async function deliver(client, line, write) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch (err) {
+        write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: `not JSON: ${err.message}` } });
+        return;
+    }
+    const answer = await handleMessage(client, parsed);
+    if (answer !== null)
+        write(answer);
+}

package/dist/mcp/tools.js

@@ -0,0 +1,348 @@
+/**
+ * The `funoteka_*` tools an agent drives this server with.
+ *
+ * **Every tool is one admin route, and this file is a table rather than a second
+ * implementation.** The contract says MCP *over* the admin API, and that is the
+ * whole design: an agent calling `funoteka_scan_start` goes through the same
+ * gate, the same audit line, the same idempotency record and the same refusal
+ * sentences as an operator with `curl`. A tool layer that reached into the
+ * database itself would be a second control surface to secure, a second place
+ * behaviour is defined, and a second answer to keep in step with the first.
+ *
+ * So a tool is a method, a path, and a way of turning its arguments into a body
+ * — and the table below is the entire surface. `tools/list` publishes it, which
+ * is how an agent finds out what it can do here without being told.
+ */
+/**
+ * The argument that makes a retry safe, offered on the tools that change
+ * something.
+ *
+ * The HTTP surface takes an `Idempotency-Key` header. A tool call is one JSON
+ * object and has nowhere to put a header, so the key is an argument here — and
+ * it reaches the same record the header does, which is what keeps this file's
+ * opening claim true: the same idempotency record as an operator with `curl`.
+ *
+ * **What it is for is not symmetry.** Until it existed, a client that lost an
+ * answer and repeated the call did the work twice, and the tool where that is
+ * not harmless is `funoteka_user_set {"rotate":"apiKey"}`: the second call mints
+ * a second key and invalidates the one the first call handed back. The contract
+ * asks for idempotent mutations without qualifying the transport (§3), and this
+ * was the transport that did not have them.
+ *
+ * Declared once and spread into every mutating tool by `server.ts`, rather than
+ * written into each of them: "which tools mutate" is one rule, and a dozen
+ * copies of it would be a dozen things to forget.
+ */
+export const IDEMPOTENCY_ARGUMENT = {
+    idempotencyKey: {
+        type: 'string',
+        description: 'Answers a repeated call with the first answer instead of doing the work twice. Send the same value when retrying.',
+    },
+};
+/** Whether a tool changes something, which is when a retry needs a key. */
+export function mutatingTool(tool) {
+    return tool.method !== 'GET';
+}
+const NOBODY = { type: 'object', properties: {}, additionalProperties: false };
+/**
+ * The tools, in the order an operator would meet them.
+ *
+ * The descriptions are written for the caller that has none of this server's
+ * context — an agent that has just been told to add a shelf has to be told, in
+ * the description, that a scan is a separate and slower thing.
+ */
+export const TOOLS = [
+    {
+        name: 'funoteka_status',
+        description: 'What this server is and what it is doing: version, uptime, how big the collection is, whether a scan is running, and how the admin surface itself is configured.',
+        inputSchema: NOBODY,
+        method: 'GET',
+        path: '/status',
+    },
+    {
+        name: 'funoteka_stats',
+        description: 'The library in numbers: roots, folders, files, songs, albums, artists, playlists, hidden albums, issues, and the size of the meta layer.',
+        inputSchema: NOBODY,
+        method: 'GET',
+        path: '/stats',
+    },
+    {
+        name: 'funoteka_issues',
+        description: 'What the scanner could not understand — every guess, skip, unmatched cue and refused tag — with a count of each kind. This is the only place those findings are visible.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                limit: { type: 'number', description: 'how many to return, 1–1000 (default 100)' },
+                severity: { type: 'string', description: 'only this severity: info, warn or error' },
+            },
+        },
+        method: 'GET',
+        path: '/issues',
+    },
+    {
+        name: 'funoteka_logs',
+        description: 'The last lines of the file this server narrates to. The read is bounded, so it is safe on a log that has been growing for months.',
+        inputSchema: {
+            type: 'object',
+            properties: { lines: { type: 'number', description: 'how many lines from the end, 1–5000 (default 200)' } },
+        },
+        method: 'GET',
+        path: '/logs',
+    },
+    {
+        name: 'funoteka_config_get',
+        description: 'Every setting, in force and where it came from (default, file, environment, flag). Secrets are reported as set and never as themselves.',
+        inputSchema: NOBODY,
+        method: 'GET',
+        path: '/config',
+    },
+    {
+        name: 'funoteka_config_set',
+        description: 'Write settings into the config file. The answer says whether each value is actually in force — the environment wins over the file — and nothing takes effect until the server is restarted.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                settings: {
+                    type: 'object',
+                    description: 'setting name to value, e.g. {"port": 8080, "logRequests": true}. null removes a key.',
+                },
+            },
+            required: ['settings'],
+        },
+        method: 'POST',
+        path: '/config',
+        body: (args) => args.settings,
+    },
+    {
+        name: 'funoteka_roots_list',
+        description: 'The directories this server reads, with what came from each and when it was last scanned. A root that has never been scanned is configured but not yet read.',
+        inputSchema: NOBODY,
+        method: 'GET',
+        path: '/roots',
+    },
+    {
+        name: 'funoteka_roots_add',
+        description: 'Configure a directory as something this server reads. The path must be a directory on the machine the *server* runs on. Adding one does not read it — start a scan for that.',
+        inputSchema: {
+            type: 'object',
+            properties: { path: { type: 'string', description: 'an absolute path as the server sees it' } },
+            required: ['path'],
+        },
+        method: 'POST',
+        path: '/roots',
+        body: (args) => ({ path: args.path }),
+    },
+    {
+        name: 'funoteka_roots_remove',
+        description: 'Stop reading a directory. Everything derived from it leaves the library with it (the answer says how much), and the files on disk are not touched.',
+        inputSchema: {
+            type: 'object',
+            properties: { path: { type: 'string', description: 'the root to stop reading' } },
+            required: ['path'],
+        },
+        method: 'DELETE',
+        path: '/roots',
+        body: (args) => ({ path: args.path }),
+    },
+    {
+        name: 'funoteka_scan_start',
+        description: 'Start reading the configured roots. The scan runs as a process of its own and this answers as soon as it has started — watch it with funoteka_scan_status. "full" reads every file again even if it has not changed; "incremental" trusts size and modification time.',
+        inputSchema: {
+            type: 'object',
+            properties: { mode: { type: 'string', enum: ['incremental', 'full'], description: 'default incremental' } },
+        },
+        method: 'POST',
+        path: '/scan',
+        body: (args) => (args.mode === undefined ? {} : { mode: args.mode }),
+    },
+    {
+        name: 'funoteka_scan_status',
+        description: 'Whether a scan is running now (and its pid), and what the last one did.',
+        inputSchema: NOBODY,
+        method: 'GET',
+        path: '/scan',
+    },
+    {
+        name: 'funoteka_scan_cancel',
+        description: 'Stop the scan that is running — or settle the record of one whose process is gone, which is the way out of a run that would otherwise refuse every later scan.',
+        inputSchema: NOBODY,
+        method: 'POST',
+        path: '/scan/cancel',
+    },
+    {
+        name: 'funoteka_scan_history',
+        description: 'What the last few scans did, newest first.',
+        inputSchema: {
+            type: 'object',
+            properties: { limit: { type: 'number', description: 'how many runs, 1–200 (default 20)' } },
+        },
+        method: 'GET',
+        path: '/scan/history',
+    },
+    {
+        name: 'funoteka_junk_list',
+        description: 'What the junk filter is keeping out of the default view, with the reason for each, and separately the edits a person made by hand.',
+        inputSchema: NOBODY,
+        method: 'GET',
+        path: '/junk',
+    },
+    {
+        name: 'funoteka_junk_mark',
+        description: 'Decide about a folder by hand, overruling the filter. verdict "junk" keeps it out of every listing; "trust" serves it whatever the rule says. Takes effect at once — no rescan.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'the folder, as the server sees it' },
+                verdict: { type: 'string', enum: ['junk', 'trust'] },
+                note: { type: 'string', description: 'why, for whoever reads this back in six months' },
+            },
+            required: ['path', 'verdict'],
+        },
+        method: 'POST',
+        path: '/junk',
+        body: (args) => ({ path: args.path, verdict: args.verdict, note: args.note }),
+    },
+    {
+        name: 'funoteka_junk_unmark',
+        description: 'Take a hand edit back and let the filter decide that folder again.',
+        inputSchema: {
+            type: 'object',
+            properties: { path: { type: 'string' } },
+            required: ['path'],
+        },
+        method: 'DELETE',
+        path: '/junk',
+        body: (args) => ({ path: args.path }),
+    },
+    {
+        name: 'funoteka_playlists_import',
+        description: 'Read the collection\'s .m3u files again and import any that are lists of their own.',
+        inputSchema: NOBODY,
+        method: 'POST',
+        path: '/playlists/import',
+    },
+    {
+        name: 'funoteka_export',
+        description: 'Everything a rescan cannot rebuild: playlists, stars, ratings, bookmarks, hand edits and api keys. The document also says what it is not holding.',
+        inputSchema: NOBODY,
+        method: 'GET',
+        path: '/export',
+    },
+    {
+        name: 'funoteka_restore',
+        description: 'Write an export document back into this library, by the files it names rather than by row ids. A merge: what is already here is left alone, and everything that could not be placed is listed.',
+        inputSchema: {
+            type: 'object',
+            properties: { document: { type: 'object', description: 'an object from funoteka_export' } },
+            required: ['document'],
+        },
+        method: 'POST',
+        path: '/restore',
+        body: (args) => args.document,
+    },
+    {
+        name: 'funoteka_user_get',
+        description: 'Who may listen: whether a password and an api key are set and where from, and the keys in the registry. Never the secrets themselves.',
+        inputSchema: NOBODY,
+        method: 'GET',
+        path: '/user',
+    },
+    {
+        name: 'funoteka_user_set',
+        description: 'Change the listener credentials. {"rotate": "apiKey"} mints a key and shows it once — the only moment this surface hands a secret back. Refused if the change would leave nobody able to get in.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                user: { type: 'string' },
+                password: { type: 'string' },
+                apiKey: { type: 'string' },
+                rotate: { type: 'string', enum: ['apiKey'] },
+            },
+        },
+        method: 'POST',
+        path: '/user',
+        body: (args) => {
+            const body = {};
+            for (const key of ['user', 'password', 'apiKey', 'rotate']) {
+                if (args[key] !== undefined)
+                    body[key] = args[key];
+            }
+            return body;
+        },
+    },
+    {
+        name: 'funoteka_restart',
+        description: 'Restart the server: exit and be started again by whatever supervises it. Refused where nothing does, because there a restart would only stop it.',
+        inputSchema: NOBODY,
+        method: 'POST',
+        path: '/restart',
+    },
+];
+export function toolNamed(name) {
+    return TOOLS.find((one) => one.name === name);
+}
+/**
+ * The arguments a tool insists on, or nothing when it has them all.
+ *
+ * **Read from the schema, which is the one place they are declared.** They used
+ * to be written twice — in `inputSchema.required` and in a field beside it — and
+ * a test existed only to check the two agreed, which is a test standing in for
+ * the second copy not existing.
+ */
+export function missingArguments(tool, args) {
+    const required = tool.inputSchema.required;
+    if (!Array.isArray(required))
+        return [];
+    return required.filter((key) => args[key] === undefined);
+}
+/**
+ * The protocol's answer to one `tools/call`.
+ *
+ * Two things are deliberately *not* errors here. A route that refused — a scan
+ * refused because one is running, a root that is not a directory — is a
+ * successful tool call whose content says what the server said: an agent that
+ * saw an MCP-level error would reach for a different tool, and the truth is that
+ * it asked the right one and got an answer. And a status the *transport* could
+ * not produce at all (the API is not answering) is the one case that is an
+ * error, because there is no answer to pass on.
+ */
+export async function callTool(client, name, args) {
+    const tool = toolNamed(name);
+    if (tool === undefined)
+        return { ok: false, error: `no such tool: ${name}` };
+    const missing = missingArguments(tool, args);
+    if (missing.length > 0) {
+        return { ok: false, error: `${name} needs ${missing.join(', ')}` };
+    }
+    // Pulled out before the arguments become a query or a body: the key is
+    // addressed to the transport, and a route that received it as a parameter
+    // would be a route that has to know about retries.
+    const { idempotencyKey, ...rest } = args;
+    const key = typeof idempotencyKey === 'string' && idempotencyKey !== '' ? idempotencyKey : undefined;
+    const query = tool.method === 'GET' ? asQuery(tool.path, rest) : tool.path;
+    const body = tool.method === 'GET' ? undefined : tool.body?.(rest);
+    try {
+        const answer = await client(tool.method, query, body, key);
+        return {
+            ok: true,
+            text: JSON.stringify(answer.body),
+            refused: answer.status >= 400,
+        };
+    }
+    catch (err) {
+        return { ok: false, error: err.message };
+    }
+}
+/**
+ * A `GET` route's arguments, as the query string it reads them from.
+ *
+ * The admin routes take their filters in the query — `?limit=`, `?severity=` —
+ * and one place has to know that, rather than each tool carrying a URL builder.
+ */
+function asQuery(path, args) {
+    const asked = Object.entries(args).filter(([, value]) => value !== undefined);
+    if (asked.length === 0)
+        return path;
+    const query = new URLSearchParams(asked.map(([key, value]) => [key, String(value)]));
+    return `${path}?${query.toString()}`;
+}