PeepIt

Un servidor solo para macOS para capturar y analizar capturas de pantalla con modelos de IA locales o basados en la nube.

GitHub

Prueba este MCPPatrocinado

Documentación

PeepIt MCP: Capturas de pantalla ultrarrápidas para macOS, pensadas para agentes de IA

PeepIt Banner

PeepIt: Porque tu IA merece ver lo que tú ves

¿Alguna vez has deseado que tu asistente de IA pudiera mirar tu pantalla y entenderla? PeepIt está aquí para otorgarle a tu compañero digital el don de la vista, sin necesidad de varitas mágicas. Ya sea que estés depurando una interfaz, capturando un error en plena acción, o simplemente quieras saber qué se esconde detrás de esa ventana misteriosa, PeepIt te cubre las espaldas (y tu pantalla).

¿Qué es PeepIt?

PeepIt es un servidor MCP exclusivo para macOS que permite a los agentes de IA capturar capturas de pantalla de tus aplicaciones, ventanas o de todo el sistema, y luego analizarlas con modelos de IA locales o en la nube. Es como darle a tu IA un par de gafas y una lupa, todo en uno.

Captura capturas de pantalla de cualquier cosa: toda la pantalla, una sola aplicación, o esa ventana que nunca encuentras
Analiza contenido visual con modelos de visión por IA (locales o en la nube, tú decides)
Lista aplicaciones y ventanas en ejecución para capturas precisas
Trabaja de forma no intrusiva: sin robar el foco de la ventana, sin interrupciones en tu flujo de trabajo, sin dramas

Características principales

🚀 Rápido y no intrusivo: Parpadea y te lo pierdes: PeepIt usa ScreenCaptureKit de Apple para capturas ultrarrápidas, todo sin secuestrar el foco de tu ventana ni interrumpir tu ritmo.
🎯 Selección inteligente de ventanas: Coincidencia difusa tan precisa que encontrará la ventana correcta incluso si solo recuerdas la mitad de su nombre (todos hemos pasado por eso).
🤖 Análisis impulsado por IA: Haz preguntas sobre tus capturas de pantalla y obtén respuestas de GPT-4o, Claude o modelos locales, porque a veces necesitas un segundo par de ojos (robóticos).
🔒 Privacidad primero: ¿Prefieres mantener las cosas en secreto? Ejecuta todo localmente con Ollama, o recurre a la nube solo cuando realmente lo necesites.
📦 Instalación fácil: Instalación con un clic a través de Cursor, o simplemente un rápido conjuro con npm/npx, sin rituales arcanos.
🛠️ Amigable para desarrolladores: API JSON limpia, soporte para TypeScript y registros tan completos que te preguntarás si PeepIt está escribiendo secretamente tus memorias.

Instalación

Requisitos

macOS 14.0+ (Sonoma o posterior)
Node.js 20.0+
Permiso de grabación de pantalla (no te preocupes, se te pedirá, no necesitas buscar en Ajustes del Sistema)

Inicio rápido

Para Cursor IDE

O añádelo manualmente a tu configuración de 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 Claude Desktop

Edita tu archivo de configuración de Claude Desktop:

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

Añade la configuración de PeepIt (copia, pega, y ya estás a mitad de camino de la visión por 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"
      }
    }
  }
}

Luego reinicia Claude Desktop. (Sí, de verdad tienes que reiniciarlo. Lo comprobamos.)

Configuración

PeepIt es tan configurable como tu editor de texto favorito. Usa variables de entorno para ajustarlo a tu flujo de trabajo:

{
  "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"
}

Variables de entorno disponibles

Variable	Descripción	Valor predeterminado
`PEEPIT_AI_PROVIDERS`	¿Quién es tu IA? Lista de proveedores para el análisis de imágenes (consulta Análisis de IA).	`""` (deshabilitado)
`PEEPIT_LOG_LEVEL`	¿Cuán hablador debe ser PeepIt? (trace, debug, info, warn, error, fatal)	`info`
`PEEPIT_LOG_FILE`	Dónde guardar los registros. Si el directorio no es escribible, PeepIt encuentra una carpeta temporal acogedora.	`~/Library/Logs/peepit-mcp.log`
`PEEPIT_DEFAULT_SAVE_PATH`	Directorio predeterminado para capturas de pantalla cuando no especificas una ruta.	Directorio temporal del sistema
`PEEPIT_OLLAMA_BASE_URL`	¿Dónde está tu API de Ollama? Solo se necesita si no está en el lugar habitual.	`http://localhost:11434`
`PEEPIT_CONSOLE_LOGGING`	¿Quieres registros en tu consola? Establécelo en `"true"` para compartir al máximo.	`"false"`
`PEEPIT_CLI_TIMEOUT`	Cuánto tiempo esperar por la magia de la CLI de Swift (ms).	`30000` (30 segundos)
`PEEPIT_CLI_PATH`	Ruta personalizada a la CLI de Swift `peepit`, si te sientes elegante.	(usa la CLI incluida)

