@mokoconsulting/mokoabs-mcp 0.0.0-stage → 4.0.2

package/Makefile

@@ -0,0 +1,94 @@
+# NPM / Node Project Makefile
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# Native build/test/lint/package logic for an npm package (incl. MCP servers). The
+# identity block below is the version source of truth — auto-filled per repo by the
+# mokocli workflow sync (--makefiles).
+
+# ==============================================================================
+# Identity (auto-filled by workflow sync — the Makefile is the version source of truth)
+# ==============================================================================
+PROJECT_NAME    := mcp-mokoabs
+PROJECT_VERSION := 04.00.02
+PLATFORM        := npm
+
+# ==============================================================================
+# Configuration
+# ==============================================================================
+SRC_DIR   := source
+BUILD_DIR := build
+NPM       := npm
+NODE      := node
+# Prefer `npm ci` when a lockfile is present (reproducible), else `npm install`.
+NPM_INSTALL := $(shell [ -f package-lock.json ] && echo ci || echo install)
+
+COLOR_RESET  := \033[0m
+COLOR_GREEN  := \033[32m
+COLOR_YELLOW := \033[33m
+COLOR_BLUE   := \033[34m
+COLOR_RED    := \033[31m
+
+# ==============================================================================
+# Targets
+# ==============================================================================
+.PHONY: help
+help: ## Show this help message
+	@echo "$(COLOR_BLUE)$(PROJECT_NAME) v$(PROJECT_VERSION) — npm package$(COLOR_RESET)"
+	@echo ""
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  $(COLOR_BLUE)%-16s$(COLOR_RESET) %s\n", $$1, $$2}'
+
+.PHONY: install-deps
+install-deps: ## Install dependencies (npm ci if lockfile present, else install)
+	@$(NPM) $(NPM_INSTALL)
+	@echo "$(COLOR_GREEN)✓ dependencies installed$(COLOR_RESET)"
+
+.PHONY: lint
+lint: ## Run the package lint script when defined
+	@if grep -q '"lint"' package.json 2>/dev/null; then $(NPM) run lint; \
+	  else echo "$(COLOR_YELLOW)⚠ no lint script — skipping$(COLOR_RESET)"; fi
+
+.PHONY: validate
+validate: lint ## Alias: static validation (lint)
+
+.PHONY: test
+test: ## Run the package test script when defined
+	@if grep -q '"test"' package.json 2>/dev/null; then $(NPM) test; \
+	  else echo "$(COLOR_YELLOW)⚠ no test script — skipping$(COLOR_RESET)"; fi
+
+.PHONY: clean
+clean: ## Remove build artifacts
+	@rm -rf $(BUILD_DIR)
+	@echo "$(COLOR_GREEN)✓ cleaned $(BUILD_DIR)/$(COLOR_RESET)"
+
+.PHONY: build
+build: ## Run the package build script when defined
+	@if grep -q '"build"' package.json 2>/dev/null; then $(NPM) run build; \
+	  echo "$(COLOR_GREEN)✓ built$(COLOR_RESET)"; \
+	  else echo "$(COLOR_YELLOW)⚠ no build script — nothing to build$(COLOR_RESET)"; fi
+
+.PHONY: minify
+minify: ## Minify assets under $(SRC_DIR) via the mokocli build agent when available
+	@MOKO=$(or $(wildcard ../mokocli),$(wildcard $(HOME)/mokocli),$(wildcard /opt/mokocli)); \
+	  if [ -n "$$MOKO" ] && [ -f "$$MOKO/build/minify.js" ]; then $(NODE) "$$MOKO/build/minify.js" $(SRC_DIR); \
+	  elif [ -f scripts/minify.js ]; then $(NODE) scripts/minify.js; \
+	  else echo "$(COLOR_YELLOW)⚠ no minify script found$(COLOR_RESET)"; fi
+
+.PHONY: package
+package: build ## Create the npm tarball (npm pack) + .sha256
+	@echo "$(COLOR_BLUE)Packaging $(PROJECT_NAME)-$(PROJECT_VERSION)...$(COLOR_RESET)"
+	@mkdir -p $(BUILD_DIR)
+	@$(NPM) pack --pack-destination $(BUILD_DIR) >/dev/null
+	@tgz=$$(ls -t $(BUILD_DIR)/*.tgz | head -1); \
+	  sha256sum "$$tgz" | awk '{print $$1}' > "$$tgz.sha256"; \
+	  echo "$(COLOR_GREEN)✓ packaged: $$tgz$(COLOR_RESET)"
+
+.PHONY: release
+release: validate test package ## Validate, test, and package for release
+	@echo "$(COLOR_GREEN)✓ release artifacts ready for $(PROJECT_NAME) v$(PROJECT_VERSION)$(COLOR_RESET)"
+
+.PHONY: version
+version: ## Print the resolved version (Makefile is the source of truth)
+	@echo "$(PROJECT_NAME) $(PROJECT_VERSION) ($(PLATFORM))"
+
+.DEFAULT_GOAL := help

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# Template-NPM
 
-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.
+> **Reporting issues:** This repository's issue tracker is disabled. All bugs, feature requests, and questions for MokoConsulting templates and shared tooling are tracked centrally in **[mokocli](https://git.mokoconsulting.tech/MokoConsulting/mokocli/issues)** — please open issues there, not in the individual template repos.
+
+
+![Language](https://img.shields.io/badge/language-TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white) ![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green?style=flat-square) ![Platform](https://img.shields.io/badge/platform-Node.js%20%7C%20MCP-339933?style=flat-square&logo=node.js&logoColor=white) ![Wiki](https://img.shields.io/badge/wiki-Template--NPM-blue?style=flat-square)
+
+Template repository for creating MokoCLI-compliant Model Context Protocol (MCP) API servers. Provides the scaffolding, configuration patterns, and architecture conventions used by all Moko Consulting MCP servers, enabling AI assistants like Claude to interact with REST APIs through a standardized tool interface.
+
+## Features
+
+- **MCP server scaffolding** -- pre-configured TypeScript project structure with entry point, tool registration, and stdio transport ready to go
+- **Multi-connection support** -- built-in `config.json` pattern for managing multiple named API connections with a default fallback; all tools accept an optional `connection` parameter
+- **REST API bridge architecture** -- standardized pattern for bridging any REST API as MCP tools, with typed request/response handling
+- **TypeScript-first** -- full TypeScript setup with `tsconfig.json`, strict mode, and ES module output
+- **Build tooling** -- Makefile with `build`, `dev`, `clean`, and `lint` targets; npm scripts for compilation and development
+- **MokoCLI compliant** -- follows all Moko Consulting governance conventions: file headers, commit messages, `.gitattributes`, `.gitmessage`, PR/issue templates
+- **Example configuration** -- `config.example.json` demonstrates the connection configuration schema
+- **Documentation templates** -- wiki pages for API reference, architecture overview, and installation pre-generated
+
+## Installation
+
+1. Create a new repository from this template (or clone directly):
+   ```bash
+   git clone https://git.mokoconsulting.tech/MokoConsulting/Template-NPM.git my-mcp-server
+   cd my-mcp-server
+   ```
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+3. Copy and configure the connection file:
+   ```bash
+   cp config.example.json config.json
+   # Edit config.json with your API credentials
+   ```
+4. Build the project:
+   ```bash
+   npm run build
+   ```
+5. Run the server:
+   ```bash
+   node build/index.js
+   ```
+
+## Usage
+
+Register the built server with your MCP client (Claude Code / Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "<name>": { "command": "npx", "args": ["-y", "@mokoconsulting/<package>"] }
+  }
+}
+```
+
+Every tool accepts an optional `connection` parameter to target a named connection from your config; omit it to use the default. See [`docs/API.md`](docs/API.md) for the full tool reference.
+
+## Configuration
+
+| Path | Purpose |
+|---|---|
+| `source/` | TypeScript source files (server entry, tool definitions, API client) |
+| `config.example.json` | Example multi-connection configuration schema |
+| `config.json` | Local connection configuration (gitignored) |
+| `package.json` | npm dependencies and scripts |
+| `tsconfig.json` | TypeScript compiler configuration |
+| `scripts/` | Build and development utility scripts |
+| `docs/` | Developer documentation |
+| `Makefile` | Build, dev, clean, and lint targets |
+
+## Requirements
+
+- Node.js 20.0.0 or later
+- npm 9+
+- TypeScript 5+ (installed via npm)
+
+## Documentation
+
+Full documentation is available on the [Wiki](https://git.mokoconsulting.tech/MokoConsulting/Template-NPM/wiki), including:
+
+- [API](https://git.mokoconsulting.tech/MokoConsulting/Template-NPM/wiki/API) -- tool reference and connection parameter documentation
+- [ARCHITECTURE](https://git.mokoconsulting.tech/MokoConsulting/Template-NPM/wiki/ARCHITECTURE) -- MCP server design and REST API bridge pattern
+- [INSTALLATION](https://git.mokoconsulting.tech/MokoConsulting/Template-NPM/wiki/INSTALLATION) -- setup prerequisites and configuration guide
+
+## Contributing
+
+See the wiki for development guidelines and contribution instructions.
+
+## License
+
+This project is licensed under the GNU General Public License v3.0 or later -- see the [LICENSE](LICENSE) file.
+
+---
+
+*[Moko Consulting](https://mokoconsulting.tech) -- [MokoCLI](https://git.mokoconsulting.tech/MokoConsulting/mokocli/wiki/Home)*
+
+## Template CI Notes
+
+Build/CI/release/version workflows are guarded to skip template repos (Template-*) and only run in repos created from them.
+
+<!-- CI: platform-specific CI (ci-go / ci-php / npm-build-test / ci-joomla); ci-generic retired. -->
+
+## Release automation
+
+On a stable release the pipeline prunes superseded-major `version/*` branches, keeping only the current major.
+<!-- The main->dev cascade (cascade-dev.yml) pushes to protected `dev` using the MOKOGIT_TOKEN PAT so the pre-receive hook accepts the push. See #257. -->
+<!-- CI: npm-build-test.yml no longer defines a `ci-summary` job; a `needs:`+`if: always()` job never dispatches on the Gitea runner and stranded every main PR under the org `*` rule. Removed (matches ci-go.yml). -->
+<!-- Release flow: bump-on-dev — the base version + CHANGELOG are bumped/promoted on `dev` pre-promotion (promote-rc via release_bump_dev.php); main publishes `--bump none --no-commit` so it never diverges from dev. -->

package/SECURITY.md

@@ -0,0 +1,245 @@
+<!--
+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
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+# FILE INFORMATION
+DEFGROUP: Template-Generic
+INGROUP: Template-Generic.Documentation
+REPO: https://git.mokoconsulting.tech/MokoConsulting/Template-Generic
+PATH: /SECURITY.md
+VERSION: 01.01.00
+BRIEF: Security vulnerability reporting and handling policy
+-->
+
+# Security Policy
+
+## Purpose and Scope
+
+This document defines the security vulnerability reporting, response, and disclosure policy for Template-Generic and all repositories governed by these standards. It establishes the authoritative process for responsible disclosure, assessment, remediation, and communication of security issues.
+
+## Supported Versions
+
+Security updates are provided for the following versions:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| [X.x.x] | :white_check_mark: |
+| < [X.0] | :x:                |
+
+Only the current major version receives security updates. Users should upgrade to the latest supported version to receive security patches.
+
+## Reporting a Vulnerability
+
+Report security vulnerabilities via MokoGIT issue (preferred):
+https://git.mokoconsulting.tech/MokoConsulting/Template-Generic/issues/new?template=security.yaml
+
+Or email: hello@mokoconsulting.tech
+
+### Where to Report
+
+**DO NOT** create public GitHub issues for security vulnerabilities.
+
+Report security vulnerabilities privately to:
+
+**Email**: `security@[DOMAIN]`
+
+**Subject Line**: `[SECURITY] Brief Description`
+
+### What to Include
+
+A complete vulnerability report should include:
+
+1. **Description**: Clear explanation of the vulnerability
+2. **Impact**: Potential security impact and severity assessment
+3. **Affected Versions**: Which versions are vulnerable
+4. **Reproduction Steps**: Detailed steps to reproduce the issue
+5. **Proof of Concept**: Code, configuration, or demonstration (if applicable)
+6. **Suggested Fix**: Proposed remediation (if known)
+7. **Disclosure Timeline**: Your expectations for public disclosure
+
+### Response Timeline
+
+* **Initial Response**: Within 3 business days
+* **Assessment Complete**: Within 7 business days
+* **Fix Timeline**: Depends on severity (see below)
+* **Disclosure**: Coordinated with reporter
+
+## Severity Classification
+
+Vulnerabilities are classified using the following severity levels:
+
+### Critical
+* Remote code execution
+* Authentication bypass
+* Data breach or exposure of sensitive information
+* **Fix Timeline**: 7 days
+
+### High
+* Privilege escalation
+* SQL injection or command injection
+* Cross-site scripting (XSS) with significant impact
+* **Fix Timeline**: 14 days
+
+### Medium
+* Information disclosure (limited scope)
+* Denial of service
+* Security misconfigurations with moderate impact
+* **Fix Timeline**: 30 days
+
+### Low
+* Security best practice violations
+* Minor information leaks
+* Issues requiring user interaction or complex preconditions
+* **Fix Timeline**: 60 days or next release
+
+## Remediation Process
+
+1. **Acknowledgment**: Security team confirms receipt and begins investigation
+2. **Assessment**: Vulnerability is validated, severity assigned, and impact analyzed
+3. **Development**: Security patch is developed and tested
+4. **Review**: Patch undergoes security review and validation
+5. **Release**: Fixed version is released with security advisory
+6. **Disclosure**: Public disclosure follows coordinated timeline
+
+## Security Advisories
+
+Security advisories are published via:
+
+* GitHub Security Advisories
+* Release notes and CHANGELOG.md
+* Security mailing list (when established)
+
+Advisories include:
+
+* CVE identifier (if applicable)
+* Severity rating
+* Affected versions
+* Fixed versions
+* Mitigation steps
+* Attribution (with reporter consent)
+
+## Security Best Practices
+
+For repositories adopting MokoCLI:
+
+### Required Controls
+
+* Enable GitHub security features (Dependabot, code scanning)
+* Implement branch protection on `main`
+* Require code review for all changes
+* Enforce signed commits (recommended)
+* Use secrets management (never commit credentials)
+* Maintain security documentation
+* Follow secure coding standards defined in `/docs/policy/`
+
+### CI/CD Security
+
+* Validate all inputs
+* Sanitize outputs
+* Use least privilege access
+* Pin dependencies with hash verification
+* Scan for vulnerabilities in dependencies
+* Audit third-party actions and tools
+
+#### Automated Security Scanning
+
+All repositories MUST implement:
+
+**CodeQL Analysis**:
+* Enabled for all supported languages (Python, JavaScript, TypeScript, Java, C/C++, C#, Go, Ruby)
+* Runs on: push to main, pull requests, weekly schedule
+* Query sets: `security-extended` and `security-and-quality`
+* Configuration: `.github/workflows/codeql-analysis.yml`
+
+**Dependabot Security Updates**:
+* Weekly scans for vulnerable dependencies
+* Automated pull requests for security patches
+* Configuration: `.github/dependabot.yml`
+
+**Secret Scanning**:
+* Enabled by default with push protection
+* Prevents accidental credential commits
+* Partner patterns enabled
+
+**Dependency Review**:
+* Required for all pull requests
+* Blocks introduction of known vulnerable dependencies
+* Automatic license compliance checking
+
+See [Security Scanning Policy](docs/policy/security-scanning.md) for detailed requirements.
+
+### Dependency Management
+
+* Keep dependencies up to date
+* Monitor security advisories for dependencies
+* Remove unused dependencies
+* Audit new dependencies before adoption
+* Document security-critical dependencies
+
+## Compliance and Governance
+
+This security policy is binding for all repositories governed by MokoCLI. Deviations require documented justification and approval from the Security Owner.
+
+Security policies are reviewed and updated at least annually or following significant security incidents.
+
+## Attribution and Recognition
+
+We acknowledge and appreciate responsible disclosure. With your permission, we will:
+
+* Credit you in security advisories
+* List you in CHANGELOG.md for the fix release
+* Recognize your contribution publicly (if desired)
+
+## Contact and Escalation
+
+* **Security Team**: security@[DOMAIN]
+* **Primary Contact**: [CONTACT_EMAIL]
+* **Escalation**: For urgent matters requiring immediate attention, contact the maintainer directly via GitHub
+
+## Out of Scope
+
+The following are explicitly out of scope:
+
+* Issues in third-party dependencies (report directly to maintainers)
+* Social engineering attacks
+* Physical security issues
+* Denial of service via resource exhaustion without amplification
+* Issues requiring physical access to systems
+* Theoretical vulnerabilities without proof of exploitability
+
+---
+
+## Metadata
+
+| Field        | Value                                           |
+| ------------ | ----------------------------------------------- |
+| Document     | Security Policy                                 |
+| Path         | /SECURITY.md                                    |
+| Repository   | https://git.mokoconsulting.tech/MokoConsulting/Template-Generic                                |
+| Owner        | [OWNER_NAME]                                    |
+| Scope        | Security vulnerability handling                 |
+| Applies To   | All repositories governed by MokoCLI            |
+| Status       | Active                                          |
+| Effective    | [YYYY-MM-DD]                                    |
+
+## Revision History
+
+| Date       | Change Description                                | Author          |
+| ---------- | ------------------------------------------------- | --------------- |
+| [YYYY-MM-DD] | Initial creation                                | [AUTHOR_NAME]   |

package/build/README.md

@@ -0,0 +1,7 @@
+# build/
+
+Generated build output lives here. Packaging is handled by the **mokocli-centric
+build system** — mokocli clones and runs the shared build tooling in CI, and this
+folder holds the generated artifacts (e.g. `build/packages/`) locally.
+
+Only this `README.md` is tracked; everything else under `build/` is git-ignored.

package/dist/README.md

@@ -0,0 +1,7 @@
+# dist/
+
+Distributable artifacts live here — the packaged installer(s) and release
+bundles emitted by the **mokocli-centric build system** (mokocli clones and runs
+the shared build tooling in CI). Generated output, not source.
+
+Only this `README.md` is tracked; everything else under `dist/` is git-ignored.

package/dist/index.js

@@ -0,0 +1,153 @@
+#!/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';
+let config;
+function clientFor(connection) {
+    return new ApiClient(getConnection(config, connection));
+}
+function formatResponse(res) {
+    if (res.status >= 400) {
+        return {
+            content: [{ type: 'text', text: `Error: HTTP ${res.status}: ${JSON.stringify(res.data, null, 2)}` }],
+        };
+    }
+    return {
+        content: [{ type: 'text', 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) {
+    const q = {};
+    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 = { ...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 = { 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 = {};
+    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', text: `Configured connections:\n${lines.join('\n')}` }],
+    };
+});
+// ── Start Server ────────────────────────────────────────────────────────
+async function main() {
+    config = await loadConfig();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal: ${err}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,35 @@
 {
-  "name": "@mokoconsulting/mokoabs-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@mokoconsulting/mokoabs-mcp",
+	"version": "4.0.2",
+	"description": "MCP server for Audiobookshelf API operations",
+	"type": "module",
+	"main": "dist/index.js",
+	"bin": {
+		"mokoabs-mcp": "dist/index.js"
+	},
+	"scripts": {
+		"build": "tsc",
+		"dev": "tsc --watch",
+		"start": "node dist/index.js",
+		"lint": "eslint source/",
+		"setup": "node scripts/setup.mjs",
+		"clean": "rm -rf dist/"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "1.12.1",
+		"zod": "^3.24.4"
+	},
+	"devDependencies": {
+		"@types/node": "^22.15.3",
+		"typescript": "^5.8.3"
+	},
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"license": "GPL-3.0-or-later",
+	"author": "Moko Consulting <hello@mokoconsulting.tech>",
+	"repository": {
+		"type": "git",
+		"url": "https://git.mokoconsulting.tech/MokoConsulting/mokoabs-mcp.git"
+	}
+}