EduBase

Servidor MCP EduBase

Este repositório contém a implementação do Protocolo de Contexto de Modelo (MCP) servidor para a plataforma EduBase. Ele permite que clientes MCP (por exemplo, Claude Desktop) e LLMs interajam com sua conta EduBase e executem tarefas em seu nome. Ele suporta os protocolos de transporte stdio, SSE e HTTP transmissível.

O que é EduBase?

EduBase é uma plataforma educacional online, inovadora, modular e interativa que torna o aprendizado mais agradável, simples e interativo, adequada para instituições de ensino ou empresas.

Por que escolher EduBase?

EduBase revoluciona o aprendizado digital com sua combinação única de recursos:

• Sistema Avançado de Quiz com parametrização que permite variações infinitas da mesma questão, detecção de fraude em tempo real, tipografia LaTeX elegante, suporte avançado a STEM e correção automática
• Ambiente de Aprendizado Unificado que centraliza todo o seu conteúdo educacional — vídeos, exames, documentos e módulos SCORM — em um sistema intuitivo
• Segurança de Nível Empresarial com recursos como integração SSO, controles de acesso granulares, auditoria abrangente e conformidade com GDPR
• Integração com seus sistemas existentes por meio de LTI, API abrangente e opções de integração personalizadas
• Ferramentas Assistidas por IA, como o Assistente EduBase, que podem transformar instantaneamente seu conteúdo existente em quizzes e avaliações interativas, ou traduzir seus materiais de um idioma para outro

De instituições de ensino superior a departamentos de treinamento corporativo, a EduBase se adapta às suas necessidades específicas, mantendo uma experiência de usuário intuitiva em todos os dispositivos.

Vídeo de demonstração

Criando e enviando questões colaborativamente, agendando exames e analisando resultados de usuários com Claude:

Obtendo suas credenciais de API

Após fazer login, no seu Painel, procure o menu Integrações, clique em "adicionar integração" e escolha o tipo "API EduBase".

Se você não vir esta opção, insira o código de ativação MCPGITHUB ou entre em contato conosco para solicitar acesso em info@edubase.net.

Ferramentas

Cada endpoint de API documentado está disponível como uma ferramenta, nomeada edubase_<method>_<endpoint>. Por exemplo, a ferramenta para o endpoint GET /user:me é nomeada edubase_get_user_me. Os endpoints de tag, permissão e transferência funcionam da mesma forma para cada tipo de conteúdo, então eles compartilham uma única ferramenta por método com um argumento type (por exemplo, edubase_post_content_tag para POST /exam:tag, POST /quiz:tag, etc.). Consulte nossa documentação para desenvolvedores para mais informações.

Conjuntos de ferramentas

As ferramentas são agrupadas em conjuntos de ferramentas, para que você possa expor apenas as ferramentas necessárias. Menos ferramentas usam menos contexto do modelo e facilitam a escolha da ferramenta correta pelo modelo. Todo conjunto de ferramentas está habilitado por padrão.

Conjunto de ferramentas	Ferramentas para
files	Uploads de arquivos temporários (sempre habilitado)
questions	Questões
quizzes	Conjuntos de quiz, suas questões, configurações e predefinições de avaliação
exams	Exames, suas configurações, usuários, certificados e identidade visual
results	Resultados de quiz e exames, downloads de certificados
users	Usuários, seus nomes, grupos e links de login
classes	Turmas e associações de turmas
organizations	Organizações, membros, departamentos, competências e webhooks
integrations	Integrações e suas chaves
tags	Tags e anexos de tags de conteúdos
permissions	Permissões de usuários em conteúdos e transferências de propriedade
metrics	Métricas personalizadas

Selecione conjuntos de ferramentas com uma lista separada por vírgulas em EDUBASE_TOOLSETS (por exemplo, questions,quizzes,exams). Defina EDUBASE_READONLY=true para expor apenas as ferramentas que leem dados (as ferramentas get, e as ferramentas que apenas geram links de download, como edubase_post_question_export).

