PeepIt

Um servidor exclusivo para macOS para capturar e analisar capturas de tela com modelos de IA locais ou baseados em nuvem.

GitHub

Experimente este MCPPatrocinado

Documentação

PeepIt MCP: Capturas de tela ultrarrápidas no macOS para Agentes de IA

PeepIt Banner

PeepIt: Porque Sua IA Merece Ver o Que Você Vê

Já desejou que seu assistente de IA pudesse apenas olhar para a sua tela e entender? O PeepIt está aqui para conceder ao seu companheiro digital o dom da visão—sem varinhas mágicas necessárias. Seja depurando uma interface, capturando um bug em ação, ou apenas querendo saber o que está escondido atrás daquela janela misteriosa, o PeepIt cuida de você (e da sua tela).

O que é o PeepIt?

O PeepIt é um servidor MCP exclusivo para macOS que permite que agentes de IA capturem capturas de tela dos seus aplicativos, janelas ou do sistema inteiro—e depois as analisem com modelos de IA locais ou baseados em nuvem. É como dar ao seu IA um par de óculos e uma lupa, tudo em um.

Capture capturas de tela de qualquer coisa: a tela inteira, um único aplicativo ou aquela janela que você nunca encontra
Analise conteúdo visual com modelos de visão de IA (local ou nuvem—você escolhe)
Liste aplicativos e janelas em execução para capturas precisas
Trabalhe de forma não intrusiva—sem roubar o foco da janela, sem interrupções no fluxo de trabalho, sem drama

Principais Recursos

🚀 Rápido e Não Intrusivo: Pisque e você perderá—o PeepIt usa o ScreenCaptureKit da Apple para capturas de tela ultrarrápidas, tudo sem sequestrar o foco da sua janela ou interromper seu ritmo.
🎯 Mira Inteligente de Janelas: Correspondência difusa tão precisa que encontrará a janela certa mesmo se você só lembrar metade do nome (todos nós já passamos por isso).
🤖 Análise com IA: Faça perguntas sobre suas capturas de tela e obtenha respostas do GPT-4o, Claude ou modelos locais—porque às vezes você precisa de um segundo par de olhos (robóticos).
🔒 Privacidade em Primeiro Lugar: Prefere manter as coisas discretas? Execute tudo localmente com Ollama, ou chame a cavalaria da nuvem apenas quando realmente precisar.
📦 Instalação Fácil: Instalação com um clique via Cursor, ou apenas um rápido encantamento npm/npx—sem rituais arcanos necessários.
🛠️ Amigável para Desenvolvedores: API JSON limpa, suporte a TypeScript e logs tão abrangentes que você vai se perguntar se o PeepIt está secretamente escrevendo suas memórias.

Instalação

Requisitos

macOS 14.0+ (Sonoma ou posterior)
Node.js 20.0+
Permissão de Gravação de Tela (não se preocupe, você será solicitado—sem necessidade de explorar as Configurações do Sistema)

Início Rápido

Para o Cursor IDE

Ou adicione manualmente às suas configurações do Cursor:

{
  "mcpServers": {
    "peepit": {
      "command": "npx",
      "args": [
        "-y",
        "@mantisware/peepit-mcp"
      ],
      "env": {
        "PEEPIT_AI_PROVIDERS": "openai/gpt-4o,ollama/llava:latest",
        "OPENAI_API_KEY": "your-openai-api-key-here"
      },
      "toolCallTimeoutMillis": 120000
    }
  }
}

Para o Claude Desktop

Edite o arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Adicione a configuração do PeepIt (copie, cole e você está a meio caminho da visão de IA):

{
  "mcpServers": {
    "peepit": {
      "command": "npx",
      "args": [
        "-y",
        "@mantisware/peepit-mcp"
      ],
      "env": {
        "PEEPIT_AI_PROVIDERS": "openai/gpt-4o,ollama/llava:latest",
        "OPENAI_API_KEY": "your-openai-api-key-here"
      }
    }
  }
}

Em seguida, reinicie o Claude Desktop. (Sim, você realmente precisa reiniciá-lo. Nós verificamos.)

