Pular para o conteúdo
Oleaflyv0.4.12

Conexões

Conecte o Claude Desktop, o Claude Code, o Cursor, o Codex ou outro cliente MCP às ferramentas locais de projeto do Oleafly.

O Oleafly pode atuar como um servidor MCP (Model Context Protocol). Clientes MCP como Claude Desktop, Claude Code, Cursor, Codex e Grok CLI podem ler, editar, buscar e compilar um projeto do Oleafly. Você não precisa de uma chave de provedor de IA no Oleafly, porque o cliente fornece o modelo.

Esta é a opção para quando você já tem uma assinatura do Claude (ou parecida) e quer que aquele aplicativo de chat conduza o Oleafly, sem colar uma chave de API nas Configurações.

MCP nos dois sentidosEm um sentido, um cliente MCP no seu computador, como o Claude Desktop, o Cursor ou o Codex, se conecta ao servidor MCP do Oleafly em 127.0.0.1 com um token Bearer. Ele pode ler, editar e compilar o projeto, e a sua política de aprovação decide quais alterações esperam por você. No outro sentido, o assistente integrado do Oleafly usa ferramentas de servidores MCP que você adiciona: um servidor local que executa um comando ou um servidor remoto em uma URL.Seu cliente MCP usa as ferramentas do OleaflyO assistente do Oleafly usa outros servidores MCPCliente MCPClaude Desktop,Cursor, CodexOleafly MCPSó 127.0.0.1ProjetoLer, editar, compilarToken BearerAprovaçõesAssistenteIntegrado ao OleaflyServidor localExecuta um comandoServidor remotoConecta a uma URLMCP nos dois sentidosEm um sentido, um cliente MCP no seu computador, como o Claude Desktop, o Cursor ou o Codex, se conecta ao servidor MCP do Oleafly em 127.0.0.1 com um token Bearer. Ele pode ler, editar e compilar o projeto, e a sua política de aprovação decide quais alterações esperam por você. No outro sentido, o assistente integrado do Oleafly usa ferramentas de servidores MCP que você adiciona: um servidor local que executa um comando ou um servidor remoto em uma URL.Seu cliente MCP usa o OleaflyO assistente usa servidoresCliente MCPClaude Desktop, CursorOleafly MCPSó 127.0.0.1ProjetoLer, editar, compilarToken BearerAprovaçõesAssistenteIntegrado ao OleaflyServidor localExecuta um comandoServidor remotoConecta a uma URL
Um cliente MCP no seu computador acessa as ferramentas de projeto do Oleafly por 127.0.0.1 e um token. No outro sentido, o assistente do Oleafly pode usar ferramentas de servidores MCP que você adiciona.
  1. Abra Configurações → Integrações → Servidor MCP do Oleafly.
  2. Ligue Ativar o servidor MCP.

O servidor funciona apenas enquanto o processo do Oleafly está aberto. Ele escuta somente em 127.0.0.1, nunca na sua rede local. Fechar a janela do projeto não para o servidor. Desligar o MCP ou encerrar o Oleafly, sim.

