audiobookshelf-mcp 0.1.0

package/dist/tools/playlists.d.ts

@@ -0,0 +1,5 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type AudiobookshelfApi } from '../api.js';
+import { type ConfirmationStore } from '../confirm.js';
+export declare function registerPlaylistReadTools(server: McpServer, api: AudiobookshelfApi): void;
+export declare function registerPlaylistWriteTools(server: McpServer, api: AudiobookshelfApi, confirmations: ConfirmationStore): void;

package/dist/tools/playlists.js

@@ -0,0 +1,200 @@
+import { z } from 'zod';
+import { assertPathSegment } from '../api.js';
+import { confirmationPrompt, setResourceKey, } from '../confirm.js';
+import { errorResult, run, textResult, untrustedJsonResult, } from '../result.js';
+import { confirmTokenParam, detailParam } from '../schema.js';
+import { compactPlaylist, listFrom } from '../shape.js';
+const playlistIdParam = z
+    .string()
+    .min(1)
+    .describe('Playlist id, as returned by list_playlists');
+/**
+ * Audiobookshelf keeps playlists homogeneous: either every entry carries an
+ * episode_id (podcast playlist) or none does (book playlist). A mixed list is
+ * rejected with HTTP 400.
+ */
+const playlistItemsParam = z
+    .array(z.object({
+    library_item_id: z.string().min(1).describe('Library item id'),
+    episode_id: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Podcast episode id — required for podcast playlists, must be omitted ' +
+        'for book playlists'),
+}))
+    .max(500);
+function toApiItems(items) {
+    return items.map((item) => ({
+        libraryItemId: assertPathSegment(item.library_item_id, 'library_item_id'),
+        ...(item.episode_id !== undefined
+            ? { episodeId: assertPathSegment(item.episode_id, 'episode_id') }
+            : {}),
+    }));
+}
+export function registerPlaylistReadTools(server, api) {
+    server.registerTool('list_playlists', {
+        title: 'List playlists',
+        description: 'Lists the playlists of the API key’s user. Without library_id it returns ' +
+            'the playlists of every accessible library. Playlists are private per ' +
+            'user and can hold books or podcast episodes; collections are shared ' +
+            'server-wide and hold books only.',
+        inputSchema: {
+            library_id: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Restrict the result to this library'),
+            detail: detailParam,
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ library_id, detail }) => run(async () => {
+        const path = library_id === undefined
+            ? '/api/playlists'
+            : `/api/libraries/${assertPathSegment(library_id, 'library_id')}/playlists`;
+        const playlists = listFrom(await api.get(path), 'playlists');
+        return untrustedJsonResult({
+            numPlaylists: playlists.length,
+            playlists: detail === 'full' ? playlists : playlists.map(compactPlaylist),
+        });
+    }));
+    server.registerTool('get_playlist', {
+        title: 'Get playlist',
+        description: 'Fetches one playlist with its entries, in order.',
+        inputSchema: {
+            playlist_id: playlistIdParam,
+            detail: detailParam,
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ playlist_id, detail }) => run(async () => {
+        const data = await api.get(`/api/playlists/${assertPathSegment(playlist_id, 'playlist_id')}`);
+        return untrustedJsonResult(detail === 'full' ? data : compactPlaylist(data));
+    }));
+}
+export function registerPlaylistWriteTools(server, api, confirmations) {
+    server.registerTool('create_playlist', {
+        title: 'Create playlist',
+        description: 'Creates a playlist for the API key’s user. Unlike a collection it may ' +
+            'start out empty and it may hold podcast episodes.',
+        inputSchema: {
+            library_id: z
+                .string()
+                .min(1)
+                .describe('Library the playlist belongs to'),
+            name: z.string().min(1).max(255).describe('Playlist name'),
+            description: z
+                .string()
+                .max(4000)
+                .optional()
+                .describe('Optional description'),
+            items: playlistItemsParam
+                .optional()
+                .describe('Initial entries, optional'),
+        },
+    }, async ({ library_id, name, description, items }) => run(async () => {
+        const created = await api.post('/api/playlists', {
+            libraryId: assertPathSegment(library_id, 'library_id'),
+            name,
+            ...(description !== undefined ? { description } : {}),
+            items: items === undefined ? [] : toApiItems(items),
+        });
+        return untrustedJsonResult(compactPlaylist(created));
+    }));
+    server.registerTool('update_playlist', {
+        title: 'Update playlist',
+        description: 'Renames a playlist, changes its description or reorders its entries. ' +
+            'items replaces the order completely, so it has to contain every entry ' +
+            'that should stay — use add_items_to_playlist and ' +
+            'remove_items_from_playlist to change membership. The library of a ' +
+            'playlist cannot be changed.',
+        inputSchema: {
+            playlist_id: playlistIdParam,
+            name: z.string().min(1).max(255).optional().describe('New name'),
+            description: z
+                .string()
+                .max(4000)
+                .optional()
+                .describe('New description'),
+            items: playlistItemsParam
+                .optional()
+                .describe('Complete, newly ordered list of entries'),
+        },
+    }, async ({ playlist_id, name, description, items }) => run(async () => {
+        if (name === undefined &&
+            description === undefined &&
+            items === undefined) {
+            return errorResult('Nothing to update: pass name, description or items.');
+        }
+        const updated = await api.patch(`/api/playlists/${assertPathSegment(playlist_id, 'playlist_id')}`, {
+            ...(name !== undefined ? { name } : {}),
+            ...(description !== undefined ? { description } : {}),
+            ...(items !== undefined ? { items: toApiItems(items) } : {}),
+        });
+        return untrustedJsonResult(compactPlaylist(updated));
+    }));
+    server.registerTool('add_items_to_playlist', {
+        title: 'Add items to playlist',
+        description: 'Appends books or podcast episodes to a playlist. All entries must come ' +
+            'from the playlist’s library and match its kind — a podcast playlist ' +
+            'needs an episode_id on every entry, a book playlist on none.',
+        inputSchema: {
+            playlist_id: playlistIdParam,
+            items: playlistItemsParam.min(1),
+        },
+    }, async ({ playlist_id, items }) => run(async () => {
+        const updated = await api.post(`/api/playlists/${assertPathSegment(playlist_id, 'playlist_id')}/batch/add`, { items: toApiItems(items) });
+        return untrustedJsonResult(compactPlaylist(updated));
+    }));
+    server.registerTool('remove_items_from_playlist', {
+        title: 'Remove items from playlist',
+        description: 'Removes entries from a playlist. The media itself is untouched and the ' +
+            'entries can be added back with add_items_to_playlist. Note that ' +
+            'Audiobookshelf deletes a playlist automatically once its last entry is ' +
+            'removed.',
+        inputSchema: {
+            playlist_id: playlistIdParam,
+            items: playlistItemsParam.min(1),
+        },
+        annotations: { destructiveHint: true },
+    }, async ({ playlist_id, items }) => run(async () => {
+        const updated = await api.post(`/api/playlists/${assertPathSegment(playlist_id, 'playlist_id')}/batch/remove`, { items: toApiItems(items) });
+        const shaped = compactPlaylist(updated);
+        // The API answers with the playlist as it was, so an emptied playlist is
+        // only recognizable by its item count — say so instead of returning
+        // something that looks like an ordinary update.
+        return untrustedJsonResult(shaped.numItems === 0
+            ? {
+                ...shaped,
+                note: 'The playlist has no entries left and was therefore deleted by ' +
+                    'Audiobookshelf. It cannot be restored — recreate it with ' +
+                    'create_playlist.',
+            }
+            : shaped);
+    }));
+    server.registerTool('delete_playlist', {
+        title: 'Delete playlist',
+        description: 'Deletes a playlist. The media stays in the library. Two-step: the first ' +
+            'call returns a confirmation token, the second call with that token ' +
+            'performs the deletion.',
+        inputSchema: {
+            playlist_id: playlistIdParam,
+            confirm_token: confirmTokenParam,
+        },
+        annotations: { destructiveHint: true },
+    }, async ({ playlist_id, confirm_token }) => run(async () => {
+        const safeId = assertPathSegment(playlist_id, 'playlist_id');
+        const resource = setResourceKey('delete_playlist', [safeId]);
+        if (!confirmations.consume(resource, confirm_token)) {
+            if (confirm_token !== undefined) {
+                return errorResult('The confirmation token is invalid, expired or was issued for a ' +
+                    'different playlist. Call delete_playlist without a token to get ' +
+                    'a new one.');
+            }
+            const token = confirmations.issue(resource);
+            return textResult(confirmationPrompt(`delete playlist ${safeId}`, token, confirmations.ttlMinutes));
+        }
+        await api.delete(`/api/playlists/${safeId}`);
+        return textResult(`Playlist ${safeId} deleted.`);
+    }));
+}
+//# sourceMappingURL=playlists.js.map

