Skip to main content
Glama

MaestroMCP

Servidor MCP para IA Musical - Bridge entre assistentes de IA e sintetizadores MIDI.

🎯 Descrição

MaestroMCP é um servidor M### 5. Validar Ferramenta Debug

No MCP Inspector:

  1. Conecte-se ao servidor

  2. Vá para a aba "Tools"

  3. Encontre debug_hello_world

  4. Execute com ou sem parâmetros

  5. Verifique o output JSON

Related MCP server: Cloudflare Playwright MCP

🎵 Ferramentas MIDI Disponíveis

midi_list_ports

Lista todas as portas MIDI disponíveis (entrada e saída).

midi_create_virtual_port

Cria porta virtual MIDI para conexão com DAWs como GarageBand.

midi_send_note

Envia mensagens MIDI Note On/Off com controle de velocity e canal.

midi_send_cc

Envia mensagens Control Change para volume, pan, effects, etc.

midi_sequence_commands

Executa sequências complexas de comandos MIDI com timing preciso.

debug_hello_world

Ferramenta de debug para validação do servidor.

🧪 Exemplos de Uso

Via Claude Desktop

Liste as portas MIDI disponíveis
Toque a nota C4 com velocity 100 no canal 1
Crie uma sequência musical tocando C4, E4, G4 com 500ms de duração cada

Via MCP Inspectorxt Protocol (MCP) desenvolvido em TypeScript que estabelece a fundação técnica para um ecossistema de IA musical. Implementa 5 ferramentas MIDI fundamentais usando WebMidi.js para controle de sintetizadores e dispositivos musicais.

📋 Características

  • ✅ Servidor MCP completo - Implementação oficial usando @modelcontextprotocol/sdk

  • ✅ 5 Ferramentas MIDI - Lista portas, criação virtual, notas, CC, sequências

  • ✅ WebMidi.js Integration - Suporte nativo para MIDI em Node.js

  • ✅ Integração Claude Desktop - Configuração completa para uso no Claude

  • ✅ MCP Inspector Support - Testado e validado via interface oficial

  • ✅ TypeScript nativo - Código tipado e moderno

  • ✅ Error handling robusto - Tratamento adequado de erros

  • ✅ Arquitetura escalável - Preparada para futuras funcionalidades musicais

🛠️ Instalação

Pré-requisitos

  • Node.js >= 18.0.0

  • npm ou yarn

Instalação

# Clone/navegue até o diretório do projeto
cd MaestroMCP

# Instale as dependências
npm install

# Compile o projeto
npm run build

🚀 Uso

1. Executar o Servidor

# Modo desenvolvimento (compila e executa)
npm run dev

# Modo produção
npm start

2. Configurar no Claude Desktop

Para usar o MaestroMCP com Claude Desktop, adicione a seguinte configuração ao arquivo claude_desktop_config.json:

macOS:

Localização: ~/Library/Application\ Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "maestro-mcp": {
      "command": "node",
      "args": [
        "/Users/SEU_USUARIO/Desktop/Encantaria Suite/Maestro2.0/MaestroMCP/dist/server.js"
      ],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Windows:

Localização: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "maestro-mcp": {
      "command": "node",
      "args": [
        "C:\\Users\\SEU_USUARIO\\Desktop\\Encantaria Suite\\Maestro2.0\\MaestroMCP\\dist\\server.js"
      ]
    }
  }
}

Linux:

Localização: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "maestro-mcp": {
      "command": "node",
      "args": [
        "/home/SEU_USUARIO/Desktop/Encantaria Suite/Maestro2.0/MaestroMCP/dist/server.js"
      ]
    }
  }
}

Importante:

  • Substitua SEU_USUARIO pelo seu nome de usuário real

  • Ajuste o caminho conforme sua instalação

  • Certifique-se de que o projeto foi compilado (npm run build)

  • Reinicie o Claude Desktop após adicionar a configuração

3. Verificar Integração

