Repository navigation
Releases
v1.4.1
O que muda
- A descrição no
server.jsone nopackage.json, o README e as instruções do servidor passam a dizer que nenhuma tool cria, edita ou apaga arquivos da pasta de estudos. As tools de escrita gravam só dúvidas e progresso, emDATA_DIR. - Versão 1.4.1 (
package.json,package-lock.json,server.json), com entrada no CHANGELOG. .env.example: o tamanho do modelo da busca por significado foi corrigido para ~310 MB.
Nenhuma tool mudou.
Por quê
No Glama, a nota de completude caiu para 3/5. O avaliador leu o servidor como um app de notas e sentiu falta de tools para criar e editar notas. Elas ficam de fora de propósito: escrever na pasta de estudos mudaria a promessa de segurança do servidor. Agora a descrição diz isso.
Como testar
npm run typecheck && npm test (142 testes) e npm run test:pack, todos passando.
Checklist
-
npm run typecheck && npm testpassam localmente - Atualizei o README e a documentação
- Não incluí material do curso, credenciais reais,
.envou caminhos da minha máquina
🤖 Generated with Claude Code
v1.4.0
Correções encontradas no uso real. As tools passam a responder só em texto, porque em alguns clientes as proteções não chegavam ao modelo. Também passa a haver um servidor montando o índice de cada vez, e a busca por significado funciona sem internet depois do primeiro download.
Corrigido
- As proteções e as dicas não chegavam ao modelo no Claude Code, no VS Code e no Codex. Quando a resposta de uma tool traz JSON (
structuredContent), esses clientes mandam ao modelo só o JSON e descartam o texto.- O que estava no texto: a delimitação
<dados_nao_confiaveis>, o alerta de prompt injection, o aviso 🔒 e as dicas. - O que continuava funcionando: as credenciais seguiam mascaradas.
- Agora: as tools respondem só em texto.
- O que estava no texto: a delimitação
- A busca por significado não funcionava sem internet, mesmo com o modelo já baixado, e ficava parada quando o Hugging Face demorava a responder. Agora, depois do primeiro download, o modelo é lido da pasta local, sem acesso à rede.
Alterado
listar_arquivoscom mais de 100 arquivos mostra um panorama por subpasta, em vez dos 100 primeiros. Cada subpasta aparece com quantos arquivos tem de cada tipo, e com o título e o primeiro parágrafo do README.- Medido no Claude Code, com a mesma pergunta sobre um módulo de 634 arquivos: de 25 para 4 chamadas de tool e de ~842 mil para ~190–230 mil tokens de entrada.
- Nas duas rodadas medidas, o modelo não tentou usar o terminal (antes, foram 3 tentativas).
- Só um servidor monta o índice de cada vez quando há vários clientes abertos (VS Code, sessões do Claude Code, Codex). Os outros esperam sem carregar o modelo e depois usam o índice salvo.
- Medido com 3 clientes na primeira indexação de ~1.700 arquivos: de 26,2 para 5,8 min, e de 3,6 para 2,4 GB de memória somada.
- O modelo só é carregado quando há algo para calcular. Um servidor aberto que ainda não buscou nada fica com ~0,3 GB de memória, em vez de ~1,4 GB. Em troca, a primeira busca de cada sessão leva ~0,6 s a mais.
- O JSON (
structuredContent) não existe mais. Quem o lia num programa encontra os mesmos dados no texto. - O índice salvo continua valendo: atualizar não refaz o índice.
npm: npx -y study-notes-mcp@latest
v1.3.0
Busca por significado bem melhor no material real, escolhida por medição: 48 perguntas sobre um material de curso de verdade, escritas com outras palavras, feitas ao servidor pelo protocolo MCP.
Alterado
- Modelo novo: snowflake-arctic-embed-m-v2.0 (Apache-2.0, multilíngue), e cada trecho ganha um cabeçalho com o nome do arquivo e os títulos da seção antes de virar vetor. Arquivo certo em 1º lugar: de 21 para 34 das 48 perguntas; entre os 5 primeiros: de 33 para 44. A busca por nome exato continua igual.
- Custos, quase todos de uma vez só: o modelo baixa ~310 MB; a primeira indexação leva ~6,5 min para ~1.700 arquivos, com a busca funcionando enquanto isso. Cada servidor aberto usa ~1 GB de memória com a busca por significado ligada. O tempo de cada busca não mudou (~0,44 s).
- O índice é refeito uma vez, sozinho, na primeira conversa depois de atualizar. O modelo antigo fica em
MODELS_DIR/Xenova(~120 MB) e pode ser apagado. - Quem não usa a busca por significado (
SEMANTIC_SEARCH) não é afetado.
Corrigido
- Buscas travavam durante a indexação: agora os pedidos do cliente têm prioridade, e as buscas continuam respondendo enquanto o índice é montado.
- O aviso "Unknown model class" não aparece mais no log.
- Correção do que foi anunciado na 1.2.0: o ganho do corte nos títulos tinha sido medido com um teste que o favorecia. Com o modelo novo, ele soma de fato (+0,04 de MRR), e o cabeçalho, +0,07.
npm: npx -y study-notes-mcp@latest
v1.2.0
A terceira parte da revisão de código externa: buscas mais relevantes (exata e por significado), PDFs mais rápidos e o estado do índice visível. Cada mudança foi medida num material de curso real.
Adicionado
- Resource
estudos://indice: o estado da busca por significado (ligada ou não, progresso da indexação, arquivos e trechos no índice e o último erro), sem precisar fazer uma busca.
Alterado
- Busca por significado: os trechos começam em cada título Markdown, para cada um falar de um assunto só. Antes, 71% dos trechos de um material real misturavam duas seções. Numa avaliação com notas longas e perguntas escritas com outras palavras, o 1º trecho começa na seção certa em 13 de 18 perguntas, contra 1 de 18. O índice é refeito uma vez, sozinho, na primeira conversa depois de atualizar (~2 min para ~1.700 arquivos).
- O texto dos PDFs fica salvo em
DATA_DIR/cache-pdf.json(permissão 600): a primeira busca de cada conversa não extrai todos os PDFs de novo (57 PDFs: de 1,2 s para 0,4 s). - A busca por texto exato ordena por relevância, e não mais pela ordem das pastas: nome do arquivo, título, palavra inteira e repetições; anotações antes de PDFs, e PDFs antes de código. Na avaliação, a busca híbrida foi de 20/25 para 22/25 no 1º lugar.
- Documentado o comportamento com links simbólicos.
- O aviso de índice em construção diz "preparando" em vez de "0 de 0 arquivos".
npm: npx -y study-notes-mcp@latest
v1.1.1
Manutenção para o projeto seguir estável com pouca intervenção.
Alterado
- Busca por significado: a versão testada passa a ser a
@huggingface/transformers4.3.2 (mesmo motor de inferência, vetores e índice iguais). O servidor aceita qualquer 4.x a partir da 4.3.1, então configurações com--package=@huggingface/transformers@4.3.1continuam funcionando sem mudança. - CI: o macOS roda só com Node 22 (o Node 24 segue testado no Ubuntu e no Windows), por causa da fila longa das máquinas macOS do GitHub. O Dependabot passa a propor atualizações a cada seis meses; correções de segurança continuam imediatas.
npm: npx -y study-notes-mcp@latest
v1.1.0
Melhorias da revisão de código externa: busca, segurança e uma tool nova. Cada uma foi medida num material de curso real antes do merge.
Adicionado
- Mais segredos mascarados: valores sem aspas (
.envcolado numa nota, frontmatter YAML), JWT,Bearer,x-api-keye tokens do Hugging Face. Textos de exemplo e referências no código ficam como estão (medido num material real: sem esse filtro, todos os casos novos eram falsos). - Linha 🔒 quando algo com cara de credencial foi mascarado, separada do alerta de prompt injection. Na busca por significado, o mascaramento é refeito na resposta, cobrindo índices gerados por versões anteriores.
- Tool
listar_arquivos: os arquivos de um módulo, com tipo e tamanho (até 100, com filtro por tipo). Ogerar_quizpassa a listar o módulo antes de ler, em vez de depender de termos de busca adivinhados.
Alterado
- Mais variações de prompt injection geram alerta: palavras entre "ignore" e "anteriores", "desconsidere o que foi dito antes", pedidos do prompt de sistema, ordens para chamar uma tool do servidor e para expor o
.env. Os alertas passaram de 4 para 8 linhas, todas com frases de ataque de verdade, e dúvidas legítimas como "posso ignorar o aviso acima?" continuam aceitas. - A busca por texto exato não diferencia mais acentos:
funcaoacha "função", eativaçãoacha também onde está escrito "ativacao". O trecho devolvido mantém os acentos originais.
Documentação
- Seção Windows nos clientes testados (
cmd /c npxquando o servidor não sobe).
npm: npx -y study-notes-mcp@latest
v1.0.2
Correções vindas de uma revisão de código externa, todas reproduzidas antes de corrigir e cobertas por teste.
Instalação: npx -y study-notes-mcp@latest. Veja o passo a passo no README.
Corrigido
- Dúvidas perdidas em chamadas simultâneas: registrar três dúvidas em paralelo gravava só uma, e uma delas respondia "sucesso" sem ter sido gravada. As gravações agora entram numa fila por arquivo.
- Uma subpasta ilegível derrubava a busca e a lista de módulos inteiras. Agora ela é pulada, com aviso no log. Um módulo que é um arquivo recebe uma explicação, em vez de
ENOTDIR. - Caminhos absolutos (com o nome do usuário) em mensagens de erro: nenhuma saída leva mais caminhos ao modelo, incluindo os erros de prompts e resources e o aviso da busca por significado.
- O trecho da busca literal podia não conter o termo numa linha longa. Agora ele fica centrado no termo, e os segredos são mascarados antes do recorte.
- Parágrafos maiores que um trecho eram lidos só no começo pela busca por significado. Agora viram vários trechos; os índices salvos continuam valendo.
- Itens menores: intervalo de páginas inválido, vetores de tamanhos diferentes, alinhamento na leitura do índice e aviso para linhas com
!no.studynotesignore.
Adicionado
- A versão aparece no log de inicialização, e
npx -y study-notes-mcp@latest --versionmostra a versão.
Documentação
- README com a seção "Por que este servidor", e descrição do npm destacando a busca híbrida local e sem chave de API.
v1.0.1
Versão de manutenção: nenhuma mudança no comportamento do servidor.
Instalação: npx -y study-notes-mcp@latest. Veja o passo a passo no README.
Documentação
- README sem o aviso de projeto educacional, e exemplos de pasta com um nome genérico (
Estudos).
Publicação
- Primeira versão publicada pelo GitHub Actions, com provenance: a página do npm mostra de qual commit e de qual workflow o pacote saiu.
- O CI e a publicação instalam as dependências sem os scripts de instalação, exceto no teste da busca por significado: uma falha no servidor de download do
onnxruntime-nodenão derruba mais uma release.
v1.0.0
Primeira versão publicada.
Instalação: npx -y study-notes-mcp@latest. Veja o passo a passo no README.
Tools, prompts e resources
buscar_material: busca por nome exato e, comSEMANTIC_SEARCH=true, por significado. As duas buscas são unidas (Reciprocal Rank Fusion), e cada resultado cita arquivo, linha e página.ler_material: lê anotações, código e PDFs por página. Em notas do Obsidian, mostra para onde cada[[link]]aponta.listar_modulos, incluindo os módulos dentro de outra pasta (como num repositório de curso clonado).registrar_duvida,resolver_duvida,marcar_aula_concluidaever_estudos.- Prompts
gerar_quiz(com autocompletar do módulo e busca pelo número ou trecho do nome) eplano_de_revisao, ambos pedindo a fonte de cada resposta. - Resources
estudos://duvidaseestudos://progresso.
Material
- Anotações (
.md,.txt), PDFs com texto e código (.ts,.js,.pye outros). - Arquivo
.studynotesignore, no formato do.gitignore, para excluir pastas e arquivos. - Busca por significado local, com o modelo
multilingual-e5-small: sem chave de API, textos repetidos calculados uma vez só.
Segurança
- Lista fechada de extensões, bloqueio de arquivos ocultos, de
../e de symlinks para fora da pasta. - Segredos trocados por
[REDACTED], alertas de prompt injection e conteúdo delimitado como dado não confiável. - Recusa igual para arquivos bloqueados que existem ou não, e mensagens de erro sem caminhos absolutos.
- Gravação atômica das dúvidas, do progresso e do índice, com novas tentativas no Windows; um arquivo ilegível nunca é sobrescrito.
Requisitos
- Node.js 22.18 ou mais novo.
Clientes testados
- VS Code com GitHub Copilot, Claude Code e Codex. Detalhes em clientes testados.