ClipToWSL

Permite que los agentes de codificación de IA lean el contenido del portapapeles de Windows, incluidos texto e imágenes, desde el Subsistema de Windows para Linux (WSL).

GitHub
5
Prueba este MCPPatrocinado

Documentación

Servidor MCP ClipToWSL

ClipToWSL es un servidor de Protocolo de Contexto de Modelo (MCP) que permite a agentes de codificación de IA como Claude Code leer el contenido del portapapeles de Windows desde WSL (Subsistema de Windows para Linux). Esto permite un acceso fluido a los datos del portapapeles, incluidos texto e imágenes, al trabajar en entornos WSL.

Inicio rápido: Para una instalación sencilla, descargue el paquete de lanzamiento que incluye binarios precompilados y scripts de configuración automatizados.

Características

  • Acceso al portapapeles multiplataforma: Lea el portapapeles de Windows desde WSL
  • Múltiples tipos de contenido: Soporte para datos de portapapeles de texto e imagen
  • Codificación de imágenes en Base64: Conversión automática a PNG y codificación en Base64 para imágenes
  • Cumplimiento del protocolo MCP: Integración completa con Claude Code y otros clientes MCP
  • Gestión robusta de procesos: Gestión automática del ciclo de vida de procesos con comprobaciones de estado
  • Manejo de errores: Mecanismos integrales de manejo y recuperación de errores

Arquitectura

El sistema consta de dos componentes principales:

  1. Lector de portapapeles de Windows (clipboard-reader/): Un ejecutable en C++ que utiliza API Win32 para acceder al portapapeles de Windows
  2. Servidor MCP (mcp-server/): Un servidor TypeScript/Node.js que gestiona el ejecutable de Windows y expone la funcionalidad del portapapeles mediante el protocolo MCP

La comunicación entre componentes utiliza JSON-RPC a través de tuberías stdin/stdout.

Requisitos previos

Para desarrollo/compilación:

  • WSL (Subsistema de Windows para Linux)
  • Distribución WSL basada en Ubuntu/Debian
  • Compilador cruzado MinGW-w64 para Windows
  • Node.js 18+
  • TypeScript

Para uso:

  • Entorno WSL
  • Node.js 18+
  • Claude Code u otro cliente compatible con MCP

Instalación

Opción 1: Instalación rápida (recomendada)

Descargue el paquete de lanzamiento que incluye binarios precompilados:

# 1. Download and extract the release package
wget https://github.com/CarlosGtrz/ClipToWslMcp/releases/download/v1.0.0/clip-to-wsl-mcp-v1.0.0.zip
unzip clip-to-wsl-mcp-v1.0.0.zip
cd clip-to-wsl-mcp-v1.0.0/

# 2. Run the automated installer
./install.sh

# 3. Follow the configuration instructions printed by the installer

El instalador:

  • Instalará las dependencias de Node.js
  • Establecerá permisos de ejecución
  • Generará la plantilla de configuración de Claude Code
  • Proporcionará los siguientes pasos para la configuración

Opción 2: Compilar desde el código fuente

Para desarrollo o personalización:

# 1. Clone the repository
git clone <repository-url>
cd ClipToWslMcp

# 2. Install build dependencies
sudo apt update
sudo apt install gcc-mingw-w64-x86-64-posix g++-mingw-w64-x86-64-posix
npm install -g typescript

# 3. Install Node.js dependencies
cd mcp-server && npm install && cd ..

# 4. Build the project
./create-release.sh  # Creates optimized release build

Configuración

Integración con Claude Code

Agregue la siguiente configuración a la configuración de Claude Code:

Linux/WSL: ~/.claude.json

Para instalación con paquete de lanzamiento:

{
  "mcpServers": {
    "clip-to-wsl": {
      "command": "node",
      "args": ["/path/to/release/index.js"],
      "env": {
        "CLIPBOARD_EXE_PATH": "/path/to/release/clipreader.exe"
      }
    }
  }
}

Para instalación desde código fuente:

{
  "mcpServers": {
    "clip-to-wsl": {
      "command": "node",
      "args": ["/full/path/to/ClipToWslMcp/mcp-server/dist/index.js"],
      "env": {
        "CLIPBOARD_EXE_PATH": "/full/path/to/ClipToWslMcp/clipboard-reader/clipreader.exe"
      }
    }
  }
}

Importante: Reemplace las rutas con su directorio de instalación real. El instalador automatizado crea un archivo claude-config-example.json con las rutas correctas para su sistema.

Variables de entorno

  • CLIPBOARD_EXE_PATH: Ruta al ejecutable del lector de portapapeles de Windows (obligatorio)

Uso

Una vez configurado, la herramienta read_clipboard estará disponible en Claude Code:

Portapapeles de texto

Cuando copie texto al portapapeles de Windows, puede preguntarle a Claude Code:

  • "¿Qué hay en mi portapapeles?"
  • "Lee el contenido del portapapeles"
  • "Usa el texto de mi portapapeles"

Portapapeles de imagen

Cuando copie una imagen (captura de pantalla, imagen copiada, etc.), Claude Code puede:

  • Ver y analizar la imagen
  • Describir lo que hay en la imagen
  • Procesar los datos de la imagen

Parámetros de la herramienta