Após configurar:

  1. Compile o projeto:

    npm run build
  2. Reinicie o Claude Desktop completamente

  3. Teste no Claude Desktop:

    Liste as ferramentas MIDI disponíveis
  4. Verifique se as ferramentas aparecem:

    • debug_hello_world

    • midi_list_ports

    • midi_create_virtual_port

    • midi_send_note

    • midi_send_cc

    • midi_sequence_commands

4. Testar com MCP Inspector (Desenvolvimento)

# Lança servidor + MCP Inspector
npm run inspector

O MCP Inspector abrirá automaticamente no navegador. Caso não abra:

  1. Acesse http://localhost:6274

  2. Use o token de autenticação exibido no terminal

3. Validar Ferramenta Debug

No MCP Inspector:

  1. Conecte-se ao servidor

  2. Vá para a aba "Tools"

  3. Encontre debug_hello_world

  4. Execute com ou sem parâmetros

  5. Verifique o output JSON

🧪 Ferramenta Debug

debug_hello_world

Descrição: Ferramenta de debug que retorna mensagem personalizada + metadata do servidor.

Input Schema:

{
  message?: string  // Mensagem personalizada (opcional, default: "Hello World")
}

Output:

{
  "success": true,
  "message": "Hello World",
  "timestamp": "2025-01-XX...",
  "server_status": "operational", 
  "debug_info": {
    "server_name": "MaestroMCP",
    "version": "0.1.0"
  }
}

Exemplos:

# Via MCP Inspector - sem parâmetros
# Retorna: message="Hello World"

# Via MCP Inspector - com parâmetro personalizado  
# Input: {"message": "Test successful"}
# Retorna: message="Test successful"

📁 Estrutura do Projeto

MaestroMCP/
├── package.json              # Dependências e scripts
├── tsconfig.json            # Configuração TypeScript  
├── src/
│   ├── server.ts           # Servidor MCP principal
│   ├── tools/
│   │   └── debug.ts        # Ferramenta debug
│   └── types/
│       └── index.ts        # Types do projeto  
├── dist/                   # Build compilado
└── README.md              # Esta documentação

🔧 Scripts Disponíveis

  • npm run build - Compila TypeScript → JavaScript

  • npm start - Executa servidor compilado

  • npm run dev - Compila + executa em modo desenvolvimento

  • npm run watch - Compila em modo watch

  • npm run inspector - Lança servidor + MCP Inspector

  • npm test - Alias para executar servidor

🐛 Debug e Troubleshooting

Servidor não conecta

  1. Verifique se compilou sem erros:

    npm run build
  2. Teste execução direta:

    node dist/server.js
  3. Verifique logs de erro (stderr não interfere no protocolo MCP)

MCP Inspector não funciona

  1. Verifique se está rodando na porta correta:

    • Inspector UI: http://localhost:6274

    • Proxy Server: http://localhost:6277

  2. Use token de autenticação exibido no terminal

  3. Limpe cache do navegador se necessário

Ferramenta não aparece

  1. Verifique se servidor iniciou sem logs de erro

  2. Recompile após mudanças: npm run build

  3. Restart do MCP Inspector

🎼 Próximos Passos

Esta é a base técnica. Futuras versões incluirão:

  • 🎹 Integração MIDI real - WebMidi.js para sintetizadores

  • 🎵 Geração musical - Algoritmos de composição automática

  • 🎧 Análise de áudio - Integração com IaraMCP

  • 🎛️ Controle semântico - Mapeamento linguagem → parâmetros musicais

  • 🎸 Suporte multi-instrumentos - Roland S-1 e outros

  • 🎚️ Performance em tempo real - Resposta musical contextual

📄 Licença

MIT

🤝 Contribuindo

  1. Fork o projeto

  2. Crie uma branch para sua feature

  3. Commit suas mudanças

  4. Abra um Pull Request


MaestroMCP v0.1.0 - Fundação para o futuro da IA musical. 🎵✨

Available Tools

11 tools
audio_analyze_realtimeAnalyze Audio RealtimeB