Configuración del proveedor de IA

La variable PEEPIT_AI_PROVIDERS es tu boleto dorado para el análisis de capturas de pantalla con IA. ¿Quieres que PeepIt responda preguntas sobre tu pantalla? Simplemente lista tus modelos favoritos:

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

O, si eres un conocedor de los puntos y comas:

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

Cada entrada es provider_name/model_identifier. Proveedores compatibles: ollama (para local), openai (para la nube), y pronto, anthropic (para los verdaderamente aventureros).

PeepIt probará los proveedores en orden, verificando las claves de API o los servicios locales según sea necesario. Puedes anular el modelo por solicitud si te sientes particular.

Configuración de IA local con Ollama

Ollama lleva la visión por IA a tu escritorio, sin necesidad de nube, sin que los datos salgan de tu Mac. (Tus secretos están a salvo. Probablemente.)

Instalación de Ollama

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

Descarga de modelos de visión

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 portátiles más ligeros:

ollama pull qwen2-vl:7b

Guía de tamaño de modelos:

qwen2-vl:7b - Descarga de ~4GB, ~6GB de RAM (ideal para mortales)
llava:7b - Descarga de ~4.5GB, ~8GB de RAM
llava:13b - Descarga de ~8GB, ~16GB de RAM
llava:34b - Descarga de ~20GB, ~40GB de RAM (trae bocadillos)

Configuración de PeepIt con Ollama

Añade Ollama a tu configuración de Claude Desktop:

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

Para máquinas más ligeras:

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

Combina y combina proveedores de IA:

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

Permisos de macOS

PeepIt necesita algunos permisos de macOS para hacer su magia. No te preocupes, no te está pidiendo tu contraseña de Netflix.

1. Permiso de grabación de pantalla (obligatorio)

macOS Sequoia (15.0+):

Ajustes del Sistema → Privacidad y seguridad
Desplázate hasta Grabación de pantalla y audio del sistema
Activa tu terminal o cliente MCP
Reinicia la aplicación (sí, otra vez)

macOS Sonoma (14.0) y anteriores:

Preferencias del Sistema → Seguridad y privacidad → Privacidad
Selecciona Grabación de pantalla
Haz clic en el candado, introduce tu contraseña
Añade tu terminal o cliente MCP
Reinicia la aplicación

Aplicaciones que necesitan permiso:

Terminal.app
Claude Desktop
VS Code
Cursor

2. Permiso de accesibilidad (opcional, pero agradable)

macOS Sequoia (15.0+):

Ajustes del Sistema → Privacidad y seguridad → Accesibilidad
Activa tu terminal/cliente MCP

macOS Sonoma (14.0) y anteriores:

Preferencias del Sistema → Seguridad y privacidad → Privacidad
Selecciona Accesibilidad
Añade tu terminal/cliente MCP

Pruebas y depuración

Uso del Inspector MCP

¿Quieres ver a PeepIt en acción? Inicia el Inspector MCP:

# 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

Pruebas directas con CLI

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

Salida esperada:

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

Herramientas disponibles

PeepIt te ofrece tres herramientas principales: piensa en ellas como la navaja suiza de tu IA:

1. `image` - Capturar capturas de pantalla

Toma una captura de pantalla de tu Mac: pantalla, aplicación o ventana. ¿Sombras y marcos? Eliminados. (De nada.)

Nota: Las capturas de pantalla siempre se guardan en archivos (sin Base64 para imágenes gigantes: a tu stack no le gustará). Si pides format: "data", PeepIt te ignorará cortésmente y guardará un PNG en su lugar, con una suave advertencia.

Ejemplos:

// 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"
});

Filtrado de procesos auxiliares del navegador: PeepIt es lo suficientemente inteligente como para evitar los procesos auxiliares del navegador (se acabaron las travesuras de "Google Chrome Helper (Renderer)"). Obtendrás la ventana real del navegador, o un mensaje claro si no se está ejecutando.

Comportamiento de nombres de archivo y rutas:

