poliedro-mcp

# Poliedro MCP Server (integração com Claude Desktop) [](LICENSE) Servidor MCP **não oficial** para consultar informações do portal Poliedro/P+ no Claude Desktop. Este projeto não é afiliado, endossado ou mantido pelo Poliedro Sistema de Ensino. Funcionalidades: - Boletim / notas - Mensagens / notificações - Calendário escolar: próximos eventos, semana, mês e ano - Funciona com Claude Desktop (vide docs/) ## Requisitos - Python 3.11 ou superior - macOS (o setup salva a senha no Keychain; em Linux use `POLIEDRO_TOKEN`) - Conta ativa no [P+](https://pmais.p4ed.com/) (responsável ou aluno) ## Primeira instalação Execute os comandos **na raiz do repositório** (`poliedro-mcp/`), não dentro de `config/`: ```bash cd poliedro-mcp python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt pip install -e . cp config/config.example.json config/config.json ``` O `config.json` inicial pode manter só a `base_url` correta; os demais campos (`auth`, `student`, `calendar`) são preenchidos no passo de login abaixo. ### Login e configuração automática ```bash python -m poliedro_mcp.setup_login ``` O script: 1. Pede o **usuário** (se `auth.username` estiver vazio ou for placeholder no config) 2. Pede a **senha** (mesma do login em https://pmais.p4ed.com/) 3. Valida o acesso na API do Poliedro 4. Salva a senha no Keychain do macOS (serviço `poliedro-pmais`) 5. Atualiza `config/config.json` com `username`, dados do aluno e calendário Confira no final a saída com `school_id`, `email_p4ed`, `enrollment_id`, etc. ### Validar instalação ```bash python -m poliedro_mcp.cli health python -m poliedro_mcp.cli grades python -m poliedro_mcp.cli messages python -m poliedro_mcp.cli calendar next ``` ## Segurança Não coloque senha nem token no `config.json`. Autenticação suportada: 1. **Keychain** (recomendado no Mac) — configure com `python -m poliedro_mcp.setup_login` 2. **Token manual** — variável de ambiente `POLIEDRO_TOKEN` (útil em CI/Linux) Para produção remota, substitua o Keychain por Secret Manager, KMS ou cofre equivalente. ## Problemas comuns ### `HTTP 401` / `Invalid user credentials` A API rejeitou usuário ou senha. Confira: - Usuário igual ao do P+ (ex.: `nome.sobrenome`, sem `@p4ed.com`) - Senha digitada corretamente (o terminal **não mostra** caracteres ao digitar) - Conta funcionando no site https://pmais.p4ed.com/ Rode o setup de novo após corrigir: ```bash cd /caminho/para/poliedro-mcp source .venv/bin/activate python -m poliedro_mcp.setup_login ``` ### `ModuleNotFoundError: poliedro_mcp` Ative o venv e instale o pacote na raiz do repo: ```bash source .venv/bin/activate pip install -e . ``` ### `Arquivo de configuração não encontrado` ```bash cp config/config.example.json config/config.json ``` ### Config em outro caminho ```bash export POLIEDRO_CONFIG=/caminho/absoluto/config.json ``` ## Rodar como MCP stdio ```bash python -m poliedro_mcp.server ``` ## Configuração no Claude Desktop Substitua `/CAMINHO/ABSOLUTO/poliedro-mcp` pelo caminho real do projeto: ```json { "mcpServers": { "poliedro": { "command": "/CAMINHO/ABSOLUTO/poliedro-mcp/.venv/bin/python", "args": ["-m", "poliedro_mcp.server"], "cwd": "/CAMINHO/ABSOLUTO/poliedro-mcp" } } } ``` ## Ferramentas MCP expostas - `poliedro_health_check` - `get_grades` - `get_unread_messages` - `get_messages` - `get_next_events` - `get_week_events` - `get_month_events` - `get_year_events` ## Observação sobre remoto Este projeto está pronto para virar um MCP remoto, mas o mais seguro é validar localmente antes. Para remoto, recomenda-se: - HTTPS obrigatório - Autenticação do MCP - Tokens Poliedro criptografados por usuário - Banco de dados para mapa usuário → credenciais - Secrets Manager/KMS ## Licença Este projeto está licenciado sob a [MIT License](LICENSE). O código deste repositório é open source; o uso da API e do portal P+ continua sujeito aos termos de uso do Poliedro. Cada usuário é responsável por suas próprias credenciais e pelo cumprimento desses termos.