PhotoFresco

Permita que agentes de IA editem imagens em uma janela do PhotoFresco que você aprova: camadas, máscaras, pré-visualizações e exportação.

GitHubExperimente este MCPPatrocinado

Documentação

PhotoFresco para agentes de IA

Permita que agentes de IA editem imagens em uma janela do PhotoFresco que você aprova: camadas, máscaras, visualizações e exportação.

PhotoFresco é um editor de imagens gratuito, de classe Photoshop, que roda no seu navegador: camadas, máscaras, camadas de ajuste, seleções, pincéis, importação e exportação de PSD e histórico completo de desfazer. Este repositório conecta agentes de IA a ele. Um agente (Claude, Cursor, VS Code, Codex ou qualquer cliente MCP, ou um script via linha de comando) controla uma janela do PhotoFresco no seu próprio computador. Você observa cada mudança, permite a conexão, escolhe o que o agente pode fazer e pode pausar ou interromper a qualquer momento. A edição em si acontece no editor, então cada mudança entra no Histórico e pode ser desfeita como se fosse sua.

An agent connects, opens a photo, masks a Hue/Saturation adjustment to the sky, checks a preview and exports a PNG

A gravação acima é uma sessão real: um cliente MCP chamando este servidor contra o editor, capturado em modo headless. Categoria: Design / edição de imagens.

O que está neste repositório:

Servidor MCP (photofresco mcp): uma ferramenta por operação do editor, visualizações como imagens, exportações como arquivos ou recursos. Guia: MCP.md.
Skill de Agente (skills/photofresco): ensina um agente quando e como usar bem o PhotoFresco.
Linha de comando (photofresco <command>): abrir, executar fluxos de trabalho salvos, exportar, parar. Guia: CLI.md.
Conector local (a biblioteca que os outros três compartilham): CONNECTOR.md.

O editor em si não está neste repositório; o conector o abre em photofresco.com.

Requisitos

Node.js 22 ou mais recente.
Um navegador baseado em Chromium instalado: Google Chrome, Microsoft Edge ou Chromium 120 ou mais recente. Nada é baixado. Aponte --browser (ou PHOTOFRESCO_BROWSER) para outro, se necessário.
macOS é verificado; Windows e Linux estão implementados, mas ainda não verificados.

Configure seu agente

Um clique (Cursor, VS Code, LM Studio):

Cada botão pede ao aplicativo para adicionar o servidor photofresco, iniciado com npx a partir do arquivo fonte do GitHub da versão 0.1.0 (commit 328cfaf; nada vem do registro npm). Ele não concede pastas: adicione os argumentos --read e --write após mcp nas configurações de MCP do aplicativo para permitir que o agente abra e salve arquivos.

Caso contrário, adicione o servidor à configuração MCP do seu cliente abaixo. Escolha as pastas das quais o agente pode abrir arquivos (--read) e salvar exportações (--write). Sem elas, o agente ainda pode editar e visualizar, mas não pode tocar nos seus arquivos.

Publicação npm pendente. O pacote npm photofresco é publicado em meados de outubro de 2026, então os comandos npx -y photofresco@0.1.0 abaixo ainda não funcionam. Até lá, coloque --package=https://github.com/photofresco/photofresco-agent/archive/328cfaf3caf6483c5660381f19f2afdb2059a215.tar.gz photofresco (a mesma versão, do GitHub) no lugar de photofresco@0.1.0, instale o plugin, ou execute a partir de um clone deste repositório como abaixo: node /path/to/photofresco-agent/src/bin/photofresco.js no lugar da parte npx -y photofresco@0.1.0 (sem npm install necessário).

A partir de um clone (funciona hoje; o SDK MCP está incluído, então não há nada para instalar):

git clone https://github.com/photofresco/photofresco-agent.git ~/photofresco-agent

Em seguida, adicione esta entrada a qualquer cliente que leia mcpServers (Claude Desktop, Cursor, Windsurf, Kiro e a maioria dos outros), com sua própria pasta pessoal no lugar de /Users/you:

{
  "mcpServers": {
    "photofresco": {
      "command": "node",
      "args": ["/Users/you/photofresco-agent/src/bin/photofresco.js", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]
    }
  }
}