Defina EDUBASE_DYNAMIC_TOOLSETS=true para habilitar conjuntos de ferramentas sob demanda: as sessões começam apenas com as ferramentas críticas, e o modelo habilita os conjuntos de ferramentas necessários com a ferramenta edubase_enable_toolsets (listada com edubase_list_toolsets). Isso mantém a lista inicial de ferramentas pequena para clientes que carregam todas as ferramentas antecipadamente, mas requer um cliente que atualize a lista de ferramentas quando notificado sobre mudanças.

Quando um transporte HTTP é usado, os clientes podem restringir ainda mais a configuração para sua própria sessão com os cabeçalhos EduBase-Mcp-Toolsets, EduBase-Mcp-ReadOnly e EduBase-Mcp-Dynamic, ou os parâmetros de consulta toolsets, read_only e dynamic_toolsets (por exemplo, https://domain.edubase.net/mcp?toolsets=exams&read_only=true). Uma sessão nunca pode habilitar conjuntos de ferramentas ou ferramentas de escrita que a configuração do servidor desabilita.

Configuração

O servidor MCP pode ser configurado usando variáveis de ambiente. As seguintes variáveis estão disponíveis:

Variável	Descrição	Obrigatória	Valor padrão
EDUBASE_API_URL	A URL base da API EduBase, provavelmente https://subdomain.edubase.net/api.	Sim	https://www.edubase.net/api
EDUBASE_API_APP	O ID do aplicativo da sua integração no EduBase, o app na API EduBase. Encontre isso na janela de detalhes da integração no EduBase.	Não se o transporte HTTP for usado com autenticação, caso contrário Sim	-
EDUBASE_API_KEY	A chave secreta do seu aplicativo de integração no EduBase, o secret na API EduBase. Encontre isso junto com o ID do aplicativo na janela de detalhes da integração no EduBase.	Não se o transporte HTTP for usado com autenticação, caso contrário Sim	-
EDUBASE_SSE_MODE	Inicia o servidor MCP em modo HTTP com transporte SSE. O valor deve ser true.	Não	false
EDUBASE_STREAMABLE_HTTP_MODE	Inicia o servidor MCP em modo HTTP com transporte HTTP transmissível. O valor deve ser true.	Não	false
EDUBASE_TOOLSETS	Lista separada por vírgulas dos conjuntos de ferramentas habilitados, ou all.	Não	all
EDUBASE_READONLY	Apenas expõe as ferramentas que leem dados. O valor deve ser true.	Não	false
EDUBASE_OUTPUT_SCHEMAS	Esquemas de saída das ferramentas e resultados estruturados de ferramentas: off lista as ferramentas sem esquemas de saída e retorna os resultados apenas como texto JSON, on inclui os esquemas de saída completos, fields inclui os esquemas de saída sem as descrições dos campos (mantendo os resultados estruturados, mas economizando a maioria dos tokens dos esquemas).	Não	fields
EDUBASE_CONFIG_PROVIDERS	Lista separada por vírgulas dos provedores de hospedagem autorizados a fornecer configuração de sessão nas solicitações quando um transporte HTTP é usado. Atualmente apenas smithery é suportado (o parâmetro de consulta config codificado em base64).	Não	-
EDUBASE_DYNAMIC_TOOLSETS	Inicia sessões apenas com as ferramentas de upload de arquivos e permite que o modelo habilite conjuntos de ferramentas sob demanda. O valor deve ser true.	Não	false
EDUBASE_HTTP_PORT	O servidor HTTP escutará nesta porta se o modo de transporte SSE ou HTTP transmissível for usado.	Não	3000
EDUBASE_OAUTH	Habilita o comportamento de recurso protegido OAuth 2.1: solicitações não autenticadas são rejeitadas com 401 + WWW-Authenticate apontando para /.well-known/oauth-protected-resource, e tokens de portador são encaminhados para a API EduBase.	Não	false
EDUBASE_OAUTH_AUTHORIZATION_SERVER	URL base pública da implantação EduBase atuando como IdP OAuth. Usada para anunciar o servidor de autorização no documento de metadados do recurso protegido.	Não	derivada de EDUBASE_API_URL
EDUBASE_OAUTH_RESOURCE_URL	URL base pública deste servidor MCP (o indicador de recurso OAuth). Usada no cabeçalho WWW-Authenticate e nos metadados do recurso.	Não	derivada de EDUBASE_API_URL
EDUBASE_ALLOW_PRIVATE_NETWORK	Quando um transporte HTTP é usado, a ferramenta edubase_filebin bloqueia solicitações de saída para endereços privados, loopback, link-local e reservados (proteção SSRF) e recusa caminhos de arquivos locais. Defina como true para permiti-los, por exemplo, uma implantação auto-hospedada em uma rede privada confiável. Não tem efeito no modo stdio, onde o usuário local é o único chamador.	Não	false
EDUBASE_FILEBIN_ALLOWED_HOSTS	Lista opcional separada por vírgulas de nomes de host permitidos como destinos de upload edubase_filebin (host exato ou qualquer subdomínio, por exemplo, edubase.net). Quando vazia, qualquer host público é permitido (ainda sujeito à filtragem de endereços acima).	Não	-

Uso como servidor MCP remoto

Você pode usar o servidor MCP EduBase como um servidor MCP remoto para seu cliente MCP. Para isso, você precisa hospedar o servidor MCP onde os clientes possam acessá-lo e, em seguida, configurar o cliente para se conectar ao servidor. Inicie-o com o modo de transporte SSE ou HTTP transmissível e sempre use HTTPS ao acessar o servidor remotamente pela internet!

Autenticação com servidores remotos

Você pode usar o servidor em dois modos:

• Sem autenticação do cliente: Neste modo, o servidor não exigirá nenhuma autenticação do cliente. Isso é útil para fins de teste ou desenvolvimento, ou em uma rede fechada, mas não é recomendado para uso em produção. Para isso, você deve configurar o servidor com EDUBASE_API_APP e EDUBASE_API_KEY também!
• Com autenticação por token de portador: Neste modo, o servidor exigirá que um token de portador seja enviado com cada solicitação. Esta é a maneira recomendada de usar o servidor em produção. Você pode obter o token de portador da sua conta EduBase criando um aplicativo de integração e fornecendo o ID do aplicativo e a chave secreta no formato {app}:{secret}, codificados em base64 como um token. O servidor usará então este token para autenticar o cliente e autorizar o acesso aos endpoints da API.
• Com OAuth 2.1 (EduBase como IdP): Quando EDUBASE_OAUTH=true, clientes compatíveis (Claude Desktop, conectores Claude.ai, Cursor, conectores ChatGPT, etc.) descobrem o servidor de autorização EduBase através de /.well-known/oauth-protected-resource, registram-se dinamicamente (RFC 7591), guiam o usuário por uma tela de consentimento EduBase e trocam um código de autorização (com PKCE S256) por um token de acesso opaco. O servidor MCP encaminha esse token literalmente para a API EduBase, que o resolve para a integração MCP provisionada automaticamente, criada no primeiro consentimento. Sem necessidade de copiar ID do aplicativo/Chave secreta — os usuários apenas clicam em "Conectar EduBase" em seu cliente.

Uso com Claude Desktop

Para um passo a passo detalhado, consulte nossa postagem no blog sobre como conectar EduBase com Claude: O Guia Completo de Integração MCP.

Usando o servidor MCP EduBase fornecido

Você pode usar o servidor MCP EduBase fornecido (se disponível) sem qualquer configuração, apenas adicionando-o como um servidor remoto em seu cliente com a URL https://domain.edubase.net/mcp (substitua pelo domínio real), se ele suportar autenticação OAuth, ou com o token de portador apropriado no cabeçalho Authorization (Authorization: Bearer ${BASE64_ENCODED_TOKEN}).

Recomendado para usuários de www.edubase.net, pois o servidor é mantido e atualizado por nós, e você não precisa se preocupar em hospedá-lo ou configurá-lo. Apenas certifique-se de usar a URL e o método de autenticação corretos ao conectar seu cliente.

Instalando manualmente

Adicione o seguinte ao seu claude_desktop_config.json:

Usando Node.js

Antes de executar o servidor MCP, certifique-se de ter o Node.js instalado. Você pode baixá-lo em nodejs.org ou usar um gerenciador de pacotes como brew.

{
  "mcpServers": {
    "edubase": {
      "command": "npx",
      "args": [
        "-y",
        "@edubase/mcp"
      ],
      "env": {
        "EDUBASE_API_URL": "https://domain.edubase.net/api",
        "EDUBASE_API_APP": "your_integration_app_id",
        "EDUBASE_API_KEY": "your_integration_secret_key"
      }
    }
  }
}

Ou baixe a versão do servidor MCP EduBase ou clone o repositório e execute npm run build para compilar o servidor. Não se esqueça de ajustar /path/to/dist para o diretório real e configurar as variáveis de ambiente!

{
  "mcpServers": {
    "edubase": {
      "command": "node",
      "args": [
        "/path/to/dist/index.js"
      ],
      "env": {
        "EDUBASE_API_URL": "https://domain.edubase.net/api",
        "EDUBASE_API_APP": "your_integration_app_id",
        "EDUBASE_API_KEY": "your_integration_secret_key"
      }
    }
  }
}

Usando Docker

Antes de executar o servidor MCP, certifique-se de ter o Docker instalado e em execução. Você pode baixá-lo em docker.com ou usar um gerenciador de pacotes. Não se esqueça de configurar as variáveis de ambiente!

{
  "mcpServers": {
    "edubase": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "EDUBASE_API_URL",
        "-e",
        "EDUBASE_API_APP",
        "-e",
        "EDUBASE_API_KEY",
        "edubase/mcp"
      ],
      "env": {
        "EDUBASE_API_URL": "https://domain.edubase.net/api",
        "EDUBASE_API_APP": "your_integration_app_id",
        "EDUBASE_API_KEY": "your_integration_secret_key"
      }
    }
  }
}