¿Captura única? Tu ruta se usa tal cual.
¿Capturas múltiples? PeepIt añade metadatos a los nombres de archivo para que nada se sobrescriba.
¿Ruta de directorio? PeepIt genera nombres únicos por ti.
¿Nombres de archivo largos? PeepIt los recorta para ajustarse al límite de 255 bytes de macOS, manteniendo tus emojis y scripts no latinos intactos.
¿Formatos no válidos? Solo se permiten PNG y JPEG. Cualquier otra cosa se convierte, con una advertencia amistosa.

2. `list` - Información del sistema

Lista aplicaciones en ejecución, ventanas o verifica el estado del servidor. Porque a veces solo necesitas saber qué hay ahí fuera.

Ejemplos:

// 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álisis de visión por IA

Alimenta una imagen a tu IA y pregúntale cualquier cosa. (Bueno, casi cualquier cosa.)

Ejemplos:

// 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"
  }
});

Pruebas

PeepIt viene con un montón de pruebas:

Pruebas de TypeScript

Pruebas unitarias: Para el código que le gusta estar solo
Pruebas de integración: Para el código que se lleva bien con los demás
Pruebas específicas de plataforma: Algunas pruebas necesitan macOS y el binario de 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

Pruebas de Swift

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

Soporte de plataforma

macOS: Todas las pruebas
Linux/CI: Solo TypeScript (las pruebas de Swift se omiten)
Variables de entorno:
- SKIP_SWIFT_TESTS=true: Omitir pruebas de Swift
- CI=true: Omitir pruebas de Swift automáticamente

Solución de problemas

Problema	Solución
`Permission denied` durante la captura	Concede el permiso de grabación de pantalla. Reinicia la aplicación.
Problemas de captura de ventanas	Concede el permiso de accesibilidad para una selección más fiable.
`Swift CLI unavailable`	Asegúrate de que el binario `peepit` esté presente y sea ejecutable. Reconstruye si es necesario.
`AI analysis failed`	Verifica la configuración de tu proveedor de IA y las claves de API. Asegúrate de que los servicios locales estén en ejecución. Revisa los registros para más detalles.
`Command not found: peepit-mcp`	Asegúrate de que tu PATH incluya los binarios de npm, o usa el comando correcto.
Rarezas generales	¡Revisa los registros! Establece `PEEPIT_LOG_LEVEL=debug` para obtener el máximo detalle.

Modo de depuración

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

Obtener ayuda

📚 Documentación

Compilación desde el código fuente

Configuración de desarrollo

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

Configuración de desarrollo local

Para desarrollo local:

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

O, ejecutando directamente con node:

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

Usa rutas absolutas y nombres de servidor únicos para evitar confusiones.

Versión de AppleScript (heredada)

Para los más clásicos:

osascript peepit.scpt

Nota: Esta versión no incluye análisis de IA ni funciones MCP.

Configuración manual para otros 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"
    }
  }
}

Documentación de herramientas

`image` - Captura de pantalla

Captura la pantalla de tu Mac y, opcionalmente, analízala. Las sombras y los marcos se eliminan automáticamente. Parámetros:

app_target (cadena, opcional): Especifica el objetivo de captura. Si se omite o está vacío, captura todas las pantallas.
- Ejemplos:
  - "screen:INDEX": Captura la pantalla en el índice de base cero especificado (p. ej., "screen:0"). (Nota: La selección de índice de múltiples pantallas está planificada para soporte completo en el CLI de Swift).
  - "frontmost": Captura la ventana más frontal de la aplicación activa actualmente.
  - "AppName": Captura todas las ventanas de la aplicación llamada AppName (p. ej., "Safari", "com.apple.Safari"). Se utiliza coincidencia difusa.
  - "PID:ProcessID": Captura todas las ventanas de la aplicación con el ID de proceso especificado (p. ej., "PID:663"). Útil cuando se ejecutan múltiples instancias de la misma aplicación.
  - "AppName:WINDOW_TITLE:Title": Captura la ventana de AppName que tiene el Title especificado (p. ej., "Notes:WINDOW_TITLE:My Important Note").
  - "AppName:WINDOW_INDEX:Index": Captura la ventana de AppName en el Index de base cero especificado (p. ej., "Preview:WINDOW_INDEX:0" para la ventana más frontal de Vista Previa).