Claude Code:

claude mcp add photofresco -- npx -y photofresco@0.1.0 mcp --read ~/Pictures --write ~/Pictures/PhotoFresco

Claude Desktop: claude_desktop_config.json (Configurações → Desenvolvedor → Editar Config):

{
  "mcpServers": {
    "photofresco": {
      "command": "npx",
      "args": ["-y", "photofresco@0.1.0", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]
    }
  }
}

Cursor: ~/.cursor/mcp.json (todos os projetos) ou .cursor/mcp.json (um projeto), com a mesma entrada mcpServers do Claude Desktop.

VS Code: .vscode/mcp.json em um workspace, ou MCP: Open User Configuration para todos eles:

{
  "servers": {
    "photofresco": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "photofresco@0.1.0", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]
    }
  }
}

Windsurf (Cascade): a mesma entrada mcpServers do Claude Desktop, em mcp_config.json (Cascade → MCPs → Open MCP config file).

Gemini CLI:

gemini mcp add -s user photofresco npx -y photofresco@0.1.0 mcp --read ~/Pictures --write ~/Pictures/PhotoFresco

Codex:

codex mcp add photofresco -- npx -y photofresco@0.1.0 mcp --read ~/Pictures --write ~/Pictures/PhotoFresco

OpenCode: opencode.json em um projeto, ou ~/.config/opencode/opencode.json para todos eles (a partir de um clone, como acima):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "photofresco": {
      "type": "local",
      "command": ["node", "/Users/you/photofresco-agent/src/bin/photofresco.js", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"],
      "enabled": true
    }
  }
}

Kiro: a entrada mcpServers do clone acima, em ~/.kiro/settings/mcp.json (todos os workspaces) ou .kiro/settings/mcp.json (um workspace).

Cline: dê este repositório ao Cline; llms-install.md o orienta na instalação, conexão e parada.

O servidor é testado com o cliente oficial MCP TypeScript via stdio; estas entradas seguem o formato stdio documentado de cada aplicativo. Opções:

Opção	Significado
`--read <folder>`	O agente pode abrir arquivos de imagem desta pasta (repetível)
`--write <folder>`	O agente pode salvar exportações nesta pasta e novas subpastas (repetível)
`--overwrite`	Exportações podem substituir arquivos existentes nas pastas `--write` (o agente também deve pedir)
`--tools <groups>`	Quais operações são listadas como ferramentas: `essentials` (padrão, no máximo 40 ferramentas), `all`, ou uma lista separada por vírgulas de grupos (MCP.md)
`--profile <folder>`	Pasta de perfil do navegador, ou `ephemeral` para uma descartável
`--browser <path>`	Navegador baseado em Chromium a usar (igual a `PHOTOFRESCO_BROWSER`)

MCP Bundle (Claude Desktop e outros aplicativos que instalam arquivos .mcpb): node scripts/build-mcpb.mjs gera dist/photofresco-mcp-0.1.0.mcpb e seu SHA-256 a partir deste repositório (reproduzível com a mesma versão do Node.js). O bundle inicia o mesmo servidor e, como um plugin, não concede pastas. Cada lançamento do GitHub anexa este arquivo; seu SHA-256 é o fileSha256 em server.json, a entrada do Official MCP Registry.

Docker (para registros MCP que verificam servidores em um contêiner): docker build -t photofresco-mcp . então docker run -i --rm photofresco-mcp executa o servidor via stdio. A imagem não tem navegador, então ela apenas lista ferramentas; photofresco_connect falha lá com browser_not_found. Edite imagens com uma instalação local como acima.

Como uma sessão funciona

O agente chama photofresco_connect. O PhotoFresco abre em sua própria janela com um código de conexão; o agente informa o mesmo código. Verifique-o e clique em Allow.
A sessão começa sem permissões. O agente pede o que precisa (Read, Edit, Export; Send e Spend apenas para IA em nuvem e paga) e você escolhe no diálogo Permissions. As ferramentas de edição aparecem para o agente conforme você as concede.
O agente edita com uma ferramenta por operação do editor, observa as visualizações e desfaz o que não gosta. Editar você mesmo pausa o agente até você pressionar Resume. Stop encerra a sessão; fechar a janela também.

