# MIDI Composition Tools

An MCP (Model Context Protocol) toolkit for AI-powered MIDI composition with theory tools, orchestration, and analysis.

## What is MCP?

The Model Context Protocol (MCP) is an open source standard created by Anthropic to standardize how AI (LLMs) communicate with external tools and services through a JSON-RPC interface.

## Features

- **AI Music Generation**: Uses AI models to create musical compositions
- **MIDI Output**: Generates standard MIDI files
- **Flexible Configuration**: Define style, tempo, duration, and instruments
- **MCP Protocol**: Standardized interface compatible with MCP clients

## Installation

```bash
cd mini-services/mcp-music-generator
bun install
```

## Development

```bash
bun run dev
```

The server will start in stdio (stdin/stdout communication) for integration with MCP clients.

## Available Tools

### generate_music

Generates an AI music composition and returns it as MIDI.

**Parameters:**
- `prompt` (string): Description of the desired music
- `style` (string, optional): Music style (e.g., "classical", "jazz", "electronic", "rock", "ambient")
- `tempo` (number, optional): BPM of the music (default: 120)
- `duration` (number, optional): Duration in seconds (default: 30)
- `key` (string, optional): Key (e.g., "C", "A", "F#m")
- `timeSignature` (string, optional): Time signature (default: "4/4")

**Returns:**
- `midiData` (string): Base64 encoded MIDI file
- `midiFile` (string): MIDI filename
- `description` (string): Description of the generated music

### list_instruments

Lists available MIDI instruments (General MIDI).

**Returns:**
- `instruments` (array): List of instruments with ID and name

### generate_melody

Generates a melody based on a prompt.

**Parameters:**
- `prompt` (string): Melody description
- `length` (number, optional): Number of notes (default: 16)
- `key` (string, optional): Key (default: "C")

**Returns:**
- `notes` (array): List of notes with duration and pitch
- `midiData` (string): MIDI in base64

## MCP Client Integration

### Claude Desktop

Add to your Claude Desktop configuration file:

```json
{
  "mcpServers": {
    "music-generator": {
      "command": "bun",
      "args": ["/home/z/my-project/mini-services/mcp-music-generator/src/index.ts"],
      "env": {}
    }
  }
}
```

### Other MCP Clients

The server implements the standard MCP protocol through stdio:

```bash
bun run src/index.ts
```

## Usage with AI

When connected to an MCP client, the AI assistant can:

1. Receive requests like "Create a smooth jazz music"
2. Use the `generate_music` tool with appropriate parameters
3. Receive the generated MIDI file
4. Explain the created composition

### Interaction Example:

**User:** "Generate a smooth classical music in C major"

**AI:** Using the generate_music tool:
- style: "classical"
- key: "C"
- tempo: 80
- duration: 60

**Result:** MIDI file with a classical composition in C major.

## Project Structure

```
mcp-music-generator/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── mcp-server.ts     # MCP protocol implementation
│   ├── music-generator.ts # Music generation logic
│   └── midi-writer.ts   # MIDI file generator
├── package.json
├── tsconfig.json
└── README.md
```

## MCP Protocol

The server implements:
- **Initialize**: Initial connection setup
- **Tools/List**: List of available tools
- **Tools/Call**: Tool execution
- **Resources/List**: List of available resources
- **Resources/Read**: Resource reading
- **Prompts/List**: List of available prompts
- **Prompts/Get**: Get prompts

## License

MIT