MaestroMCP

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

Descrio

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 parmetros
5. Verifique o output JSON

Ferramentas MIDI Disponveis

midi_list_ports

Lista todas as portas MIDI disponveis (entrada e sada).

midi_create_virtual_port

Cria porta virtual MIDI para conexo 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 sequncias complexas de comandos MIDI com timing preciso.

debug_hello_world

Ferramenta de debug para validao do servidor.

Exemplos de Uso

Via Claude Desktop

Liste as portas MIDI disponveis

Toque a nota C4 com velocity 100 no canal 1

Crie uma sequncia musical tocando C4, E4, G4 com 500ms de durao cada

Via MCP Inspectorxt Protocol (MCP) desenvolvido em TypeScript que estabelece a fundao tcnica para um ecossistema de IA musical. Implementa 5 ferramentas MIDI fundamentais usando WebMidi.js para controle de sintetizadores e dispositivos musicais.

Caractersticas

• Servidor MCP completo - Implementao oficial usando @modelcontextprotocol/sdk
• 5 Ferramentas MIDI - Lista portas, criao virtual, notas, CC, sequncias
• WebMidi.js Integration - Suporte nativo para MIDI em Node.js
• Integrao Claude Desktop - Configurao completa para uso no Claude
• MCP Inspector Support - Testado e validado via interface oficial
• TypeScript nativo - Cdigo tipado e moderno
• Error handling robusto - Tratamento adequado de erros
• Arquitetura escalvel - Preparada para futuras funcionalidades musicais

Instalao

Pr-requisitos

• Node.js >= 18.0.0
• npm ou yarn

Instalao

# Clone/navegue at o diretrio do projeto
cd MaestroMCP

# Instale as dependncias
npm install

# Compile o projeto
npm run build

Uso

1. Executar o Servidor

# Modo desenvolvimento (compila e executa)
npm run dev

# Modo produo
npm start

2. Configurar no Claude Desktop

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

macOS:

Localizao: ~/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:

Localizao: %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:

Localizao: ~/.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 usurio real
• Ajuste o caminho conforme sua instalao
• Certifique-se de que o projeto foi compilado (npm run build)
• Reinicie o Claude Desktop aps adicionar a configurao

3. Verificar Integrao

Aps configurar:

1. Compile o projeto:

   npm run build
   

2. Reinicie o Claude Desktop completamente

3. Teste no Claude Desktop:

   Liste as ferramentas MIDI disponveis
   

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)

# Lana servidor + MCP Inspector
npm run inspector

O MCP Inspector abrir automaticamente no navegador. Caso no abra:

1. Acesse http://localhost:6274
2. Use o token de autenticao 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 parmetros
5. Verifique o output JSON

Ferramenta Debug

debug_hello_world

Descrio: 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 parmetros
# Retorna: message="Hello World"

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

Estrutura do Projeto

MaestroMCP/
 package.json              # Dependncias e scripts
 tsconfig.json            # Configurao TypeScript  
 src/
    server.ts           # Servidor MCP principal
    tools/
       debug.ts        # Ferramenta debug
    types/
        index.ts        # Types do projeto  
 dist/                   # Build compilado
 README.md              # Esta documentao

Scripts Disponveis

• 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 - Lana servidor + MCP Inspector
• npm test - Alias para executar servidor

Debug e Troubleshooting

Se…