La herramienta read_clipboard acepta un parámetro opcional format:

  • "auto" (predeterminado): Detecta automáticamente y devuelve el mejor formato disponible
  • "text": Forzar lectura solo como texto
  • "image": Forzar lectura solo como imagen

Pruebas

Probar el ejecutable de Windows

cd clipboard-reader
echo '{"jsonrpc":"2.0","method":"read_clipboard","id":1}' | ./clipreader.exe

Probar el servidor MCP

node test-server.js

Probar la integración

cd mcp-server
npm start
# In another terminal, send MCP requests to test functionality

Solución de problemas

Problemas comunes

  1. Errores de "comando no encontrado"

    • Asegúrese de que MinGW-w64 esté instalado correctamente: x86_64-w64-mingw32-g++ --version
    • Verifique que todas las rutas en la configuración sean rutas absolutas

  2. Tiempo de espera de comunicación del proceso

    • Verifique que la ruta del ejecutable sea correcta y accesible
    • Compruebe que el ejecutable de Windows tenga los permisos adecuados
    • Asegúrese de que el ejecutable pueda ejecutarse (pruebe con ejecución directa)

  3. La herramienta MCP no aparece en Claude Code

    • Verifique la ruta y la sintaxis de la configuración
    • Revise los registros de Claude Code para ver errores de inicio del servidor MCP
    • Reinicie Claude Code después de los cambios de configuración

  4. Fallos de acceso al portapapeles

    • Asegúrese de estar ejecutando desde WSL con acceso al portapapeles de Windows
    • Verifique que el portapapeles de Windows contenga datos
    • Compruebe que ninguna otra aplicación esté bloqueando el acceso al portapapeles

Comandos de depuración

# Check if executable was built successfully
ls -la clipboard-reader/clipreader.exe

# Test executable directly
echo '{"method":"read_clipboard","id":1}' | /path/to/clipreader.exe

# Check MCP server startup
cd mcp-server && node dist/index.js

# Monitor process communication
ps aux | grep clipreader

Registros

El servidor MCP proporciona registro en consola para depuración:

  • Eventos de inicio y apagado de procesos
  • Resultados de comprobaciones de estado
  • Mensajes de error y seguimientos de pila
  • Registros de comunicación de solicitud/respuesta

Desarrollo

Estructura del proyecto

ClipToWslMcp/
├── clipboard-reader/        # C++ Windows executable
│   ├── src/
│   │   ├── main.cpp        # JSON-RPC communication
│   │   ├── clipboard.cpp   # Windows clipboard access
│   │   ├── clipboard.h
│   │   ├── base64.cpp      # Base64 encoding
│   │   └── base64.h
│   ├── Makefile            # Build configuration with optimizations
│   └── clipreader.exe      # Built executable (after build)
├── mcp-server/             # TypeScript MCP server
│   ├── src/
│   │   ├── index.ts        # Main server
│   │   ├── clipboard-manager.ts  # Process management
│   │   └── types.ts        # Type definitions
│   ├── dist/               # Compiled JavaScript (after build)
│   ├── package.json
│   └── tsconfig.json
├── release/                # Ready-to-use release package
│   ├── index.js           # Compiled MCP server
│   ├── clipreader.exe     # Optimized Windows executable
│   ├── package.json       # Runtime dependencies only
│   ├── install.sh         # Automated installer
│   └── README.md          # Installation instructions
├── create-release.sh       # Automated release builder
├── shared/                 # Shared configuration
│   └── config.json         # Claude Code config template
└── docs/                   # Documentation

Compilación desde el código fuente

  1. Instale las dependencias de desarrollo (MinGW-w64, Node.js, TypeScript)
  2. Compile de forma cruzada el ejecutable de Windows usando MinGW-w64
  3. Compile el servidor MCP de TypeScript
  4. Use ./create-release.sh para crear el paquete de lanzamiento optimizado
  5. Pruebe la integración entre componentes

Creación del paquete de lanzamiento

El compilador de lanzamiento automatizado crea un paquete listo para distribución:

./create-release.sh

Este script:

  • Compila el ejecutable de Windows optimizado con optimización de tamaño
  • Compila TypeScript a JavaScript
  • Crea el paquete de lanzamiento solo con dependencias de ejecución
  • Genera scripts de instalación y documentación
  • Produce un paquete independiente listo para distribución

Contribuciones

  1. Haga un fork del repositorio
  2. Cree una rama de características
  3. Realice sus cambios
  4. Pruebe a fondo
  5. Envíe una solicitud de extracción

Consideraciones de seguridad

  • El ejecutable de Windows se ejecuta con permisos mínimos
  • Los datos del portapapeles se procesan localmente sin transmisión por red
  • El aislamiento de procesos evita el acceso al entorno WSL sensible
  • La validación de entrada previene ataques de inyección
  • Los límites de recursos previenen el agotamiento de memoria

Rendimiento

  • Uso de memoria: Optimizado para imágenes grandes con procesamiento por flujo
  • Tiempo de inicio: La reutilización de procesos minimiza la sobrecarga de inicialización
  • Manejo de imágenes: Compresión PNG eficiente y codificación Base64
  • Recuperación de errores: Reinicio automático de procesos en caso de fallos

Licencia

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

Soporte

Para problemas, informes de errores o solicitudes de funciones, cree un problema en el repositorio.