Nada abre até o agente chamar photofresco_connect: iniciar o servidor e listar suas ferramentas não inicia nenhum navegador.

Instalar como plugin

Este repositório também é um plugin para Claude Code, Codex, Cursor, Gemini CLI, Hermes Agent, OpenClaw, Antigravity, Devin e Kiro: uma instalação adiciona o servidor MCP e a Agent Skill. O cliente copia o repositório e inicia o servidor com node <plugin folder>/src/bin/photofresco.js mcp; nada é baixado do npm, porque o SDK MCP está incluído legível em vendor/. Node.js 22 ou mais recente deve estar no seu PATH.

Uma instalação de plugin concede nenhuma pasta: o agente edita a imagem aberta na janela do PhotoFresco, e você abre e salva arquivos lá mesmo. Para acesso do agente a arquivos, configure o servidor com --read e --write como acima.

Claude Code (em uma sessão; a terceira linha faz ambos os passos em um no Claude Code 2.1.275 ou posterior):

/plugin marketplace add photofresco/photofresco-agent
/plugin install photofresco@photofresco
/plugin install photofresco --marketplace photofresco/photofresco-agent

Codex:

codex plugin marketplace add photofresco/photofresco-agent
codex plugin add photofresco@photofresco

Gemini CLI:

gemini extensions install https://github.com/photofresco/photofresco-agent

O Gemini CLI passa apenas algumas variáveis de ambiente para extensões, então PHOTOFRESCO_BROWSER não alcança este; com um navegador fora dos locais padrão, use a configuração MCP acima.

Cursor: instale o PhotoFresco em Customize assim que estiver listado, ou copie este repositório para ~/.cursor/plugins/local/photofresco e recarregue a janela.

Hermes Agent (uma versão com suporte a Agent Plugins, que tem hermes plugins validate). Plugins instalam desabilitados; habilitar carrega o servidor e a skill na próxima sessão:

hermes plugins install photofresco/photofresco-agent --no-enable
hermes plugins enable photofresco

OpenClaw (ele pede que você revise o código-fonte, depois aceite o servidor MCP e a skill do plugin):

openclaw plugins install photofresco --marketplace photofresco/photofresco-agent

Antigravity (CLI):

agy plugin install https://github.com/photofresco/photofresco-agent

Devin (CLI; ou Customize → Plugins → Add plugin → From repository no aplicativo):

devin plugins install photofresco/photofresco-agent

Kiro: Powers → Add Custom Power → Import power from GitHub, depois https://github.com/photofresco/photofresco-agent.

Os manifestos são .claude-plugin/ (Claude Code, também lido pelo Devin), plugin.json com mcp.json (o padrão Agent Plugins, usado por Codex, Hermes Agent e Kiro), .cursor-plugin/plugin.json (Cursor e OpenClaw, que lê .mcp.json através dele), gemini-extension.json (Gemini CLI), mcp_config.json (Antigravity) e openclaw.plugin.json (metadados OpenClaw e ClawHub).

Skill de agente

A Agent Skill em skills/photofresco ensina agentes com suporte a skills (Claude Code, Codex, Cursor e outros) quando usar o PhotoFresco, como conectar e pedir permissões, o loop orientar → editar → visualizar → desfazer, fluxos de trabalho, exportações, cada código de erro e a linha de comando. Ela não configura o servidor MCP; configure-o como acima. Instale-a com a CLI skills no projeto atual (-g para seu usuário):

npx skills add photofresco/photofresco-agent

Remova-a com npx skills remove photofresco. A referência de operações é a própria lista de ferramentas do servidor (photofresco_list_tool_groups, ou photofresco ops na linha de comando).

Linha de comando

O mesmo pacote instala um comando photofresco para scripts e agentes que têm um shell, mas nenhum cliente MCP. Ele controla o mesmo tipo de janela aprovada através de um processo conector em segundo plano. Até o pacote npm ser publicado (meados de outubro de 2026), execute-o a partir de um clone em vez de npm install -g: alias photofresco="node /path/to/photofresco-agent/src/bin/photofresco.js".