path (cadena, opcional): Ruta absoluta base para guardar la(s) imagen(es) capturada(s). Si format es "data" y path también se proporciona, la imagen se guarda en esta ruta (como PNG) Y se devuelven datos Base64. Si se proporciona un question y se omite path, se utiliza una ruta temporal para la captura y el archivo se elimina después del análisis.
question (cadena, opcional): Si se proporciona, la imagen capturada será analizada. El servidor selecciona automáticamente un proveedor de IA de los configurados en la variable de entorno PEEPIT_AI_PROVIDERS.
format (cadena, opcional, predeterminado: "png"): Especifica el formato de imagen de salida o el tipo de retorno de datos.
- "png" o "jpg": Guarda la imagen en el path especificado en el formato elegido. Para capturas de aplicación: si no se proporciona path, se comporta como "data". Para capturas de pantalla: siempre guarda en archivo.
- "data": Devuelve datos PNG codificados en Base64 de la imagen directamente en la respuesta MCP. Si también se especifica path, también se guarda un archivo PNG en ese path. Nota: Las capturas de pantalla no pueden usar este formato y automáticamente recurrirán al formato de archivo PNG.
- Los valores no válidos (cadenas vacías, nulos o formatos no reconocidos) recurren automáticamente a "png".
capture_focus (cadena, opcional, predeterminado: "background"): Controla el comportamiento del foco de ventana durante la captura.
- "background": Captura sin alterar el foco de ventana actual (predeterminado).
- "foreground": Intenta llevar la aplicación/ventana objetivo al primer plano antes de la captura. Esto puede ser necesario para ciertas aplicaciones o para asegurar que se capture una ventana específica si hay varias abiertas.

Comportamiento con question (Análisis de IA):

Si se proporciona un question, la herramienta capturará la imagen (guardándola en path si se especifica, o en una ruta temporal en caso contrario).
Esta imagen se envía luego a un modelo de IA para su análisis. El proveedor y el modelo de IA son elegidos automáticamente por el servidor según su variable de entorno PEEPIT_AI_PROVIDERS (probándolos en orden hasta que uno tenga éxito).
El resultado del análisis se devuelve como analysis_text en la respuesta. Los datos de imagen (Base64) NO se devuelven en el arreglo content cuando se hace una pregunta.
Si se usó una ruta temporal para la imagen, se elimina después del intento de análisis.

Estructura de salida (simplificada):

content: Puede contener ImageContentItem (si se omitió format: "data" o path, y no hay question) y/o TextContentItem (para resúmenes, texto de análisis, advertencias).
saved_files: Arreglo de objetos, cada uno detallando un archivo guardado en path (si se proporcionó path).
analysis_text: Texto de IA (si se preguntó question).
model_used: Identificador del modelo de IA (si se preguntó question).

Para documentación detallada de parámetros, consulte docs/spec.md.

Comportamiento de nombres de archivo y rutas

PeepIt gestiona inteligentemente las rutas de salida para evitar sobrescrituras de archivos respetando sus intenciones:

Principio clave: capturas únicas vs. múltiples

Cuando proporciona una ruta de archivo específica (p. ej., ~/Desktop/screenshot.png), PeepIt determina si usarla exactamente o agregar metadatos según el contexto de captura:

Captura única → Ruta exacta
- Capturar una ventana específica
- Capturar una pantalla específica (cuando solo existe una pantalla)
- Capturar con app_target: "frontmost"
- Su ruta se usa exactamente como se especificó
Capturas múltiples → Se agregan metadatos
- Capturar todas las ventanas de una aplicación (mode: "multi" o existen múltiples ventanas)
- Capturar todas las pantallas (cuando existen múltiples pantallas)
- Capturar sin objetivo específico (por defecto todas las pantallas)
- Se agregan metadatos para evitar sobrescrituras

Ejemplos:

// 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

Protección de nombres de archivo largos:

PeepIt maneja automáticamente las limitaciones del sistema de archivos:

Trunca nombres de archivo que exceden el límite de 255 bytes de macOS
Preserva caracteres multibyte UTF-8 (emoji, escrituras no latinas)
Asegura que los metadatos siempre se incluyan cuando sea necesario
Nunca crea nombres de archivo no válidos

Ejemplo:

// 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

Validación de formato:

Los formatos no válidos ("bmp", "gif", "tiff", etc.) se convierten automáticamente a PNG
Recibirá un mensaje de advertencia claro cuando ocurra la corrección de formato
Solo "png" y "jpg"/"jpeg" son formatos válidos

Filtrado de ayudantes de navegador:

