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