Instalando via servidor MCP remoto

Você pode usar o servidor MCP EduBase fornecido (se disponível) como um servidor remoto. Recomendamos codificar em Base64 seus EDUBASE_API_APP e EDUBASE_API_KEY e usá-los como um token Bearer no cabeçalho Authorization (Authorization: Bearer ${BASE64_ENCODED_TOKEN}).

{
  "mcpServers": {
    "edubase": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://domain.edubase.net/mcp",
        "--header",
        "Authorization: Bearer ${EDUBASE_API_APP}:${EDUBASE_API_KEY}"
      ]
    }
  }
}

Instalação via Smithery

Para instalar o servidor MCP EduBase para o Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @EduBase/MCP --client claude

Desenvolvimento

Execute npm test para compilar o servidor e verificar a listagem de ferramentas: os orçamentos de tamanho da lista de ferramentas e das instruções do servidor, as descrições das ferramentas, o conjunto de ferramentas, os modos de conjuntos de ferramentas somente leitura e dinâmicos, e o tratamento de configuração do transporte HTTP. Quando novas ferramentas excederem um orçamento, encurte seus esquemas ou aumente o orçamento em test/server.test.mjs deliberadamente, pois cada cliente paga pela lista de ferramentas em cada sessão.

Contato

Site: www.edubase.net
Documentação do desenvolvedor: developer.edubase.net
E-mail: info@edubase.net