package/dist/tools/playlists.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playlists.js","sourceRoot":"","sources":["../../src/tools/playlists.ts"],"names":[],"mappings":"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"}

package/dist/tools/progress.d.ts

@@ -0,0 +1,5 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type AudiobookshelfApi } from '../api.js';
+import { type ConfirmationStore } from '../confirm.js';
+export declare function registerProgressWriteTools(server: McpServer, api: AudiobookshelfApi, confirmations: ConfirmationStore): void;
+export declare function registerBookmarkWriteTools(server: McpServer, api: AudiobookshelfApi): void;

package/dist/tools/progress.js

@@ -0,0 +1,161 @@
+import { z } from 'zod';
+import { assertPathSegment } from '../api.js';
+import { confirmationPrompt, setResourceKey, } from '../confirm.js';
+import { errorResult, run, textResult } from '../result.js';
+import { confirmTokenParam, libraryItemIdParam } from '../schema.js';
+const episodeIdParam = z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Podcast episode id — required to address a podcast episode, omitted for books');
+export function registerProgressWriteTools(server, api, confirmations) {
+    server.registerTool('set_media_progress', {
+        title: 'Set media progress',
+        description: 'Creates or updates the listening progress of the API key’s user for one ' +
+            'book or podcast episode. Set is_finished=true to mark it as finished, ' +
+            'is_finished=false to reopen it (which resets the position to 0), or ' +
+            'current_time to jump to a position in seconds. Audiobookshelf also marks ' +
+            'an item finished on its own once less than ten seconds remain.',
+        inputSchema: {
+            library_item_id: libraryItemIdParam,
+            episode_id: episodeIdParam,
+            current_time: z
+                .number()
+                .min(0)
+                .optional()
+                .describe('New playback position in seconds'),
+            progress: z
+                .number()
+                .min(0)
+                .max(1)
+                .optional()
+                .describe('Progress as a fraction between 0 and 1. Only used when is_finished ' +
+                'is not given.'),
+            is_finished: z
+                .boolean()
+                .optional()
+                .describe('Mark the item as finished (true) or unfinished (false)'),
+            hide_from_continue_listening: z
+                .boolean()
+                .optional()
+                .describe('Hide the item from the "Continue Listening" shelf without changing ' +
+                'its position'),
+        },
+    }, async ({ library_item_id, episode_id, current_time, progress, is_finished, hide_from_continue_listening, }) => run(async () => {
+        if (current_time === undefined &&
+            progress === undefined &&
+            is_finished === undefined &&
+            hide_from_continue_listening === undefined) {
+            return errorResult('Nothing to update: pass current_time, progress, is_finished or ' +
+                'hide_from_continue_listening.');
+        }
+        const safeItemId = assertPathSegment(library_item_id, 'library_item_id');
+        const path = `/api/me/progress/${safeItemId}` +
+            (episode_id === undefined
+                ? ''
+                : `/${assertPathSegment(episode_id, 'episode_id')}`);
+        // Only the fields below are forwarded. The endpoint applies its payload
+        // to the progress record wholesale, so passing arbitrary keys through
+        // would let a caller write columns this tool never intended to touch.
+        await api.patch(path, {
+            ...(current_time !== undefined ? { currentTime: current_time } : {}),
+            ...(progress !== undefined ? { progress } : {}),
+            ...(is_finished !== undefined ? { isFinished: is_finished } : {}),
+            ...(hide_from_continue_listening !== undefined
+                ? { hideFromContinueListening: hide_from_continue_listening }
+                : {}),
+        });
+        // The endpoint answers with 200 and no body; read the result back so the
+        // model sees the state that actually got stored.
+        const updated = await api.get(path);
+        return textResult(`Progress updated.\n${JSON.stringify(updated, null, 2)}`);
+    }));
+    server.registerTool('delete_media_progress', {
+        title: 'Delete media progress',
+        description: 'Deletes a progress record of the API key’s user, which removes the ' +
+            'listening history for that item — position, finished state and dates. ' +
+            'Takes the media progress id (field "id" of get_media_progress), not the ' +
+            'library item id. Two-step: the first call returns a confirmation token, ' +
+            'the second call with that token performs the deletion.',
+        inputSchema: {
+            media_progress_id: z
+                .string()
+                .min(1)
+                .describe('Media progress id, from the "id" field of get_media_progress'),
+            confirm_token: confirmTokenParam,
+        },
+        annotations: { destructiveHint: true },
+    }, async ({ media_progress_id, confirm_token }) => run(async () => {
+        const safeId = assertPathSegment(media_progress_id, 'media_progress_id');
+        const resource = setResourceKey('delete_media_progress', [safeId]);
+        if (!confirmations.consume(resource, confirm_token)) {
+            if (confirm_token !== undefined) {
+                return errorResult('The confirmation token is invalid, expired or was issued for a ' +
+                    'different progress record. Call delete_media_progress without a ' +
+                    'token to get a new one.');
+            }
+            const token = confirmations.issue(resource);
+            return textResult(confirmationPrompt(`delete the listening history of media progress ${safeId}`, token, confirmations.ttlMinutes));
+        }
+        await api.delete(`/api/me/progress/${safeId}`);
+        return textResult(`Media progress ${safeId} deleted.`);
+    }));
+}
+export function registerBookmarkWriteTools(server, api) {
+    server.registerTool('create_bookmark', {
+        title: 'Create bookmark',
+        description: 'Creates a bookmark at a position of a book for the API key’s user. The ' +
+            'position in seconds is the bookmark’s identity — a second bookmark at ' +
+            'the same second is rejected.',
+        inputSchema: {
+            library_item_id: libraryItemIdParam,
+            time: z
+                .number()
+                .min(0)
+                .describe('Position in seconds where the bookmark is placed'),
+            title: z.string().min(1).max(255).describe('Bookmark title'),
+        },
+    }, async ({ library_item_id, time, title }) => run(async () => {
+        const created = await api.post(`/api/me/item/${assertPathSegment(library_item_id, 'library_item_id')}/bookmark`, { time, title });
+        return textResult(`Bookmark created.\n${JSON.stringify(created, null, 2)}`);
+    }));
+    server.registerTool('update_bookmark', {
+        title: 'Update bookmark',
+        description: 'Renames the bookmark at a given position. The position itself cannot be ' +
+            'changed — delete the bookmark and create a new one for that.',
+        inputSchema: {
+            library_item_id: libraryItemIdParam,
+            time: z
+                .number()
+                .min(0)
+                .describe('Position in seconds identifying the bookmark'),
+            title: z.string().min(1).max(255).describe('New bookmark title'),
+        },
+    }, async ({ library_item_id, time, title }) => run(async () => {
+        const updated = await api.patch(`/api/me/item/${assertPathSegment(library_item_id, 'library_item_id')}/bookmark`, { time, title });
+        return textResult(`Bookmark updated.\n${JSON.stringify(updated, null, 2)}`);
+    }));
+    server.registerTool('delete_bookmark', {
+        title: 'Delete bookmark',
+        description: 'Deletes the bookmark at a given position. No confirmation token: a ' +
+            'bookmark is a position and a title, and create_bookmark restores it.',
+        inputSchema: {
+            library_item_id: libraryItemIdParam,
+            time: z
+                .number()
+                .min(0)
+                .describe('Position in seconds identifying the bookmark'),
+        },
+        annotations: { destructiveHint: true },
+    }, async ({ library_item_id, time }) => run(async () => {
+        const safeId = assertPathSegment(library_item_id, 'library_item_id');
+        // The position goes into the path, so it must be a finite number and
+        // never a string that could carry path segments.
+        if (!Number.isFinite(time)) {
+            throw new Error('invalid time: must be a finite number of seconds');
+        }
+        await api.delete(`/api/me/item/${safeId}/bookmark/${time}`);
+        return textResult(`Bookmark at ${time} seconds of item ${safeId} deleted.`);
+    }));
+}
+//# sourceMappingURL=progress.js.map

package/dist/tools/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../src/tools/progress.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "audiobookshelf-mcp",
+  "version": "0.1.0",
+  "mcpName": "io.github.ni-c/audiobookshelf-mcp",
+  "description": "MCP server for Audiobookshelf, the self-hosted audiobook and podcast server",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "audiobookshelf",
+    "audiobook",
+    "podcast",
+    "selfhosted"
+  ],
+  "license": "MIT",
+  "author": "Willi Thiel",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ni-c/audiobookshelf-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ni-c/audiobookshelf-mcp/issues"
+  },
+  "homepage": "https://github.com/ni-c/audiobookshelf-mcp#readme",
+  "type": "module",
+  "bin": {
+    "audiobookshelf-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run lint && npm test && npm run build",
+    "docs:tools:check": "node scripts/gen-tools-doc.mjs --check",
+    "docs:tools": "node scripts/gen-tools-doc.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "undici": "^8.10.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.2.0",
+    "@vitest/coverage-v8": "4.1.10",
+    "eslint": "^10.8.1",
+    "prettier": "^3.9.6",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.67.0",
+    "vitest": "^4.1.10"
+  }
+}