Configuração

O PeepIt é tão configurável quanto seu editor de texto favorito. Use variáveis de ambiente para ajustá-lo ao seu fluxo de trabalho:

{
  "PEEPIT_AI_PROVIDERS": "openai/gpt-4o,ollama/llava:latest",
  "OPENAI_API_KEY": "your-openai-api-key-here",
  "PEEPIT_LOG_LEVEL": "debug",
  "PEEPIT_LOG_FILE": "~/Library/Logs/peepit-mcp-debug.log",
  "PEEPIT_DEFAULT_SAVE_PATH": "~/Pictures/PeepItCaptures",
  "PEEPIT_CONSOLE_LOGGING": "true",
  "PEEPIT_CLI_TIMEOUT": "30000",
  "PEEPIT_CLI_PATH": "/opt/custom/peepit"
}

Variáveis de Ambiente Disponíveis

Variável	Descrição	Padrão
`PEEPIT_AI_PROVIDERS`	Quem é sua IA? Liste provedores para análise de imagens (veja Análise de IA).	`""` (desativado)
`PEEPIT_LOG_LEVEL`	Quão tagarela o PeepIt deve ser? (trace, debug, info, warn, error, fatal)	`info`
`PEEPIT_LOG_FILE`	Onde guardar os logs. Se o diretório não for gravável, o PeepIt encontra uma pasta temporária aconchegante.	`~/Library/Logs/peepit-mcp.log`
`PEEPIT_DEFAULT_SAVE_PATH`	Diretório padrão para capturas de tela quando você não especifica um caminho.	Diretório temporário do sistema
`PEEPIT_OLLAMA_BASE_URL`	Onde está sua API do Ollama? Só é necessário se não estiver no local usual.	`http://localhost:11434`
`PEEPIT_CONSOLE_LOGGING`	Quer logs no seu console? Defina como `"true"` para compartilhamento máximo.	`"false"`
`PEEPIT_CLI_TIMEOUT`	Quanto tempo esperar pela mágica do Swift CLI (ms).	`30000` (30 segundos)
`PEEPIT_CLI_PATH`	Caminho personalizado para o CLI `peepit` do Swift, se você estiver se sentindo chique.	(usa CLI integrado)

Configuração do Provedor de IA

A variável PEEPIT_AI_PROVIDERS é seu bilhete dourado para análise de capturas de tela com IA. Quer que o PeepIt responda perguntas sobre sua tela? Basta listar seus modelos favoritos:

PEEPIT_AI_PROVIDERS="openai/gpt-4o,ollama/llava:latest,anthropic/claude-3-haiku-20240307"

Ou, se você é um conhecedor de ponto e vírgula:

PEEPIT_AI_PROVIDERS="openai/gpt-4o;ollama/llava:latest;anthropic/claude-3-haiku-20240307"

Cada entrada é provider_name/model_identifier. Provedores suportados: ollama (para local), openai (para a nuvem) e, em breve, anthropic (para os verdadeiramente aventureiros).

O PeepIt tentará os provedores em ordem, verificando chaves de API ou serviços locais conforme necessário. Você pode substituir o modelo por solicitação se estiver se sentindo exigente.

Configurando IA Local com Ollama

Ollama traz visão de IA para sua área de trabalho—sem nuvem necessária, sem dados saindo do seu Mac. (Seus segredos estão seguros. Provavelmente.)

Instalando o Ollama

brew install ollama
# Or download from https://ollama.ai
ollama serve

Baixando Modelos de Visão

Para máquinas potentes:

ollama pull llava:latest
ollama pull llava:7b-v1.6
ollama pull llava:13b-v1.6  # For the RAM-rich
ollama pull llava:34b-v1.6  # For the RAM-obsessed

Para laptops mais leves:

ollama pull qwen2-vl:7b

Guia de Tamanho de Modelo:

qwen2-vl:7b - ~4GB de download, ~6GB de RAM (ótimo para mortais)
llava:7b - ~4.5GB de download, ~8GB de RAM
llava:13b - ~8GB de download, ~16GB de RAM
llava:34b - ~20GB de download, ~40GB de RAM (traga lanches)

