# music21 MCP Server

Servidor MCP de **análise musical** usando music21 + FastMCP + Pydantic.

Complementa o seu [MIDI-compostion-tools-MCP](https://github.com/FernandoDaSilva-T/MIDI-compostion-tools-MCP) focado em construção:
enquanto o toolkit **constrói** composições, este servidor **analisa** arquivos existentes.

---

## 🛠 Tools disponíveis (8)

| Tool | O que faz |
|---|---|
| `score_info` | Visão geral: título, compositor, partes, assinaturas, duração |
| `analyze_key` | Detecta tonalidade (algoritmo Krumhansl-Schmuckler) com confiança |
| `analyze_harmony` | Extrai acordes, numerais romanos, cadências, progressão resumida |
| `analyze_melody` | Contorno, âmbito, intervalos, clímax, lista de notas |
| `analyze_rhythm` | Fórmula de compasso, tempo, densidade, síncope, padrões rítmicos |
| `analyze_form` | Detecta seções (A, B, A'…), repetições, forma geral (ABA, Rondó…) |
| `check_counterpoint` | Erros de voice-leading: quintas paralelas, cruzamentos, saltos |
| `analyze_motifs` | Motivos recorrentes e suas transformações (inversão, retrogrado…) |

---

## 📦 Instalação

```bash
# 1. Clonar / copiar a pasta music21-mcp
cd music21-mcp

# 2. Criar ambiente virtual (recomendado)
python -m venv .venv
source .venv/bin/activate      # Linux/macOS
.venv\Scripts\activate         # Windows

# 3. Instalar dependências
pip install -r requirements.txt
```

---

## ▶️ Executar

```bash
python server.py
```

O servidor roda via **stdio** — padrão para integração local com Claude Desktop, Cursor, etc.

---

## ⚙️ Configuração no Claude Desktop

Adicione ao seu `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "music21": {
      "command": "python",
      "args": ["/caminho/absoluto/para/music21-mcp/server.py"],
      "env": {}
    }
  }
}
```

> **Dica:** se usar virtualenv, use o Python do venv:
> `"/caminho/para/music21-mcp/.venv/bin/python"`

---

## 🔗 Integração com seu MCP Music Toolkit

Pipeline típico:

```
music21 MCP (analyze_harmony)
    → detecta progressão do arquivo
    → passa para seu toolkit (comp_set_progression)
    → gera variação ou arranjo

music21 MCP (check_counterpoint)
    → aponta erros no MIDI gerado
    → seu toolkit (theory_voice_lead_sequence)
    → corrige o voice leading
```

---

## 📁 Estrutura

```
music21-mcp/
├── server.py              # FastMCP — 8 tools registradas
├── models.py              # Pydantic schemas input/output
├── requirements.txt
├── analyzers/
│   ├── harmony.py         # Acordes + numerais romanos + cadências
│   ├── melody.py          # Contorno, âmbito, intervalos
│   ├── rhythm.py          # Tempo, densidade, síncope
│   ├── form.py            # Seções e forma musical
│   ├── counterpoint.py    # Erros de contraponto/voice-leading
│   ├── score_info.py      # Metadados e visão geral
│   └── motifs.py          # Padrões motívicos recorrentes
└── utils/
    └── loader.py          # Carregar arquivos + helpers music21
```

---

## 💡 Exemplo de uso

```python
# analyze_key
{
  "file_path": "/home/user/bach_prelude.mid",
  "response_format": "json"
}

# analyze_harmony com recorte de compasses
{
  "file_path": "/home/user/sonata.xml",
  "measures": [1, 16],
  "response_format": "markdown"
}

# analyze_motifs customizado
{
  "file_path": "/home/user/symphony.mid",
  "motif_length": 5,
  "min_occurrences": 3
}
```