Pitch: criei o FirstMate, um gerenciador de ferramentas locais

Eu tenho mania de fazer ferramentas para mim mesmo. A ideia é ter as ferramentas que eu uso no dia a dia sem precisar pagar por elas, coisa que hoje em dia, com IA enfiada em todo produto, está cada vez mais difícil.

Até agora fiz um diário de trabalho para lembrar o que fiz entre uma reunião e outra, um agendador e um lugar para cuidar das skills do Claude e do Codex. Toda vez a parte chata era igual: subir um servidor, escolher uma porta livre, achar um jeito de abrir aquilo rápido e de receber um aviso quando algo acontece. Depois de copiar essa infraestrutura algumas vezes, percebi que a ferramenta em si era a menor parte do código.

Então tirei essa parte de dentro de cada uma e coloquei num lugar só. Isso virou o FirstMate, que comecei no dia 16 de setembro. A primeira versão rodava dentro do WSL como serviço do systemd e só funcionava na minha máquina, do meu jeito. A 2.0, que acabou de sair, é um App para Windows e Linux que outra pessoa consegue instalar com um comando.

Como funciona

Cada ferramenta é um Plugin, e um Plugin é uma pasta. Não tem manifesto nem arquivo de configuração:

meu-plugin/
├── web/       # a página, servida como está
└── mcp.ts     # opcional: um servidor MCP com as ferramentas do Plugin

O FirstMate roda o mcp.ts, mostra a página numa janela e cuida do resto. Você liga um atalho de teclado global a um Plugin, e ele abre a página num Popup por cima de tudo. No GIF abaixo dá para ver isso: eu adiciono uma entrada no worklog sem sair do que estava fazendo. O Plugin também pode mandar notificação para o desktop.

Quando um Plugin cai, o ícone da bandeja muda e ele fica parado até eu mandar reiniciar com firstmate restart. Prefiro ver o erro a ter um processo reiniciando em loop escondido. E um Plugin pode chamar as ferramentas de outro, mas só depois que eu dou permissão com firstmate grant. É assim que o scheduler chama a ferramenta de outro Plugin no horário que eu escolho.

Tudo roda em 127.0.0.1, e cada requisição precisa de um token. Nada sai da sua máquina, e o FirstMate não lê nem guarda os dados dos Plugins.

O que aprendi fazendo

Um servidor HTTP em localhost não está protegido só por estar em localhost. Um site qualquer aberto no navegador consegue mandar requisições para ele, e com DNS rebinding consegue até ler a resposta. Por isso o FirstMate escuta só em 127.0.0.1 e confere o cabeçalho Host, o Origin e um token novo a cada execução em toda requisição. O token chega na primeira navegação e vira um cookie SameSite=Strict.

O FirstMate não tem nenhuma dependência em tempo de execução. Em vez do SDK do MCP, escrevi o cliente JSON-RPC sobre stdio na mão, e ele tem pouco mais de 200 linhas. O Node 24 roda TypeScript direto, então o Host também não tem etapa de build.

No Windows, quem escreve um Plugin não precisa instalar Node. O App é feito em Electron, e o executável dele, com ELECTRON_RUN_AS_NODE=1, vira o Node que roda o mcp.ts de cada Plugin.

Para testar

npx @luan-afonso/firstmate desktop
firstmate setup

Uma coisa que é melhor você saber antes:

O App ainda não tem assinatura de código. Pedi para a SignPath, que assina projetos open source de graça, e estou esperando a resposta. Até lá o Windows vai dizer que o App é desconhecido. Clique em "Mais informações" e depois em "Executar assim mesmo". Chato, eu sei.

O código é MIT: https://github.com/luanAfons0/FirstMate