@mokoconsulting/mokoabs-mcp 0.0.0-stage → 4.0.2

package/source/index.ts

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: mokoabs-mcp.Server
+ * INGROUP: mokoabs-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokoabs-mcp
+ * PATH: /source/index.ts
+ * VERSION: 01.00.00
+ * BRIEF: MCP server entry point — registers all Audiobookshelf API tools
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { loadConfig, getConnection } from './config.js';
+import { ApiClient } from './client.js';
+import type { ApiConfig, ApiResponse } from './types.js';
+
+let config: ApiConfig;
+
+function clientFor(connection?: string): ApiClient {
+	return new ApiClient(getConnection(config, connection));
+}
+
+function formatResponse(res: ApiResponse): { content: Array<{ type: 'text'; text: string }> } {
+	if (res.status >= 400) {
+		return {
+			content: [{ type: 'text' as const, text: `Error: HTTP ${res.status}: ${JSON.stringify(res.data, null, 2)}` }],
+		};
+	}
+	return {
+		content: [{ type: 'text' as const, text: JSON.stringify(res.data, null, 2) }],
+	};
+}
+
+// ── Shared parameter definitions ────────────────────────────────────────
+
+const ConnectionParam = {
+	connection: z.string().optional().describe('Named connection from config (uses default if omitted)'),
+};
+
+const PaginationParams = {
+	limit: z.number().optional().describe('Max results'),
+	page: z.number().optional().describe('Page number (0-based)'),
+};
+
+function paginationQuery(params: { limit?: number; page?: number }): Record<string, string> {
+	const q: Record<string, string> = {};
+	if (params.limit !== undefined) q['limit'] = String(params.limit);
+	if (params.page !== undefined) q['page'] = String(params.page);
+	return q;
+}
+
+// ── Server ──────────────────────────────────────────────────────────────
+
+const server = new McpServer({
+	name: 'mokoabs-mcp',
+	version: '1.0.0',
+});
+
+// ════════════════════════════════════════════════════════════════════════
+// Audiobookshelf tools. The client prepends the "/api" prefix and a Bearer
+// Authorization header, so endpoints below are written without "/api".
+// ════════════════════════════════════════════════════════════════════════
+
+// ── Libraries ────────────────────────────────────────────────────────────
+
+server.tool(
+	'abs_libraries_list',
+	'List all Audiobookshelf libraries (id, name, mediaType).',
+	{ ...ConnectionParam },
+	async ({ connection }) => formatResponse(await clientFor(connection).get('/libraries')),
+);
+
+server.tool(
+	'abs_library_items',
+	'List items in a library (paginated). Optional ABS sort/desc/filter.',
+	{
+		libraryId: z.string().describe('Library ID'),
+		sort: z.string().optional().describe('Sort field, e.g. "media.metadata.title"'),
+		desc: z.boolean().optional().describe('Sort descending'),
+		filter: z.string().optional().describe('ABS filter string, e.g. "genres.<base64>"'),
+		...PaginationParams,
+		...ConnectionParam,
+	},
+	async ({ libraryId, sort, desc, filter, limit, page, connection }) => {
+		const params: Record<string, string> = { ...paginationQuery({ limit, page }) };
+		if (sort) params['sort'] = sort;
+		if (desc !== undefined) params['desc'] = desc ? '1' : '0';
+		if (filter) params['filter'] = filter;
+		return formatResponse(await clientFor(connection).get(`/libraries/${libraryId}/items`, params));
+	},
+);
+
+server.tool(
+	'abs_library_search',
+	'Search a library (books, series, authors, narrators, tags) by query.',
+	{
+		libraryId: z.string().describe('Library ID'),
+		q: z.string().describe('Search query'),
+		limit: z.number().optional().describe('Max results per group'),
+		...ConnectionParam,
+	},
+	async ({ libraryId, q, limit, connection }) => {
+		const params: Record<string, string> = { q };
+		if (limit !== undefined) params['limit'] = String(limit);
+		return formatResponse(await clientFor(connection).get(`/libraries/${libraryId}/search`, params));
+	},
+);
+
+server.tool(
+	'abs_library_scan',
+	'Trigger a scan of a library (picks up newly added/removed files).',
+	{
+		libraryId: z.string().describe('Library ID'),
+		force: z.boolean().optional().describe('Force a full re-scan of all items'),
+		...ConnectionParam,
+	},
+	async ({ libraryId, force, connection }) =>
+		formatResponse(await clientFor(connection).post(`/libraries/${libraryId}/scan${force ? '?force=1' : ''}`)),
+);
+
+server.tool(
+	'abs_library_collections',
+	'List collections in a library.',
+	{ libraryId: z.string().describe('Library ID'), ...ConnectionParam },
+	async ({ libraryId, connection }) =>
+		formatResponse(await clientFor(connection).get(`/libraries/${libraryId}/collections`)),
+);
+
+server.tool(
+	'abs_library_series',
+	'List series in a library (paginated).',
+	{ libraryId: z.string().describe('Library ID'), ...PaginationParams, ...ConnectionParam },
+	async ({ libraryId, limit, page, connection }) =>
+		formatResponse(await clientFor(connection).get(`/libraries/${libraryId}/series`, paginationQuery({ limit, page }))),
+);
+
+server.tool(
+	'abs_library_authors',
+	'List authors in a library.',
+	{ libraryId: z.string().describe('Library ID'), ...ConnectionParam },
+	async ({ libraryId, connection }) =>
+		formatResponse(await clientFor(connection).get(`/libraries/${libraryId}/authors`)),
+);
+
+// ── Items ────────────────────────────────────────────────────────────────
+
+server.tool(
+	'abs_item_get',
+	'Get a library item by ID (optionally with expanded media/metadata).',
+	{
+		itemId: z.string().describe('Library item ID'),
+		expanded: z.boolean().optional().describe('Include full media/metadata'),
+		...ConnectionParam,
+	},
+	async ({ itemId, expanded, connection }) => {
+		const params: Record<string, string> = {};
+		if (expanded) params['expanded'] = '1';
+		return formatResponse(await clientFor(connection).get(`/items/${itemId}`, params));
+	},
+);
+
+// ── Account ──────────────────────────────────────────────────────────────
+
+server.tool(
+	'abs_me',
+	'Get the authenticated user (from the API key).',
+	{ ...ConnectionParam },
+	async ({ connection }) => formatResponse(await clientFor(connection).get('/me')),
+);
+
+// ── Generic API Call ────────────────────────────────────────────────────
+
+server.tool(
+	'api_request',
+	'Make a raw Audiobookshelf API request to any endpoint (path is relative to /api).',
+	{
+		method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).describe('HTTP method'),
+		endpoint: z.string().describe('API endpoint path relative to /api (e.g. "/libraries")'),
+		body: z.record(z.string(), z.unknown()).optional().describe('Request body for POST/PUT/PATCH'),
+		params: z.record(z.string(), z.string()).optional().describe('Query parameters'),
+		...ConnectionParam,
+	},
+	async ({ method, endpoint, body, params, connection }) => {
+		const client = clientFor(connection);
+		switch (method) {
+			case 'GET':
+				return formatResponse(await client.get(endpoint, params));
+			case 'POST':
+				return formatResponse(await client.post(endpoint, body));
+			case 'PUT':
+				return formatResponse(await client.put(endpoint, body));
+			case 'PATCH':
+				return formatResponse(await client.patch(endpoint, body));
+			case 'DELETE':
+				return formatResponse(await client.delete(endpoint));
+		}
+	},
+);
+
+// ── Connections Management ──────────────────────────────────────────────
+
+server.tool(
+	'list_connections',
+	'List configured Audiobookshelf connections.',
+	{},
+	async () => {
+		const lines = Object.entries(config.connections).map(([name, conn]) => {
+			const is_default = name === config.defaultConnection ? ' (default)' : '';
+			return `  ${name}${is_default}: ${conn.baseUrl}`;
+		});
+		return {
+			content: [{ type: 'text' as const, text: `Configured connections:\n${lines.join('\n')}` }],
+		};
+	},
+);
+
+// ── Start Server ────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+	config = await loadConfig();
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+
+main().catch((err) => {
+	process.stderr.write(`Fatal: ${err}\n`);
+	process.exit(1);
+});