Configurando o PeepIt com Ollama

Adicione o Ollama à sua configuração do Claude Desktop:

{
  "mcpServers": {
    "peepit": {
      "command": "npx",
      "args": [
        "-y",
        "@mantisware/peepit-mcp@beta"
      ],
      "env": {
        "PEEPIT_AI_PROVIDERS": "ollama/llava:latest"
      }
    }
  }
}

Para máquinas mais leves:

{
  "mcpServers": {
    "peepit": {
      "command": "npx",
      "args": [
        "-y",
        "@mantisware/peepit-mcp@beta"
      ],
      "env": {
        "PEEPIT_AI_PROVIDERS": "ollama/qwen2-vl:7b"
      }
    }
  }
}

Combine e misture provedores de IA:

{
  "env": {
    "PEEPIT_AI_PROVIDERS": "ollama/llava:latest,openai/gpt-4o",
    "OPENAI_API_KEY": "your-api-key-here"
  }
}

Permissões do macOS

O PeepIt precisa de algumas permissões do macOS para fazer sua mágica. Não se preocupe, não está pedindo sua senha da Netflix.

1. Permissão de Gravação de Tela (Obrigatória)

macOS Sequoia (15.0+):

Configurações do Sistema → Privacidade e Segurança
Role até Gravação de Tela e Áudio do Sistema
Ative seu terminal ou cliente MCP
Reinicie o aplicativo (sim, de novo)

macOS Sonoma (14.0) e anteriores:

Preferências do Sistema → Segurança e Privacidade → Privacidade
Selecione Gravação de Tela
Clique no cadeado, digite sua senha
Adicione seu terminal ou cliente MCP
Reinicie o aplicativo

Aplicativos que precisam de permissão:

Terminal.app
Claude Desktop
VS Code
Cursor

2. Permissão de Acessibilidade (Opcional, mas agradável)

macOS Sequoia (15.0+):

Configurações do Sistema → Privacidade e Segurança → Acessibilidade
Ative seu terminal/cliente MCP

macOS Sonoma (14.0) e anteriores:

Preferências do Sistema → Segurança e Privacidade → Privacidade
Selecione Acessibilidade
Adicione seu terminal/cliente MCP

Testes e Depuração

Usando o MCP Inspector

Quer ver o PeepIt em ação? Inicie o MCP Inspector:

# Test with OpenAI
OPENAI_API_KEY="your-key" PEEPIT_AI_PROVIDERS="openai/gpt-4o" npx @modelcontextprotocol/inspector npx -y @mantisware/peepit-mcp

# Test with local Ollama
PEEPIT_AI_PROVIDERS="ollama/llava:latest" npx @modelcontextprotocol/inspector npx -y @mantisware/peepit-mcp

Teste Direto via CLI

./peepit --help
./peepit list server_status --json-output
./peepit image --mode screen --format png
peepit-mcp

Saída esperada:

{
  "success": true,
  "data": {
    "swift_cli_available": true,
    "permissions": {
      "screen_recording": true
    },
    "system_info": {
      "macos_version": "14.0"
    }
  }
}

Ferramentas Disponíveis

O PeepIt oferece três ferramentas principais—pense nelas como o canivete suíço da sua IA:

1. `image` - Capture Capturas de Tela

Tire uma captura de tela do seu Mac—tela, aplicativo ou janela. Sombras e molduras? Removidas. (De nada.)

Nota: As capturas de tela são sempre salvas em arquivos (sem Base64 para imagens gigantes—sua pilha não vai gostar). Se você pedir format: "data", o PeepIt educadamente ignorará você e salvará um PNG, com um aviso gentil.

Exemplos:

// Capture entire screen
await use_mcp_tool("peepit", "image", {
  app_target: "screen:0",
  path: "~/Desktop/screenshot.png"
});

// Capture a specific app window and analyze it
await use_mcp_tool("peepit", "image", {
  app_target: "Safari",
  question: "What website is currently open?",
  format: "data"
});

