Screenshot MCP Server

Servidor de capturas de pantalla (enfocado en la ruta del archivo)

Este proyecto proporciona un servidor MCP (Protocolo de comunicación modular) diseñado para capturar capturas de pantalla y facilitar su uso por otros procesos o asistentes de IA, principalmente guardando la captura de pantalla en una ruta de archivo especificada por el cliente (Host) .

Problema central y solución

La interpretación directa de los datos de captura de pantalla enviados a través de MCP por los asistentes de IA resultó poco fiable en las pruebas. Este servidor adopta flujos de trabajo más robustos centrados en las rutas de archivo:

Flujo de trabajo recomendado (Host WSL -> Servidor Windows):

1. Un host MCP (como un asistente de IA que se ejecuta en WSL) llama a la herramienta save_screenshot_to_host_workspace y proporciona su ruta de espacio de trabajo WSL como argumento.
2. Este servidor (que se ejecuta en Windows) captura la pantalla.
3. El servidor convierte la ruta WSL recibida en una ruta UNC accesible para Windows (por ejemplo, \\wsl$\Distro\path ).
4. El servidor guarda la captura de pantalla en la ubicación especificada dentro del sistema de archivos WSL del Host a través de la ruta UNC.
5. El servidor devuelve "success" o "failed:..." .
6. El host MCP sabe que el archivo está guardado en su espacio de trabajo (o en un subdirectorio si se especifica en el argumento de ruta).
7. Luego, el host MCP puede pasar la ruta WSL a otro servidor MCP especializado (que se ejecuta en WSL) para el análisis de imágenes.

Flujo de trabajo alternativo (general):

1. El host MCP llama take_screenshot_and_return_path y especifica opcionalmente un nombre de archivo.
2. El servidor guarda la captura de pantalla en su directorio images/ local.
3. El servidor devuelve la ruta absoluta (por ejemplo, la ruta de Windows) al archivo guardado.
4. El host MCP recibe la ruta y la pasa (con posible conversión) a un servidor de análisis.

Herramientas disponibles

Este servidor proporciona las siguientes herramientas, ordenadas según el uso recomendado:

• save_screenshot_to_host_workspace(host_workspace_path: str, name: str = "workspace_screenshot.jpg")
  • Uso recomendado: Guarda una captura de pantalla directamente en el espacio de trabajo actual de WSL del Asistente de IA (Anfitrión). Este es el método preferido para una integración fluida.
  • Acción: Toma una captura de pantalla, convierte la ruta WSL proporcionada a una ruta UNC y guarda el archivo en el espacio de trabajo del host. Detecta automáticamente el nombre de la distribución WSL.
  • Argumentos:
    • host_workspace_path (str): la ruta WSL absoluta del espacio de trabajo del host (por ejemplo, /home/user/project ).
    • name (str, opcional): nombre de archivo. El valor predeterminado es workspace_screenshot.jpg .
  • Devuelve: str - "success" o "failed: [error message]" .
• take_screenshot_and_return_path(name: str = "latest_screenshot.jpg")
  • Caso de uso: Guarda una captura de pantalla en un directorio images/ fijo, relativo a la ubicación del servidor, y devuelve la ruta absoluta (normalmente una ruta de Windows). Resulta útil si el usuario necesita la ruta para procesamiento externo.
  • Argumentos:
    • name (str, opcional): nombre de archivo. El valor predeterminado es latest_screenshot.jpg .
  • Devuelve: str - Ruta absoluta o "failed: [error message]" .
• take_screenshot_path(path: str = "./", name: str = "screenshot.jpg")
  • Caso de uso: Guarda una captura de pantalla en una ubicación arbitraria especificada por una ruta de Windows o una ruta UNC (p. ej., para guardarla fuera del espacio de trabajo del host). Requiere una especificación cuidadosa de la ruta por parte del llamador.
  • Argumentos:
    • path (str, opcional): Directorio de destino (ruta de Windows o UNC). El valor predeterminado es el directorio de trabajo del servidor.
    • name (str, opcional): nombre de archivo. El valor predeterminado es screenshot.jpg .
  • Devuelve: str - "success" o "failed: [error message]" .

Configuración y uso

1. Requisitos previos

• Python 3.x: Requerido en la máquina donde se ejecutará el servidor.
• Dependencias: Instalar usando uv :
  uv sync
  Las bibliotecas necesarias incluyen mcp[cli]>=1.4.1 , pyautogui y Pillow .

2. Ejecución del servidor

Este servidor normalmente lo inicia un host MCP en función de su configuración.

3. Consideraciones ambientales (especialmente WSL2)

Punto crucial: para capturar la pantalla de Windows , este servidor screenshot.py debe ejecutarse directamente en Windows .

Configuración recomendada de host WSL2 -> servidor Windows:

1. Ubicación del proyecto: coloque esta carpeta del proyecto screenshot-server en su sistema de archivos de Windows (por ejemplo, C:\Users\YourUser\projects\screenshot-server ).
2. Dependencias de Windows: Instale Python, uv y las dependencias del proyecto ( uv sync ... ) directamente en Windows dentro de la carpeta del proyecto.
3. Configuración del host MCP (en WSL): Configure su host MCP (que se ejecuta en WSL) para iniciar el servidor en Windows mediante PowerShell. Actualice mcp_settings.json (o equivalente).
   { "mcpServers": { "Screenshot-server": { "command": "powershell.exe", "args": [ "-Command", "Invoke-Command -ScriptBlock { cd '<YOUR_WINDOWS_PROJECT_PATH>'; & '<YOUR_WINDOWS_UV_PATH>' run screenshot.py }" ] } // ... other servers ... } }
   • Reemplace las rutas con sus rutas reales de Windows.

4. Ejemplo de flujo de trabajo (Asistente de IA en WSL)

1. El Asistente de IA identifica su ruta de espacio de trabajo actual (por ejemplo, /home/user/current_project ).
2. AI Assistant usa use_mcp_tool para llamar save_screenshot_to_host_workspace en Screenshot-server , pasando host_workspace_path="/home/user/current_project" y opcionalmente un name .
3. Recibe "success" .
4. El Asistente de IA sabe que la captura de pantalla ahora está en /home/user/current_project/workspace_screenshot.jpg (o el nombre especificado).
5. AI Assistant usa use_mcp_tool para llamar a un servidor/herramienta de análisis de imágenes (que también se ejecuta en WSL), pasando la ruta WSL /home/user/current_project/workspace_screenshot.jpg .
6. El servidor de análisis de imágenes lee el archivo y realiza su tarea.

Estructura de archivos

• screenshot.py : El script principal del servidor MCP.
• README.md : Este archivo de documentación.
• pyproject.toml : Definición del proyecto y dependencias para uv .
• uv.lock : Archivo de bloqueo de dependencia.
• .gitignore : Git ignora la configuración.
• .python-version : (opcional) especificador de la versión de Python.
• server.log : Archivo de registro generado por el servidor.
• images/ : Directorio predeterminado para take_screenshot_and_return_path .