package/source/tokenReader.ts

@@ -0,0 +1,120 @@
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: mokoabs-mcp.TokenReader
+ * INGROUP: mokoabs-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokoabs-mcp
+ * PATH: /source/tokenReader.ts
+ * VERSION: 01.00.00
+ * BRIEF: MokoCLI #1043 — JSON-aware credential/token reader (vendored per-repo).
+ *
+ * GitHub standard primary; Google secondary = DETECT + WARN (no exchange).
+ * Secret values are NEVER written to stdout and NEVER echoed in errors/warnings.
+ *
+ * Detection ladder (resolveTokenValue):
+ *   1. trim; empty -> throw (no silent anonymous request).
+ *   2. JSON.parse; parse-fail OR non-object(array/null/scalar) -> the trimmed
+ *      string IS the bearer (bare PAT, `gh auth token` output).  [raw]
+ *   3. object .type in {service_account, authorized_user, external_account,
+ *      impersonated_service_account}  OR  (.refresh_token && .token_uri)
+ *      -> GOOGLE: emit a stderr WARNING and return an UNUSABLE result
+ *         (bearer '', needsExchange true). Never bearer a private key.
+ *   4. else .token || .access_token -> bearer (+ expiry/scope/permissions). [github-json]
+ *   5. else -> throw (unrecognized object; never leak the blob as a token).
+ */
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+
+export type TokenKind = 'raw' | 'github-json' | 'google';
+
+export interface ResolvedToken {
+	/** Bearer value to send. '' when unusable (Google needs-exchange). */
+	bearer: string;
+	kind: TokenKind;
+	/** true for Google creds — not usable as a bearer by this server. */
+	needsExchange?: boolean;
+	expiresAt?: string;
+	expiresIn?: number;
+	scopes?: string[];
+	permissions?: Record<string, unknown>;
+}
+
+const GOOGLE_TYPES = new Set([
+	'service_account',
+	'authorized_user',
+	'external_account',
+	'impersonated_service_account',
+]);
+
+/** Expand a leading "~" to $HOME, then resolve to an absolute path. */
+export function expandHome(p: string): string {
+	if (p === '~') return homedir();
+	if (p.startsWith('~/') || p.startsWith('~\\')) return resolve(homedir(), p.slice(2));
+	return resolve(p);
+}
+
+/** stderr ONLY — must never touch stdout (the MCP stdio channel). Never prints secret values. */
+function warn(msg: string): void {
+	process.stderr.write(`[token] WARNING: ${msg}\n`);
+}
+
+/**
+ * Resolve RAW credential content into a bearer per MokoCLI #1043.
+ * `source` only labels errors/warnings; secret values are never echoed.
+ */
+export function resolveTokenValue(raw: string, source = 'credential'): ResolvedToken {
+	const trimmed = (raw ?? '').trim();
+	if (!trimmed) {
+		throw new Error(`Credential "${source}" is empty — refusing an anonymous request (set the token or remove the connection).`);
+	}
+
+	let obj: unknown;
+	try {
+		obj = JSON.parse(trimmed);
+	} catch {
+		return { bearer: trimmed, kind: 'raw' }; // bare PAT / `gh auth token`
+	}
+	if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+		return { bearer: trimmed, kind: 'raw' };
+	}
+
+	const o = obj as Record<string, unknown>;
+	const type = typeof o.type === 'string' ? o.type : '';
+	const isGoogle = GOOGLE_TYPES.has(type) || (typeof o.refresh_token === 'string' && typeof o.token_uri === 'string');
+	if (isGoogle) {
+		warn(`credential "${source}" is a Google ${type || 'OAuth token-cache'} JSON; this server does not perform Google token exchange, so it will NOT be used (a private key is never sent as a bearer token).`);
+		return { bearer: '', kind: 'google', needsExchange: true };
+	}
+
+	const bearer = typeof o.token === 'string' ? o.token : typeof o.access_token === 'string' ? o.access_token : '';
+	if (bearer) {
+		const scopes = Array.isArray(o.scopes)
+			? o.scopes.map(String)
+			: typeof o.scope === 'string'
+				? o.scope.split(/\s+/).filter(Boolean)
+				: undefined;
+		const expiresAt = typeof o.expires_at === 'string' ? o.expires_at : typeof o.expiry === 'string' ? o.expiry : undefined;
+		const expiresIn = typeof o.expires_in === 'number' ? o.expires_in : undefined;
+		const permissions = o.permissions && typeof o.permissions === 'object' ? (o.permissions as Record<string, unknown>) : undefined;
+		return { bearer, kind: 'github-json', expiresAt, expiresIn, scopes, permissions };
+	}
+
+	throw new Error(`Credential "${source}" is an unrecognized JSON object (no "token"/"access_token") — refusing to use it as a bearer token.`);
+}
+
+/** Read a token file (~ expands) and resolve it per #1043. */
+export async function readTokenFile(path: string, source?: string): Promise<ResolvedToken> {
+	const abs = expandHome(path);
+	let raw: string;
+	try {
+		raw = await readFile(abs, 'utf-8');
+	} catch (err) {
+		throw new Error(`Failed to read token file "${abs}": ${err instanceof Error ? err.message : String(err)}`);
+	}
+	return resolveTokenValue(raw, source ?? abs);
+}