PeepIt filtra automáticamente los procesos auxiliares del navegador al buscar navegadores comunes (Chrome, Safari, Firefox, Edge, Brave, Arc, Opera). Esto evita errores confusos cuando se emparejan procesos auxiliares como "Google Chrome Helper (Renderer)" en lugar de la aplicación principal del navegador.

Ejemplos:

// ✅ 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"

Mensajes de error específicos del navegador:

En lugar del genérico "Aplicación no encontrada"
Muestra mensajes claros como "El navegador Chrome no está en ejecución o no se encontró"
Solo se aplica a identificadores de navegador: otras aplicaciones funcionan normalmente

Características técnicas

Soporte multi-pantalla: Cada monitor tiene su propio momento de protagonismo
Orientación inteligente de aplicaciones: Coincidencia difusa para nombres de aplicaciones
Múltiples formatos: PNG, JPEG, WebP, HEIF
Nombrado automático: Basado en marcas de tiempo, sin sobrescrituras
Verificación de permisos: Sin sorpresas
Listado de aplicaciones: Vea lo que está en ejecución
Enumeración de ventanas: Liste todas las ventanas de una aplicación
Orientación por PID: Para los obsesionados con procesos
Monitoreo de estado: Sepa qué está activo
Independiente del proveedor: Ollama, OpenAI y pronto Anthropic
Lenguaje natural: Haga preguntas sobre imágenes
Configurable: Basado en entorno
Soporte de respaldo: Conmutación automática entre proveedores

Arquitectura

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

Detalles técnicos

Formato de salida JSON

El CLI de Swift genera JSON estructurado cuando se llama con --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"]
}

Integración MCP

El servidor Node.js proporciona:

Validación de esquema mediante Zod
Códigos de error MCP adecuados
Registro estructurado mediante Pino
Seguridad de tipos completa en TypeScript

Seguridad

PeepIt respeta la seguridad de macOS:

Verifica permisos antes de las operaciones
Manejo elegante de permisos faltantes
Guía clara para la configuración de permisos

Desarrollo

Comandos de prueba

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

Compilación

npm run build
cd peepit-cli && swift build

Problemas conocidos

Advertencia de FileHandle: Advertencia no crítica de Swift sobre la conformidad con TextOutputStream
Configuración del proveedor de IA: Requiere la variable de entorno PEEPIT_AI_PROVIDERS para las funciones de análisis

Licencia

Licencia MIT: consulte el archivo LICENSE para más detalles.

Contribuciones

Haga un fork del repositorio
Cree una rama de características (git checkout -b feature/amazing-feature)
Haga commit de sus cambios (git commit -m 'Add amazing feature')
Haga push a la rama (git push origin feature/amazing-feature)
Abra una solicitud de extracción (Pull Request)

Autor

Creado por Peter Steinberger - @mantisware

Lea más sobre el diseño e implementación de PeepIt en la publicación del blog.

PeepIt

Documentación

PeepIt MCP: Capturas de pantalla ultrarrápidas para macOS, pensadas para agentes de IA

PeepIt: Porque tu IA merece ver lo que tú ves

¿Qué es PeepIt?

Características principales

Instalación

Requisitos

Inicio rápido

Para Cursor IDE

Para Claude Desktop

Configuración

Variables de entorno disponibles

Configuración del proveedor de IA

Configuración de IA local con Ollama

Instalación de Ollama

Descarga de modelos de visión

Configuración de PeepIt con Ollama

Permisos de macOS

1. Permiso de grabación de pantalla (obligatorio)

2. Permiso de accesibilidad (opcional, pero agradable)

Pruebas y depuración

Uso del Inspector MCP

Pruebas directas con CLI

Herramientas disponibles

1. image - Capturar capturas de pantalla

2. list - Información del sistema

3. analyze - Análisis de visión por IA

Pruebas

Pruebas de TypeScript

Pruebas de Swift

Soporte de plataforma

Solución de problemas

Modo de depuración

Obtener ayuda

Compilación desde el código fuente

Configuración de desarrollo

Configuración de desarrollo local

Versión de AppleScript (heredada)

Configuración manual para otros clientes MCP

Documentación de herramientas

image - Captura de pantalla

Comportamiento de nombres de archivo y rutas

Características técnicas

Arquitectura

Detalles técnicos

Formato de salida JSON

Integración MCP

Seguridad

Desarrollo

Comandos de prueba

Compilación

Problemas conocidos

Licencia

Contribuciones

Autor

1. `image` - Capturar capturas de pantalla

2. `list` - Información del sistema

3. `analyze` - Análisis de visión por IA

`image` - Captura de pantalla