supercollider-mcp 0.2.0__py3-none-any.whl

supercollider_mcp-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,30 @@
+supercollidermcp/__init__.py,sha256=V8XlubtKzdQeA6ON8W5CcPPYKQrjFCwaYv9EmNPUNE8,315
+supercollidermcp/__main__.py,sha256=89kDbLOQmPt9dNWJn1Wv3-JQb7BCpwnsgVq4LPlOMaA,1226
+supercollidermcp/compose.py,sha256=NFVPQVYO_bdbIVX-sTOjkoA4LVq3bBL4hBAPN1py_4w,23413
+supercollidermcp/engine.py,sha256=rVZkVG1BRZv9IdgLLZF2Ovo2SqwRFcCoVSfVG7gJvuc,7127
+supercollidermcp/osc.py,sha256=uCHNj_JDuBL1gqktw_YfhP5A3DC9BgBrmYt8RYUrS90,8773
+supercollidermcp/patterns.py,sha256=bDhgDya3Uv2ve0xajOyxoQeBumclhiFe4EuO51qj4rw,4567
+supercollidermcp/server.py,sha256=s9HxjOYqXM4YbX91C_xgLfis_T5jj4leFCG3Z26EAhQ,15630
+supercollidermcp/theory.py,sha256=ZcB_cnW29v_E_4M5sPTyoPDu1erbxmMt8RQSWS6LmVE,5691
+supercollidermcp/synthdefs/__init__.py,sha256=1DahkqoG7VsmTFFqTklEPESsweZJTb-EVT5gAjqa_5k,673
+supercollidermcp/synthdefs/mcp_blip.scsyndef,sha256=Lm-E4IAtcQJVTGwxmTB8An5vbXJqOJlJKKmrFL4SjKE,634
+supercollidermcp/synthdefs/mcp_fm.scsyndef,sha256=sJJ2DgbpDin0Vw99gg-Uk-aStLIeYzlSQsfZ5msyln8,1009
+supercollidermcp/synthdefs/mcp_fx.scsyndef,sha256=b1oKcUSx6WLcso7SaSsRllSU_E0uS6zFyT7CsDdzgD8,1614
+supercollidermcp/synthdefs/mcp_grain.scsyndef,sha256=KdNRd-AU9-MM8nkwZnKc9Wmlt6iwE9FMAA4BNoZ7Cfc,590
+supercollidermcp/synthdefs/mcp_hat.scsyndef,sha256=WY2WonKEHu4ZYnxNph1piajTQX4t0aQx8VrJ9lF74oI,573
+supercollidermcp/synthdefs/mcp_kick.scsyndef,sha256=eTK5nTF8vp-8R6gmhc2zSscFwnpYNDSJYR_N9OB_agI,1124
+supercollidermcp/synthdefs/mcp_lfo.scsyndef,sha256=h55CxZcAIvqayU7K7FYHzARfvGZ4WikDaBlSSieGwTk,1101
+supercollidermcp/synthdefs/mcp_limiter.scsyndef,sha256=xjq7X_2qEw9pAU9DOWc5NwlS3xSh6O1Je7pEEDuzvr0,249
+supercollidermcp/synthdefs/mcp_noise.scsyndef,sha256=nQbyqksEqkF4X8lClZRrETiMb5YPWADX3ywgK3PtSac,744
+supercollidermcp/synthdefs/mcp_pad.scsyndef,sha256=wZUTWbxM0OJskgAyHl_9y2b5ufCzf1y7x1xOLTvCevM,1745
+supercollidermcp/synthdefs/mcp_pluck.scsyndef,sha256=ydGv8JTaYWTwci2SRXgb2duedkXx0iZcgmZluzLMD1I,985
+supercollidermcp/synthdefs/mcp_saw.scsyndef,sha256=cUyImaUVWJqLwuHokb_bqMXqKnJHBo3eOvY0Gd5kiXo,715
+supercollidermcp/synthdefs/mcp_sine.scsyndef,sha256=IPZ_2cY-oIVzAKrV4g-HNKYmJwFr2ZdUK0Ea3M34Ouk,564
+supercollidermcp/synthdefs/mcp_snare.scsyndef,sha256=Rf99ZL4YMgHlX9dgEwSaczzgV9k6xebSIcLv303YcWM,1018
+supercollidermcp/synthdefs/mcp_square.scsyndef,sha256=hkNwPVUL2OahlrAnLlfnNNmOQSaGEGFCUFZbf9pbCVs,792
+supercollidermcp/synthdefs/synthdefs.scd,sha256=WGf2K-JLAP_lopubQRFhGxSrhgMCufF3afbzA5kYmQw,7774
+supercollider_mcp-0.2.0.dist-info/METADATA,sha256=7PNmKKzzL5CdnliJx2EEIPFqWjbPzkSHJukBKRPgCa0,10789
+supercollider_mcp-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+supercollider_mcp-0.2.0.dist-info/entry_points.txt,sha256=1e19aubxQcUUdND1rUTXwa4W5J_bmTkTOdK0RdDTpXo,69
+supercollider_mcp-0.2.0.dist-info/licenses/LICENSE,sha256=mHYNjxna5ngTcw4nxr78_bU5XJw8MFjn1Uox5nihAZw,1060
+supercollider_mcp-0.2.0.dist-info/RECORD,,

supercollider_mcp-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

supercollider_mcp-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+supercollider-mcp = supercollidermcp.__main__:main

supercollider_mcp-0.2.0.dist-info/licenses/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.

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"

supercollidermcp/__main__.py

@@ -0,0 +1,30 @@
+"""Run the MCP server over stdio: `supercollider-mcp` or `python -m supercollidermcp`."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+from . import __version__
+from .engine import Engine
+from .osc import SCClient
+from .server import config_from_env, create_server
+
+
+def main(argv: list[str] | None = None) -> None:
+    host, port = config_from_env()
+    parser = argparse.ArgumentParser(prog="supercollider-mcp", description="MCP server for SuperCollider (stdio)")
+    parser.add_argument("--host", default=host, help=f"scsynth host (env SC_HOST, default {host})")
+    parser.add_argument("--port", type=int, default=port, help=f"scsynth UDP port (env SC_PORT, default {port})")
+    parser.add_argument("--log-level", default="WARNING", choices=["DEBUG", "INFO", "WARNING", "ERROR"])
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    args = parser.parse_args(argv)
+
+    # stdout carries the MCP protocol, so logs must go to stderr
+    logging.basicConfig(level=args.log_level, stream=sys.stderr, format="%(levelname)s %(name)s: %(message)s")
+    create_server(Engine(SCClient(args.host, args.port))).run()
+
+
+if __name__ == "__main__":
+    main()