audial-mcp 0.1.0__tar.gz

audial_mcp-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+dist/
+build/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.superpowers/

audial_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Audial
+
+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.

audial_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.5
+Name: audial-mcp
+Version: 0.1.0
+Summary: MCP server for Audial: stem splitting, mastering, MIDI, music generation, resynthesis and vocal synthesis from any MCP client.
+Project-URL: Homepage, https://audialmusic.ai
+Project-URL: Documentation, https://audialmusic.ai/resources/api-reference
+Project-URL: Repository, https://github.com/AudialAI/audial-mcp
+Author-email: Audial <contact@audialmusic.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audial,audio,mcp,model-context-protocol,music,stems
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4
+Requires-Dist: audial-sdk>=1.2.3
+Requires-Dist: mcp<3,>=2.2
+Requires-Dist: pydantic>=2
+Requires-Dist: typing-extensions>=4
+Description-Content-Type: text/markdown
+
+# audial-mcp
+
+Run Audial's hosted audio tools from any MCP client: split stems, analyze and segment audio,
+master tracks, build sample packs, convert audio to MIDI, generate music, turn a one-shot into
+an editable Audial Synth preset, and sing lyrics in a reference voice.
+
+mcp-name: io.github.AudialAI/audial-mcp
+
+## Install
+
+You need an Audial account (user id + API key from https://audialmusic.ai) and
+[`uv`](https://docs.astral.sh/uv/getting-started/installation/).
+
+**Claude Code**
+
+```bash
+claude mcp add audial \
+  -e AUDIAL_USER_ID=your-user-id -e AUDIAL_API_KEY=your-api-key -e AUDIAL_RESULTS_DIR=~/Audial \
+  -- uvx audial-mcp
+```
+
+**Claude Desktop / Cursor / any client with a JSON config**
+
+```json
+{
+  "mcpServers": {
+    "audial": {
+      "command": "uvx",
+      "args": ["audial-mcp"],
+      "env": {
+        "AUDIAL_USER_ID": "your-user-id",
+        "AUDIAL_API_KEY": "your-api-key",
+        "AUDIAL_RESULTS_DIR": "~/Audial"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `stem_split` | Split a track into vocals, drums, bass, other (optionally retime / rekey) |
+| `analyze` | BPM, key and other characteristics |
+| `segment` | Sections and component analysis |
+| `master` | Mastering, optionally matched to a reference |
+| `generate_samples` | Sample pack from a track |
+| `generate_midi` | Audio to MIDI |
+| `generate_music` | Text to music, covers, remixes, extraction, completion with the Audial music model |
+| `sound2vital` | One-shot → editable Audial Synth (Vital) preset |
+| `text2vox` | Lyrics + reference voice → sung vocal and MIDI |
+| `list_results` | Browse previous results in your results folder |
+
+## What leaves your machine
+
+Audio and text you pass to a tool are uploaded to Audial's API (https://api.audialmusic.ai)
+over HTTPS and processed on Audial's servers; results are downloaded into
+`AUDIAL_RESULTS_DIR` (default `~/Audial`). Nothing else is sent.
+
+Two other files are *read* if they exist, because the Audial SDK looks for them:
+`~/.audial/.audial_config.json` and a `.env` in the directory the server was started from.
+Credentials from your MCP client's config always win: `audial-mcp` snapshots its environment
+before the SDK loads either file, so neither can redirect your credentials or the API host.
+
+Some tools require an active Audial subscription; the tool tells you when that is the case.
+
+## Configuration
+
+| Variable | Required | Default |
+|---|---|---|
+| `AUDIAL_USER_ID` | yes | |
+| `AUDIAL_API_KEY` | yes | |
+| `AUDIAL_RESULTS_DIR` | no | `~/Audial` |
+| `AUDIAL_JOB_TIMEOUT_S` | no | `900` |
+| `AUDIAL_API_BASE_URL` | no | production API |
+
+## License
+
+MIT. Source: https://github.com/AudialAI/audial-mcp

audial_mcp-0.1.0/README.md

@@ -0,0 +1,80 @@
+# audial-mcp
+
+Run Audial's hosted audio tools from any MCP client: split stems, analyze and segment audio,
+master tracks, build sample packs, convert audio to MIDI, generate music, turn a one-shot into
+an editable Audial Synth preset, and sing lyrics in a reference voice.
+
+mcp-name: io.github.AudialAI/audial-mcp
+
+## Install
+
+You need an Audial account (user id + API key from https://audialmusic.ai) and
+[`uv`](https://docs.astral.sh/uv/getting-started/installation/).
+
+**Claude Code**
+
+```bash
+claude mcp add audial \
+  -e AUDIAL_USER_ID=your-user-id -e AUDIAL_API_KEY=your-api-key -e AUDIAL_RESULTS_DIR=~/Audial \
+  -- uvx audial-mcp
+```
+
+**Claude Desktop / Cursor / any client with a JSON config**
+
+```json
+{
+  "mcpServers": {
+    "audial": {
+      "command": "uvx",
+      "args": ["audial-mcp"],
+      "env": {
+        "AUDIAL_USER_ID": "your-user-id",
+        "AUDIAL_API_KEY": "your-api-key",
+        "AUDIAL_RESULTS_DIR": "~/Audial"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `stem_split` | Split a track into vocals, drums, bass, other (optionally retime / rekey) |
+| `analyze` | BPM, key and other characteristics |
+| `segment` | Sections and component analysis |
+| `master` | Mastering, optionally matched to a reference |
+| `generate_samples` | Sample pack from a track |
+| `generate_midi` | Audio to MIDI |
+| `generate_music` | Text to music, covers, remixes, extraction, completion with the Audial music model |
+| `sound2vital` | One-shot → editable Audial Synth (Vital) preset |
+| `text2vox` | Lyrics + reference voice → sung vocal and MIDI |
+| `list_results` | Browse previous results in your results folder |
+
+## What leaves your machine
+
+Audio and text you pass to a tool are uploaded to Audial's API (https://api.audialmusic.ai)
+over HTTPS and processed on Audial's servers; results are downloaded into
+`AUDIAL_RESULTS_DIR` (default `~/Audial`). Nothing else is sent.
+
+Two other files are *read* if they exist, because the Audial SDK looks for them:
+`~/.audial/.audial_config.json` and a `.env` in the directory the server was started from.
+Credentials from your MCP client's config always win: `audial-mcp` snapshots its environment
+before the SDK loads either file, so neither can redirect your credentials or the API host.
+
+Some tools require an active Audial subscription; the tool tells you when that is the case.
+
+## Configuration
+
+| Variable | Required | Default |
+|---|---|---|
+| `AUDIAL_USER_ID` | yes | |
+| `AUDIAL_API_KEY` | yes | |
+| `AUDIAL_RESULTS_DIR` | no | `~/Audial` |
+| `AUDIAL_JOB_TIMEOUT_S` | no | `900` |
+| `AUDIAL_API_BASE_URL` | no | production API |
+
+## License
+
+MIT. Source: https://github.com/AudialAI/audial-mcp

audial_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "audial-mcp"
+version = "0.1.0"
+description = "MCP server for Audial: stem splitting, mastering, MIDI, music generation, resynthesis and vocal synthesis from any MCP client."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Audial", email = "contact@audialmusic.ai" }]
+keywords = ["mcp", "audio", "music", "stems", "audial", "model-context-protocol"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Multimedia :: Sound/Audio",
+]
+dependencies = [
+  "mcp>=2.2,<3",
+  "audial-sdk>=1.2.3",
+  "anyio>=4",
+  "pydantic>=2",
+  "typing_extensions>=4",
+]
+
+[project.urls]
+Homepage = "https://audialmusic.ai"
+Documentation = "https://audialmusic.ai/resources/api-reference"
+Repository = "https://github.com/AudialAI/audial-mcp"
+
+[project.scripts]
+audial-mcp = "audial_mcp.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "anyio>=4", "ruff>=0.6", "build>=1.2"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/audial_mcp"]
+
+# The sdist ships the package and its metadata, not the project's working notes: docs/ is
+# design and checklist material, .github/ is CI, .superpowers/ is planning scratch.
+[tool.hatch.build.targets.sdist]
+exclude = ["docs", ".github", ".superpowers"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+# `ruff format` rewrites Python code blocks inside Markdown, which reflows the illustrative
+# snippets in the design and plan documents. Those are prose, not code that runs.
+extend-exclude = ["docs"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

audial_mcp-0.1.0/server.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.AudialAI/audial-mcp",
+  "description": "Stem splitting, analysis, mastering, sample packs, audio-to-MIDI, music generation, resynthesis and vocal synthesis with Audial's hosted engines.",
+  "version": "0.1.0",
+  "repository": { "url": "https://github.com/AudialAI/audial-mcp", "source": "github" },
+  "websiteUrl": "https://audialmusic.ai/resources/api-reference",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "audial-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": { "type": "stdio" },
+      "environmentVariables": [
+        { "name": "AUDIAL_USER_ID", "description": "Audial user id", "isRequired": true, "isSecret": false },
+        { "name": "AUDIAL_API_KEY", "description": "Audial API key", "isRequired": true, "isSecret": true },
+        { "name": "AUDIAL_RESULTS_DIR", "description": "Folder results are written to", "default": "~/Audial" },
+        { "name": "AUDIAL_JOB_TIMEOUT_S", "description": "Seconds to wait for a job before giving up", "default": "900" },
+        { "name": "AUDIAL_API_BASE_URL", "description": "Override the Audial API base URL (advanced)", "isRequired": false, "isSecret": false }
+      ]
+    }
+  ]
+}

audial_mcp-0.1.0/src/audial_mcp/__init__.py

@@ -0,0 +1,15 @@
+"""audial-mcp: a local MCP server for the Audial audio tools."""
+
+import os
+
+__version__ = "0.1.0"
+
+# The environment as the client handed it to us, snapshotted before anything else runs.
+#
+# `import audial` calls `dotenv.load_dotenv()`, which copies a `.env` in the *process's working
+# directory* into `os.environ`. The working directory of an MCP server is the client's, not the
+# user's project, and a `.env` that happens to sit there would silently redirect credentials and
+# the API host. This package is imported before `audial_mcp.server` executes its `import audial`
+# (importing a submodule initialises its package first), so this snapshot predates that call.
+# `config.load_settings()` reads from here rather than from the live `os.environ`.
+BOOT_ENV: dict[str, str] = dict(os.environ)

audial_mcp-0.1.0/src/audial_mcp/__main__.py

@@ -0,0 +1,4 @@
+from audial_mcp.server import main
+
+if __name__ == "__main__":
+    main()

audial_mcp-0.1.0/src/audial_mcp/config.py

@@ -0,0 +1,85 @@
+"""Environment-driven settings for the audial MCP server."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from audial_mcp import BOOT_ENV
+
+DEFAULT_RESULTS_DIR = "~/Audial"
+DEFAULT_JOB_TIMEOUT_S = 900
+
+CREDENTIALS_HELP = (
+    "AUDIAL_USER_ID and AUDIAL_API_KEY are not set. Add both to the `audial` server's env in "
+    "your MCP client config (for Claude Code: `claude mcp add audial -e AUDIAL_USER_ID=... "
+    "-e AUDIAL_API_KEY=... -- uvx audial-mcp`). Get them from your dashboard at "
+    "https://audialmusic.ai, then restart the client."
+)
+
+
+class ConfigError(Exception):
+    """Raised when the environment cannot be turned into usable settings."""
+
+
+@dataclass(frozen=True)
+class Settings:
+    user_id: str | None
+    api_key: str | None
+    results_dir: Path
+    api_base_url: str | None
+    job_timeout_s: int
+
+    def require_credentials(self) -> None:
+        if not self.user_id or not self.api_key:
+            raise ConfigError(CREDENTIALS_HELP)
+
+
+def _always_parseable(env: Mapping[str, str]) -> dict[str, Any]:
+    """The settings fields that cannot fail to parse: credentials, base URL, results dir."""
+    results_dir = Path(
+        os.path.expandvars(env.get("AUDIAL_RESULTS_DIR") or DEFAULT_RESULTS_DIR)
+    ).expanduser()
+    return {
+        "user_id": (env.get("AUDIAL_USER_ID") or "").strip() or None,
+        "api_key": (env.get("AUDIAL_API_KEY") or "").strip() or None,
+        "results_dir": results_dir,
+        "api_base_url": (env.get("AUDIAL_API_BASE_URL") or "").strip() or None,
+    }
+
+
+def load_settings(env: Mapping[str, str] | None = None) -> Settings:
+    """Read settings from `env`, defaulting to the environment as it was at import time.
+
+    The default is `audial_mcp.BOOT_ENV`, not the live `os.environ`: the Audial SDK calls
+    `dotenv.load_dotenv()` when it is imported, so a `.env` file in whatever directory the MCP
+    client happened to launch the server from would otherwise be able to override the
+    credentials and API host the client configured.
+    """
+    env = BOOT_ENV if env is None else env
+    raw_timeout = env.get("AUDIAL_JOB_TIMEOUT_S", str(DEFAULT_JOB_TIMEOUT_S))
+    try:
+        timeout = int(raw_timeout)
+        if timeout <= 0:
+            raise ValueError
+    except ValueError:
+        raise ConfigError(
+            "AUDIAL_JOB_TIMEOUT_S must be a positive integer number of seconds, "
+            f"got {raw_timeout!r}"
+        ) from None
+
+    return Settings(**_always_parseable(env), job_timeout_s=timeout)
+
+
+def fallback_settings(env: Mapping[str, str] | None = None) -> Settings:
+    """Settings to run with when `load_settings` raised: what parsed, defaults for what did not.
+
+    The server keeps starting on a bad `AUDIAL_JOB_TIMEOUT_S` so that it can list its tools and
+    return the configuration error as a readable message. A server that dies at import shows up
+    in clients as an opaque "failed to start".
+    """
+    env = BOOT_ENV if env is None else env
+    return Settings(**_always_parseable(env), job_timeout_s=DEFAULT_JOB_TIMEOUT_S)

audial_mcp-0.1.0/src/audial_mcp/errors.py

@@ -0,0 +1,34 @@
+"""Turn every failure into a ToolError the model can read and act on."""
+
+from __future__ import annotations
+
+import logging
+
+from audial.api.exceptions import AudialAuthError, AudialError, SubscriptionRequiredError
+from mcp.server.mcpserver.exceptions import ToolError
+
+from audial_mcp.config import ConfigError
+from audial_mcp.jobs import JobTimeout
+from audial_mcp.validation import ValidationError
+
+log = logging.getLogger("audial_mcp")
+
+
+def to_tool_error(exc: BaseException, *, tool: str, execution_id: str | None = None) -> ToolError:
+    if isinstance(exc, (ConfigError, ValidationError, SubscriptionRequiredError)):
+        return ToolError(str(exc))
+    if isinstance(exc, AudialAuthError):
+        return ToolError(
+            "Audial rejected the credentials. Check AUDIAL_USER_ID and AUDIAL_API_KEY in the "
+            "server's env and restart the client."
+        )
+    if isinstance(exc, JobTimeout):
+        ref = f" (execution {execution_id})" if execution_id else ""
+        return ToolError(
+            f"{exc.label} did not finish within {exc.elapsed_s:.0f} s{ref}. The job may still "
+            "complete on Audial's side; try again, or use a shorter file."
+        )
+    if isinstance(exc, AudialError):
+        return ToolError(str(exc))
+    log.exception("%s failed", tool)
+    return ToolError(f"{tool} failed unexpectedly. Details were logged to the server's stderr.")

audial_mcp-0.1.0/src/audial_mcp/jobs.py

@@ -0,0 +1,72 @@
+"""Run blocking SDK calls without freezing the MCP connection."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+import anyio
+
+T = TypeVar("T")
+
+
+class JobTimeout(Exception):
+    def __init__(self, label: str, elapsed_s: float):
+        super().__init__(f"{label} did not finish within {elapsed_s:.0f} s")
+        self.label = label
+        self.elapsed_s = elapsed_s
+
+
+async def run_job(
+    ctx: Any,
+    label: str,
+    fn: Callable[[], T],
+    *,
+    timeout_s: float,
+    heartbeat_s: float = 5.0,
+) -> T:
+    """Run `fn` in a worker thread; report elapsed seconds as progress until it returns."""
+    started = time.monotonic()
+
+    async def heartbeat() -> None:
+        while True:
+            await anyio.sleep(heartbeat_s)
+            elapsed = int(time.monotonic() - started)
+            try:
+                # Progress is best-effort: a disconnected client must not
+                # decide the job's outcome, so swallow reporting failures here
+                # rather than let them cross the task group as an error.
+                await ctx.report_progress(elapsed, message=f"{label}: {elapsed} s elapsed")
+            except Exception:
+                return
+
+    # Exceptions (other than cancellation) are caught here rather than left to
+    # propagate out of the `async with` block: anyio's TaskGroup.__aexit__
+    # unconditionally wraps any non-CancelledError exception raised in the
+    # block's body in a BaseExceptionGroup, even when there is only one.
+    # Catching and re-raising after the block exits keeps the caller-facing
+    # exception a bare JobTimeout / the original error. CancelledError is left
+    # to propagate normally; anyio already excludes it from that wrapping.
+    #
+    # A bare `except TimeoutError` here would be wrong: fn itself may raise a
+    # TimeoutError (socket.timeout / concurrent.futures.TimeoutError are
+    # aliases of it), which must propagate as itself, not get relabeled as a
+    # JobTimeout. So the deadline is detected via move_on_after's
+    # cancelled_caught instead of by catching an exception type.
+    error: Exception | None = None
+    result: T | None = None
+    async with anyio.create_task_group() as tg:
+        tg.start_soon(heartbeat)
+        with anyio.move_on_after(timeout_s) as scope:
+            try:
+                # Cancelling to_thread does not stop the thread; it finishes quietly.
+                result = await anyio.to_thread.run_sync(fn, abandon_on_cancel=True)
+            except Exception as exc:
+                error = exc
+        tg.cancel_scope.cancel()
+    if scope.cancelled_caught:
+        raise JobTimeout(label, time.monotonic() - started)
+    if error is not None:
+        raise error
+    return result

audial_mcp-0.1.0/src/audial_mcp/results.py

@@ -0,0 +1,88 @@
+"""Where results live and how they are reported back to the model."""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from typing_extensions import TypedDict
+
+_SLUG_RE = re.compile(r"[^A-Za-z0-9_-]+")
+SLUG_MAX = 40
+
+
+class FileInfo(TypedDict):
+    name: str
+    path: str
+    size_bytes: int
+
+
+class JobResult(TypedDict):
+    tool: str
+    execution_id: str | None
+    output_dir: str
+    files: list[FileInfo]
+    metadata: dict[str, Any]
+    summary: str
+
+
+def slugify(text: str, fallback: str = "job") -> str:
+    slug = _SLUG_RE.sub("_", text.strip()).strip("_")[:SLUG_MAX]
+    return slug or fallback
+
+
+def new_job_dir(results_dir: Path, tool: str, slug: str, now: datetime | None = None) -> Path:
+    stamp = (now or datetime.now()).strftime("%Y-%m-%d_%H%M%S")
+    folder = results_dir / tool / f"{stamp}_{slug}"
+    folder.mkdir(parents=True, exist_ok=True)
+    return folder
+
+
+def inventory(folder: Path) -> list[FileInfo]:
+    if not folder.is_dir():
+        return []
+    files: list[FileInfo] = []
+    for path in sorted(folder.rglob("*")):
+        rel_path = path.relative_to(folder)
+        if not path.is_file() or any(part.startswith(".") for part in rel_path.parts):
+            continue
+        files.append(
+            FileInfo(
+                name=rel_path.as_posix(),
+                path=str(path.resolve()),
+                size_bytes=path.stat().st_size,
+            )
+        )
+    return files
+
+
+def list_jobs(results_dir: Path, tool: str | None, limit: int) -> list[JobResult]:
+    if not results_dir.is_dir():
+        return []
+    tools = [tool] if tool else sorted(p.name for p in results_dir.iterdir() if p.is_dir())
+    jobs: list[tuple[str, JobResult]] = []
+    for name in tools:
+        tool_dir = results_dir / name
+        if not tool_dir.is_dir():
+            continue
+        for job_dir in tool_dir.iterdir():
+            if not job_dir.is_dir():
+                continue
+            files = inventory(job_dir)
+            jobs.append(
+                (
+                    job_dir.name,
+                    JobResult(
+                        tool=name,
+                        execution_id=None,
+                        output_dir=str(job_dir),
+                        files=files,
+                        metadata={},
+                        summary=f"{name}: {len(files)} file(s) in {job_dir}",
+                    ),
+                )
+            )
+    jobs.sort(key=lambda item: item[0], reverse=True)
+    return [job for _, job in jobs[: max(limit, 0)]]