supercollider-mcp 0.2.0__tar.gz

supercollider_mcp-0.2.0/.gitignore

@@ -0,0 +1,42 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE specific files
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Local
+.pytest_cache/
+.ruff_cache/

supercollider_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+## 0.2.0
+
+A rewrite. Every tool now produces the sound it describes, and none of them block.
+
+### Added
+
+- Bundled SynthDefs: `sine`, `saw`, `square`, `noise`, `fm`, `pad`, `pluck`, `kick`, `snare`, `hat`, `blip`,
+  `grain`, plus `mcp_fx` (distortion, low-pass, delay, reverb), `mcp_lfo` and an output limiter. They are
+  uploaded to scsynth automatically, and the source is `supercollidermcp/synthdefs/synthdefs.scd`.
+- `server_status` tool: connection check, CPU, running playbacks, recent scsynth errors.
+- `stop_all` tool: silence everything and cancel scheduled notes.
+- `seed` on every generative tool (the seed used is reported), so a result can be replayed exactly.
+- Custom drum patterns as step strings (`X x o .`), five lanes, independent lane lengths, swing.
+- Scales: harmonic/melodic minor, the church modes, minor pentatonic, whole tone, chromatic.
+- Chords: 6, m6, mmaj7, m7b5, 7sus4, 9, maj9, m9, madd9 and slash chords (`G/B`).
+- `supercollider-mcp` command (`uvx supercollider-mcp`), configurable with `--host`/`--port` or
+  `SC_HOST`/`SC_PORT`.
+- Test suite: unit tests, protocol tests against a fake scsynth, offline renders of every SynthDef with
+  `scsynth -N`, and an end-to-end test against a live server. CI on Python 3.10–3.13.
+
+### Changed
+
+- Requires the current MCP SDK (`mcp>=2.3`) and Python 3.10+ (was 3.12+).
+- Playback is scheduled on scsynth with timestamped OSC bundles, so tools return immediately and
+  calls can overlap. Before, each call blocked the server for the whole sound.
+- Tool parameters have real types, ranges and enums in their schemas (before, everything was a string),
+  and `effects` is an object instead of a JSON string.
+- Invalid notes, chords and patterns are reported as errors instead of silently becoming A440.
+- `create_drum_pattern` takes `bars` (16 steps each) instead of `beats`, and steps are 16th notes. Before,
+  every step lasted a whole beat, so grooves played four times too slow.
+- `play_melody` makes stepwise melodies that resolve to the tonic (and takes `root`, `notes`, `synth`). It no
+  longer appends an unrelated scale run.
+- `create_chord_progression` keeps roots near middle C, and its `staccato` and `arpeggio` styles play on the
+  beat and in 8th notes. New `octave`, `synth` and `repeats` parameters.
+- `create_layered_synth`: `detune` 1.0 now means ±50 cents (it used to reach a full octave), and there is a
+  new `stereo_width` parameter.
+- `create_ambient_soundscape` events now actually overlap, and each mood has its own effects.
+- `create_generative_rhythm` really evolves (patterns mutate bar by bar and snap back every 8 bars).
+
+### Fixed
+
+- `create_granular_texture` crashed with `pitch_spread=0`.
+- `create_sequence` ignored its `synth` parameter and split undelimited input into single characters.
+- Every "synth type" and effect was silently ignored, because all sounds used sclang's `default` SynthDef.
+- Notes ended with a click (`/n_free` instead of an envelope release).
+- Node IDs could collide between overlapping calls.
+
+### Removed
+
+- The `sc-osc` CLI (its entry point never worked).
+- The duplicated helper modules (`melody.py`, `rhythm.py`, the old `osc.py`), which `server.py` never used.
+
+## 0.1.1
+
+- Pin `mcp<2`: mcp 2.0 renamed `FastMCP`, so fresh installs crashed on startup.
+
+## 0.1.0
+
+- Initial release.

supercollider_mcp-0.2.0/LICENSE

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