npm install -g photofresco@0.1.0
photofresco connect --read ~/Pictures --write ~/Pictures/PhotoFresco
photofresco run warm.json --open ~/Pictures/beach.png --input amount=0.6 \
  --export ~/Pictures/PhotoFresco/beach-warm.png
photofresco stop

connect abre o PhotoFresco e imprime um código de conexão; verifique se a janela mostra o mesmo código, clique em Allow e escolha as permissões. run abre a imagem em uma nova aba, executa um fluxo de trabalho salvo (o arquivo portátil que o painel Actions do editor exporta) e grava a exportação somente após seu SHA-256 corresponder. stop encerra a sessão, fecha a janela e interrompe o processo conector.

Comando	O que faz
`connect`	Inicia o conector se necessário, abre o PhotoFresco e emparelha (você clica em Allow)
`status`	Conector, janela, sessão, permissões e pastas concedidas
`request-access <list>`	Pede mais permissões (`read,edit,export,external-write,spend`)
`documents`, `attach <id>`	Lista documentos abertos; direciona outro
`open <file>`	Abre uma imagem de uma pasta concedida em uma nova aba
`run <workflow.json>`	Executa um fluxo de trabalho (ou `--action <id>`) com `--open`, `--input` e `--export`
`export <file>`	Exporta o documento (PNG, PSD ou `.pfd`) para uma pasta concedida
`exec <op> [params-json]`	Executa uma operação do editor
`ops [prefix]`, `describe <op>`	Operações que esta sessão pode executar e seus parâmetros
`outcome <request-id>`	O resultado de uma solicitação anterior após uma conexão perdida
`disconnect`, `stop`	Encerra a sessão; `stop` também fecha a janela e o conector
`mcp`	O servidor MCP acima

Todo comando aceita --json (um objeto em stdout, também em falha) e retorna um código de saída documentado (0 sucesso, 2 uso, 3 não conectado, 4 caminho recusado, 5 recusado pelo editor, 8 cancelado, 75 ainda esperando por você). Referência completa: CLI.md.

O que isso executa, envia e busca

Observado no macOS com Chrome for Testing 145 contra uma build local do editor, registrado em DISCLOSURE.md com todos os detalhes; qualquer coisa não observada está marcada lá.

Execuções

Um processo Node.js: o servidor MCP que seu cliente inicia (ele termina quando o cliente o fecha), ou cada comando photofresco mais um processo conector em segundo plano por pasta de dados (ele termina em photofresco stop, quando você fecha a janela dele, ou após um minuto sem janela ou comando).
Uma árvore de processos do navegador, apenas quando o agente se conecta: seu Chrome, Edge ou Chromium instalado, iniciado com um perfil dedicado e o pipe de DevTools (--user-data-dir=<profile> --remote-debugging-pipe --no-first-run --no-default-browser-check --disable-extensions). Ele mostra uma janela normal e visível (a demonstração acima foi gravada em modo headless). Seus perfis de navegador do dia a dia nunca são abertos, lidos ou anexados.
Nenhum outro programa, comando de shell, instalador, serviço, item de login ou extensão.

Arquivos e canais locais

Pasta de dados: ~/Library/Application Support/PhotoFresco Connector (macOS), %LOCALAPPDATA%\PhotoFresco Connector (Windows) ou ~/.local/share/photofresco-connector (Linux). Ela contém o perfil do navegador (cookies e login se você entrar lá, cache, o armazenamento local do editor e salvamento automático), um arquivo de bloqueio e, para a linha de comando, cli/ com um socket Unix (0600 em uma pasta 0700), uma chave aleatória por inicialização e connector.log (eventos sem segredos: caminhos de pastas concedidos, caminhos, tamanhos e SHA-256 de arquivos lidos ou gravados; sem chaves, conteúdos de arquivos ou pixels; no máximo 4 MiB).
Seus arquivos: leitura apenas dentro de pastas --read quando o agente abre um arquivo (no máximo 32 MiB), e gravação apenas dentro de pastas --write quando ele exporta, por meio de um arquivo temporário renomeado no lugar após seu SHA-256 corresponder. Arquivos existentes são substituídos apenas com --overwrite e o agente solicitando isso.
Nenhuma porta de rede em escuta. O navegador é controlado por seu pipe privado; a linha de comando usa o socket local. Observado: nenhum socket TCP no servidor ou no processo conector.

