# usp-mcp

Feito por Caio Castro & João Pedro Gunthen

Consulta em português a sistemas acadêmicos da USP: o cardápio dos bandejões, os prazos e
o material do e-Disciplinas, e o catálogo de disciplinas do JupiterWeb.

Ele não tem interface própria. Você o conecta a um assistente e passa a poder perguntar em
linguagem comum. A resposta vem dos sistemas da USP, no momento da pergunta.

Qualquer assistente que fale MCP serve. Este guia mostra os passos com o Claude, porque é
o que os autores usam, e a seção *Onde ele funciona* conta o resto.

Projeto não-oficial, sem nenhum vínculo com a Universidade de São Paulo.

Você não precisa saber programar para usar, nem contribuir com nada: instale, conecte e
pergunte. Quem quiser mexer no código encontra o combinado em *Escopo e contribuição*.

[<img src="docs/demo/demo-multi-agente-poster.jpg" alt="Demo: três assistentes respondendo ao vivo pelo usp-mcp" width="100%">](docs/demo/demo-multi-agente.mp4)

Três perguntas reais, respondidas ao vivo por três assistentes diferentes usando o mesmo
servidor. Clique na imagem para ver o vídeo.

## O que ele responde

| Pergunta que você faz | Onde ele busca |
|---|---|
| "O que tem no bandejão hoje, na sexta ou na semana inteira?" | Cardápio dos quatro restaurantes, com horário e preço |
| "Quais matérias eu tenho?" | Suas disciplinas no e-Disciplinas: as do semestre primeiro, com a sigla que as outras perguntas usam |
| "O que eu tenho para entregar essa semana?" | Tarefas e questionários do e-Disciplinas, com prazo |
| "Que arquivos tem em PTC3314?" | Lista o material da disciplina: regras, listas, provas antigas |
| "Como é a avaliação de PTC3314?" | Lê o texto que o professor escreveu na página da disciplina |
| "Baixa a lista 2 pra mim" | Baixa o arquivo e diz onde ele ficou no seu computador |
| "Já entreguei o EP1?" | O que você já enviou, o que ficou só como rascunho e se saiu no prazo |
| "Perdi algum prazo?" | O que já venceu e o e-Disciplinas não registra como entregue, rascunho salvo incluído |
| "Como estou de nota?" | As notas que o professor lançou no e-Disciplinas, de todas as disciplinas ou item a item de uma |
| "O professor avisou alguma coisa?" | Os recados nos fóruns da disciplina, o mural de avisos primeiro |
| "Mudou alguma coisa desde ontem?" | O que mexeu na disciplina nos últimos dias: arquivo novo, tópico novo, prazo alterado |
| "Quantos créditos vale MAC0110?" | Créditos, carga horária e ementa pela sigla; programa, bibliografia e avaliação sob pedido |
| "O que preciso ter feito antes de MAT2454?" | Pré-requisitos, pelo seu currículo |

Bandejão e JupiterWeb funcionam para qualquer pessoa. O e-Disciplinas mostra as **suas**
disciplinas, então ele precisa de uma chave sua, e obter essa chave dá um pouco mais de
trabalho. A seção *Configuração* explica.

## Onde ele funciona

O programa roda no seu computador, e o assistente fala com ele ali mesmo. Três lugares
costumam ser confundidos por terem o mesmo nome, e a diferença entre eles decide se a
instalação vai dar certo:

| Onde você pergunta | Funciona? |
|---|---|
| Claude Desktop, que é o **chat** no aplicativo de computador | sim, e é onde entra o bloco de configuração da próxima seção |
| Claude Code, no terminal ou na aba Code do aplicativo | sim, e o registro é por linha de comando |
| claude.ai aberto no **navegador** | não |

O navegador fica de fora porque, do lado do site, não existe nada capaz de conversar com um
programa que está na sua máquina. Não é um defeito à espera de conserto: é a outra face de
uma decisão registrada do projeto, que é a sua chave do e-Disciplinas nunca sair do seu
computador. Pelo navegador nem o bandejão responde, e ele nem chave usa.

O Claude aparece nesse quadro porque é o assistente que os autores usam, e não porque o
projeto precise dele. Por dentro, isto aqui é um servidor MCP comum, o padrão aberto que os
assistentes usam para falar com ferramentas, e não há uma linha de código escrita para um
assistente em particular. A seção *Detalhes técnicos*, no fim do arquivo, diz o que foi
medido a esse respeito.

## Instalando

Este é um MCP: um conjunto de ferramentas que um assistente passa a saber usar. A
instalação tem duas partes. Primeiro você baixa o projeto para o seu computador. Depois
você avisa o assistente que ele existe, e esse segundo passo muda conforme o lugar do
quadro acima.

Os comandos mudam conforme o sistema do seu computador, e por isso esta seção separa Mac,
Windows e Linux. Se não tiver certeza de qual é o seu: Mac tem uma maçã no canto de cima
da tela, Windows tem o botão Iniciar embaixo, e quem usa Linux costuma saber que usa.

### O caminho rápido

Se você já tem o Claude Code, escolha abaixo a mensagem do seu sistema, mande-a para ele
e pule o resto desta seção. Ele instala, confere, configura e te guia nos passos que
precisam da sua mão. Um deles acontece sempre, que é o da chave do e-Disciplinas. O outro
só aparece se faltar o Python ou o `git` no seu computador, e o quanto ele resolve sozinho
aí depende do sistema.

As três mensagens fazem a mesma coisa. O que muda são os caminhos e os comandos de cada
sistema, e é por isso que a mensagem de um sistema não serve num computador de outro: o
assistente segue o que está escrito, e a pessoa que colou não tem como perceber o erro.
A conferência que elas pedem roda sem internet e sem a chave, e é a mesma nos três.

As três mandam o assistente instalar o que faltar, e não só explicar como se instala. Até
onde ele consegue ir sozinho, porém, depende do sistema, e as mensagens dizem isso em vez
de prometer o mesmo nos três. No Windows, o `winget` já vem com o Windows 11 e faz a
instalação na sua conta: o Python entra sem perguntar nada, e o Git abre uma janela de
confirmação do sistema que é sua para responder. No Mac, com o Homebrew já instalado nada
é perguntado, mas instalar o próprio Homebrew pede a sua senha. No Linux, o instalador de
programas da distribuição exige `sudo`, e senha ninguém digita por você. A regra, nos
três, é a mesma: o assistente tenta instalar sozinho primeiro, e só pede "abra este site"
quando não existe instalador de programas ou quando a senha é necessária. Quando for
necessária, ele avisa logo no começo, em vez de você descobrir no meio.

#### No Mac