supercollider_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.5
+Name: supercollider-mcp
+Version: 0.2.0
+Summary: MCP server that lets AI assistants make sound with SuperCollider over OSC
+Project-URL: Homepage, https://github.com/Tok/SuperColliderMCP
+Project-URL: Issues, https://github.com/Tok/SuperColliderMCP/issues
+Project-URL: Changelog, https://github.com/Tok/SuperColliderMCP/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audio,mcp,model-context-protocol,music,osc,supercollider,synthesis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Sound Synthesis
+Requires-Python: >=3.10
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: python-osc>=1.9
+Description-Content-Type: text/markdown
+
+[![CI](https://github.com/Tok/SuperColliderMCP/actions/workflows/ci.yml/badge.svg)](https://github.com/Tok/SuperColliderMCP/actions/workflows/ci.yml)
+[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/70ac07b9-ec05-4fec-9456-5c4331cdf994)
+
+# SuperCollider MCP 🎛️
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) server that lets AI assistants make sound with
+[SuperCollider](https://supercollider.github.io/). Ask for "a dark ambient drone with slow swells" or
+"a breakbeat at 170 under a Cm7-Fm7 arpeggio" and it plays on your SuperCollider server.
+
+- **Real synths and drums.** It ships its own SynthDefs (sine, saw, square, noise, FM, pad, Karplus-Strong
+  pluck, kick, snare, hats, grains) plus an effect chain (distortion, low-pass, delay, reverb) and a safety
+  limiter. Nothing depends on sclang's `default` synth or on sc3-plugins.
+- **Sample-accurate timing.** Phrases are streamed to scsynth as timestamped OSC bundles, so every tool
+  returns immediately. Calls can overlap, so you can layer drums, chords and melody.
+- **Music-aware tools.** Melodies follow 14 scales, chords understand symbols like `Am7`, `Bbmaj9` and `G/B`,
+  drum patterns are readable step strings the assistant can write itself, and generative tools take a
+  `seed` so a result you like can be replayed exactly.
+- **A panic button.** `stop_all` silences everything this server started.
+
+## Requirements
+
+- [SuperCollider](https://supercollider.github.io/downloads) 3.10 or newer (tested with 3.13). Only the
+  audio server, `scsynth`, has to be running.
+- [uv](https://docs.astral.sh/uv/), or any Python 3.10+ with pip.
+
+## Quick start
+
+**1. Install and boot SuperCollider.** Install it from the
+[downloads page](https://supercollider.github.io/downloads) (or `brew install --cask supercollider` on
+macOS, `sudo apt install supercollider` on Debian/Ubuntu), then boot the server:
+
+- in the SuperCollider IDE: *Server → Boot Server* (or run `s.boot;`)
+- or without the IDE: `scsynth -u 57110`
+
+**2. Add the MCP server to your assistant.**
+
+Claude Code:
+
+```bash
+claude mcp add supercollider -- uvx supercollider-mcp
+```
+
+Claude Desktop, Cursor, Cline, Roo Code and other clients that use an `mcpServers` config:
+
+```json
+{
+  "mcpServers": {
+    "supercollider": {
+      "command": "uvx",
+      "args": ["supercollider-mcp"]
+    }
+  }
+}
+```
+
+To run the latest code from GitHub instead of the PyPI release, use
+`"args": ["--from", "git+https://github.com/Tok/SuperColliderMCP", "supercollider-mcp"]`.
+
+**3. Ask for something.** Start with "play a test sound" to check the connection, then try the prompts
+below.
+
+### Configuration
+
+| Setting | Flag | Environment | Default |
+| --- | --- | --- | --- |
+| scsynth host | `--host` | `SC_HOST` | `127.0.0.1` |
+| scsynth UDP port | `--port` | `SC_PORT` | `57110` |
+| log level (stderr) | `--log-level` | | `WARNING` |
+
+For example `"args": ["supercollider-mcp", "--port", "57111"]`.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `server_status` | Connection check: scsynth version, CPU, running playbacks, recent server errors |
+| `stop_all` | Silence everything this server started and cancel scheduled notes |
+| `play_example_osc` | A short test chime |
+| `play_synth` | One note on `sine`, `saw`, `square`, `noise`, `fm`, `pad` or `pluck` |
+| `create_layered_synth` | A thick unison: several detuned copies of one note spread in stereo |
+| `create_lfo_modulation` | A held note with a server-side LFO on pitch, volume, filter or pan |
+| `create_granular_texture` | A cloud of 5–100 tiny grains per second, scattered in pitch and space |
+| `play_melody` | A generated melody in one of 14 scales that resolves to the tonic |
+| `create_sequence` | A melody you spell out: `"C4 E4_ G4_ . C5+"` |
+| `create_chord_progression` | Chord symbols as pads, staccato stabs, 8th-note arpeggios or power chords |
+| `create_drum_pattern` | `four_on_floor`, `breakbeat`, `shuffle`, `half_time`, `two_step`, `random`, or your own |
+| `create_generative_rhythm` | Drums that keep mutating: `minimal`, `techno`, `glitch`, `jazz`, `ambient` |
+| `create_ambient_soundscape` | A drone with overlapping swells in a `calm`, `dark`, `bright`, `mysterious` or `chaotic` mood |
+
+Most tools also take `volume` (0–1) and an optional `effects` object:
+
+```json
+{"reverb": 0.6, "delay": 0.3, "delay_time": 0.25, "distortion": 0.0, "filter": 0.2}
+```
+
+All amounts are 0–1, and 0 means off. `filter` darkens the sound with a low-pass filter. `delay_time` is in
+seconds and defaults to three quarters of a beat.
+
+**Notes** are names like `C4` (middle C), `F#3` or `Bb2`, or frequencies like `"440"` or `"440hz"`.
+
+**Sequences** separate notes with spaces or dashes. `_` halves a note, `+` doubles it, `:1.5` sets its
+length in beats, and `.` is a rest.
+
+**Drum patterns** use one character per 16th note: `X` accent, `x` hit, `o` ghost note, `.` rest. Lanes
+(`kick`, `snare`, `hat`, `open_hat`, `perc`) can have different lengths and loop independently:
+
+```json
+{"custom": {"kick": "X..x..X...x.....", "snare": "....X.......X..o", "hat": "x.x.x.x.x.x.x.x."}, "tempo": 92, "swing": 0.2}
+```
+
+### Things to try
+
+- "Play a dorian melody in D on the pluck synth with some delay, then the same one an octave lower."
+- "Give me two bars of breakbeat at 170 BPM, then layer an Am7-Dm7-G7-Cmaj7 arpeggio on top."
+- "A mysterious ambient soundscape, 60 seconds, low register."
+- "Sweep a saw's filter with a slow triangle LFO while a granular cloud shimmers around A5."
+- "Write me a half-time drum pattern with ghost notes on the snare."
+
+## How it works
+
+```
+assistant ──MCP (stdio)──▶ supercollider-mcp ──OSC/UDP──▶ scsynth ──▶ speakers
+```
+
+On first use the server checks that scsynth answers, uploads its SynthDefs (`/d_recv`) and creates its own
+node group with a voice group, an effects group and a limiter. Node IDs sit far above the ranges sclang
+uses, so your own SuperCollider work is not affected. If scsynth restarts, the setup runs again on the next
+call.
+
+Each tool call turns into a *phrase*: a time-ordered stream of synth events (`supercollidermcp/compose.py`,
+pure Python). A background task sends each event about half a second ahead as an OSC bundle with an NTP
+timetag, and scsynth starts it at exactly that time. Every synth frees itself when its envelope ends. When
+a call asks for effects, its voices go to a private bus that one `mcp_fx` synth reads.
+
+## Upgrading from 0.1
+
+- Point your MCP config at `uvx supercollider-mcp` as shown above. Old configs that run
+  `mcp run path/to/server.py` still work through a small compatibility `server.py`.
+- Sounds now come from real SynthDefs, so you no longer need sclang's `default` synth.
+- Tools return right away instead of blocking until the sound ends.
+- Some parameters changed meaning. `create_drum_pattern` takes `bars` (16 steps each) instead of `beats`.
+  `effects` is an object instead of a JSON string. `detune` is now ±50 cents at 1.0 instead of up to an
+  octave. The `sc-osc` command-line tool is gone.
+
+See [CHANGELOG.md](CHANGELOG.md) for everything else.
+
+## Troubleshooting
+
+- **"No reply from the SuperCollider server…"**: scsynth is not running, or it listens on a different
+  port. Boot it, or set `SC_PORT`.
+- **Calls succeed but you hear nothing**: check that scsynth's outputs are connected to your sound card
+  and that `server_status` shows synths while something plays.
+- **Linux with PipeWire** (the default on current Ubuntu and Fedora): scsynth talks to JACK, so install
+  PipeWire's JACK layer (`sudo apt install pipewire-jack`) and start SuperCollider through it:
+  `pw-jack scide`, or `pw-jack scsynth -u 57110` without the IDE. Otherwise scsynth tries to start its
+  own `jackd`, which conflicts with PipeWire.
+- **`FAILURE IN SERVER /g_queryTree Group 2147480000 not found` in the post window** on first connect is
+  expected: it is how the server notices that scsynth still needs to be set up.
+- **Remote scsynth**: timetags use wall-clock time, so keep both machines' clocks in sync (NTP).
+
+## Development
+
+```bash
+git clone https://github.com/Tok/SuperColliderMCP.git
+cd SuperColliderMCP
+uv sync
+uv run pytest          # unit and protocol tests run anywhere
+uv run ruff check . && uv run ruff format --check .
+```
+
+Some tests need SuperCollider:
+
+- `tests/test_synthdefs_nrt.py` renders every SynthDef with `scsynth -N` (no audio device needed) and
+  checks the audio. It runs automatically when `scsynth` is on `PATH`, or set `SCSYNTH=/path/to/scsynth`.
+- `tests/test_live_server.py` runs every tool against a live server. Start a silent one with
+  `scsynth -u 57199 -i 0 -o 0`, then run `SC_TEST_PORT=57199 uv run pytest`.
+
+The SynthDefs are written in SuperCollider itself, in `supercollidermcp/synthdefs/synthdefs.scd`. After
+editing that file, rebuild the compiled `.scsyndef` files with `python scripts/build_synthdefs.py`
+(needs `sclang`; it runs headless).
+
+```
+supercollidermcp/
+├── server.py      MCP tools: validation and wiring
+├── compose.py     musical logic: requests → timed events (pure, unit-tested)
+├── theory.py      notes, scales, chords
+├── patterns.py    drum patterns as step strings
+├── engine.py      server setup, buses, streaming playback, stop_all
+├── osc.py         async OSC client that also reads scsynth's replies
+└── synthdefs/     synthdefs.scd (source) + compiled .scsyndef files
+```
+
+Contributions are welcome. New sounds usually mean a SynthDef in `synthdefs.scd` plus a composer function
+in `compose.py`.
+
+## External Security Assessment
+
+[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/tok-supercollidermcp-badge.png)](https://mseep.ai/app/tok-supercollidermcp)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

supercollider_mcp-0.2.0/README.md

@@ -0,0 +1,202 @@
+[![CI](https://github.com/Tok/SuperColliderMCP/actions/workflows/ci.yml/badge.svg)](https://github.com/Tok/SuperColliderMCP/actions/workflows/ci.yml)
+[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/70ac07b9-ec05-4fec-9456-5c4331cdf994)
+
+# SuperCollider MCP 🎛️
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) server that lets AI assistants make sound with
+[SuperCollider](https://supercollider.github.io/). Ask for "a dark ambient drone with slow swells" or
+"a breakbeat at 170 under a Cm7-Fm7 arpeggio" and it plays on your SuperCollider server.
+
+- **Real synths and drums.** It ships its own SynthDefs (sine, saw, square, noise, FM, pad, Karplus-Strong
+  pluck, kick, snare, hats, grains) plus an effect chain (distortion, low-pass, delay, reverb) and a safety
+  limiter. Nothing depends on sclang's `default` synth or on sc3-plugins.
+- **Sample-accurate timing.** Phrases are streamed to scsynth as timestamped OSC bundles, so every tool
+  returns immediately. Calls can overlap, so you can layer drums, chords and melody.
+- **Music-aware tools.** Melodies follow 14 scales, chords understand symbols like `Am7`, `Bbmaj9` and `G/B`,
+  drum patterns are readable step strings the assistant can write itself, and generative tools take a
+  `seed` so a result you like can be replayed exactly.
+- **A panic button.** `stop_all` silences everything this server started.
+
+## Requirements
+
+- [SuperCollider](https://supercollider.github.io/downloads) 3.10 or newer (tested with 3.13). Only the
+  audio server, `scsynth`, has to be running.
+- [uv](https://docs.astral.sh/uv/), or any Python 3.10+ with pip.
+
+## Quick start
+
+**1. Install and boot SuperCollider.** Install it from the
+[downloads page](https://supercollider.github.io/downloads) (or `brew install --cask supercollider` on
+macOS, `sudo apt install supercollider` on Debian/Ubuntu), then boot the server:
+
+- in the SuperCollider IDE: *Server → Boot Server* (or run `s.boot;`)
+- or without the IDE: `scsynth -u 57110`
+
+**2. Add the MCP server to your assistant.**
+
+Claude Code:
+
+```bash
+claude mcp add supercollider -- uvx supercollider-mcp
+```
+
+Claude Desktop, Cursor, Cline, Roo Code and other clients that use an `mcpServers` config:
+
+```json
+{
+  "mcpServers": {
+    "supercollider": {
+      "command": "uvx",
+      "args": ["supercollider-mcp"]
+    }
+  }
+}
+```
+
+To run the latest code from GitHub instead of the PyPI release, use
+`"args": ["--from", "git+https://github.com/Tok/SuperColliderMCP", "supercollider-mcp"]`.
+
+**3. Ask for something.** Start with "play a test sound" to check the connection, then try the prompts
+below.
+
+### Configuration
+
+| Setting | Flag | Environment | Default |
+| --- | --- | --- | --- |
+| scsynth host | `--host` | `SC_HOST` | `127.0.0.1` |
+| scsynth UDP port | `--port` | `SC_PORT` | `57110` |
+| log level (stderr) | `--log-level` | | `WARNING` |
+
+For example `"args": ["supercollider-mcp", "--port", "57111"]`.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `server_status` | Connection check: scsynth version, CPU, running playbacks, recent server errors |
+| `stop_all` | Silence everything this server started and cancel scheduled notes |
+| `play_example_osc` | A short test chime |
+| `play_synth` | One note on `sine`, `saw`, `square`, `noise`, `fm`, `pad` or `pluck` |
+| `create_layered_synth` | A thick unison: several detuned copies of one note spread in stereo |
+| `create_lfo_modulation` | A held note with a server-side LFO on pitch, volume, filter or pan |
+| `create_granular_texture` | A cloud of 5–100 tiny grains per second, scattered in pitch and space |
+| `play_melody` | A generated melody in one of 14 scales that resolves to the tonic |
+| `create_sequence` | A melody you spell out: `"C4 E4_ G4_ . C5+"` |
+| `create_chord_progression` | Chord symbols as pads, staccato stabs, 8th-note arpeggios or power chords |
+| `create_drum_pattern` | `four_on_floor`, `breakbeat`, `shuffle`, `half_time`, `two_step`, `random`, or your own |
+| `create_generative_rhythm` | Drums that keep mutating: `minimal`, `techno`, `glitch`, `jazz`, `ambient` |
+| `create_ambient_soundscape` | A drone with overlapping swells in a `calm`, `dark`, `bright`, `mysterious` or `chaotic` mood |
+
+Most tools also take `volume` (0–1) and an optional `effects` object:
+
+```json
+{"reverb": 0.6, "delay": 0.3, "delay_time": 0.25, "distortion": 0.0, "filter": 0.2}
+```
+
+All amounts are 0–1, and 0 means off. `filter` darkens the sound with a low-pass filter. `delay_time` is in
+seconds and defaults to three quarters of a beat.
+
+**Notes** are names like `C4` (middle C), `F#3` or `Bb2`, or frequencies like `"440"` or `"440hz"`.
+
+**Sequences** separate notes with spaces or dashes. `_` halves a note, `+` doubles it, `:1.5` sets its
+length in beats, and `.` is a rest.
+
+**Drum patterns** use one character per 16th note: `X` accent, `x` hit, `o` ghost note, `.` rest. Lanes
+(`kick`, `snare`, `hat`, `open_hat`, `perc`) can have different lengths and loop independently:
+
+```json
+{"custom": {"kick": "X..x..X...x.....", "snare": "....X.......X..o", "hat": "x.x.x.x.x.x.x.x."}, "tempo": 92, "swing": 0.2}
+```
+
+### Things to try
+
+- "Play a dorian melody in D on the pluck synth with some delay, then the same one an octave lower."
+- "Give me two bars of breakbeat at 170 BPM, then layer an Am7-Dm7-G7-Cmaj7 arpeggio on top."
+- "A mysterious ambient soundscape, 60 seconds, low register."
+- "Sweep a saw's filter with a slow triangle LFO while a granular cloud shimmers around A5."
+- "Write me a half-time drum pattern with ghost notes on the snare."
+
+## How it works
+
+```
+assistant ──MCP (stdio)──▶ supercollider-mcp ──OSC/UDP──▶ scsynth ──▶ speakers
+```
+
+On first use the server checks that scsynth answers, uploads its SynthDefs (`/d_recv`) and creates its own
+node group with a voice group, an effects group and a limiter. Node IDs sit far above the ranges sclang
+uses, so your own SuperCollider work is not affected. If scsynth restarts, the setup runs again on the next
+call.
+
+Each tool call turns into a *phrase*: a time-ordered stream of synth events (`supercollidermcp/compose.py`,
+pure Python). A background task sends each event about half a second ahead as an OSC bundle with an NTP
+timetag, and scsynth starts it at exactly that time. Every synth frees itself when its envelope ends. When
+a call asks for effects, its voices go to a private bus that one `mcp_fx` synth reads.
+
+## Upgrading from 0.1
+
+- Point your MCP config at `uvx supercollider-mcp` as shown above. Old configs that run
+  `mcp run path/to/server.py` still work through a small compatibility `server.py`.
+- Sounds now come from real SynthDefs, so you no longer need sclang's `default` synth.
+- Tools return right away instead of blocking until the sound ends.
+- Some parameters changed meaning. `create_drum_pattern` takes `bars` (16 steps each) instead of `beats`.
+  `effects` is an object instead of a JSON string. `detune` is now ±50 cents at 1.0 instead of up to an
+  octave. The `sc-osc` command-line tool is gone.
+
+See [CHANGELOG.md](CHANGELOG.md) for everything else.
+
+## Troubleshooting
+
+- **"No reply from the SuperCollider server…"**: scsynth is not running, or it listens on a different
+  port. Boot it, or set `SC_PORT`.
+- **Calls succeed but you hear nothing**: check that scsynth's outputs are connected to your sound card
+  and that `server_status` shows synths while something plays.
+- **Linux with PipeWire** (the default on current Ubuntu and Fedora): scsynth talks to JACK, so install
+  PipeWire's JACK layer (`sudo apt install pipewire-jack`) and start SuperCollider through it:
+  `pw-jack scide`, or `pw-jack scsynth -u 57110` without the IDE. Otherwise scsynth tries to start its
+  own `jackd`, which conflicts with PipeWire.
+- **`FAILURE IN SERVER /g_queryTree Group 2147480000 not found` in the post window** on first connect is
+  expected: it is how the server notices that scsynth still needs to be set up.
+- **Remote scsynth**: timetags use wall-clock time, so keep both machines' clocks in sync (NTP).
+
+## Development
+
+```bash
+git clone https://github.com/Tok/SuperColliderMCP.git
+cd SuperColliderMCP
+uv sync
+uv run pytest          # unit and protocol tests run anywhere
+uv run ruff check . && uv run ruff format --check .
+```
+
+Some tests need SuperCollider:
+
+- `tests/test_synthdefs_nrt.py` renders every SynthDef with `scsynth -N` (no audio device needed) and
+  checks the audio. It runs automatically when `scsynth` is on `PATH`, or set `SCSYNTH=/path/to/scsynth`.
+- `tests/test_live_server.py` runs every tool against a live server. Start a silent one with
+  `scsynth -u 57199 -i 0 -o 0`, then run `SC_TEST_PORT=57199 uv run pytest`.
+
+The SynthDefs are written in SuperCollider itself, in `supercollidermcp/synthdefs/synthdefs.scd`. After
+editing that file, rebuild the compiled `.scsyndef` files with `python scripts/build_synthdefs.py`
+(needs `sclang`; it runs headless).
+
+```
+supercollidermcp/
+├── server.py      MCP tools: validation and wiring
+├── compose.py     musical logic: requests → timed events (pure, unit-tested)
+├── theory.py      notes, scales, chords
+├── patterns.py    drum patterns as step strings
+├── engine.py      server setup, buses, streaming playback, stop_all
+├── osc.py         async OSC client that also reads scsynth's replies
+└── synthdefs/     synthdefs.scd (source) + compiled .scsyndef files
+```
+
+Contributions are welcome. New sounds usually mean a SynthDef in `synthdefs.scd` plus a composer function
+in `compose.py`.
+
+## External Security Assessment
+
+[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/tok-supercollidermcp-badge.png)](https://mseep.ai/app/tok-supercollidermcp)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

supercollider_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "supercollider-mcp"
+version = "0.2.0"
+description = "MCP server that lets AI assistants make sound with SuperCollider over OSC"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+keywords = ["supercollider", "mcp", "model-context-protocol", "osc", "music", "audio", "synthesis"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Multimedia :: Sound/Audio :: Sound Synthesis",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "mcp>=2.3,<3",
+    "python-osc>=1.9",
+]
+
+[project.urls]
+Homepage = "https://github.com/Tok/SuperColliderMCP"
+Issues = "https://github.com/Tok/SuperColliderMCP/issues"
+Changelog = "https://github.com/Tok/SuperColliderMCP/blob/main/CHANGELOG.md"
+
+[project.scripts]
+supercollider-mcp = "supercollidermcp.__main__:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.8",
+]
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["supercollidermcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["supercollidermcp", "tests", "scripts", "README.md", "CHANGELOG.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

supercollider_mcp-0.2.0/scripts/build_synthdefs.py

@@ -0,0 +1,59 @@
+"""Compile supercollidermcp/synthdefs/synthdefs.scd into .scsyndef files.
+
+Needs sclang (SuperCollider 3.10+). It runs headless, so no IDE or display is needed.
+
+    python scripts/build_synthdefs.py
+
+Environment overrides:
+    SCLANG       path to the sclang binary (default: found on PATH)
+    SCLANG_CONF  path to a sclang_conf.yaml, passed as `sclang -l`
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+SYNTHDEF_DIR = Path(__file__).resolve().parent.parent / "supercollidermcp" / "synthdefs"
+SOURCE = SYNTHDEF_DIR / "synthdefs.scd"
+
+
+def main() -> int:
+    sclang = os.environ.get("SCLANG") or shutil.which("sclang")
+    if not sclang:
+        print("sclang not found: install SuperCollider or set SCLANG=/path/to/sclang", file=sys.stderr)
+        return 1
+
+    for old in SYNTHDEF_DIR.glob("*.scsyndef"):
+        old.unlink()
+
+    cmd = [sclang]
+    if conf := os.environ.get("SCLANG_CONF"):
+        cmd += ["-l", conf]
+    cmd += [str(SOURCE), str(SYNTHDEF_DIR)]
+
+    env = {**os.environ, "QT_QPA_PLATFORM": os.environ.get("QT_QPA_PLATFORM", "offscreen")}
+    result = subprocess.run(cmd, env=env, capture_output=True, text=True, timeout=120)
+    output = result.stdout + result.stderr
+    built = sorted(p.name for p in SYNTHDEF_DIR.glob("*.scsyndef"))
+    wrote = re.search(r"wrote (\d+) SynthDefs", output)
+
+    # Judge success by what sclang reports and writes, not by its exit code: headless
+    # sclang 3.13 often segfaults while shutting down, after the files are written.
+    if "ERROR" in output or not wrote or int(wrote.group(1)) != len(built):
+        print(output, file=sys.stderr)
+        print("SynthDef build failed", file=sys.stderr)
+        return 1
+
+    print(f"built {len(built)} SynthDefs in {SYNTHDEF_DIR}:")
+    for name in built:
+        print(f"  {name}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

supercollider_mcp-0.2.0/supercollidermcp/__init__.py

@@ -0,0 +1,8 @@
+"""SuperColliderMCP: an MCP server for making sound with SuperCollider over OSC."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("supercollider-mcp")
+except PackageNotFoundError:  # running from a source checkout without installing
+    __version__ = "0.0.0+unknown"