Submit
vbarreiratt

MaestroMCP

Community vbarreiratt
Updated

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

🎵 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. 🎵✨

MCP Server · Populars

MCP Server · New