```text
Instale o usp-mcp neste computador e me conecte a ele. Estou num Mac.

1. Confira se existe Python 3.11 ou mais novo (`python3 --version`) e se existe o `git`,
   que é o programa que baixa o projeto no passo 2. Se faltar algum, instale você mesmo,
   em vez de só me explicar como se instala. Veja primeiro se este computador já tem o
   Homebrew, que é o instalador de programas mais usado no Mac: se `brew --version`
   responder, rode `brew install` com o que estiver faltando (`brew install python`,
   `brew install git`, ou os dois) e siga, porque isso não pede senha. Se não
   houver Homebrew, me diga isso antes de começar qualquer outra coisa: instalar o
   próprio Homebrew pede a minha senha de administrador, e quem digita a senha sou eu.
   Nesse caso me passe o comando que a página brew.sh mostra, espere eu rodar e digitar a
   senha, e continue. Se eu responder que prefiro não instalar o Homebrew, o caminho sem
   ele é baixar o Python em python.org e rodar `xcode-select --install`, que traz o `git`;
   aí também espere eu avisar que terminei.
2. Clone https://github.com/CaioCastro1/usp-mcp em ~/usp-mcp, crie um venv em
   ~/usp-mcp/.venv e instale com `~/usp-mcp/.venv/bin/pip install -e ~/usp-mcp`. Copie
   ~/usp-mcp/.env.example para ~/usp-mcp/.env.
3. Confira a instalação com este comando, que não usa internet nem chave:
   `~/usp-mcp/.venv/bin/python -m usp_mcp.rucard.server --auto-verificar`. Repita
   trocando `rucard` por `jupiter` e depois por `moodle`. Os três têm de terminar sem
   erro. O do moodle vai dizer que o MOODLE_TOKEN está AUSENTE, e isso é esperado: a
   chave é o passo 5.
4. Registre os três servidores no meu Claude Code, no escopo de usuário, com os nomes
   usp-moodle, usp-jupiter e usp-rucard, apontando para
   ~/usp-mcp/.venv/bin/usp-mcp-moodle, ~/usp-mcp/.venv/bin/usp-mcp-jupiter e
   ~/usp-mcp/.venv/bin/usp-mcp-rucard. Use o caminho completo, começando em /Users/,
   no lugar do ~.
5. O e-Disciplinas precisa de uma chave pessoal minha, e este passo tem duas
   partes. A primeira parte é sua: rode você mesmo, no seu terminal, o comando
   `~/usp-mcp/scripts/token.sh`. Não me peça para rodar esse comando; a minha
   parte aqui é só o navegador.
   A segunda parte é essa: o navegador que o comando abre na página do
   e-Disciplinas, e nela quem me guia é você.
   UM PASSO POR MENSAGEM: diga o que fazer, espere eu responder que fiz, e só
   então mande o próximo. Não me mande a lista inteira de uma vez. Nessa página
   o que vale é o link azul escrito "Clique aqui se a aplicação não abrir
   automaticamente"; a caixa verde "O seu cadastro foi confirmado" e o botão
   cinza "Ambientes" são distração. Mande eu clicar nesse link azul com o botão
   direito e escolher "copiar endereço do link", e me avise que o botão
   esquerdo não copia nada, só tenta abrir o aplicativo do Moodle.
6. No fim, rode de novo o comando do moodle do passo 3: agora ele tem de dizer que o
   MOODLE_TOKEN está presente. Me diga o que ficou funcionando e o que eu ainda preciso
   fazer.

Me explique em português comum. Eu não sei o que são MCP, venv, token, Homebrew nem
escopo de usuário: quando precisar de uma dessas palavras, diga numa frase o que ela
significa antes de usar.
```

#### No Windows

No Windows 11 você não precisa preparar nada antes de mandar a mensagem: o sistema já vem
com o `winget`, que é o instalador de programas da Microsoft, e a mensagem abaixo manda o
assistente usá-lo para instalar o Python e o Git se estiverem faltando. O Python entra só
na sua conta e não pergunta nada. O Git abre a janela de confirmação do Windows, a que
pergunta se você permite que o programa faça alterações no computador: responder é com
você, e numa conta que não seja de administrador ela pede a senha de uma que seja. Num
Windows mais antigo, que não tenha `winget`, o assistente cai no caminho dos sites
oficiais: o Python em python.org, marcando na instalação a caixa "Add python.exe to
PATH", e o Git em git-scm.com. Aí a instalação é sua, e ele espera.

```text
Instale o usp-mcp neste computador e me conecte a ele. Estou no Windows. Não use
comandos nem caminhos de Mac ou Linux: aqui o ambiente isolado não tem a pasta `bin`,
tem `Scripts`, e os programas terminam em `.exe`. Os comandos abaixo estão em
PowerShell; se você rodar por outro terminal, adapte a forma, mas mantenha `Scripts` e
`.exe`.

1. Confira se existe Python 3.11 ou mais novo (`python --version`) e se existe o `git`,
   que é o programa que baixa o projeto no passo 2. Se o `python` abrir a Microsoft Store
   ou não existir, conte como ausente. Se faltar algum dos dois, instale você mesmo, em
   vez de só me explicar como se instala: use o `winget`, que vem no Windows 11. Os
   comandos são `winget install --id Python.Python.3.13 -e --scope user` e
   `winget install --id Git.Git -e --scope user`; se `winget search Python.Python`
   mostrar uma versão 3 mais nova que a 3.13, use a mais nova. O do Python instala só na
   minha conta e não pergunta nada. O do Git abre a janela de confirmação do Windows, e
   quem responde sou eu: me avise antes que ela vai aparecer, e espere. Depois de
   instalar, abra uma janela nova do PowerShell e siga por ela: a janela que já estava
   aberta não enxerga o que acabou de ser instalado. Se este Windows não tiver `winget`,
   aí sim me diga para instalar pelos sites oficiais, o Python em python.org marcando a
   caixa "Add python.exe to PATH" e o Git em git-scm.com, e espere eu avisar que
   instalei.
2. Clone https://github.com/CaioCastro1/usp-mcp em $HOME\usp-mcp, crie um venv em
   $HOME\usp-mcp\.venv e instale com
   `& $HOME\usp-mcp\.venv\Scripts\pip install -e $HOME\usp-mcp`. Copie
   $HOME\usp-mcp\.env.example para $HOME\usp-mcp\.env.
3. Confira a instalação com este comando, que não usa internet nem chave:
   `& $HOME\usp-mcp\.venv\Scripts\python.exe -m usp_mcp.rucard.server --auto-verificar`.
   Repita trocando `rucard` por `jupiter` e depois por `moodle`. Os três têm de terminar
   sem erro. O do moodle vai dizer que o MOODLE_TOKEN está AUSENTE, e isso é esperado: a
   chave é o passo 5.
4. Registre os três servidores no meu Claude Code, no escopo de usuário, com os nomes
   usp-moodle, usp-jupiter e usp-rucard, apontando para
   C:\Users\MEU-USUARIO\usp-mcp\.venv\Scripts\usp-mcp-moodle.exe,
   C:\Users\MEU-USUARIO\usp-mcp\.venv\Scripts\usp-mcp-jupiter.exe e
   C:\Users\MEU-USUARIO\usp-mcp\.venv\Scripts\usp-mcp-rucard.exe, com o meu nome de
   usuário no lugar de MEU-USUARIO.
5. O e-Disciplinas precisa de uma chave pessoal minha, e este passo tem duas
   partes. A primeira parte é sua: rode você mesmo, no seu terminal, o comando
   `& $HOME\usp-mcp\.venv\Scripts\usp-mcp-token.exe`. Ele foi instalado no
   passo 2, ao lado dos três do passo 4, e roda aqui mesmo no PowerShell, sem
   trocar de terminal. Não me peça para rodar esse comando; a minha parte aqui é
   só o navegador.
   A segunda parte é essa: o navegador que o comando abre na página do
   e-Disciplinas, e nela quem me guia é você.
   UM PASSO POR MENSAGEM: diga o que fazer, espere eu responder que fiz, e só
   então mande o próximo. Não me mande a lista inteira de uma vez. Nessa página
   o que vale é o link azul escrito "Clique aqui se a aplicação não abrir
   automaticamente"; a caixa verde "O seu cadastro foi confirmado" e o botão
   cinza "Ambientes" são distração. Mande eu clicar nesse link azul com o botão
   direito e escolher "copiar endereço do link", e me avise que o botão
   esquerdo não copia nada, só tenta abrir o aplicativo do Moodle.
   Se o comando encerrar sem receber o endereço, logo depois de eu copiar rode
   `Get-Clipboard | & $HOME\usp-mcp\.venv\Scripts\usp-mcp-token.exe`.
6. No fim, rode de novo o comando do moodle do passo 3: agora ele tem de dizer que o
   MOODLE_TOKEN está presente. Me diga o que ficou funcionando e o que eu ainda preciso
   fazer.

Me explique em português comum. Eu não sei o que são MCP, venv, token, winget nem
escopo de usuário: quando precisar de uma dessas palavras, diga numa frase o que ela
significa antes de usar.
```

