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

Servidor no conecta

1. Verifique se compilou sem erros:

   npm run build
   

2. Teste execuo direta:

   node dist/server.js
   

3. Verifique logs de erro (stderr no interfere no protocolo MCP)

MCP Inspector no funciona

1. Verifique se est rodando na porta correta:

   • Inspector UI: http://localhost:6274
   • Proxy Server: http://localhost:6277

2. Use token de autenticao exibido no terminal

3. Limpe cache do navegador se necessrio

Ferramenta no aparece

1. Verifique se servidor iniciou sem logs de erro
2. Recompile aps mudanas: npm run build
3. Restart do MCP Inspector

Prximos Passos

Esta a base tcnica. Futuras verses incluiro:

• Integrao MIDI real - WebMidi.js para sintetizadores
• Gerao musical - Algoritmos de composio automtica
• Anlise de udio - Integrao com IaraMCP
• Controle semntico - Mapeamento linguagem parmetros musicais
• Suporte multi-instrumentos - Roland S-1 e outros
• Performance em tempo real - Resposta musical contextual

Licena

MIT

Contribuindo

1. Fork o projeto
2. Crie uma branch para sua feature
3. Commit suas mudanas
4. Abra um Pull Request

---

MaestroMCP v0.1.0 - Fundao para o futuro da IA musical.