Rede

O conector, o servidor MCP e a linha de comando não fazem solicitações de rede por conta própria. npx/npm install baixa o pacote do registro npm primeiro (os botões de um clique, até o lançamento no npm, baixam o arquivo de origem deste repositório do GitHub); uma instalação de plugin faz o cliente do agente copiar este repositório (do GitHub), e iniciar o servidor não baixa nada.
O navegador abre https://photofresco.com/app/?pf_ref=mcp (ou cli), uma tag não secreta para atribuição, e carrega o editor como uma visita normal. Como o navegador é automatizado, ele não mostra anúncios de terceiros.
A janela do conector inicia com a gravação de sessão desativada. O editor reconhece a janela que o conector abriu (um canal privado que nenhum link ou site pode configurar) e a inicia com nada permitido em Dados e privacidade, então nada dos seus arquivos é enviado: sem gravação de sessão, sem diagnósticos, sem cópia dos arquivos que o agente abre e sem eventos de uso. Observado: nenhuma solicitação de gravação ou telemetria desde a conexão até o fim da sessão, inclusive após o agente importar uma foto. Permitir o agente ativa apenas Agentes externos lá.
A gravação permanece desativada a menos que você ative a gravação em Dados e privacidade nessa janela. A partir daí, ela envia ao PhotoFresco os eventos de entrada, comandos do editor, nomes de documentos, texto digitado (campos de senha e e-mail mascarados) e uma cópia de cada imagem aberta na janela, incluindo arquivos que o agente abre por meio do conector (no máximo 16 MiB cada, 6 por carregamento de página), além de diagnósticos (erros, eventos de recursos, desempenho, um perfil de dispositivo) e eventos de uso seguros para privacidade (referral, open, edit, export, marcados automated; sem nomes de arquivos ou pixels). Uma visita normal a photofresco.com, não aberta pelo conector, tem a gravação ativada por padrão.
O tráfego de fundo do próprio navegador (atualizações, navegação segura) segue seus padrões; não medido. Solicitações de terceiros do site de produção não foram verificadas.

O que o agente recebe

Apenas o que suas permissões permitem: status da sessão, estado do documento, resultados de operações, prévias (pixels) e arquivos exportados. Tudo o que o agente recebe vai para o provedor de modelo desse agente, sob a política desse provedor.
Recursos de IA pagos são executados apenas com a permissão de Gasto e o orçamento de créditos que você definir; enviar dados aos serviços do PhotoFresco (documentos na nuvem, IA) exige a permissão de Envio.
A janela mostra quem está se conectando: o nome que o cliente MCP envia no handshake (" via MCP"), ou --client na linha de comando ("Terminal via CLI" por padrão).

Você mantém o controle: cada conexão exige sua Permissão, uma sessão começa sem permissões, e Parar, fechar a janela, recarregar ou sair do editor encerra a sessão. Fechar o conector fecha a janela dele.

Desinstalação

Remova a entrada do MCP da configuração do seu cliente (ou execute photofresco stop e npm uninstall -g photofresco), ou remova o plugin (/plugin uninstall photofresco@photofresco no Claude Code, codex plugin remove photofresco@photofresco, gemini extensions uninstall photofresco, hermes plugins remove photofresco, openclaw plugins uninstall photofresco, agy plugin uninstall photofresco, devin plugins remove photofresco, ou Personalizar no Cursor e o painel Powers no Kiro). Remova a skill com npx skills remove photofresco e exclua a pasta de dados acima. Nada mais está instalado.

Suporte

Perguntas e bugs: Issues do GitHub ou hello@photofresco.com.
Documentação: Usar o PhotoFresco com agentes de IA.
Política de privacidade: photofresco.com/docs/privacy.
Termos de serviço: photofresco.com/docs/terms.
Site: photofresco.com.

Licença

Este repositório (o servidor MCP, a linha de comando, o conector e a skill) é lançado sob a Licença MIT. O editor PhotoFresco e o serviço photofresco.com não fazem parte dele.