Perform real-time audio analysis with pitch detection and spectral features

Inputs: analysis_type, duration_ms, pitch_detection, spectral_features.

audio_midi_feedbackAudio MIDI Feedback SystemC

Continuous audio monitoring and intelligent learning feedback for AI improvement

Inputs: analysis_depth, include_raw_data, monitoring_duration.

audio_start_captureStart Audio CaptureC

Initialize real-time audio capture for MIDI-audio correlation analysis

Inputs: bufferSize, latencyHint, sampleRate, source.

configure_musical_intelligence🧠 Configure Musical Intelligence & Superior Audio SystemC

Configure global musical intelligence settings and superior audio feedback system (sample rate, buffer size, analysis capabilities)

Inputs: audio_feedback_level, auto_sustain, default_articulation, enable_harmonic_analysis, +9 more.

debug_hello_worldDebug Hello WorldC

Ferramenta de debug que retorna mensagem personalizada

Inputs: message.

midi_list_portsList MIDI PortsC

Lists all available MIDI input and output ports

Inputs: refresh.

midi_play_and_listenMIDI Play and ListenC

Execute MIDI sequence while analyzing audio response - core of the self-listening AI system

Inputs: outputPort (required), sequence (required), audio_analysis, correlation_mode, +1 more.

midi_play_phraseMIDI Play PhraseB

🎼 Play musical phrase with natural articulation and expression - converts 'C4 E4 G4' to legato/staccato

Inputs: notes (required), channel, outputPort, rhythm, +2 more.

midi_send_cc_enhanced🎛️ Enhanced MIDI Control Change with Superior Audio ContextA

Send MIDI CC with musical context awareness and real-time analysis of CC effects on audio output. REPLACES basic midi_send_cc with enhanced capabilities.

Inputs: controller (required), value (required), channel, outputPort.

midi_send_note_enhanced🎼 Enhanced MIDI Send Note with Superior Audio HearingA

Send MIDI note with automatic musical expression, real-time spectral/temporal/pitch analysis, and superior audio feedback. REPLACES basic midi_send_note with enhanced capabilities.

Inputs: note (required), action, channel, duration, +2 more.

midi_sequence_commands_enhanced🎵 Enhanced MIDI Sequence with Superior Audio AnalysisA

Execute MIDI sequence with musical intelligence and comprehensive temporal/spectral audio analysis during execution. REPLACES basic midi_sequence_commands and midi_sequence_with_articulation with enhanced capabilities.

Inputs: commands (required), outputPort.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 11 tools

    Disambiguation3/5

    The tools have some clear distinctions, such as between audio analysis and MIDI operations, but there is overlap and potential confusion. For example, 'midi_play_and_listen' and 'midi_sequence_commands_enhanced' both involve playing MIDI sequences with audio analysis, making their boundaries unclear. Additionally, the 'enhanced' tools replace basic ones, which could lead to misselection if both were present, but since they are replacements, this is mitigated.

    Naming Consistency4/5

    Most tools follow a consistent snake_case pattern with clear prefixes like 'audio_' or 'midi_', which aids readability. However, there are minor deviations: 'debug_hello_world' uses a different naming style (no prefix, mixed language in description), and some tool names include emojis or lengthy descriptions that break the pattern slightly. Overall, the naming is mostly predictable and well-structured.

    Tool Count5/5

    With 11 tools, the count is well-scoped for a server focused on audio and MIDI processing with AI integration. Each tool appears to serve a distinct purpose within this domain, such as capture, analysis, configuration, and playback, without feeling excessive or insufficient. This number supports comprehensive functionality while remaining manageable.

    Completeness4/5

    The tool set covers key aspects of audio-MIDI interaction, including capture, analysis, playback, and configuration, with enhanced versions for core operations. A minor gap is the lack of explicit tools for stopping or managing ongoing processes (e.g., stop capture or reset), but agents can likely work around this using existing tools. The domain is well-represented with no major dead ends.

    Related MCP Connectors

    Related MCP Servers