// Capture window by title
await use_mcp_tool("peepit", "image", {
  app_target: "Notes:WINDOW_TITLE:Meeting Notes",
  path: "~/Desktop/notes.png"
});

// Capture the frontmost window
await use_mcp_tool("peepit", "image", {
  app_target: "frontmost",
  format: "png"
});

// Capture by Process ID
await use_mcp_tool("peepit", "image", {
  app_target: "PID:663",
  path: "~/Desktop/process.png"
});

Filtragem de Auxiliares do Navegador: O PeepIt é inteligente o suficiente para evitar processos auxiliares do navegador (chega de travessuras do "Google Chrome Helper (Renderer)"). Você verá a janela real do navegador ou uma mensagem clara se não estiver em execução.

Comportamento de Nomes de Arquivo e Caminhos:

Captura única? Seu caminho é usado como está.
Várias capturas? O PeepIt adiciona metadados aos nomes de arquivo para que nada seja sobrescrito.
Caminho de diretório? O PeepIt gera nomes exclusivos para você.
Nomes de arquivo longos? O PeepIt os reduz para caber no limite de 255 bytes do macOS, mantendo seus emojis e scripts não latinos intactos.
Formatos inválidos? Apenas PNG e JPEG são permitidos. Qualquer outra coisa é convertida, com um aviso amigável.

2. `list` - Informações do Sistema

Liste aplicativos em execução, janelas ou verifique o status do servidor. Porque às vezes você só precisa saber o que está por aí.

Exemplos:

// List all running apps
await use_mcp_tool("peepit", "list", {
  item_type: "running_applications"
});

// List windows of a specific app
await use_mcp_tool("peepit", "list", {
  item_type: "application_windows",
  app: "Preview"
});

// List windows by PID
await use_mcp_tool("peepit", "list", {
  item_type: "application_windows",
  app: "PID:663"
});

// Check server status
await use_mcp_tool("peepit", "list", {
  item_type: "server_status"
});

3. `analyze` - Análise de Visão de IA

Alimente sua IA com uma imagem e pergunte qualquer coisa. (Bem, quase qualquer coisa.)

Exemplos:

// Analyze with auto-selected provider
await use_mcp_tool("peepit", "analyze", {
  image_path: "~/Desktop/screenshot.png",
  question: "What applications are visible?"
});

// Force a specific provider
await use_mcp_tool("peepit", "analyze", {
  image_path: "~/Desktop/diagram.jpg",
  question: "Explain this diagram",
  provider_config: {
    type: "ollama",
    model: "llava:13b"
  }
});

Testes

O PeepIt vem com muitos testes:

Testes TypeScript

Testes Unitários: Para o código que gosta de ficar sozinho
Testes de Integração: Para o código que se dá bem com os outros
Testes Específicos de Plataforma: Alguns testes precisam de macOS e do binário Swift

npm test                # Run all tests (macOS required for full suite)
npm run test:unit       # Unit tests only (any platform)
npm run test:typescript # TypeScript-only tests (Linux-friendly)
npm run test:typescript:watch # Watch mode
npm run test:coverage   # With coverage

Testes Swift

npm run test:swift      # Swift CLI tests (macOS only)
npm run test:integration # Full integration (TypeScript + Swift)

Suporte a Plataformas

macOS: Todos os testes
Linux/CI: Apenas TypeScript (testes Swift são ignorados)
Variáveis de Ambiente:
- SKIP_SWIFT_TESTS=true: Pular testes Swift
- CI=true: Pular testes Swift automaticamente

Solução de Problemas

Problema	Solução
`Permission denied` durante a captura	Conceda permissão de Gravação de Tela. Reinicie o aplicativo.
Problemas de captura de janela	Conceda permissão de Acessibilidade para uma segmentação mais confiável.
`Swift CLI unavailable`	Certifique-se de que o binário `peepit` esteja presente e executável. Reconstrua se necessário.
`AI analysis failed`	Verifique a configuração do provedor de IA e as chaves de API. Certifique-se de que os serviços locais estejam em execução. Verifique os logs para obter detalhes.
`Command not found: peepit-mcp`	Certifique-se de que seu PATH inclua os binários npm, ou use o comando correto.
Estranheza geral	Verifique os logs! Defina `PEEPIT_LOG_LEVEL=debug` para obter o máximo de detalhes.