#### No Linux

```text
Instale o usp-mcp neste computador e me conecte a ele. Estou no Linux.

1. Confira se existe Python 3.11 ou mais novo (`python3 --version`) e se existe o `git`,
   que é o programa que baixa o projeto no passo 2. Se faltar algum, diga de uma vez, no
   começo, que essa parte é minha: o instalador de programas daqui (`apt`, `dnf` ou
   `pacman`, conforme a distribuição) só roda com `sudo`, o `sudo` pede a minha senha, e
   senha quem digita sou eu. Não tente instalar sozinho nem me peça a senha. Veja qual
   dos três existe nesta máquina, monte o comando, me explique numa frase o que ele
   instala e espere eu rodar e avisar. Os pacotes são `python3`, `python3-venv` e `git`
   no Debian e no Ubuntu (`sudo apt install python3 python3-venv git`), `python3` e `git`
   no Fedora (`sudo dnf install python3 git`), e `python` e `git` no Arch
   (`sudo pacman -S python git`).
2. Clone https://github.com/CaioCastro1/usp-mcp em ~/usp-mcp, crie um venv em
   ~/usp-mcp/.venv e instale com `~/usp-mcp/.venv/bin/pip install -e ~/usp-mcp`. Copie
   ~/usp-mcp/.env.example para ~/usp-mcp/.env. Se a criação do venv falhar dizendo que
   falta o ensurepip, o pacote do sistema que falta costuma se chamar python3-venv, e
   vale a mesma regra do passo 1: monte o comando com `sudo`, me explique e espere eu
   rodar.
3. Confira a instalação com este comando, que não usa internet nem chave:
   `~/usp-mcp/.venv/bin/python -m usp_mcp.rucard.server --auto-verificar`. Repita
   trocando `rucard` por `jupiter` e depois por `moodle`. Os três têm de terminar sem
   erro. O do moodle vai dizer que o MOODLE_TOKEN está AUSENTE, e isso é esperado: a
   chave é o passo 5.
4. Registre os três servidores no meu Claude Code, no escopo de usuário, com os nomes
   usp-moodle, usp-jupiter e usp-rucard, apontando para
   ~/usp-mcp/.venv/bin/usp-mcp-moodle, ~/usp-mcp/.venv/bin/usp-mcp-jupiter e
   ~/usp-mcp/.venv/bin/usp-mcp-rucard. Use o caminho completo, começando em /home/, no
   lugar do ~.
5. O e-Disciplinas precisa de uma chave pessoal minha, e este passo tem duas
   partes. A primeira parte é sua: rode você mesmo, no seu terminal, o comando
   `~/usp-mcp/scripts/token.sh`. Não me peça para rodar esse comando; a minha
   parte aqui é só o navegador.
   A segunda parte é essa: o navegador que o comando abre na página do
   e-Disciplinas, e nela quem me guia é você.
   UM PASSO POR MENSAGEM: diga o que fazer, espere eu responder que fiz, e só
   então mande o próximo. Não me mande a lista inteira de uma vez. Nessa página
   o que vale é o link azul escrito "Clique aqui se a aplicação não abrir
   automaticamente"; a caixa verde "O seu cadastro foi confirmado" e o botão
   cinza "Ambientes" são distração. Mande eu clicar nesse link azul com o botão
   direito e escolher "copiar endereço do link", e me avise que o botão
   esquerdo não copia nada, só tenta abrir o aplicativo do Moodle.
   O script lê a área de transferência com `wl-paste` ou `xclip`; se não houver
   nenhum dos dois, ele avisa, e aí, logo depois de eu copiar o endereço, rode
   `wl-paste | ~/usp-mcp/scripts/token.sh` ou
   `xclip -selection clipboard -o | ~/usp-mcp/scripts/token.sh`, conforme o que existir.
6. No fim, rode de novo o comando do moodle do passo 3: agora ele tem de dizer que o
   MOODLE_TOKEN está presente. Me diga o que ficou funcionando e o que eu ainda preciso
   fazer.

Me explique em português comum. Eu não sei o que são MCP, venv, token, sudo nem escopo de
usuário: quando precisar de uma dessas palavras, diga numa frase o que ela significa
antes de usar.
```

O que acontece depois de colar, em qualquer dos três: o assistente roda os primeiros
passos sozinho e mostra o que está fazendo. Se faltar o Python ou o `git`, ele para logo
no primeiro passo, e o que acontece aí depende do sistema, como está acima: no Windows ele
instala, com a janela de confirmação do Git para você responder; no Mac com Homebrew ele
instala e segue sozinho; no Linux, e no Mac sem Homebrew, ele monta o comando e devolve a
vez para você, porque a senha é sua. No passo da chave ele para de novo e passa a falar
com você, uma instrução por vez: abrir a página do e-Disciplinas, achar o link, copiar o
endereço dele. Essa parada acontece sempre, e a seção *Configuração* descreve essa página
com calma, para o caso de você querer saber o que está clicando. Quando ele disser que
terminou, feche e abra o Claude Code: é aí que os três servidores passam a existir para
ele.

