ClipToWSL

Permite que agentes de codificação de IA leiam o conteúdo da área de transferência do Windows, incluindo texto e imagens, de dentro do Subsistema Windows para Linux (WSL).

GitHub
5
Experimente este MCPPatrocinado

Documentação

Servidor MCP ClipToWSL

O ClipToWSL é um servidor Model Context Protocol (MCP) que permite que agentes de codificação de IA, como o Claude Code, leiam o conteúdo da área de transferência do Windows a partir do WSL (Subsistema Windows para Linux). Isso permite acesso contínuo aos dados da área de transferência, incluindo texto e imagens, ao trabalhar em ambientes WSL.

Início Rápido: Para instalação fácil, baixe o pacote de lançamento que inclui binários pré-compilados e scripts de configuração automatizados.

Recursos

  • Acesso à área de transferência entre plataformas: Leia a área de transferência do Windows a partir do WSL
  • Múltiplos tipos de conteúdo: Suporte para dados de texto e imagem na área de transferência
  • Codificação de imagem Base64: Conversão automática para PNG e codificação Base64 para imagens
  • Conformidade com o protocolo MCP: Integração completa com o Claude Code e outros clientes MCP
  • Gerenciamento robusto de processos: Gerenciamento automático do ciclo de vida de processos com verificações de integridade
  • Tratamento de erros: Mecanismos abrangentes de tratamento e recuperação de erros

Arquitetura

O sistema consiste em dois componentes principais:

  1. Leitor de Área de Transferência do Windows (clipboard-reader/): Um executável C++ que usa APIs Win32 para acessar a área de transferência do Windows
  2. Servidor MCP (mcp-server/): Um servidor TypeScript/Node.js que gerencia o executável do Windows e expõe a funcionalidade da área de transferência via protocolo MCP

A comunicação entre os componentes usa JSON-RPC por pipes stdin/stdout.

Pré-requisitos

Para Desenvolvimento/Compilação:

  • WSL (Subsistema Windows para Linux)
  • Distribuição WSL baseada em Ubuntu/Debian
  • Compilador cruzado MinGW-w64 para Windows
  • Node.js 18+
  • TypeScript

Para Uso:

  • Ambiente WSL
  • Node.js 18+
  • Claude Code ou outro cliente compatível com MCP

Instalação

Opção 1: Instalação Rápida (Recomendada)

Baixe o pacote de lançamento que inclui binários pré-compilados:

# 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

O instalador irá:

  • Instalar dependências do Node.js
  • Definir permissões de execução
  • Gerar modelo de configuração do Claude Code
  • Fornecer próximos passos para a configuração

Opção 2: Compilar a partir do Código Fonte

Para desenvolvimento ou personalização:

# 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

Configuração

Integração com Claude Code

Adicione a seguinte configuração às suas configurações do Claude Code:

Linux/WSL: ~/.claude.json

Para Instalação com Pacote de Lançamento:

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

Para Instalação com Compilação do Código Fonte:

{
  "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: Substitua os caminhos pelo seu diretório de instalação real. O instalador automatizado cria um arquivo claude-config-example.json com os caminhos corretos para o seu sistema.

Variáveis de Ambiente

  • CLIPBOARD_EXE_PATH: Caminho para o executável do leitor de área de transferência do Windows (obrigatório)

Uso

Uma vez configurado, a ferramenta read_clipboard estará disponível no Claude Code:

Área de Transferência de Texto

Quando você copia texto para a área de transferência do Windows, pode perguntar ao Claude Code:

  • "O que está na minha área de transferência?"
  • "Leia o conteúdo da área de transferência"
  • "Use o texto da minha área de transferência"

Área de Transferência de Imagem

Quando você copia uma imagem (captura de tela, imagem copiada, etc.), o Claude Code pode:

  • Visualizar e analisar a imagem
  • Descrever o que está na imagem
  • Processar os dados da imagem

Parâmetros da Ferramenta

A ferramenta read_clipboard aceita um parâmetro opcional format:

  • "auto" (padrão): Detecta automaticamente e retorna o melhor formato disponível
  • "text": Força a leitura apenas como texto
  • "image": Força a leitura apenas como imagem

Testes

Testar o Executável do Windows

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

Testar o Servidor MCP

node test-server.js

Testar a Integração

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

Solução de Problemas

Problemas Comuns

  1. Erros de "Comando não encontrado"

    • Certifique-se de que o MinGW-w64 está instalado corretamente: x86_64-w64-mingw32-g++ --version
    • Verifique se todos os caminhos na configuração são caminhos absolutos

  2. Tempo limite de comunicação do processo

    • Verifique se o caminho do executável está correto e acessível
    • Verifique se o executável do Windows tem permissões adequadas
    • Certifique-se de que o executável pode ser executado (teste com execução direta)

  3. Ferramenta MCP não aparecendo no Claude Code

    • Verifique o caminho e a sintaxe da configuração
    • Verifique os logs do Claude Code para erros de inicialização do servidor MCP
    • Reinicie o Claude Code após alterações na configuração

  4. Falhas no acesso à área de transferência

    • Certifique-se de que está executando a partir do WSL com acesso à área de transferência do Windows
    • Verifique se a área de transferência do Windows contém dados
    • Verifique se outros aplicativos não estão bloqueando o acesso à área de transferência

Comandos de Depuração

# 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

Logs

O servidor MCP fornece registro em console para depuração:

  • Eventos de inicialização e encerramento de processos
  • Resultados de verificações de integridade
  • Mensagens de erro e rastreamentos de pilha
  • Logs de comunicação de solicitação/resposta

Desenvolvimento

Estrutura do Projeto

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

Compilação a partir do Código Fonte

  1. Instale as dependências de desenvolvimento (MinGW-w64, Node.js, TypeScript)
  2. Compile o executável do Windows usando MinGW-w64
  3. Compile o servidor MCP TypeScript
  4. Use ./create-release.sh para criar pacote de lançamento otimizado
  5. Teste a integração entre os componentes

Criando Pacote de Lançamento

O construtor automatizado de lançamentos cria um pacote pronto para distribuição:

./create-release.sh

Este script:

  • Compila executável otimizado do Windows com otimização de tamanho
  • Compila TypeScript para JavaScript
  • Cria pacote de lançamento apenas com dependências de execução
  • Gera scripts de instalação e documentação
  • Produz um pacote independente pronto para distribuição

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Faça suas alterações
  4. Teste minuciosamente
  5. Envie uma solicitação de pull

Considerações de Segurança

  • O executável do Windows é executado com permissões mínimas
  • Os dados da área de transferência são processados localmente sem transmissão pela rede
  • O isolamento de processos impede o acesso ao ambiente WSL sensível
  • A validação de entrada impede ataques de injeção
  • Os limites de recursos impedem o esgotamento de memória

Desempenho

  • Uso de memória: Otimizado para imagens grandes com processamento em fluxo
  • Tempo de inicialização: A reutilização de processos minimiza a sobrecarga de inicialização
  • Manipulação de imagens: Compressão PNG eficiente e codificação Base64
  • Recuperação de erros: Reinício automático de processos em caso de falhas

Licença

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

Suporte

Para problemas, relatórios de bugs ou solicitações de recursos, crie um problema no repositório.