# audio-mcp

A mock-first [Model Context Protocol](https://modelcontextprotocol.io/) server for
audio generation. It creates deterministic placeholder WAV files locally, making
it possible to develop and test an audio-tool workflow without credentials,
network calls, or generation fees.

## Tools

- `generate_music(prompt, duration_seconds=2.0)`
- `generate_sound_effect(prompt, duration_seconds=1.0)`
- `get_generation_status(generation_id)`

Generation calls complete synchronously and return a generation ID plus a local
asset containing its path, file URI, MIME type, format, and duration. Durations
must be between 0.1 and 30 seconds.

## Development

Python 3.10 or newer is required.

```bash
python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
pytest
```

The integration test launches the STDIO server, initializes an MCP client, lists
the tools, calls every tool, and checks the generated WAV asset.

## Run the server

The default transport is STDIO:

```bash
python -m audio_mcp.server
```

Generated files are written to `.audio-mcp/`. Override that location with
`AUDIO_MCP_OUTPUT_DIR`.

To register a development checkout with Codex CLI:

```bash
codex mcp add audio-dev -- python -m audio_mcp.server
codex mcp list
```

The server intentionally has no paid provider integration. A production provider
can later implement the same asset response contract once the MCP workflow has
been validated.