Modo de Depuração

OPENAI_API_KEY="your-key" PEEPIT_AI_PROVIDERS="openai/gpt-4o" PEEPIT_LOG_LEVEL=debug PEEPIT_CONSOLE_LOGGING=true npx @mantisware/peepit-mcp
./peepit list server_status --json-output

Obtendo Ajuda

📚 Documentação

Compilando a partir do Código Fonte

Configuração de Desenvolvimento

git clone https://github.com/mantisware/peepit.git
cd peepit
npm install
npm run build
cd peepit-cli
swift build -c release
cp .build/release/peepit ../peepit
cd ..
npm link # Optional: install globally

Configuração de Desenvolvimento Local

Para desenvolvimento local:

{
  "mcpServers": {
    "peepit_local": {
      "command": "peepit-mcp",
      "args": [],
      "env": {
        "PEEPIT_LOG_LEVEL": "debug",
        "PEEPIT_CONSOLE_LOGGING": "true"
      }
    }
  }
}

Ou, executando diretamente com node:

{
  "mcpServers": {
    "peepit_local_node": {
      "command": "node",
      "args": [
        "/Users/mantisware/Projects/PeepIt/dist/index.js"
      ],
      "env": {
        "PEEPIT_LOG_LEVEL": "debug",
        "PEEPIT_CONSOLE_LOGGING": "true"
      }
    }
  }
}

Use caminhos absolutos e nomes de servidor exclusivos para evitar confusão.

Versão AppleScript (Legado)

Para o pessoal da velha escola:

osascript peepit.scpt

Nota: Sem análise de IA ou recursos MCP nesta versão.

Configuração Manual para Outros Clientes MCP

{
  "server": {
    "command": "node",
    "args": ["/path/to/peepit/dist/index.js"],
    "env": {
      "PEEPIT_AI_PROVIDERS": "openai/gpt-4o,ollama/llava",
      "OPENAI_API_KEY": "your-openai-api-key-here"
    }
  }
}

Documentação de Ferramentas

`image` - Captura de Tela

Capture a tela do seu Mac e opcionalmente analise-a. Sombras e molduras são automaticamente banidas. Parâmetros:

app_target (string, opcional): Especifica o alvo da captura. Se omitido ou vazio, captura todas as telas.
- Exemplos:
  - "screen:INDEX": Captura a tela no índice baseado em zero especificado (ex.: "screen:0"). (Observação: A seleção de índice entre múltiplas telas está planejada para suporte completo no Swift CLI).
  - "frontmost": Captura a janela mais à frente do aplicativo ativo no momento.
  - "AppName": Captura todas as janelas do aplicativo chamado AppName (ex.: "Safari", "com.apple.Safari"). A correspondência difusa é usada.
  - "PID:ProcessID": Captura todas as janelas do aplicativo com o ID de processo especificado (ex.: "PID:663"). Útil quando várias instâncias do mesmo aplicativo estão em execução.
  - "AppName:WINDOW_TITLE:Title": Captura a janela de AppName que possui o Title especificado (ex.: "Notes:WINDOW_TITLE:My Important Note").
  - "AppName:WINDOW_INDEX:Index": Captura a janela de AppName no Index baseado em zero especificado (ex.: "Preview:WINDOW_INDEX:0" para a janela mais à frente do Preview).