### O caminho manual

Você vai precisar do Python 3.11 ou mais novo. Para saber qual você tem, abra o terminal e
cole:

```bash
python3 --version
```

Se o Terminal responder que não conhece o comando `python3`, ou se o número for menor que
3.11, instale a versão atual pelo site python.org antes de seguir. Se você já usa o
Homebrew, `brew install python` também serve, e é o que o caminho rápido pede ao
assistente. Com uma versão mais antiga, o passo de instalação abaixo falha com uma
mensagem do pip que não explica o motivo.

Depois cole estes quatro comandos, um de cada vez:

```bash
git clone https://github.com/CaioCastro1/usp-mcp.git ~/usp-mcp
python3 -m venv ~/usp-mcp/.venv
~/usp-mcp/.venv/bin/pip install -e ~/usp-mcp
cp ~/usp-mcp/.env.example ~/usp-mcp/.env
```

O primeiro baixa o projeto para uma pasta chamada `usp-mcp` dentro da sua pasta pessoal. O
segundo cria, dentro dela, um ambiente isolado, sem alterar o Python nem os programas já
instalados no computador. O terceiro instala o projeto nesse ambiente. O quarto cria o
arquivo de configuração a partir do modelo que vem no projeto: ele já traz preenchida a
única coisa que o bandejão precisa, e é nele que a sua chave do e-Disciplinas vai ficar
guardada depois.

Tudo fica junto em `~/usp-mcp`, de propósito. O programa lê o arquivo de configuração de
dentro dessa pasta, então não instale o projeto em outro lugar separado dela. Para
desinstalar, basta apagar a pasta.

Se o Terminal disser que não conhece o comando `git`, no Mac ele mesmo oferece instalar na
hora: aceite, espere terminar e repita o primeiro comando.

Para conferir se deu certo:

```bash
ls ~/usp-mcp/.venv/bin | grep usp
```

Tem que aparecer `usp-mcp-jupiter`, `usp-mcp-moodle` e `usp-mcp-rucard`. Junto deles
aparece também `usp-mcp-token`, que é o programa da chave do e-Disciplinas e não um
servidor; ele entra na seção *Configuração*.

Agora avise o assistente que eles existem. Em qualquer um dos caminhos abaixo você troca
`SEU-USUARIO` pelo nome da sua conta no computador; se não souber qual é, o comando
`whoami` no Terminal responde.

**No Claude Desktop**, a configuração mora num arquivo. Pelo menu, o caminho até ele é
Configurações, depois Desenvolvedor, depois o botão que edita a configuração (em inglês,
Settings e Developer). Se preferir abrir o arquivo direto, no Mac ele é

```text
~/Library/Application Support/Claude/claude_desktop_config.json
```

e no Linux, `~/.config/Claude/claude_desktop_config.json`. Se ele estiver vazio, cole isto
inteiro:

```json
{
  "mcpServers": {
    "usp-rucard": { "command": "/Users/SEU-USUARIO/usp-mcp/.venv/bin/usp-mcp-rucard" },
    "usp-jupiter": { "command": "/Users/SEU-USUARIO/usp-mcp/.venv/bin/usp-mcp-jupiter" },
    "usp-moodle": { "command": "/Users/SEU-USUARIO/usp-mcp/.venv/bin/usp-mcp-moodle" }
  }
}
```

Se já tiver alguma coisa escrita, não troque o conteúdo pelo de cima: as três linhas `usp-`
entram dentro do `mcpServers` que já está lá, depois do que já existe, com uma vírgula
separando uma da outra.

**No Claude Code**, não há arquivo para editar à mão. Cole estes três comandos no Terminal,
um de cada vez:

```bash
claude mcp add usp-rucard --scope user -- /Users/SEU-USUARIO/usp-mcp/.venv/bin/usp-mcp-rucard
claude mcp add usp-jupiter --scope user -- /Users/SEU-USUARIO/usp-mcp/.venv/bin/usp-mcp-jupiter
claude mcp add usp-moodle --scope user -- /Users/SEU-USUARIO/usp-mcp/.venv/bin/usp-mcp-moodle
```

O `--scope user` é o que faz o registro valer em qualquer pasta, e não só na que você
estiver quando rodar o comando.

**Em outro assistente que fale MCP**, a ideia é a mesma: apontar o programa para os três
comandos que apareceram no passo anterior. Onde essa configuração se escreve muda de
assistente para assistente, e quem diz é a documentação de cada um.

No Linux, o começo do caminho é `/home/` em vez de `/Users/` nos dois blocos. No Windows os
caminhos são outros, e a subseção *No Windows*, logo abaixo, diz o que muda e o que ainda
não foi conferido por ninguém.

Feche e abra o assistente. Pronto: bandejão e JupiterWeb já respondem. O e-Disciplinas
ainda vai reclamar que falta a chave, e é a próxima seção.

Se algo não funcionar, este comando diz o que está no lugar e o que não está, sem usar
internet nem chave:

```bash
~/usp-mcp/.venv/bin/python -m usp_mcp.rucard.server --auto-verificar
```

Troque `rucard` por `jupiter` e por `moodle` para conferir os outros dois. O do moodle
dizer que a chave está ausente é o esperado até a próxima seção. No Windows, o comando é
`& $HOME\usp-mcp\.venv\Scripts\python.exe -m usp_mcp.rucard.server --auto-verificar`.

### No Windows

Os três programas são Python puro, sem uma linha específica de sistema operacional, e a
pasta onde guardam arquivos baixados existe no Windows também. O caminho desta subseção foi
percorrido do começo ao fim num Windows em 20/09/2026, da instalação até a chave do
e-Disciplinas, e as ferramentas responderam. Foi uma máquina só: se na sua alguma coisa
sair diferente, o relato é o que uma issue pede.

O que muda na instalação: o ambiente isolado que o Python cria no Windows não tem a pasta
`bin`, tem `Scripts`, e os comandos são um pouco diferentes. No PowerShell:

```powershell
git clone https://github.com/CaioCastro1/usp-mcp.git $HOME\usp-mcp
python -m venv $HOME\usp-mcp\.venv
& $HOME\usp-mcp\.venv\Scripts\pip install -e $HOME\usp-mcp
Copy-Item $HOME\usp-mcp\.env.example $HOME\usp-mcp\.env
```

