# 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:

```bash
pnpm install
```

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

```bash
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](./apps/mcp-server): servidor MCP que vai registrar e expor as tools usadas pelo cliente MCP
- [apps/llm-orchestrator](./apps/llm-orchestrator): camada que vai transformar linguagem natural em chamadas seguras de tools
- [apps/ops-ui](./apps/ops-ui): painel operacional para jobs, auditoria, confirmacoes e status do sistema

### Packages
- [packages/shared](./packages/shared): utilitarios compartilhados do workspace, como `config`, `errors`, `logger` e `result`
- [packages/tool-contracts](./packages/tool-contracts): contratos e tipos de entrada/saida das tools MCP
- [packages/domain](./packages/domain): entidades e regras centrais do dominio do sistema
- [packages/holyrics-client](./packages/holyrics-client): adapter HTTP para a API do Holyrics, com autenticacao, transporte e mapeamento de erros
- [packages/scheduler](./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](./docs/mcp-holyrics-execution-plan.md)
- [phase-0-api-matrix.md](./docs/phase-0-api-matrix.md)
- [phase-0-v1-baseline.md](./docs/phase-0-v1-baseline.md)
- [phase-0-backlog.md](./docs/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