path (string, opcional): Caminho absoluto base para salvar a(s) imagem(ns) capturada(s). Se format for "data" e path também for fornecido, a imagem é salva neste caminho (como PNG) E os dados Base64 são retornados. Se um question for fornecido e path for omitido, um caminho temporário é usado para a captura, e o arquivo é excluído após a análise.
question (string, opcional): Se fornecido, a imagem capturada será analisada. O servidor seleciona automaticamente um provedor de IA entre os configurados na variável de ambiente PEEPIT_AI_PROVIDERS.
format (string, opcional, padrão: "png"): Especifica o formato da imagem de saída ou o tipo de retorno de dados.
- "png" ou "jpg": Salva a imagem no path especificado no formato escolhido. Para capturas de aplicativos: se path não for fornecido, comporta-se como "data". Para capturas de tela: sempre salva em arquivo.
- "data": Retorna dados PNG codificados em Base64 da imagem diretamente na resposta do MCP. Se path também for especificado, um arquivo PNG também é salvo nesse path. Observação: Capturas de tela não podem usar este formato e automaticamente usarão o formato de arquivo PNG.
- Valores inválidos (strings vazias, nulos ou formatos não reconhecidos) automaticamente usam "png".
capture_focus (string, opcional, padrão: "background"): Controla o comportamento do foco da janela durante a captura.
- "background": Captura sem alterar o foco atual da janela (padrão).
- "foreground": Tenta trazer o aplicativo/janela alvo para o primeiro plano antes da captura. Isso pode ser necessário para certos aplicativos ou para garantir que uma janela específica seja capturada se várias estiverem abertas.

Comportamento com question (Análise de IA):

Se um question for fornecido, a ferramenta capturará a imagem (salvando-a em path se especificado, ou em um caminho temporário caso contrário).
Esta imagem é então enviada a um modelo de IA para análise. O provedor de IA e o modelo são escolhidos automaticamente pelo servidor com base na sua variável de ambiente PEEPIT_AI_PROVIDERS (tentando-os em ordem até que um tenha sucesso).
O resultado da análise é retornado como analysis_text na resposta. Os dados da imagem (Base64) NÃO são retornados no array content quando uma pergunta é feita.
Se um caminho temporário foi usado para a imagem, ele é excluído após a tentativa de análise.

Estrutura de Saída (Simplificada):

content: Pode conter ImageContentItem (se format: "data" ou path foi omitido, e nenhum question) e/ou TextContentItem (para resumos, texto de análise, avisos).
saved_files: Array de objetos, cada um detalhando um arquivo salvo em path (se path foi fornecido).
analysis_text: Texto da IA (se question foi perguntado).
model_used: Identificador do modelo de IA (se question foi perguntado).

Para documentação detalhada dos parâmetros, consulte docs/spec.md.

Nomenclatura de Arquivos e Comportamento de Caminho

O PeepIt gerencia inteligentemente os caminhos de saída para evitar sobrescritas de arquivos, respeitando suas intenções:

Princípio-chave: Capturas Únicas vs. Múltiplas

Quando você fornece um caminho de arquivo específico (ex.: ~/Desktop/screenshot.png), o PeepIt determina se deve usá-lo exatamente ou adicionar metadados com base no contexto da captura:

Captura Única → Caminho Exato
- Capturar uma janela específica
- Capturar uma tela específica (quando existe apenas um monitor)
- Capturar com app_target: "frontmost"
- Seu caminho é usado exatamente como especificado
Capturas Múltiplas → Metadados Adicionados
- Capturar todas as janelas de um aplicativo (mode: "multi" ou várias janelas existem)
- Capturar todas as telas (quando existem múltiplos monitores)
- Capturar sem alvo específico (padrão para todas as telas)
- Metadados são anexados para evitar sobrescritas

Exemplos:

// SINGLE CAPTURES - Use exact path
// ================================

// One window of Safari
await use_mcp_tool("peepit", "image", {
  app_target: "Safari",
  path: "~/Desktop/browser.png"
});
// Result: ~/Desktop/browser.png ✓

// Specific screen (when you have only one monitor)
await use_mcp_tool("peepit", "image", {
  app_target: "screen:0",
  path: "~/Desktop/myscreen.png"
});
// Result: ~/Desktop/myscreen.png ✓

// Frontmost window
await use_mcp_tool("peepit", "image", {
  app_target: "frontmost",
  path: "~/Desktop/active.png"
});
// Result: ~/Desktop/active.png ✓

// MULTIPLE CAPTURES - Add metadata
// ================================

