sonilo-mcp: Instructions file for Codex

AGENTS.md

Notes for coding agents working on sonilo-mcp, and for agents connecting to it.

What this repo is

A local stdio MCP server (Python, FastMCP) that wraps Sonilo's public API: music, sound effects, combined music + SFX, video analysis, audio ducking, dubbing and proofreading. It uploads local files, waits on async tasks and saves results to disk. Published to PyPI as sonilo-mcp and to the MCP Registry as io.github.sonilo-ai/sonilo-mcp.

There is also a hosted, OAuth-authenticated server at https://api.sonilo.com/mcp. It is not built from this repo.

Layout

src/sonilo_mcp/api.py          every tool, HTTP calls, polling, downloads, path confinement; entry point `main`
src/sonilo_mcp/credentials.py  reads the `sonilo login` credential file
tests/test_api.py              tool tests (respx mocks the API; no network)
tests/test_credentials.py
tests/conftest.py              clears SONILO_* env vars and points HOME at a tmp dir
pyproject.toml                 package metadata and the real version
server.json                    MCP Registry manifest; release CI rewrites its version
uv.lock                        pins mcp to 1.x (2.x removed mcp.server.fastmcp)

setup.py is legacy and its version is not used. pyproject.toml is the source of truth.

Commands

uv sync --extra dev --frozen   # install, honouring uv.lock
uv run pytest -v               # what CI runs
uv run sonilo-mcp              # start the server on stdio

Use uv sync --frozen, not a plain pip install: an unpinned resolve can pull mcp 2.x and every import fails. There is no PR CI in this repo; tests run in .github/workflows/release.yml before publishing, so run them locally.

Releasing

1. Bump version in pyproject.toml; put the version in the commit title, e.g. proofread: ... (0.26.0).
2. Push a vX.Y.Z tag that matches it. The release workflow tests, publishes to PyPI (trusted publishing), waits until PyPI serves the version, then syncs server.json and publishes to the MCP Registry.