constraint-mcp-server

MCP (Model Context Protocol) server for the constraint theory ecosystem — query constraints, snap pitches, diagnose sequences, generate music, and render audio from any MCP-compatible AI tool.

What Is This?

This is an MCP server that exposes the SuperInstance constraint theory tools as MCP tools. It's designed to work with Copilot for Eclipse, Claude Desktop, and any other MCP-compatible client.

The server provides tools for:

• Pitch snapping — snap notes to the nearest Eisenstein lattice point
• Constraint funneling — apply gravitational pull toward a target pitch
• Diagnostics — run 4-order Goodman diagnostic on note sequences
• Music generation — generate music in a given mode + terrain
• Audio rendering — render notes to WAV audio bytes
• Terrain listing — list available musical terrains

Quick Start

Installation

pip install constraint-mcp-server

Or from source:

git clone https://github.com/SuperInstance/constraint-mcp-server.git
cd constraint-mcp-server
pip install -e .

Dependencies

• Python ≥ 3.10
• mcp[cli] ≥ 1.0.0
• The constraint ecosystem (lazy-loaded):
  • constraint-substrate
  • constraint-synth
  • constraint_instrument

Running the Server

# As a module
python -m constraint_mcp_server

# As an installed script
constraint-mcp

Configuring with MCP Client

Add to your MCP client configuration (e.g., claude_desktop_config.json):

{
  "servers": {
    "constraint-ecosystem": {
      "command": "python3",
      "args": ["-m", "constraint_mcp_server"],
      "env": {
        "PYTHONPATH": "/path/to/constraint-mcp-server:/path/to/constraint-substrate/python:/path/to/constraint_instrument:/path/to/constraint-synth",
        "CONSTRAINT_WORKSPACE": "/path/to/workspace"
      },
      "type": "stdio"
    }
  }
}

MCP Tools Provided

constraint_snap

Snap a pitch to the nearest Eisenstein lattice point.

{
  "pitch": 60,
  "scale": "major",
  "octave_range": [3, 6]
}

Returns the snapped pitch and the snap distance (how far it moved).

constraint_funnel

Apply gravitational pull toward a target pitch, simulating constraint funnel dynamics.

{
  "current_pitch": 62,
  "target_pitch": 60,
  "strength": 0.7,
  "scale": "major"
}

Returns the funnel-adjusted pitch.

constraint_diagnose

Run a 4-order Goodman diagnostic on a sequence of notes. Analyzes:

1. First order: Note-to-note intervals
2. Second order: Interval-to-interval changes (acceleration)
3. Third order: Rate of change of acceleration
4. Fourth order: Structural coherence measure

{
  "notes": [60, 62, 64, 65, 67, 69, 71, 72],
  "key": "C"
}

Returns a diagnostic report with scores at each order.

constraint_generate

Generate music in a given mode and terrain.

{
  "mode": "dorian",
  "terrain": "rolling_hills",
  "bars": 8,
  "tempo": 120
}

Returns generated MIDI-like note data.

constraint_render

Render notes to WAV audio bytes.

{
  "notes": [
    {"pitch": 60, "duration": 0.5, "velocity": 80},
    {"pitch": 64, "duration": 0.5, "velocity": 80},
    {"pitch": 67, "duration": 1.0, "velocity": 90}
  ],
  "sample_rate": 44100
}

Returns base64-encoded WAV audio.

constraint_terrain_list

List all available musical terrains for generation.

{}

Returns a list of terrain names with descriptions.

Architecture

constraint_mcp_server/
├── __init__.py          # Server implementation + tool handlers
├── __main__.py          # Entry point for `python -m`
mcp-config.json          # Example MCP client configuration
pyproject.toml           # Build config with entry point

Design Principles

1. Lazy loading: The constraint ecosystem libraries are loaded on first use, not at import time
2. Workspace-relative paths: Automatically finds sibling repos in the same workspace
3. stdio transport: Uses MCP's stdio transport for maximum compatibility
4. Graceful degradation: Tools that need unavailable libraries return helpful error messages

Integration Examples

With Claude Desktop

1. Install: pip install constraint-mcp-server
2. Add to claude_desktop_config.json:

{
  "mcpServers": {
    "constraints": {
      "command": "python3",
      "args": ["-m", "constraint_mcp_server"]
    }
  }
}

3. Restart Claude Desktop
4. Ask Claude: "Snap pitch 62 to the nearest lattice point in C major"

With Copilot for Eclipse

The server is designed for integration with Copilot for Eclipse via the MCP protocol:

1. Configure the server in Eclipse's MCP settings
2. Use the constraint tools in your coding workflow
3. Generate constraint-aware music directly in your IDE

With Custom MCP Client

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command="python3",
    args=["-m", "constraint_mcp_server"],
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        
        # List available tools
        tools = await session.list_tools()
        
        # Snap a pitch
        result = await session.call_tool("constraint_snap", {
            "pitch": 62,
            "scale": "major"
        })

Constraint Theory Background

The tools in this server are based on constraint theory as developed in the SuperInstance research program:

• Constraints define valid regions in a musical space
• Snapping moves a note to the nearest valid point on a constraint lattice
• Funnels simulate gravitational dynamics that pull notes toward attractors
• Terrains define the overall constraint landscape (hills, valleys, ridges)
• Diagnostics measure how well a sequence satisfies constraints at multiple orders

The underlying mathematics uses Eisenstein integers (the ring ℤ[ω] where ω = e^(2πi/3)) to model musical constraint lattices. This provides:

• Natural 3-dimensional structure (perfect fifth, major third, octave)
• Efficient computation via integer lattice operations
• Connection to the Tonnetz and neo-Riemannian theory

Related Projects

Repository	Description
constraint-substrate	Multi-language constraint substrate (C, Python, Rust)
constraint-synth	Constraint-based audio synthesis
constraint-viz	Multi-scale constraint visualization oscilloscope
constraint-theory-core	Core constraint theory mathematics
constraint-toolkit	Python constraint toolkit
fortran-constraint-checking	High-performance Fortran constraint checker
constraint-instrument	Live constraint-based musical instrument

Development

git clone https://github.com/SuperInstance/constraint-mcp-server.git
cd constraint-mcp-server
pip install -e .

Adding a New Tool

1. Define the tool schema in list_tools()
2. Handle the tool in call_tool()
3. Add any needed lazy imports
4. Update this README

Testing

# Test the server starts
python -m constraint_mcp_server &
sleep 2
kill %1

Citation

@software{constraint_mcp_server_2026,
  title = {constraint-mcp-server: MCP Server for the Constraint Theory Ecosystem},
  author = {SuperInstance Research},
  year = {2026},
  url = {https://github.com/SuperInstance/constraint-mcp-server}
}

License

MIT — see LICENSE for details.

---

Part of the SuperInstance constraint theory ecosystem.