// All windows of Safari (mode: multi)
await use_mcp_tool("peepit", "image", {
  app_target: "Safari",
  mode: "multi",
  path: "~/Desktop/browser.png"
});
// Results: ~/Desktop/browser_Safari_window_0_20250610_120000.png
//          ~/Desktop/browser_Safari_window_1_20250610_120000.png

// All screens (multiple monitors)
await use_mcp_tool("peepit", "image", {
  app_target: "screen",  // or omit app_target
  path: "~/Desktop/monitor.png"
});
// Results: ~/Desktop/monitor_1_20250610_120000.png
//          ~/Desktop/monitor_2_20250610_120000.png

// DIRECTORY PATHS - Always use generated names
// ============================================

// Directory path (note trailing slash)
await use_mcp_tool("peepit", "image", {
  app_target: "Safari",
  path: "~/Desktop/screenshots/"
});
// Result: ~/Desktop/screenshots/Safari_20250610_120000.png

Proteção de Nomes de Arquivo Longos:

O PeepIt lida automaticamente com as limitações do sistema de arquivos:

Trunca nomes de arquivo que excedem o limite de 255 bytes do macOS
Preserva caracteres multibyte UTF-8 (emoji, scripts não latinos)
Garante que os metadados sejam sempre incluídos quando necessário
Nunca cria nomes de arquivo inválidos

Exemplo:

// Very long filename with emoji
await use_mcp_tool("peepit", "image", {
  app_target: "Safari",
  path: "~/Desktop/" + "🎯".repeat(100) + "_screenshot.png"
});
// Result: Filename safely truncated to fit 255-byte limit
//         while preserving valid UTF-8 characters

Validação de Formato:

Formatos inválidos ("bmp", "gif", "tiff", etc.) são automaticamente convertidos para PNG
Você receberá uma mensagem de aviso clara quando a correção de formato ocorrer
Apenas "png" e "jpg"/"jpeg" são formatos válidos

Filtragem de Auxiliares do Navegador:

O PeepIt filtra automaticamente os processos auxiliares do navegador ao procurar navegadores comuns (Chrome, Safari, Firefox, Edge, Brave, Arc, Opera). Isso evita erros confusos quando processos auxiliares como "Google Chrome Helper (Renderer)" são correspondidos em vez do aplicativo principal do navegador.

Exemplos:

// ✅ Finds main Chrome browser, not helpers
await use_mcp_tool("peepit", "image", {
  app_target: "Chrome"
});

// ❌ Old behavior: Could match "Google Chrome Helper (Renderer)"
//     Result: "no capturable windows were found" 
// ✅ New behavior: Finds "Google Chrome" or shows "Chrome browser is not running"

Mensagens de Erro Específicas do Navegador:

Em vez de "Aplicativo não encontrado" genérico
Mostra mensagens claras como "O navegador Chrome não está em execução ou não foi encontrado"
Aplica-se apenas a identificadores de navegador - outros aplicativos funcionam normalmente

Recursos Técnicos

Suporte a múltiplos monitores: Cada monitor tem seu próprio momento de destaque
Segmentação inteligente de aplicativos: Correspondência difusa para nomes de aplicativos
Múltiplos formatos: PNG, JPEG, WebP, HEIF
Nomenclatura automática: Baseada em timestamp, sem sobrescritas
Verificação de permissões: Sem surpresas
Listagem de aplicativos: Veja o que está em execução
Enumeração de janelas: Liste todas as janelas de um aplicativo
Segmentação por PID: Para os obcecados por processos
Monitoramento de status: Saiba o que está ativo
Independente de provedor: Ollama, OpenAI e em breve Anthropic
Linguagem natural: Faça perguntas sobre imagens
Configurável: Baseado em ambiente
Suporte a fallback: Failover automático entre provedores

Arquitetura