Os três comandos instalados ficam em `$HOME\usp-mcp\.venv\Scripts\`, com a extensão
`.exe`: `usp-mcp-rucard.exe`, `usp-mcp-jupiter.exe` e `usp-mcp-moodle.exe`. É para eles
que o assistente aponta. No Claude Desktop o arquivo de configuração fica em
`%APPDATA%\Claude\claude_desktop_config.json`, e dentro de JSON cada barra invertida se
escreve dobrada:

```json
"usp-rucard": { "command": "C:\\Users\\SEU-USUARIO\\usp-mcp\\.venv\\Scripts\\usp-mcp-rucard.exe" }
```

No Claude Code é o mesmo comando dos outros sistemas, com o caminho do Windows:

```powershell
claude mcp add usp-rucard --scope user -- C:\Users\SEU-USUARIO\usp-mcp\.venv\Scripts\usp-mcp-rucard.exe
```

Para conferir o que ficou no lugar, sem internet e sem chave:

```powershell
& $HOME\usp-mcp\.venv\Scripts\python.exe -m usp_mcp.rucard.server --auto-verificar
```

Com `jupiter` e `moodle` no lugar de `rucard`, confere os outros dois. Com isso, bandejão
e JupiterWeb respondem.

A chave do e-Disciplinas sai por um quarto comando, instalado junto com os três acima e na
mesma pasta: `usp-mcp-token.exe`. Ele roda no PowerShell, como o resto desta subseção:

```powershell
& $HOME\usp-mcp\.venv\Scripts\usp-mcp-token.exe
```

Este era o ponto fraco daqui até 18/09/2026, porque o programa que obtém a chave só
existia em bash e o Windows não tem bash: quem instalava no Windows precisava instalar
também o Git Bash e trocar de terminal só neste passo. O programa foi reescrito em Python
e virou o comando acima. O `scripts/token.sh` continua existindo para quem está no Mac ou
no Linux, e chama o mesmo código.

O programa sabe achar o Python de `.venv\Scripts`, ler a área de transferência pelo
PowerShell (`Get-Clipboard`) e abrir o navegador pelo `rundll32`. Antes de 18/09/2026 a
vigia descrita na seção *Configuração* não existia no Windows, e foi isso que o dono do
projeto encontrou ao instalar lá. Essas três escolhas estão testadas com dublês: o que
está provado é que o programa escolhe a ferramenta certa quando ela existe, não que a
ferramenta faz o que se espera num Windows real. Se a vigia não funcionar, o fluxo em dois
passos continua valendo: copie o endereço do link e rode

```powershell
Get-Clipboard | & $HOME\usp-mcp\.venv\Scripts\usp-mcp-token.exe
```

Dentro do WSL vale o caminho do Linux, o `scripts/token.sh`, e ele reconhece esse caso:
lê a área de transferência do Windows pelo `powershell.exe` e abre o navegador do Windows
pelo `wslview`. Mas o clone, o ambiente isolado e o `.env` que o script grava têm de ser
os mesmos que o assistente usa, e um ambiente isolado criado dentro do WSL não serve a um
assistente rodando no Windows. Quem instalar pelo WSL tem de instalar tudo lá e apontar o
assistente para lá. Isso tampouco foi conferido.

Os outros arquivos de `scripts/`, o de verificação antes de commit incluído, seguem sem
adaptação de propósito: são de quem mantém o projeto, e não de quem usa, e ainda
procuram `.venv/bin/python`. Nenhum passo da instalação passa por eles. Se você usar o
caminho rápido, a mensagem *No Windows* de lá já traz estes caminhos e este comando da
chave; a de Mac não serve aqui, e o assistente não tem como perceber sozinho.

Ainda no Windows, uma coisa aparece sozinha logo no começo e assusta. A pasta do projeto
traz um arquivo chamado `.mcp.json`, e ele registra os três programas de um segundo jeito,
que vale só enquanto o assistente está aberto dentro daquela pasta. Esse segundo registro
chama um atalho escrito em bash, e o atalho procura o Python em `.venv/bin/`, que é o
endereço do Mac e do Linux. No Windows esse endereço não existe, então esse registro não
funciona aqui e não tem como funcionar. O que você pode ver, se abrir o assistente dentro
de `$HOME\usp-mcp`: um aviso de que `usp-rucard` e `usp-jupiter` estão registrados em dois
lugares ao mesmo tempo, e o `usp-moodle` parado, esperando uma aprovação sua. Não é
defeito da sua instalação, e você não precisa aprovar nada.

A saída é abrir o assistente em qualquer outra pasta. Fora da pasta do projeto esse
segundo registro nem existe, e vale só o que você fez acima, com o caminho completo até
`.venv\Scripts\`, que é o que funciona no Windows. Você não perde nada: o bandejão, o
JupiterWeb e o e-Disciplinas respondem igual de qualquer pasta, porque os programas sabem
sozinhos onde o projeto está.

## Configuração

Só o e-Disciplinas precisa disto. Bandejão e JupiterWeb funcionam sem nada.

A chave é sua e pessoal, e cada pessoa obtém a dela. Ela nunca sai do seu computador, e é
por isso que ninguém pode te dar uma pronta.

O script que a obtém já está no seu computador, na pasta do projeto que a instalação
baixou. Cole no terminal:

```bash
~/usp-mcp/scripts/token.sh
```

Se você instalou pelo caminho rápido, a pasta é a mesma.

No Windows o comando é outro, e roda no PowerShell:
`& $HOME\usp-mcp\.venv\Scripts\usp-mcp-token.exe`. Ele foi instalado junto com os três
servidores, e não fica na pasta `scripts`. É o mesmo programa do bloco acima, e tudo o que
esta seção diz vale para ele.

Ele abre uma página do e-Disciplinas no seu navegador. Você precisa já estar logado na
Senha Única. A página mostra três coisas, e duas são distração: a caixa verde "O seu
cadastro foi confirmado" e o botão cinza "Ambientes". O que importa é o link azul escrito
"Clique aqui se a aplicação não abrir automaticamente".

Clique nele com o **botão direito** e escolha "copiar endereço do link". Não clique com o
esquerdo: isso tenta abrir o aplicativo do Moodle e não copia nada. Volte no Terminal e
aperte Enter.

O script confere o que você copiou, testa a chave contra a USP e só então guarda. Se você
copiou o endereço errado, ele avisa e não estraga nada. A chave nunca aparece na tela.

Se quem roda o script é o assistente, e não você no Terminal, não há Enter para apertar:
o script fica de vigia no clipboard por até 90 segundos, lendo o que está lá a cada meio
segundo, e segue sozinho assim que aparecer um endereço que comece com
`moodlemobile://token=`. Ele avisa disso antes de começar. Só esse endereço faz o script
agir; qualquer outra coisa que você copiar nesse intervalo ele ignora, sem guardar,
mostrar ou dizer o tamanho, e o que já estava no clipboard antes não conta. Se você
copiar o endereço errado, ele diz o que veio errado e continua esperando. Passados os 90
segundos sem o endereço, ele para de ler e diz como entregar depois:
`pbpaste | ~/usp-mcp/scripts/token.sh` (no Windows, no PowerShell:
`Get-Clipboard | & $HOME\usp-mcp\.venv\Scripts\usp-mcp-token.exe`). Para rodar sem essa
vigia, defina `USP_MCP_VIGIA_SEGUNDOS=0` antes do comando. Num computador
sem ferramenta de clipboard (sem `pbpaste`, `wl-paste`, `xclip` nem PowerShell) a vigia não
existe e o script diz isso.