package/source/types.ts

@@ -0,0 +1,63 @@
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: mokoabs-mcp.Types
+ * INGROUP: mokoabs-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokoabs-mcp
+ * PATH: /source/types.ts
+ * VERSION: 01.00.00
+ * BRIEF: TypeScript type definitions for Audiobookshelf MCP server
+ */
+
+/**
+ * Connection configuration for a single API instance.
+ *
+ * Rename and extend these fields to match your target API's auth mechanism:
+ * - `apiKey` + DOLAPIKEY header  (Dolibarr)
+ * - `apiToken` + Bearer header   (Joomla, GitHub)
+ * - `username`/`password`        (Basic auth)
+ * - `oauth` fields               (OAuth2 flows)
+ */
+export interface ApiConnection {
+	/** Base URL of the API instance (no trailing slash) */
+	baseUrl: string;
+	/**
+	 * API key or token for authentication. Either a raw bearer string (passes
+	 * through unchanged) or a JSON credential blob (GitHub token/access_token,
+	 * or a Google credential which is detected and refused) per MokoCLI #1043.
+	 * Optional when `tokenFile` is supplied instead.
+	 */
+	apiKey?: string;
+	/**
+	 * Path to a file holding the credential (~ expands). Read and resolved per
+	 * MokoCLI #1043; takes precedence over inline `apiKey` when both are set.
+	 */
+	tokenFile?: string;
+	/**
+	 * Resolved bearer value used for `Authorization: Bearer <bearer>`. Populated
+	 * by loadConfig() from `apiKey`/`tokenFile`; not provided by users directly.
+	 */
+	bearer?: string;
+	/** Skip TLS certificate verification (self-signed certs) */
+	insecure?: boolean;
+}
+
+/**
+ * Top-level configuration supporting multiple named connections.
+ */
+export interface ApiConfig {
+	connections: Record<string, ApiConnection>;
+	defaultConnection: string;
+}
+
+/**
+ * Normalized API response returned by the HTTP client.
+ */
+export interface ApiResponse {
+	status: number;
+	data: unknown;
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "Node16",
+		"moduleResolution": "Node16",
+		"outDir": "./dist",
+		"rootDir": "./source",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true
+	},
+	"include": ["source/**/*"],
+	"exclude": ["node_modules", "dist"]
+}