MCP Holyrics

Monorepo em TypeScript para operar o Holyrics via MCP, com interpretacao de linguagem natural, busca de midias, CRUD de conteudos/eventos e automacao segura de playlist e agenda.

O projeto esta sendo construido em fases. Neste momento, a fundacao do monorepo ja esta pronta e a Fase 2 ja possui a primeira camada funcional de leitura: client HTTP real do Holyrics, casos de uso de leitura e registry inicial de tools no mcp-server.

Objetivo

• expor tools MCP para consultar e alterar dados do Holyrics
• interpretar comandos em PT-BR com LLM
• permitir busca de letras, musicas, textos, videos, audios, imagens e arquivos
• operar eventos, playlists e agendamentos com trilha de auditoria
• manter baixo custo, rodando localmente junto ao Holyrics

Stack

• Node.js 22+
• TypeScript
• pnpm
• turbo
• eslint
• vitest

Requisitos

• Node.js >=22
• pnpm 10.x
• Holyrics v2.26.0+
• token da API Server do Holyrics
• OpenAI API Key para a fase de orquestracao por linguagem natural

Setup

1. Instale as dependencias:

pnpm install

2. Crie o arquivo .env a partir do exemplo:

cp .env.example .env

3. Preencha os valores do ambiente:

• HOLYRICS_HOST: host da API Server do Holyrics
• HOLYRICS_PORT: porta da API Server
• HOLYRICS_TOKEN: token com as permissoes necessarias
• HOLYRICS_AUTH_MODE: token ou hash
• OPENAI_API_KEY: chave da OpenAI
• OPENAI_MODEL: modelo do orquestrador
• DATABASE_URL: caminho do SQLite local
• LOG_LEVEL: nivel de log

Comandos principais

• pnpm install: instala as dependencias do workspace
• pnpm dev: roda os apps em modo desenvolvimento via turbo
• pnpm build: compila todos os pacotes e apps
• pnpm typecheck: valida TypeScript no monorepo
• pnpm typecheck:shared: valida somente o package @mcp-holyrics/shared
• pnpm typecheck:watch: executa a checagem de tipos em modo watch
• pnpm lint: executa lint em todos os pacotes
• pnpm test: executa testes do workspace
• pnpm clean: limpa artefatos locais

Estrutura do monorepo

Apps

• apps/mcp-server: servidor MCP que vai registrar e expor as tools usadas pelo cliente MCP
• apps/llm-orchestrator: camada que vai transformar linguagem natural em chamadas seguras de tools
• apps/ops-ui: painel operacional para jobs, auditoria, confirmacoes e status do sistema

Packages

• packages/shared: utilitarios compartilhados do workspace, como config, errors, logger e result
• packages/tool-contracts: contratos e tipos de entrada/saida das tools MCP
• packages/domain: entidades e regras centrais do dominio do sistema
• packages/holyrics-client: adapter HTTP para a API do Holyrics, com autenticacao, transporte e mapeamento de erros
• packages/scheduler: agendamento local de execucoes, retries e persistencia de jobs

Responsabilidade de cada package

@mcp-holyrics/shared

Responsavel por infraestrutura transversal:

• configuracao do ambiente
• loadConfig() para ler .env e process.env
• erros tipados
• logger padrao
• tipo de retorno comum para casos de uso e tools

@mcp-holyrics/tool-contracts

Responsavel por:

• definir inputs e outputs das tools MCP
• padronizar requestId, idempotencyKey e contratos de busca
• centralizar os tipos que serao compartilhados entre mcp-server, domain e llm-orchestrator
• hoje contem contratos para get_schedules, get_events, search_lyrics, search_texts e search_media

@mcp-holyrics/domain

Responsavel por:

• entidades do negocio
• regras de seguranca e validacao
• casos de uso
• politicas de confirmacao e resolucao de ambiguidades
• hoje contem use cases de leitura para agenda, eventos, letras, textos e midias

@mcp-holyrics/holyrics-client

Responsavel por:

• encapsular a API do Holyrics
• implementar autenticacao token e hash
• abstrair diferencas entre chamadas locais e futuras chamadas remotas
• mapear respostas e erros da API para tipos internos
• hoje suporta GetSchedules, GetEvents, SearchLyrics, SearchText, GetAudios, GetVideos, GetImages e GetFiles

@mcp-holyrics/scheduler

Responsavel por:

• representar jobs agendados
• executar tools em horario futuro
• manter retries, idempotencia e coordenacao com auditoria

Fluxo arquitetural esperado

1. o usuario envia um pedido em linguagem natural
2. apps/llm-orchestrator interpreta a intencao e resolve entidades
3. apps/mcp-server seleciona e executa a tool correta
4. packages/domain aplica regras de negocio e seguranca
5. packages/holyrics-client chama a API do Holyrics
6. packages/scheduler entra no fluxo quando a execucao for futura
7. apps/ops-ui acompanha jobs, auditoria e confirmacoes

Estado atual

• Fase 0 concluida: descoberta tecnica, baseline e backlog inicial
• Fase 1 concluida: scaffold do monorepo, configs base e validacao de typecheck, lint e test
• Fase 2 em andamento:
• packages/holyrics-client implementado com auth token/hash, timeout e erros tipados
• packages/domain com use cases de leitura
• apps/mcp-server com registry inicial das tools de leitura
• tools de leitura disponiveis no registry:
• get_schedules
• get_events
• search_lyrics
• search_texts
• search_media

Documentacao complementar

• mcp-holyrics-execution-plan.md
• phase-0-api-matrix.md
• phase-0-v1-baseline.md
• phase-0-backlog.md

Observacoes importantes

• CRUD premium no Holyrics exige Holyrics Plan e permissao avancada habilitada
• operacoes com event_id em playlist dependem de Holyrics v2.26.0+
• o projeto ja possui integracao real com a API do Holyrics no packages/holyrics-client
• o apps/mcp-server ainda nao sobe um servidor MCP real com @modelcontextprotocol/sdk; por enquanto ele expone um registry interno de tools