soundiiz-mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project are documented here. The project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — Unreleased
+
+Initial release.
+
+### Added
+
+- MCP server for the [Soundiiz User API (BETA)](https://soundiiz.com/api/doc).
+- Vendored OpenAPI spec at `specs/soundiiz-openapi.json` (refresh with `npm run sync:spec`).
+- Bearer auth via `SOUNDIIZ_API_KEY`, with three key stores: env, on-disk file (mode 0600), or OS keychain (`keytar`).
+- Curated tools:
+  - User: `soundiiz_me`, `soundiiz_auth_status`, `soundiiz_auth_set`, `soundiiz_auth_clear`.
+  - Syncs (read): `soundiiz_syncs_list`, `soundiiz_sync_get`, `soundiiz_syncs_overview`, `soundiiz_syncs_due`.
+  - Syncs (write): `soundiiz_sync_trigger`, `soundiiz_sync_delete`.
+  - SmartLinks (read): `soundiiz_smartlinks_list`, `soundiiz_smartlink_get`, `soundiiz_smartlinks_overview`.
+  - SmartLinks (write): `soundiiz_smartlink_delete`.
+  - Local: `soundiiz_cache_invalidate`.
+- Auto-generated `soundiiz_read_<operationId>` and `soundiiz_write_<operationId>` tools from every operation in the spec.
+- Opt-in raw layer: `soundiiz_call`, `soundiiz_list_operations` (enable with `rawTools.enabled=true`).
+- Confirmation-token flow on `soundiiz_sync_trigger`, `soundiiz_sync_delete`, `soundiiz_smartlink_delete` — the first call returns a `confirmId`; the second call (same args + `confirmId`) executes. Tokens are bound to tool name + arg hash and expire after `writes.confirmTtlMs` (120s default).
+- Per-resource allowlists: `syncs.allowlist`, `smartlinks.allowlist`.
+- Token-bucket rate limiter (60 req/min default, configurable).
+- TTL cache with explicit invalidation per scope (`me`, `syncsList`, `syncDetail`, `smartlinksList`, `smartlinkDetail`).
+- Local harness scripts: `mcp:status`, `mcp:list-tools`, `mcp:call`, `smoke:live`, `sync:spec`, `generate:tools-docs`.
+- 25 Vitest cases covering spec parsing, tool naming, cache, confirmation tokens, allowlist, rate limiter, and a full mock-server-driven service E2E.
+
+### Configuration defaults
+
+- `writes.allow = true` — writes are enabled. Set to `false` (or `SOUNDIIZ_MCP_ALLOW_WRITES=false`) to lock the server to GET-only.
+- `writes.confirmDestructive = true` — destructive operations require the confirmation flow. Disable for trusted automation.
+- `auth.keyStore = env` — read API key from `SOUNDIIZ_API_KEY`. Switch to `file` or `keychain` for persistence.
+
+### Known gaps
+
+- The Soundiiz User API is currently in BETA (v1.0). The publisher explicitly warns that the surface may change. Track changes by re-running `npm run sync:spec`.
+- The Soundiiz "exports" endpoints announced in the May 2026 changelog are not in the current spec; the `src/services/exports/` placeholder is reserved.
+- This release has been validated against the mock server (25 passing tests) but **has not been live-validated against a real Soundiiz Creator-plan account by the maintainer**. If you're an early adopter, `npm run smoke:live` is the first thing to run, and please file an issue if any endpoint behaves differently than the spec suggests.
+- The Soundiiz User API requires a [Creator-plan](https://soundiiz.com/pricing) subscription. The webapp's internal API was evaluated but rejected as a backend ([Soundiiz ToS Article 15(f)](https://soundiiz.com/data/termsofservice/Terms_of_Service_SOUNDIIZ20211123EN.pdf) prohibits programmatic use outside the documented API).
+
+[0.1.0]: https://github.com/BASIC-BIT/soundiiz-mcp/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BASIC-BIT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+<p align="center">
+  <img src="assets/logo.svg" alt="Soundiiz MCP logo" width="112" height="112" />
+</p>
+
+# Soundiiz MCP
+
+An MCP server for [Soundiiz](https://soundiiz.com). Lets your AI assistant inspect your sync jobs and SmartLinks across streaming services, trigger syncs, and clean up stale links.
+
+Built for [Claude Desktop](https://claude.ai/download), [OpenCode](https://opencode.ai/), and any other [Model Context Protocol](https://modelcontextprotocol.io/) client.
+
+Your API key stays on your machine. Curated tools on top of the Soundiiz User API so agents don't have to paginate through raw endpoints.
+
+This project is unofficial and is not affiliated with Soundiiz.
+
+## Status
+
+`v0.1.0` — early. The Soundiiz User API is itself in BETA, so the surface this server wraps may shift. The 25-test mock suite exercises every curated tool, but the maintainer hasn't run it against a real Creator-plan account in the wild — if you're an early adopter, please try `npm run smoke:live` and file an issue if anything breaks.
+
+## What You Can Ask
+
+- Show me all my Soundiiz syncs and which ones are due to run next.
+- Summarize sync status: how many succeeded, how many failed, which platforms are involved.
+- Which syncs failed recently, and why?
+- Trigger sync #42 to run now.
+- List all my published SmartLinks and their shortcodes.
+- Show details for SmartLink "abc123": fallback URL, per-platform links, status.
+- Delete this stale draft SmartLink.
+
+## Writes and confirmations
+
+The Soundiiz API exposes three write operations: delete sync, delete smartlink, and trigger sync. All three are callable, but each goes through a two-step confirm flow:
+
+1. The first call returns a `confirmId` and a recap of what would happen.
+2. Re-call the same tool with the same args plus that `confirmId` to execute. The token is single-use and bound to the tool name + arg hash.
+
+Knobs:
+
+- `writes.confirmDestructive = false` — skip the confirm step (one-call writes).
+- `writes.allow = false` (or `SOUNDIIZ_MCP_ALLOW_WRITES=false`) — disable writes entirely.
+- `syncs.allowlist` / `smartlinks.allowlist` — restrict writes to specific IDs.
+
+## Auth and storage
+
+Your API key is read from `SOUNDIIZ_API_KEY`, a local file, or the OS keychain (via `keytar`). It never leaves your machine except in `Authorization: Bearer` headers to `api.soundiiz.com`.
+
+Logs go to stderr so stdout stays reserved for MCP protocol messages. Live smoke checks and LLM evals are opt-in and read gitignored fixture files.
+
+## Quick Start
+
+Requirements:
+
+- Node.js 22 or newer.
+- A Soundiiz account on the **Creator plan**. The Soundiiz User API is currently in BETA and gated to Creator subscribers.
+- An MCP client such as Claude Desktop, OpenCode, or another MCP-compatible host.
+
+Generate your personal API key at [soundiiz.com/webapp/settings/api](https://soundiiz.com/webapp/settings/api).
+
+Install from source:
+
+```bash
+git clone https://github.com/BASIC-BIT/soundiiz-mcp.git
+cd soundiiz-mcp
+npm install
+npm run build
+```
+
+## MCP Client Config
+
+Use the built server for day-to-day use. Replace the path with your local checkout.
+
+```json
+{
+  "mcpServers": {
+    "soundiiz": {
+      "command": "node",
+      "args": ["<ABS_PATH_TO_REPO>/dist/bin/cli.js"],
+      "env": {
+        "SOUNDIIZ_API_KEY": "<YOUR_KEY>",
+        "SOUNDIIZ_MCP_USER_AGENT": "your-name (email@example.com)"
+      }
+    }
+  }
+}
+```
+
+For active development, point at the TypeScript entrypoint instead:
+
+```json
+{
+  "mcpServers": {
+    "soundiiz-dev": {
+      "command": "npx",
+      "args": ["tsx", "<ABS_PATH_TO_REPO>/src/index.ts"],
+      "env": {
+        "SOUNDIIZ_API_KEY": "<YOUR_KEY>",
+        "SOUNDIIZ_MCP_USER_AGENT": "your-name (email@example.com)"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+Defaults live in `src/config/defaults.json`. To override them, create a JSON config file and point to it with `SOUNDIIZ_MCP_CONFIG_FILE`.
+
+Example `soundiiz-mcp.config.json`:
+
+```json
+{
+  "api": {
+    "baseUrl": "https://api.soundiiz.com",
+    "userAgent": "your-name (email@example.com)"
+  },
+  "auth": { "keyStore": "env" },
+  "writes": { "allow": false, "confirmDestructive": true, "confirmTtlMs": 120000 },
+  "syncs": { "allowlist": [] },
+  "smartlinks": { "allowlist": [] },
+  "rateLimit": { "perMinute": 60 },
+  "cache": { "enabled": true }
+}
+```
+
+Environment variables override the config file when set.
+
+Common environment variables:
+
+- `SOUNDIIZ_MCP_CONFIG_FILE`: path to a JSON config file.
+- `SOUNDIIZ_API_KEY`: your personal Soundiiz User API key (Bearer token).
+- `SOUNDIIZ_MCP_USER_AGENT`: descriptive user agent. Include contact info when possible.
+- `SOUNDIIZ_MCP_API_BASE`: override the API base URL. Defaults to `https://api.soundiiz.com`.
+- `SOUNDIIZ_MCP_LOG_LEVEL`: `debug`, `info`, `warn`, or `error`.
+- `SOUNDIIZ_MCP_KEY_STORE`: `env`, `file`, or `keychain`.
+- `SOUNDIIZ_MCP_KEY_FILE`: file path when `SOUNDIIZ_MCP_KEY_STORE=file`.
+- `SOUNDIIZ_MCP_ALLOW_WRITES`: enable non-GET operations.
+- `SOUNDIIZ_MCP_CONFIRM_DESTRUCTIVE`: require a confirmation token for DELETE / trigger.
+- `SOUNDIIZ_MCP_SYNC_ALLOWLIST`: comma-separated list of sync IDs permitted for write actions.
+- `SOUNDIIZ_MCP_SMARTLINK_ALLOWLIST`: comma-separated list of smartlink IDs permitted for write actions.
+- `SOUNDIIZ_MCP_ENABLE_RAW_CALL`: enable the raw `soundiiz_call` tool. Disabled by default.
+- `SOUNDIIZ_MCP_DISABLE_GENERATED_READ_TOOLS`: disable auto-generated read tools.
+- `SOUNDIIZ_MCP_DISABLE_GENERATED_WRITE_TOOLS`: disable auto-generated write tools.
+
+## Tool Surface
+
+Soundiiz MCP exposes three layers (mirroring the vrchat-mcp pattern):
+
+- **Curated tools** for common agent workflows: `soundiiz_me`, `soundiiz_syncs_list`, `soundiiz_syncs_overview`, `soundiiz_syncs_due`, `soundiiz_sync_get`, `soundiiz_smartlinks_list`, `soundiiz_smartlinks_overview`, `soundiiz_smartlink_get`, `soundiiz_sync_trigger`, `soundiiz_sync_delete`, `soundiiz_smartlink_delete`.
+- **Auto-generated read tools** named `soundiiz_read_<operationId>` for GET operations from the Soundiiz OpenAPI spec.
+- **Auto-generated write tools** named `soundiiz_write_<operationId>` for non-GET operations.
+
+Local-only tools include:
+
+- `soundiiz_auth_status` — check whether a key is loaded and valid (calls `/v1/me`).
+- `soundiiz_cache_invalidate` for MCP-local cache control.
+
+The generated catalog lives in `docs/tools.md`. The shorter usage guide lives in `docs/tools-guide.md`.
+
+## Optional Swagger UI
+
+If you want a Swagger UI proxy for the MCP tools, use `mcpo`:
+
+```bash
+uvx mcpo --port 8000 --api-key "top-secret" -- node <ABS_PATH_TO_REPO>/dist/bin/cli.js
+```
+
+Then open `http://localhost:8000/docs`.
+
+## Development
+
+Useful scripts:
+
+- `npm run dev` — run `src/index.ts` through `tsx`.
+- `npm run build` — type-check and emit to `dist/`.
+- `npm run start` — run the built server from `dist/`.
+- `npm run lint`, `npm run typecheck`, `npm test` — quality gates.
+- `npm run check` — lint + typecheck + test.
+- `npm run mcp:status` — check whether the configured key authenticates.
+- `npm run mcp:list-tools`, `npm run mcp:call` — local harness.
+- `npm run smoke:live` — opt-in live smoke matrix against the built server.
+- `npm run sync:spec` — refetch the Soundiiz OpenAPI spec from `https://soundiiz.com/api/doc`.
+- `npm run generate:schemas` — regenerate Zod schemas from `specs/soundiiz-openapi.json`.
+- `npm run generate:tools-docs` — regenerate `docs/tools.md`.
+
+Project layout (planned):
+
+- `src/index.ts` — server bootstrap.
+- `src/config/` — defaults and config loader.
+- `src/auth/` — API key loading from env / file / keychain.
+- `src/core/` — HTTP client, spec parser, generated tool registries.
+- `src/services/` — domain services for syncs, smartlinks, user, cache.
+- `src/schemas/` — shared Zod schemas for tool inputs and outputs.
+- `src/generated/` — Zod schemas generated from the Soundiiz OpenAPI spec.
+- `src/tools/` — MCP tool registration (curated + auto-generated + raw + auth + cache).
+- `src/infra/` — logging.
+- `src/utils/` — small helpers.
+- `specs/soundiiz-openapi.json` — vendored copy of the Soundiiz User API spec.
+- `docs/` — architecture, tool inventory, evals, design notes, launch plan.
+
+## Testing And Evals
+
+Local checks:
+
+```bash
+npm run check
+```
+
+Live smoke checks are opt-in and require a Creator-plan API key:
+
+```bash
+npm run build
+SOUNDIIZ_API_KEY=... npm run smoke:live
+```
+
+Live E2E and LLM evals use gitignored local fixture files. See `docs/evals.md`.
+
+## Documentation
+
+- `docs/tools.md` — generated tool catalog with schemas.
+- `docs/tools-guide.md` — short human guide for the tool surface.
+- `docs/architecture.md` — codebase overview and data flow.
+- `docs/curated-tools.md` — curated tool charter and risk tiers.
+- `docs/evals.md` — smoke, LLM, and manual agent eval workflow.
+- `docs/public-launch-plan.md` — release awareness, registry, and launch-channel plan.
+- `docs/design-notes.md` — archived design notes and future-facing ideas.
+
+## License
+
+MIT.

package/assets/logo.svg

@@ -0,0 +1,42 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" role="img" aria-labelledby="title desc">
+  <title id="title">Soundiiz MCP logo</title>
+  <desc id="desc">A central hub node connected by lines to four satellite nodes at compass points, on a dark rounded square.</desc>
+  <defs>
+    <linearGradient id="hub" x1="0" y1="0" x2="1" y2="1">
+    <stop offset="0" stop-color="#f472b6" />
+    <stop offset="0.55" stop-color="#a855f7" />
+    <stop offset="1" stop-color="#6366f1" />
+  </linearGradient>
+  <linearGradient id="line" x1="0" y1="0" x2="1" y2="1">
+    <stop offset="0" stop-color="#fbcfe8" stop-opacity="0.85" />
+    <stop offset="1" stop-color="#c7d2fe" stop-opacity="0.85" />
+  </linearGradient>
+  <radialGradient id="glow" cx="0.5" cy="0.5" r="0.5">
+    <stop offset="0" stop-color="#a855f7" stop-opacity="0.55" />
+    <stop offset="1" stop-color="#a855f7" stop-opacity="0" />
+  </radialGradient>
+  </defs>
+  <rect width="256" height="256" rx="56" fill="#0b0721" />
+  <circle cx="128" cy="128" r="78" fill="url(#glow)" />
+  <g stroke="url(#line)" stroke-width="9" stroke-linecap="round" fill="none">
+    <line x1="128" y1="128" x2="128" y2="32" />
+    <line x1="128" y1="128" x2="224" y2="128" />
+    <line x1="128" y1="128" x2="128" y2="224" />
+    <line x1="128" y1="128" x2="32" y2="128" />
+  </g>
+  <g fill="#f8fafc">
+    <circle cx="128" cy="32" r="16" />
+    <circle cx="224" cy="128" r="16" />
+    <circle cx="128" cy="224" r="16" />
+    <circle cx="32" cy="128" r="16" />
+  </g>
+  <g fill="#a855f7">
+    <circle cx="128" cy="32" r="6" />
+    <circle cx="224" cy="128" r="6" />
+    <circle cx="128" cy="224" r="6" />
+    <circle cx="32" cy="128" r="6" />
+  </g>
+  <circle cx="128" cy="128" r="34" fill="url(#hub)" />
+  <circle cx="128" cy="128" r="34" fill="none" stroke="#f8fafc" stroke-width="3" />
+  <circle cx="128" cy="128" r="10" fill="#f8fafc" />
+</svg>

package/dist/bin/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// CLI entry: starts the stdio MCP server.
+import '../src/index.js';
+//# sourceMappingURL=cli.js.map

package/dist/bin/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":";AACA,0CAA0C;AAC1C,OAAO,iBAAiB,CAAC"}

package/dist/package.json

@@ -0,0 +1,90 @@
+{
+    "name": "soundiiz-mcp",
+    "version": "0.1.0",
+    "mcpName": "io.github.basic-bit/soundiiz-mcp",
+    "description": "MCP server for Soundiiz syncs and SmartLinks. Curated tools, auto-generated read/write layer from the OpenAPI spec, and confirmation-gated destructive operations.",
+    "type": "module",
+    "main": "dist/src/index.js",
+    "bin": {
+        "soundiiz-mcp": "dist/bin/cli.js"
+    },
+    "files": [
+        "dist",
+        "specs/soundiiz-openapi.json",
+        "assets/logo.svg",
+        "docs/architecture.md",
+        "docs/curated-tools.md",
+        "docs/design-notes.md",
+        "docs/evals.md",
+        "docs/tools-guide.md",
+        "CHANGELOG.md",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.json",
+        "typecheck": "tsc -p tsconfig.json --noEmit",
+        "dev": "tsx src/index.ts",
+        "lint": "eslint . --ext .ts,.tsx,.mts --max-warnings=0",
+        "lint:fix": "npm run lint -- --fix",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "test:coverage": "vitest run --coverage",
+        "smoke:live": "tsx scripts/live-smoke.ts",
+        "check": "npm run lint && npm run typecheck && npm test",
+        "mcp:status": "tsx scripts/mcp-client.ts status",
+        "mcp:list-tools": "tsx scripts/mcp-client.ts list-tools",
+        "mcp:call": "tsx scripts/mcp-client.ts call",
+        "sync:spec": "tsx scripts/sync-spec.ts",
+        "generate:tools-docs": "tsx scripts/generate-tools-docs.ts",
+        "build:assets": "tsx scripts/build-assets.ts",
+        "mcpo": "uvx mcpo --port 8000 --api-key \"top-secret\" -- npx tsx src/index.ts",
+        "start": "node dist/bin/cli.js"
+    },
+    "engines": {
+        "node": ">=22"
+    },
+    "keywords": [
+        "soundiiz",
+        "mcp",
+        "modelcontextprotocol",
+        "model-context-protocol",
+        "claude",
+        "opencode",
+        "music",
+        "playlist",
+        "smartlinks",
+        "sync"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/BASIC-BIT/soundiiz-mcp.git"
+    },
+    "bugs": {
+        "url": "https://github.com/BASIC-BIT/soundiiz-mcp/issues"
+    },
+    "homepage": "https://github.com/BASIC-BIT/soundiiz-mcp#readme",
+    "license": "MIT",
+    "devDependencies": {
+        "@eslint/js": "^9.18.0",
+        "@types/node": "^22.10.5",
+        "@typescript-eslint/eslint-plugin": "^8.20.0",
+        "@typescript-eslint/parser": "^8.20.0",
+        "@vitest/coverage-v8": "^3.0.0",
+        "eslint": "^9.18.0",
+        "eslint-config-prettier": "^10.0.1",
+        "globals": "^15.14.0",
+        "prettier": "^3.4.2",
+        "tsx": "^4.19.2",
+        "typescript": "^5.7.3",
+        "vitest": "^3.0.0"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.0.4",
+        "keytar": "^7.9.0",
+        "undici": "^7.2.0",
+        "zod": "^3.24.1"
+    }
+}

package/dist/src/auth/index.js

@@ -0,0 +1,42 @@
+import { getKeyStore } from './keyStore.js';
+import { logger } from '../infra/logger.js';
+class AuthManager {
+    store;
+    memKey = null;
+    constructor() {
+        this.store = getKeyStore();
+    }
+    async init() {
+        try {
+            this.memKey = await this.store.load();
+            if (this.memKey) {
+                logger.debug('Loaded Soundiiz API key', { length: this.memKey.length });
+            }
+            else {
+                logger.warn('No Soundiiz API key found. Set SOUNDIIZ_API_KEY (env), or use file/keychain key store.');
+            }
+        }
+        catch (err) {
+            logger.warn('Failed to initialize key store', { message: err.message });
+        }
+    }
+    hasKey() {
+        return Boolean(this.memKey);
+    }
+    getKey() {
+        return this.memKey;
+    }
+    async setKey(key) {
+        const trimmed = key.trim();
+        if (!trimmed)
+            throw new Error('Empty API key');
+        this.memKey = trimmed;
+        await this.store.save(trimmed);
+    }
+    async clear() {
+        this.memKey = null;
+        await this.store.clear();
+    }
+}
+export const authManager = new AuthManager();
+//# sourceMappingURL=index.js.map

package/dist/src/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAiB,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,MAAM,WAAW;IACP,KAAK,CAAW;IAChB,MAAM,GAAkB,IAAI,CAAC;IAErC;QACE,IAAI,CAAC,KAAK,GAAG,WAAW,EAAE,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,IAAI;QACR,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YACtC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChB,MAAM,CAAC,KAAK,CAAC,yBAAyB,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;YAC1E,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,IAAI,CACT,wFAAwF,CACzF,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,gCAAgC,EAAE,EAAE,OAAO,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACrF,CAAC;IACH,CAAC;IAED,MAAM;QACJ,OAAO,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QAC3B,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;QAC/C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC;QACtB,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC"}

package/dist/src/auth/keyStore.js

@@ -0,0 +1,104 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { getConfig } from '../config/index.js';
+import { logger } from '../infra/logger.js';
+class EnvStore {
+    load() {
+        const v = process.env.SOUNDIIZ_API_KEY?.trim();
+        return Promise.resolve(v ? v : null);
+    }
+    save() {
+        logger.warn('keyStore=env: save() is a no-op; set SOUNDIIZ_API_KEY in your environment.');
+        return Promise.resolve();
+    }
+    clear() {
+        logger.warn('keyStore=env: clear() is a no-op; unset SOUNDIIZ_API_KEY in your environment.');
+        return Promise.resolve();
+    }
+}
+class FileStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async load() {
+        try {
+            const content = await fs.readFile(this.filePath, 'utf8');
+            const trimmed = content.trim();
+            return trimmed || null;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return null;
+            logger.warn('Failed to load key file', { message: err.message });
+            return null;
+        }
+    }
+    async save(key) {
+        await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+        await fs.writeFile(this.filePath, key, { encoding: 'utf8', mode: 0o600 });
+        if (process.platform !== 'win32') {
+            await fs.chmod(this.filePath, 0o600);
+        }
+    }
+    async clear() {
+        try {
+            await fs.unlink(this.filePath);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT') {
+                logger.warn('Failed to delete key file', { message: err.message });
+            }
+        }
+    }
+}
+class KeychainStore {
+    service = 'soundiiz-mcp';
+    account = 'default';
+    keytar = null;
+    async ensureKeytar() {
+        if (this.keytar)
+            return this.keytar;
+        try {
+            const mod = await import('keytar');
+            this.keytar = (mod.default ?? mod);
+            return this.keytar;
+        }
+        catch (err) {
+            logger.warn('keytar not available; OS keychain disabled', {
+                message: err.message,
+            });
+            return null;
+        }
+    }
+    async load() {
+        const keytar = await this.ensureKeytar();
+        if (!keytar)
+            return null;
+        const v = (await keytar.getPassword(this.service, this.account))?.trim();
+        return v ? v : null;
+    }
+    async save(key) {
+        const keytar = await this.ensureKeytar();
+        if (!keytar) {
+            throw new Error('keytar is not available; cannot save to OS keychain');
+        }
+        await keytar.setPassword(this.service, this.account, key);
+    }
+    async clear() {
+        const keytar = await this.ensureKeytar();
+        if (!keytar)
+            return;
+        await keytar.deletePassword(this.service, this.account);
+    }
+}
+export function getKeyStore() {
+    const config = getConfig();
+    const mode = config.auth.keyStore;
+    if (mode === 'file')
+        return new FileStore(path.resolve(config.auth.keyFile));
+    if (mode === 'keychain')
+        return new KeychainStore();
+    return new EnvStore();
+}
+//# sourceMappingURL=keyStore.js.map

package/dist/src/auth/keyStore.js.map

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

package/dist/src/config/defaults.json

@@ -0,0 +1,45 @@
+{
+    "api": {
+        "baseUrl": "https://api.soundiiz.com",
+        "userAgent": "soundiiz-mcp/{version} (+https://github.com/BASIC-BIT/soundiiz-mcp)",
+        "timeoutMs": 15000
+    },
+    "auth": {
+        "keyStore": "env",
+        "keyFile": "~/.soundiiz-mcp-key"
+    },
+    "writes": {
+        "allow": true,
+        "confirmDestructive": true,
+        "confirmTtlMs": 120000
+    },
+    "syncs": {
+        "allowlist": []
+    },
+    "smartlinks": {
+        "allowlist": []
+    },
+    "rateLimit": {
+        "perMinute": 60
+    },
+    "cache": {
+        "enabled": true,
+        "ttls": {
+            "me": 3600,
+            "syncsList": 60,
+            "syncDetail": 30,
+            "smartlinksList": 300,
+            "smartlinkDetail": 300
+        }
+    },
+    "rawTools": {
+        "enabled": false
+    },
+    "generatedTools": {
+        "read": true,
+        "write": true
+    },
+    "logging": {
+        "level": "info"
+    }
+}