Quando é você no Terminal, o script para entre um passo e o outro e espera um Enter:
abrir a página, achar o link, copiar o endereço. É de propósito: as instruções todas de
uma vez ninguém lê. `USP_MCP_SEM_PAUSA=1` tira as paradas para quem já sabe o caminho.

No WSL, não instale `xclip` achando que resolve: ele lê a área de transferência do lado
Linux, e a sua está do lado Windows. O script já prefere o caminho certo ali.

Sobre o que vale no Windows, e o que ainda não foi conferido lá, está
na subseção *No Windows*, acima.

Ela fica guardada no arquivo `~/usp-mcp/.env`, na linha `MOODLE_TOKEN`. É o mesmo
arquivo que o programa lê, então não há nada para copiar de um lugar para outro: feche e
abra o assistente e o e-Disciplinas passa a responder. Você não precisa abrir esse
arquivo, mas se um dia abrir, é essa a linha.

Ela vence com o tempo e pode ser cancelada em `edisciplinas.usp.br`, em gerenciar tokens.
Se um dia o e-Disciplinas parar de responder, rode `~/usp-mcp/scripts/token.sh` de novo,
ou, no Windows, o comando do PowerShell acima.

## Usando

Depois de conectado, é só perguntar. Alguns exemplos do que funciona:

- "o que tem no bandejão da Física hoje no jantar?"
- "que dia tem lasanha essa semana?"
- "tem alguma coisa vencendo nos próximos 3 dias?"
- "quais arquivos tem em PTC3314?"
- "baixa o EP1 de PTC3314 e me explica o que ele pede"
- "quantos créditos vale MAC0110 e qual é a ementa?"

A última encadeia duas coisas: o projeto baixa o PDF e o assistente lê o arquivo para
responder.

Se você pedir algo que ele não sabe, a resposta diz o que faltou em vez de inventar. Vale
ler a seção *O que o projeto não responde* antes de concluir que quebrou.

## Como funciona

Cada um dos três comandos é um programa que fica em segundo plano aguardando perguntas do
assistente. Quem conversa com ele é o assistente, não você: executá-lo direto no terminal
não produz saída, porque não é para ser usado assim.

Quem decide qual ferramenta usar é o assistente, lendo a descrição de cada uma diante da
sua pergunta. Por isso as descrições são escritas na linguagem de quem pergunta, e não com
o nome técnico da função por trás.

O acesso à USP é limitado de propósito. De todas as operações que a sua chave permitiria,
só um punhado está liberado aqui, e por padrão todas são de leitura. Começar uma prova,
responder questionário ou mandar mensagem em seu nome estão bloqueados e continuam
bloqueados mesmo se alguém ligar a permissão de escrita. Entregar trabalho é a única
exceção que pode ser ligada, e a seção *Entregando trabalho* explica com que cuidados. O
motivo de tanta cerca é simples: quem escolhe o que chamar é um assistente interpretando
uma frase ambígua, e "manda ver a lista de exercícios" não pode ter caminho até entregar o
trabalho.

A sua chave do e-Disciplinas fica só no seu computador. Ela não vai para nenhum servidor,
nem para a nuvem. É por isso que o e-Disciplinas só funciona rodando local.

As respostas da USP são enxugadas antes de chegar ao assistente. A lista de disciplinas,
por exemplo, sai de 104.712 bytes para 7.816: o resto é metadado que não responde pergunta
nenhuma e só ocuparia espaço.

## Entregando trabalho

Por padrão o projeto só lê. Entregar trabalho no e-Disciplinas é a única exceção que pode
ser ligada, e ela vem desligada: enquanto você não ligar, essas ferramentas nem aparecem
para o assistente.

Para ligar, ponha `USP_MCP_ENTREGA=1` no arquivo `.env` e reinicie.

Aparecem então duas coisas separadas: salvar rascunho e entregar para correção. São duas
de propósito, porque "salva aí" e "entrega isso" estão a uma palavra de distância e só uma
das duas tem volta.

Entregar nunca acontece no primeiro pedido. O primeiro devolve um plano: qual atividade,
que arquivos estão anexados, qual é o prazo e o que exatamente vai mudar. Só o segundo
pedido, confirmando aquele plano, escreve. Se alguma coisa mudou entre um e outro, a
confirmação é recusada e o plano volta atualizado.

Três coisas para saber antes de ligar:

- Entregar para correção não tem desfazer, nem aqui nem pelo site.
- Salvar rascunho só funciona em atividade de texto online. Enviar arquivo não existe neste
  projeto atualmente, mas está sendo implementado.
- Trabalho em grupo é recusado, porque a entrega valeria também por pessoas que não estão
  na conversa.
- O MCP não responde testes ou questionários valendo nota, ou com submissões limitadas.

A confirmação em duas etapas protege contra acidente e contra frase ambígua. Ela não é um
cadeado: quem roda o projeto dentro de um assistente que também tem acesso ao terminal
pode contornar qualquer trava que o programa tente impor. Ligar ou não é decisão sua, e
vale tomá-la sabendo disso.

## O que o projeto não responde, e por quê

Histórico escolar, evolução do curso e saldo do RUCard ficam de fora. O motivo é falta de
caminho, não de trabalho. Medido em 14/09/2026:

- A parte pública e organizada do JupiterWeb é o catálogo de entrada. A grade dos cursos de
  ingresso da Poli para no 5º semestre (verificado em quatro cursos), e da ênfase (7º) e do
  módulo (9º) em diante não há grade, requisito nem código de curso alcançável.
- Dado pessoal exige a área logada, que não oferece chave como o Moodle. Só sessão de
  navegador, com dois cookies e um tempo de expiração ainda não medido.

O roteiro para medir isso está em
`docs/superpowers/plans/2026-09-14-jupiter-sessao-recon.md`. Nada dele foi executado.

Também não existem: histórico de cardápio, saldo do cartão, horário, sala e vagas.

Aviso de professor passou a existir em 14/09, e cobre o que foi escrito no fórum da
disciplina. Recado dado em sala e não postado não chega até lá, e nem o projeto nem o
e-Disciplinas têm como saber dele. Quem escreveu cada tópico não sai na resposta: o fórum é
o único lugar do e-Disciplinas em que a resposta traz nome de outras pessoas, e esses nomes
param aqui.

As notas que o projeto mostra são as que o professor lançou no e-Disciplinas, e só elas.
Prova corrigida no papel, nota combinada em aula e o histórico oficial da USP não estão
ali, e nenhuma soma que o projeto fizesse seria a sua média de verdade. O comentário
escrito do professor também não sai: a resposta avisa quando existe um para você ler na
página da disciplina.