PeepIt/
├── src/                      # Node.js MCP Server (TypeScript)
│   ├── index.ts             # Main MCP server entry point
│   ├── tools/               # Individual tool implementations
│   │   ├── image.ts         # Screen capture tool
│   │   ├── analyze.ts       # AI analysis tool  
│   │   └── list.ts          # Application/window listing
│   ├── utils/               # Utility modules
│   │   ├── peepit-cli.ts   # Swift CLI integration
│   │   ├── ai-providers.ts  # AI provider management
│   │   └── server-status.ts # Server status utilities
│   └── types/               # Shared type definitions
├── peepit-cli/            # Native Swift CLI
│   └── Sources/peepit/    # Swift source files
│       ├── main.swift       # CLI entry point
│       ├── ImageCommand.swift    # Image capture implementation
│       ├── ListCommand.swift     # Application listing
│       ├── Models.swift          # Data structures
│       ├── ApplicationFinder.swift   # App discovery logic
│       ├── WindowManager.swift      # Window management
│       ├── PermissionsChecker.swift # macOS permissions
│       └── JSONOutput.swift        # JSON response formatting
├── package.json             # Node.js dependencies
├── tsconfig.json           # TypeScript configuration
└── README.md               # This file

Detalhes Técnicos

Formato de Saída JSON

O Swift CLI gera JSON estruturado quando chamado com --json-output:

{
  "success": true,
  "data": {
    "applications": [
      {
        "app_name": "Safari",
        "bundle_id": "com.apple.Safari", 
        "pid": 1234,
        "is_active": true,
        "window_count": 2
      }
    ]
  },
  "debug_logs": ["Found 50 applications"]
}

Integração MCP

O servidor Node.js fornece:

Validação de esquema via Zod
Códigos de erro MCP adequados
Registro estruturado via Pino
Segurança total de tipos TypeScript

Segurança

O PeepIt respeita a segurança do macOS:

Verifica permissões antes das operações
Tratamento gracioso de permissões ausentes
Orientação clara para configuração de permissões

Desenvolvimento

Comandos de Teste

./peepit list apps --json-output | head -20
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js

Compilação

npm run build
cd peepit-cli && swift build

Problemas Conhecidos

Aviso de FileHandle: Aviso não crítico do Swift sobre conformidade com TextOutputStream
Configuração do Provedor de IA: Requer a variável de ambiente PEEPIT_AI_PROVIDERS para recursos de análise

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Contribuindo

Faça um fork do repositório
Crie um branch de recurso (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

Autor

Criado por Peter Steinberger - @mantisware

Leia mais sobre o design e a implementação do PeepIt no post do blog.

PeepIt

Documentação

PeepIt MCP: Capturas de tela ultrarrápidas no macOS para Agentes de IA

PeepIt: Porque Sua IA Merece Ver o Que Você Vê

O que é o PeepIt?

Principais Recursos

Instalação

Requisitos

Início Rápido

Para o Cursor IDE

Para o Claude Desktop

Configuração

Variáveis de Ambiente Disponíveis

Configuração do Provedor de IA

Configurando IA Local com Ollama

Instalando o Ollama

Baixando Modelos de Visão

Configurando o PeepIt com Ollama

Permissões do macOS

1. Permissão de Gravação de Tela (Obrigatória)

2. Permissão de Acessibilidade (Opcional, mas agradável)

Testes e Depuração

Usando o MCP Inspector

Teste Direto via CLI

Ferramentas Disponíveis

1. image - Capture Capturas de Tela

2. list - Informações do Sistema

3. analyze - Análise de Visão de IA

Testes

Testes TypeScript

Testes Swift

Suporte a Plataformas

Solução de Problemas

Modo de Depuração

Obtendo Ajuda

Compilando a partir do Código Fonte

Configuração de Desenvolvimento

Configuração de Desenvolvimento Local

Versão AppleScript (Legado)

Configuração Manual para Outros Clientes MCP

Documentação de Ferramentas

image - Captura de Tela

Nomenclatura de Arquivos e Comportamento de Caminho

Recursos Técnicos

Arquitetura

Detalhes Técnicos

Formato de Saída JSON

Integração MCP

Segurança

Desenvolvimento

Comandos de Teste

Compilação

Problemas Conhecidos

Licença

Contribuindo

Autor

1. `image` - Capture Capturas de Tela

2. `list` - Informações do Sistema

3. `analyze` - Análise de Visão de IA

`image` - Captura de Tela