EuConquisto Composer MCP

--- document: Requisitos de Acesso à API para Equipe de Desenvolvimento version: 1.0.0 status: pronto_para_submissao priority: CRÍTICO target_audience: Equipe de Desenvolvimento EuConquisto created: 2025-07-01 context: Implementação da Ferramenta MCP v1.1.0 --- # Requisitos de Acesso à API para Equipe de Desenvolvimento EuConquisto ## 🎯 **Resumo da Solicitação** **Solicitando**: Configuração de acesso à API para integração com a API DigitalPages **Finalidade**: Permitir criação e gerenciamento automatizado de composições via ferramentas Claude MCP **Status Atual**: Implementação completa, acesso à API bloqueado (erros 500) **Impacto no Negócio**: Viabiliza criação de conteúdo educacional via IA para instituições ## 📋 **Requisitos Técnicos Específicos** ### **1. Validação de Acesso do Token JWT** ⭐ **CRÍTICO** **Problema Atual**: Token JWT retorna 500 Internal Server Error **Necessário**: Validar e configurar acesso à API para o token JWT existente **Endpoints com Falha**: ``` ❌ GET https://api.digitalpages.com.br/auth/v1.0/user/me ❌ GET https://api.digitalpages.com.br/auth/v1.0/project/uid/36c92686-c494-ec11-a22a-dc984041c95d ❌ POST https://api.digitalpages.com.br/storage/v1.0/content/versions/dynamic ``` **Solicitação**: Por favor, verificar e habilitar acesso à API para o token JWT atualmente usado na interface do Composer. ### **2. Configuração de Acesso ao Projeto** **Detalhes do Projeto**: - **Project UID**: `36c92686-c494-ec11-a22a-dc984041c95d` - **Connector UID**: `93c952c2-680c-ed11-bd6e-dc98407f3f93` - **Project Key**: `e3894d14dbb743d78a7efc5819edc52e` - **Environment**: `prd` (produção) **Solicitação**: Confirmar se estes identificadores estão corretos e possuem as devidas permissões de acesso à API. ### **3. Endpoints da API Necessários** 🎯 **ESSENCIAL** Baseado na análise de tráfego de rede, a ferramenta MCP precisa de acesso a: #### **Endpoints de Autenticação** ``` GET /auth/v1.0/user/me GET /auth/v1.0/project/uid/{project_uid} GET /auth/v1.1/connector/uid/{connector_uid} ``` #### **Endpoints de Gerenciamento de Conteúdo** ``` POST /storage/v1.0/content/versions/dynamic ?manual_project_uid={project_uid}&uid={composition_uid} GET /storage/v1.0/content/versions/?uid={composition_uid} GET /storage/v1.0/content ?uid={composition_uid}&access_token={jwt}&project_key={key}&api_env=prd ``` **Solicitação**: Habilitar acesso programático a estes endpoints com as credenciais de autenticação atuais. ## 🔍 **Contexto Técnico** ### **Método de Descoberta** Os endpoints da API foram descobertos através de **monitoramento de tráfego de rede ao vivo** durante operações manuais de criação e salvamento de composições na interface do Composer. ### **Arquitetura de Integração** ``` Solicitação do Usuário → Ferramenta Claude MCP → API DigitalPages → Armazenamento Persistente ↓ ↓ Cache localStorage Persistência Server-side ``` ### **Status da Implementação Atual** - ✅ **Ferramenta MCP**: Implementação completa pronta - ✅ **Fluxo de Autenticação**: Implementado baseado nos padrões descobertos - ✅ **Estrutura de Requisições**: Compatível com o tráfego de rede observado - ❌ **Acesso à API**: Bloqueado com 500 Internal Server Error ### **Análise das Interfaces C#** 🔍 **NOVAS DESCOBERTAS** Baseado na análise dos arquivos de interface C#, os seguintes padrões de autorização são críticos: #### **Requisitos de Autorização** ```csharp // IBaseAuthorization.cs - Componentes de autorização necessários - Role: RoleType (ver roles específicos abaixo) - EntityUid: Guid? (associação da entidade) - UserUid: Guid? (usuário executando a ação) - AuthorUid: Guid? (usuário que criou a autorização) - DirectoryUid: Guid? (contexto do diretório) - ProjectUid: Guid? (contexto do projeto) ← CRÍTICO ``` #### **Roles Necessários para Gerenciamento de Composições** ```csharp // De Enums.cs - Roles prováveis para operações do composer ManagedContentAdmin = 1L << 30, // Gerenciamento completo de composições ManagedContentContributor = 1L << 31, // Criar/editar composições ManagedContentViewer = 1L << 32, // Visualizar composições ``` #### **Análise do Tipo de Connector** ```csharp // De Enums.cs - Enum ConnectorType Composer_1 = 100, // ← Este é o tipo de connector do Composer ``` #### **Requisitos do IComposerObject** ```csharp // IComposerObject.cs - Campos obrigatórios para objetos de composição - ObjectUid: Guid (identificador do objeto da composição) - ContentUid: Guid (identificador do conteúdo da composição) - ObjectData: string (dados JSON da composição) - Type: string (tipo da composição) - Version: string (versão da composição) - ConnectorUid: Guid (deve corresponder ao connector Composer_1) ← CRÍTICO ``` ## 📊 **Comportamento Observado vs. Necessário** ### **Processo Manual Funcionando** ✅ 1. Usuário faz login no Composer com token JWT 2. Usuário cria composição manualmente 3. Composição salva com sucesso via API 4. Tráfego de rede mostra chamadas de API bem-sucedidas ### **Processo Automatizado Bloqueado** ❌ 1. Ferramenta MCP autentica com o mesmo token JWT 2. Ferramenta MCP tenta chamadas de API idênticas 3. **API retorna 500 Internal Server Error** 4. Criação de composição falha **Lacuna**: Mesmas credenciais funcionam manualmente mas falham programaticamente. ## 🚨 **Detalhes Específicos do Erro** ### **Erro de Autenticação** ```json { "statusCode": 500, "message": "Internal server error", "activityId": "1c7e8b8b-1ecb-4b92-a9f6-837ebaecc3df" } ``` ### **Headers de Requisição Utilizados** ``` Authorization: Bearer {jwt_token} Content-Type: application/json Accept: application/json ``` **Perguntas para a Equipe de Dev**: 1. São necessários headers adicionais para acesso programático? 2. É necessária uma chave de API ou registro de aplicação? 3. Existem limitações de taxa ou restrições de IP? 4. O escopo do token JWT é suficiente para essas operações? ### **🔍 NOVO: Perguntas Baseadas nas Interfaces C#** ⭐ **CRÍTICO** Baseado na análise das interfaces C#, perguntas adicionais sobre autorização: 5. **Autorização de Role**: O token JWT possui os roles necessários? - `ManagedContentContributor` (1L << 31) para criação de composições? - `ManagedContentAdmin` (1L << 30) para gerenciamento completo? 6. **Autorização de Connector**: O usuário está autorizado para o connector do Composer? - ConnectorUid: `93c952c2-680c-ed11-bd6e-dc98407f3f93` - ConnectorType: `Composer_1 = 100` 7. **Permissões no Nível do Projeto**: As autorizações no nível do projeto estão configuradas adequadamente? - ProjectUid: `36c92686-c494-ec11-a22a-dc984041c95d` - Necessário: Permissões ManagedContent no nível do projeto 8. **Acesso no Nível do Diretório**: É necessária autorização no nível do diretório? - Associação DirectoryUid necessária? - Permissões com escopo de diretório para criação de conteúdo? 9. **Estrutura IComposerObject**: Nossas chamadas de API estão usando a estrutura de objeto correta? - Distinção entre ObjectUid vs ContentUid - ConnectorUid obrigatório no payload da composição - Campos Type e Version adequados ## 💼 **Justificativa de Negócio** ### **Caso de Uso** Permitir que educadores criem conteúdo profissional do Composer através de prompts em linguagem natural via Claude Desktop, eliminando o fluxo de trabalho manual de criação de composições. ### **Usuários-Alvo** - Instituições educacionais usando a plataforma EuConquisto - Professores criando conteúdo educacional interativo - Criadores de conteúdo que precisam de desenvolvimento rápido de composições ### **Benefícios Esperados** - **Criação de conteúdo 10x mais rápida** através de automação via IA - **Gerenciamento profissional de composições** com armazenamento persistente - **Confiabilidade de nível empresarial** para uso institucional ## 🎯 **Ações Solicitadas** ### **Imediato (Alta Prioridade)** 1. **Validar Token JWT**: Confirmar se o token atual possui permissões de acesso à API 2. **Verificar Acesso ao Projeto**: Verificar se project UID e connector UID estão configurados adequadamente 3. **Habilitar Endpoints**: Garantir que os endpoints listados aceitem requisições programáticas 4. **Testar Acesso à API**: Executar teste básico de autenticação com as credenciais atuais ### **Configuração (Prioridade Média)** 1. **Revisão de Headers**: Confirmar headers necessários para acesso programático 2. **Limitação de Taxa**: Esclarecer quaisquer restrições de uso da API 3. **Configuração de Ambiente**: Validar configuração do ambiente de produção 4. **Tratamento de Erros**: Fornecer documentação de códigos de erro para tratamento adequado ### **Documentação (Prioridade Baixa)** 1. **Documentação da API**: Compartilhar documentação oficial da API se disponível 2. **Guia de Autenticação**: Fornecer diretrizes de autenticação programática 3. **Melhores Práticas**: Compartilhar padrões recomendados para integração com API ## 📋 **Requisitos de Teste** ### **Caso de Teste Mínimo** Por favor, habilitar um teste simples para verificar acesso à API: ```bash # Testar autenticação curl -H "Authorization: Bearer {jwt_token}" \ https://api.digitalpages.com.br/auth/v1.0/user/me # Esperado: 200 OK com dados do usuário # Atual: 500 Internal Server Error ``` ### **Critérios de Sucesso** - ✅ Endpoints de autenticação retornam 200 OK - ✅ Endpoint de salvamento de composição aceita requisições POST - ✅ Endpoints de verificação retornam dados da composição - ✅ Mesmas permissões da interface manual do Composer ## 🔄 **Processo de Acompanhamento** ### **Após Habilitação do Acesso à API** 1. **Teste Imediato**: Validar todos os endpoints com suite de testes 2. **Teste de Integração**: Validação completa do fluxo de trabalho da ferramenta MCP 3. **Aceitação do Usuário**: Deploy no Claude Desktop para testes institucionais 4. **Configuração de Monitoramento**: Acompanhar uso e métricas de performance da API ### **Métricas de Sucesso** - **Técnico**: 100% de taxa de sucesso dos endpoints da API - **Funcional**: Fluxo de trabalho completo de criação de composições - **Experiência do Usuário**: <30 segundos do prompt à composição visualizável ## 📞 **Informações de Contato** **Equipe de Implementação**: Projeto de Integração Claude Code **Contato Técnico**: Ricardo Kawasaki **Prioridade do Projeto**: ALTA - Bloqueando deploy de produção **Cronograma**: Habilitação imediata solicitada para rollout institucional --- ## 📎 **Documentação de Apoio** - **Análise de Tráfego de Rede**: `/docs/analysis/network-traffic-analysis-results-v1.0.0.md` - **Implementação da API**: `/src/api/digitalpages-api-client.js` - **Resultados de Teste**: `/logs/test-reports/v1.1.0-validation-*.md` - **Ferramenta MCP Completa**: `/dist/inject-and-view-composition-v1.1.0.js` **Toda a implementação técnica está completa e pronta para deploy imediato após habilitação do acesso à API.**