A lista de disciplinas é a do e-Disciplinas, e o e-Disciplinas não é a sua matrícula
oficial. O que separa uma matéria "em andamento" de uma encerrada ali são as datas que o
professor declarou no espaço da disciplina: trancamento e cancelamento não chegam até lá, e
uma matéria sem data declarada aparece à parte, dizendo que não dá para saber. Matéria de
semestre passado continua na lista, com a sigla, porque você ainda pergunta sobre ela.

"Já entreguei o EP1?" responde só sobre tarefa. Questionário não entra, e prova marcada só
no quadro da sala não existe em sistema nenhum. A resposta diz isso quando você pergunta.

A lista do que ficou para trás é a mesma coisa vista pelo outro lado, e ela tem um limite
que vale ler devagar: o projeto sabe o que está registrado no e-Disciplinas, não o que você
fez. Entrega no papel, por e-mail, num sistema do laboratório, ou que o professor recebeu e
nunca lançou no site, não aparece como enviada. Por isso a resposta nunca diz que você não
entregou: ela diz que não há registro, e manda confirmar. Quando o professor já lançou a
nota sem receber arquivo, ela separa esse caso e não conta como falta.

Uma limitação que costuma confundir: ao listar material, o projeto diz o nome, o tipo e o
tamanho de cada arquivo, mas não devolve o endereço dele. Endereço sem a credencial não
abre, e quem baixa de fato é a ferramenta de download, sem nunca pôr a sua chave num
endereço.

## Escopo e contribuição

O repositório é público para ler, baixar e usar, sob licença MIT: você pode usar, modificar
e redistribuir, desde que mantenha o aviso de autoria. O texto completo está no arquivo
[`LICENSE`](LICENSE).