O Oleafly prefere a porta 5323 (http://127.0.0.1:5323/mcp). Se ela estiver ocupada, o servidor se vincula automaticamente a outra porta local livre e a guarda para a próxima inicialização. As Configurações mostram a URL ativa. O botão de reiniciar delas reaproveita a porta atual quando possível ou escolhe outra livre.

As Configurações mostram trechos prontos para copiar e colar para os clientes comuns. Copie a URL ativa, porque a porta escolhida pode ser diferente de 5323, e depois substitua <token> pelo token Bearer das Configurações (Revelar / Copiar).

Janela do terminal
claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"

Adicione ao claude_desktop_config.json (ponte stdio via mcp-remote, porque o Desktop prefere stdio):

{
"mcpServers": {
"oleafly": {
"command": "npx",
"args": [
"-y",
"mcp-remote@latest",
"http://127.0.0.1:5323/mcp",
"--header",
"Authorization: Bearer <token>",
"--transport",
"http-only"
]
}
}
}

Cada versão inclui oleafly.mcpb, uma extensão do Claude Desktop, então você não precisa do arquivo de configuração nem do token. Baixe-a da versão mais recente (abre em uma nova guia) e abra-a com o Claude Desktop para instalá-la.

A extensão inicia o comando oleafly que vem com o aplicativo e trabalha no projeto aberto no Oleafly, então mantenha o Oleafly aberto com o servidor MCP ativado. Se o Claude Desktop não encontrar o comando, escolha-o nas configurações da extensão: oleafly-cli dentro de Oleafly.app/Contents/MacOS no macOS, ou oleafly-cli.exe em %LOCALAPPDATA%\Oleafly no Windows.

O MCP Registry lista a mesma extensão como io.github.Oleafly/oleafly.

Em .cursor/mcp.json (ou na configuração MCP do seu cliente):

{
"mcpServers": {
"oleafly": {
"url": "http://127.0.0.1:5323/mcp",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}

Em ~/.grok/config.toml:

[mcp_servers.oleafly]
url = "http://127.0.0.1:5323/mcp"
headers = { Authorization = "Bearer <token>" }

Use o trecho Codex CLI nas configurações do Oleafly, que fornece uma ponte stdio para o servidor em execução. Adicione a entrada à sua configuração do Codex e use a URL ativa e o token mostrados pelo Oleafly:

~/.codex/config.toml
[mcp_servers.oleafly]
command = "npx"
args = [
"-y",
"mcp-remote@latest",
"http://127.0.0.1:5323/mcp",
"--header",
"Authorization: Bearer <token>",
"--transport",
"http-only"
]

A ponte exige o Node.js e o npx. Reinicie ou reconecte o cliente depois de mudar a configuração dele.

O arquivo mcp.json, ao lado dos seus dados do Oleafly (mostrado nas Configurações), guarda a mesma URL e o mesmo token, se você preferir automatizar a configuração com um script. Ele é gravado apenas enquanto o servidor está em execução (modo 0600 no Unix) e excluído quando o servidor para. Trate-o como qualquer outro segredo local.

A maioria das ferramentas MCP compartilha nomes e esquemas com o assistente interno do aplicativo. As ferramentas de descoberta e roteamento de projetos são fornecidas pelo backend do aplicativo.

As ferramentas atuam no projeto aberto no aplicativo, quando houver um. Com uma janela conectada, use list_projects e open_project para selecionar outro projeto.

Depois do fechamento da última janela, o backend mantém read_file, list_files e search_project disponíveis. Gravações, substituições, criações e renomeações nativas também continuam disponíveis quando a política de aprovação as permite. Essas ferramentas usam apenas o último projeto informado pelo aplicativo e recusam a chamada se esse projeto não for mais válido. Elas nunca adivinham a partir de outros projetos da biblioteca. Status, seleção de projetos, exclusão, compilação, logs, inspeção de PDF, mudanças de tema e ferramentas de figuras exigem uma janela conectada.

FerramentaO que faz
get_statusVersão do Oleafly, projeto aberto, motor de documento dele, documento principal, status da última compilação e por que a última compilação falhou ou não pôde rodar
list_projectsProjetos com IDs, nomes, motores, tipos, documentos principais, datas e horas, cores, estado de prévia e histórico de exportação
open_projectAbre um projeto pelo id para que as outras ferramentas atuem nele
list_filesÁrvore de arquivos do projeto
project_mapSumário, labels, citações, macros, grafo de entradas, referências não resolvidas
search_projectBusca texto no projeto atual
FerramentaO que faz
read_fileLê um arquivo do projeto
get_logLog da última compilação
get_pdf_textTexto extraído do PDF compilado
verify_pdf_pagesConfere as páginas renderizadas do PDF em busca de problemas de layout, a partir de imagens ou do texto das páginas

get_pdf_text e verify_pdf_pages leem o último PDF que o Oleafly tem. Quando a última compilação falhou ou não pôde rodar, o resultado delas diz que o PDF está desatualizado e por quê, porque ele vem de uma compilação anterior ou é um PDF parcial da compilação que falhou. get_log diz o mesmo quando a última compilação não pôde rodar, porque o log então é de uma compilação anterior.

FerramentaO que faz
write_fileGrava ou substitui um arquivo
replace_in_fileBusca e substitui dentro de um arquivo
create_fileCria um arquivo ou pasta
rename_fileRenomeia ou move um caminho
delete_fileExclui um arquivo ou pasta
set_main_docDefine o documento de entrada da compilação
FerramentaO que faz
compileCompila o projeto para PDF
preview_figureRenderiza uma figura isolada e devolve uma imagem PNG
insert_figureInsere no documento a última figura pré-visualizada
load_imageCarrega uma imagem do projeto para trabalhar em figuras

O compile diz se a compilação funcionou, lista os erros dela, diz se há um PDF e termina com a última parte do log. Uma compilação que terminou também informa os avisos dela. Quando a compilação não pôde rodar, não terminou ou precisa de algo fora do código-fonte, como uma instalação TeX ou uma versão do Typst que não está lá, o resultado dá o motivo e nomeia a correção que o Oleafly está oferecendo a você no aplicativo. A ferramenta pede ao cliente que avise você e deixe o seu código-fonte em paz. Uma compilação que você interrompeu é marcada como interrompida, para o cliente não tratá-la como um erro no código. O próprio assistente do Oleafly recebe o mesmo resultado.

Chame get_status primeiro para saber se o projeto é LaTeX, Typst ou Markdown, e então escreva o código-fonte nesse formato. preview_figure e insert_figure funcionam em projetos LaTeX e Typst:

  • No LaTeX, a figura é um código TikZ compilado em um pequeno documento standalone, e insert_figure a envolve em um ambiente figure.
  • No Typst, a figura é uma marcação Typst, como um canvas do CeTZ ou um diagrama do fletcher, renderizada com a versão de Typst do projeto. insert_figure a envolve em #figure, põe o label depois dela e move as linhas #import para acima dela.
  • Em um projeto Markdown, as duas ferramentas devolvem um erro e não mudam nada.

load_image funciona em qualquer projeto.

FerramentaO que faz
toggle_themeAlterna o modo claro / escuro
FerramentaO que faz
list_skillsLista as habilidades instaladas com o ID, o nome, a descrição e se estão ligadas
load_skillCarrega as instruções completas de uma habilidade e a lista de arquivos dela
read_skill_fileLê uma referência ou um script da pasta de uma habilidade

As ferramentas de habilidades funcionam logo depois de conectar, sem projeto aberto e sem janela do Oleafly. Um cliente vê toda habilidade válida, inclusive as desligadas nas Configurações: os interruptores decidem quais habilidades o próprio assistente do Oleafly usa, não o que um cliente pode ler. Agentes que leem habilidades de uma pasta, em vez disso, podem usar Compartilhar habilidades com outros agentes deste computador em Configurações → Assistente de IA → Habilidades. Veja Habilidades.

Essas ferramentas ficam disponíveis enquanto Notas está ativado em Configurações → Experimentação, como descreve Ative as Notas. Elas trabalham nas suas notas, não no projeto aberto, e precisam de uma janela conectada.

FerramentaO que faz
list_knowledge_notesLista as suas notas, das mais novas para as mais antigas, com IDs, títulos, tags, projetos vinculados e resumos curtos. Filtre por tag ou por projeto
search_notesBusca nas suas notas e devolve IDs, títulos, tags, links e trechos que correspondem
read_note_by_idLê uma nota como Markdown, com o front matter dela
today_noteLê a nota diária de hoje, ou o título que ela teria se ainda não existisse
list_note_tasksLista as tarefas com caixa de seleção das suas notas, da nota mais nova para a mais antiga. Filtre por nota e por abertas ou concluídas
note_backlinksLista as notas que apontam para uma nota, com o texto em volta de cada link
append_to_noteAdiciona Markdown ao fim de uma nota ou da nota diária de hoje
edit_note_sectionReescreve a parte de uma nota sob um título, ou acrescenta ao fim dela
create_noteCria uma nota com título, Markdown, tags e um projeto vinculado

append_to_note e edit_note_section não gravam na nota. As mudanças delas aparecem na nota como sugestões até você aceitá-las no Oleafly. create_note espera pela sua aprovação no Oleafly, e append_to_note também espera quando precisa criar antes a nota diária de hoje. Em Confiar nesta conexão, criar uma nota não pergunta. Uma nota compartilhada por um servidor de colaboração pode ser lida, mas não alterada por aqui. Somente leitura remove as três ferramentas que alteram notas.

Muitos clientes MCP perguntam antes de chamar uma ferramenta. O Oleafly também aplica a política escolhida em Configurações → Integrações → Servidor MCP do Oleafly:

  • Confirmar cada mudança é o padrão. Gravações, renomeações e exclusões mostram um cartão de aprovação enquanto uma janela do aplicativo está conectada. Sem uma janela, essas operações são recusadas porque não há onde mostrar o cartão.
  • Aprovar edições automaticamente, confirmar exclusões deixa gravações e renomeações rodarem no backend. As exclusões ainda precisam de uma janela conectada para confirmação.
  • Confiar nesta conexão deixa gravações e renomeações do backend rodarem sem um aviso do Oleafly. A exclusão ainda exige uma janela conectada. Use esta política apenas quando você confia no cliente e nos controles de aprovação dele.

Dois outros interruptores reforçam isso:

  • Somente leitura (interruptor separado) remove as ferramentas de modificação de tools/list por completo, então um aplicativo externo pode ler e compilar, mas nunca modificar arquivos, seja qual for a política acima.
  • Token Bearer: um valor aleatório de 256 bits guardado em um armazenamento local criptografado e autenticado sob ~/.oleafly/. Gere um novo para invalidar os clientes antigos. Leituras gerais de configuração nunca expõem o token. Só os controles de conexão do servidor em execução podem revelá-lo nas Configurações.

E duas invariantes que você não configura:

  • Somente localhost: o endereço de escuta é 127.0.0.1. Requisições com um cabeçalho Origin de navegador são rejeitadas, e o Host precisa ser loopback.
  • Confinamento ao projeto: as ferramentas de arquivo do backend aceitam caminhos relativos ao projeto e restringem os caminhos canônicos ao projeto informado pelo aplicativo. Uma chamada de ferramenta não pode fornecer outro ID de projeto nem fazer o backend escolher um projeto diferente da biblioteca.

Enquanto uma janela está conectada, uma aba de Atividade MCP registra as chamadas recebidas. As chamadas do backend podem continuar depois do fechamento da última janela, mas não há painel de atividade nem cartão de aprovação até uma janela se reconectar.

Por que o claude.ai no navegador não consegue conectar

Seção intitulada “Por que o claude.ai no navegador não consegue conectar”

Um serviço de chat na nuvem não alcança o 127.0.0.1 da sua máquina. Use o Claude Desktop (ou o Claude Code, o Cursor etc.) em vez disso. Não crie um túnel da porta do MCP para a internet pública: isso deixaria qualquer pessoa com a URL editar e excluir os arquivos do seu projeto local.

SintomaO que tentar
Algumas ferramentas não estão disponíveisPrévias de figuras e outras ferramentas só de interface precisam de uma janela do Oleafly. Abra o aplicativo e o projeto e tente tools/list de novo.
A porta mudou de 5323A porta preferida estava ocupada, então o Oleafly escolheu uma livre. Copie a URL ativa das Configurações.
HTTP 401Divergência de token (por exemplo, depois de Gerar novo). Copie o token novo para o cliente.
HTTP 403O cliente enviou um cabeçalho Origin ou um Host fora do loopback. Use um cliente MCP nativo, não uma aba do navegador.
A chamada expirouCada chamada de ferramenta espera até 5 minutos (300 s) por compilações ou por você clicar em Aprovar. Aprove ou rejeite os cartões pendentes, ou tente de novo. Uma compilação pode demorar mais, até uma hora para um notebook Quarto ou Calepin. Ela continua rodando no Oleafly depois que a chamada expira, e as ferramentas que precisam da janela do Oleafly esperam por ela, então deixe-a terminar antes de tentar de novo.
compile devolve um motivo em vez de errosA compilação não pôde rodar, por exemplo porque o TeX não está instalado. Use a correção que o Oleafly oferece no aplicativo, como instalar o TinyTeX, e compile de novo.
Não conectaO Oleafly precisa estar em execução com o MCP ativado. Este servidor para quando você encerra o aplicativo; para ter as ferramentas do projeto com o aplicativo fechado, conecte o cliente ao oleafly mcp.
Configurações → Assistente de IA → MCP. Adicione um servidor, explore o registro ou importe configurações de outra ferramenta.
Configurações → Assistente de IA → MCP. Adicione um servidor, explore o registro ou importe configurações de outra ferramenta. Abrir captura de tela completa

Para dar mais ferramentas ao assistente integrado, abra Configurações → Assistente de IA → MCP.

  • Explorar o registro para encontrar um servidor e revisar a configuração dele.
  • Importar de outras ferramentas para selecionar configurações de servidor existentes. Revise as entradas escolhidas antes de importar.
  • Adicionar servidor para digitar um servidor você mesmo e depois validar a conexão.

Os servidores conectados expõem as ferramentas deles ao assistente. Você pode inspecionar o estado da conexão e ativar ou desativar servidores na mesma página. Credenciais e comandos pertencem a cada configuração de servidor; revise-os antes de conectar um servidor novo.

O alphaXiv também se conecta como um servidor MCP, mas você o configura em Configurações → Integrações → alphaXiv, com uma chave de API, em vez de aqui. Depois de conectado, ele aparece nesta lista como alphaXiv. Conecte fontes de pesquisa cobre os passos.

Adicionar servidor → Formulário. Escolha Comando local ou URL remota, preencha os campos de conexão e depois use Adicionar e validar.
Adicionar servidor → Formulário. Escolha Comando local ou URL remota, preencha os campos de conexão e depois use Adicionar e validar. Abrir captura de tela completa

Em Configurações → Assistente de IA → MCP, escolha Adicionar servidor. Um servidor local executa um comando por stdio; um servidor remoto se conecta a uma URL. O formulário JSON usa o formato de servidor do Oleafly:

Configuração de servidor local
{
"name": "Research tools",
"enabled": true,
"transport": "stdio",
"command": "your-mcp-server",
"args": ["--stdio"],
"env": {}
}

Substitua o comando e os argumentos pelos documentados pelo servidor que você instalou. Valores de ambiente ficam no objeto env.

Configuração de servidor remoto
{
"name": "Research service",
"enabled": true,
"transport": "remote",
"url": "https://your-server.example/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}

Substitua a URL e o token de exemplo pelos dados de conexão do serviço. Use Validar para verificar a conexão e depois revise as ferramentas que o servidor expõe. Ative ou desative o servidor na linha dele. Use a ação de editar para mudar a configuração e a de remover para desconectá-lo.

Escolha Importar de outras ferramentas, inspecione as configurações descobertas e selecione os servidores que você quer. Revise caminhos de executáveis, variáveis de ambiente, URLs e credenciais antes de importar. Isso importa configurações de conexão; não instala o executável do servidor para você.

  1. Abra um projeto pequeno de prática no Oleafly.
  2. Conecte o cliente externo usando o trecho copiado do aplicativo.
  3. Peça ao cliente para chamar get_status e listar os arquivos do projeto.
  4. Peça a ele para ler o documento principal e sugerir uma mudança de título.
  5. Revise a ação no Oleafly antes de aprovar uma gravação.
  6. Compile e inspecione o PDF.

Para uma ferramenta externa conectada dentro do Oleafly, comece com uma requisição simples de somente leitura suportada por esse servidor e inspecione o cartão de ferramenta resultante no chat.

Visualização da imagem

Não foi possível carregar as respostas da IA

Tente de novo ou pesquise na documentação.