O que este projeto mais precisa não é código: é saber quando a USP mudou alguma coisa e a
resposta parou de bater. Se uma pergunta que funcionava parou, ou se o passo da chave
travou, [abra uma issue](https://github.com/CaioCastro1/usp-mcp/issues/new/choose): há um
modelo para cada um dos dois casos, e o relato leva meio minuto. **Nunca cole o valor do
seu token**, nem em issue, nem em log.

Mudança no código precisa de acordo antes da PR, porque o projeto se apoia em invariantes
que não são óbvios lendo o diff. Se você quer mexer, abra a issue primeiro; o combinado
inteiro está em [`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md).

Uma observação para quem instalou pelo assistente e não veio programar: a pasta do projeto
tem, junto com o código, os documentos de quem o mantém, e um assistente que os lê pode
começar a propor mexer no código, abrir PR ou rever decisão do projeto. Isso é engano dele,
não pedido seu: basta dizer que você só quer usar. Desde 17/09/2026 o padrão já é esse, e
o raciocínio está em [`docs/agents/PAPEL-DA-SESSAO.md`](docs/agents/PAPEL-DA-SESSAO.md).
Na direção contrária vale o mesmo: se você **quer** contribuir, dizer isso uma vez basta.

## Rodando a partir do código

Esta seção é para quem vai mexer no código. Quem só quer usar, inclusive o e-Disciplinas,
já tem tudo o que precisa pela seção *Instalando*: ela baixa o projeto inteiro, e o
script da chave vem junto.

```bash
git clone git@github.com:CaioCastro1/usp-mcp.git && cd usp-mcp
uv venv
uv pip install -e ".[dev]"
cp .env.example .env
./scripts/gate.sh
```

`uv` cria o mesmo `.venv/` que `python3 -m venv` criaria (é o que `scripts/servidor.sh` e o
`.mcp.json` procuram), com uma diferença que importa neste Mac: instala por hardlink a partir
de um cache único, então dez checkouts não custam dez cópias do SDK. Se não tiver `uv`,
`python3 -m venv .venv && .venv/bin/python -m pip install -e ".[dev]"` continua funcionando.

O `cp` vem antes do gate porque sem `.env` ele reprova. A hash do RUCard é o único valor
que o gate precisa, e ela já vem preenchida no exemplo: é a chave embutida no app oficial,
pública e compartilhada, não credencial de ninguém. O gate roda offline e não toca a USP.

O `.mcp.json` versionado registra os três servidores sem segredo nenhum. Abra um cliente
MCP neste diretório e pergunte. Cada entrada chama `scripts/servidor.sh <sistema>`, e quem
resolve a raiz do checkout é o script, não o cliente.

Cliente que não faz `cd` no diretório do projeto, como o Claude Desktop, precisa do
caminho absoluto do lançador:

```json
{
  "mcpServers": {
    "usp-rucard": {
      "command": "<CAMINHO-DO-CHECKOUT>/scripts/servidor.sh",
      "args": ["rucard"]
    }
  }
}
```

O `.mcp.json` é relativo de propósito, porque é versionado e caminho absoluto de máquina
não entra em arquivo rastreado. O absoluto fica no arquivo de config da sua máquina.

**Esse arquivo não serve no Windows**, pela mesma razão dos outros scripts de `scripts/`:
o lançador é bash e procura `.venv/bin/python`, que é endereço de Mac e de Linux. Quem
abre um cliente MCP dentro do clone num Windows recebe um aviso de servidor registrado em
dois escopos e um servidor pendente de aprovação, e as entradas de escopo de projeto não
sobem lá de jeito nenhum. Relatado por quem instalou num Windows real em 21/09/2026. O
registro que funciona nos três sistemas é o de escopo de usuário, por caminho completo,
que a seção *Instalando* ensina. Se este arquivo continua versionado, sai do repositório
ou passa a apontar para outra coisa é decisão em aberto, com as opções e o custo de cada
uma em `docs/decisions/BACKLOG-correcoes.md`.

### Detalhes técnicos

Três servidores MCP, treze ferramentas, quinze com a escrita de entrega ligada.
Comunicação por stdio, JSON-RPC, um processo por servidor. As treze têm medição contra a
USP de verdade registrada no §9 do `SPEC1.md`. As quatro de 14/09 (`avisos`, `o_que_mudou`,
`disciplinas` e `atrasadas`) nasceram numa cópia sem chave, contra resposta escrita à mão
ou capturada em agosto, e foram medidas ao vivo no mesmo dia; a metade de `atrasadas` que
era escrita à mão, o estado de cada entrega, virou captura real em 15/09
(`fixtures/moodle/submission_status_ec1.json`). As duas de entrega não entram em teste ao
vivo em fase nenhuma, de propósito.

Nada aqui é escrito para um assistente específico. A dependência de execução é uma só, o
`mcp`, que é o SDK oficial do protocolo, e a única vez em que a palavra Claude aparece
dentro de `usp_mcp/` é numa docstring citando o `CLAUDE.md`. A versão do protocolo é
negociada com quem chega, e não fixada numa só. Medido em 16/09/2026, nos três servidores:
cliente pedindo `2024-11-05` recebe `2024-11-05`, pedindo `2025-03-26` recebe `2025-03-26`
e pedindo `2025-06-18` recebe `2025-06-18`. Outros clientes MCP, como Cursor, Windsurf,
Zed, Continue e a extensão do VS Code, falam esse mesmo protocolo. Isso é o que se sabe
pelo protocolo em comum, e não o relato de alguém que tenha rodado este projeto dentro
deles: ninguém rodou ainda.

| Servidor | Ferramentas |
|---|---|
| `usp-rucard` | `bandejao` |
| `usp-moodle` | `o_que_vence`, `material`, `baixar_arquivo`, `diagnostico`, `ja_entreguei`, `notas`, `avisos`, `o_que_mudou`, `disciplinas`, `atrasadas` |
| `usp-moodle`, só com `USP_MCP_ENTREGA=1` | `salvar_rascunho`, `entregar` |
| `usp-jupiter` | `disciplina`, `requisitos` |

A superfície é allowlist: só saem daqui as funções nomeadas nela, por igualdade exata de
nome, e o default é negar. Sobre ela existe o bloqueio permanente do §2.2, que vale mesmo
com `USP_MCP_ALLOW_WRITES` ligada. A sua chave alcança 447 funções neste site, e é esse
número que faz as duas camadas existirem.

**As duas ferramentas que escrevem não existem por padrão.** `salvar_rascunho` e `entregar`
só aparecem no `tools/list` com `USP_MCP_ENTREGA=1` no ambiente. Desligada, elas não
existem, e não é o caso de uma ferramenta visível que recusa. Ligada, cada uma ainda exige
duas chamadas: a primeira devolve um plano do que mudaria, com um código; a segunda,
repetindo o código, é a que escreve. Se o estado mudar no e-Disciplinas entre as duas, o
código não confere e a resposta traz o plano novo em vez de escrever. Isso é forte contra
acidente e **fraco contra um modelo com shell**, e essa fraqueza é conhecida e aceita: quem
liga a flag precisa saber o que ligou.

`baixar_arquivo` entrega o caminho e não o conteúdo. Um blob em base64 custaria cerca de
302k tokens no PDF médio, e extrair o texto no servidor perderia as figuras. Numa lista
manuscrita escaneada isso devolveria 9 bytes e chamaria de sucesso (§9, 01/09 e 03/09). O
arquivo cai em `~/.cache/usp-mcp/moodle/`.

São três comandos e não um com argumento: o nome de cada um é o mesmo `serverInfo.name`
que o servidor responde no `initialize`. O porquê está no `pyproject.toml`. O
`usp-mcp-token`, que obtém a chave do e-Disciplinas, é um quarto comando instalado ao lado
deles, e não é servidor: é o mesmo programa que `scripts/token.sh` chama, e existe como
comando porque no Windows não há bash.

A conferência que a seção *Instalando* pede, `--auto-verificar`, existe nos três
servidores desde 31/08/2026 e é offline: lista as ferramentas expostas, diz se achou o
`.env` e se o SDK do MCP está instalado, e compara o schema que o modelo vê com a
assinatura de cada ferramenta. No Moodle diz também se a chave do e-Disciplinas está
presente, pela contagem de caracteres e nunca pelo valor. Ela só responde por
`python -m usp_mcp.<sistema>.server --auto-verificar`, com o Python do `.venv`, e de
qualquer pasta. Não responde pelo comando instalado: `usp-mcp-rucard --auto-verificar`
ignora o argumento, sobe o servidor stdio e, sem cliente na outra ponta, sai com código 0
sem imprimir nada (medido em 18/09/2026). Por isso o README só ensina a primeira forma.
Ela entrou no lugar do `scripts/gate.sh` e da ferramenta `diagnostico` no roteiro de
instalação em 18/09/2026: o gate é verificação de pré-commit, procura `.venv/bin/python`
e no Windows caía para o `python3` da Microsoft Store, com 58 testes reprovando por isso;
e `diagnostico` exige a chave e faz uma chamada à USP, que é justamente o que ainda não
existe no meio da instalação.

Desde 18/09/2026 os três prompts do caminho rápido mandam o assistente instalar o que
faltar, e não só ensinar a instalar. Os nomes de pacote foram conferidos no mesmo dia, e
não escritos de memória. No `winget`, `Python.Python.3.13` e `Git.Git` existem nos
manifestos oficiais (`microsoft/winget-pkgs`) e os dois trazem instalador de escopo de
usuário; o do Python entra com `InstallAllUsers=0 PrependPath=1` e sem exigência de
elevação, e o do Git declara `ElevationRequirement: elevatesSelf`, que é a janela de
confirmação do Windows que o README avisa em vez de prometer instalação calada. No
Homebrew, `brew install python` e `brew install git` resolvem para `python@3.14` e `git`.
No Linux, `python3`, `python3-venv` e `git` existem no Debian, `python3` e `git` no
Fedora, e `python` e `git` no Arch. O que está conferido é que os nomes existem e o que os
manifestos declaram; nenhum desses comandos foi rodado num Windows ou num Linux de
verdade. O `sudo` do Linux é o motivo de lá o texto parar e devolver a vez: senha não se
digita por procuração, e descobrir isso no meio do caminho é pior do que ler no começo.

Medido em 14/09/2026: instalação editável num venv limpo, e os três comandos subindo de
`/tmp` com cliente MCP real. Em 16/09/2026 o caminho manual da seção *Instalando* foi
percorrido inteiro numa pasta limpa, com ambiente vazio: a hash do bandejão chega ao
comando instalado a partir do `.env` do clone, e `scripts/token.sh` grava no mesmo
arquivo. Instalar o pacote sozinho, fora do clone (`pip install git+...`), não funciona:
o programa procura o `.env` na pasta do projeto, e em `site-packages` não há nenhum. Era o
que este README ensinava até 16/09. `pipx` e `uvx` não foram exercitados, e
`pip install --user` é barrado pelo PEP 668 no Python do Homebrew. Empacotar como MCP
Bundle (`.mcpb`) segue sem teste, descrito no §6.1 por leitura de documentação.

Ferramenta não nasce por conveniência: o critério está no §5, e as questões abertas do §4
fecham com dado registrado no §9. O `SPEC1.md` é a autoridade do projeto.

- `usp_mcp/`, os servidores, um pacote por sistema
- `tests/`, quatro camadas: política, contrato e handshake offline, `live` atrás de env var
- `notas/`, análise por sistema, com custo medido em bytes e tokens
- `fixtures/`, respostas capturadas; as do Moodle só entram no git depois de higienizadas, e o cru delas (`fixtures/moodle/raw/`) fica fora
- `scripts/`, chamadores da descoberta e o gate de pré-commit
- `docs/decisions/BACKLOG-correcoes.md`, a dívida que está em aberto