cliptunnel-mcp

Opera una máquina remota bloqueada a través de su portapapeles.

Qué hace

cliptunnel-mcp convierte un portapapeles compartido en un canal de control fiable entre dos máquinas. Cuando la máquina remota está detrás de una sesión de Citrix, una VDI bloqueada o cualquier entorno que impida SSH, la transferencia de archivos y la red, pero que aún exponga un portapapeles, ClipTunnel canaliza comandos a través de esa única ranura y los expone como herramientas de Model Context Protocol.

El paquete incluye tres capas:

• Protocolo — un formato de trama (CT1) con cargas útiles en base64, números de secuencia y mensajes tipados (comando, respuesta, error, ack).

• Extremos — Controller (lado del operador) y Agent (lado remoto), conectados por un Transport inyectado. Ambos ejecutan hilos en segundo plano con retransmisión ARQ, deduplicación acotada por secuencia y un ciclo de vida seguro entre generaciones.

• Servidor MCP — una aplicación FastMCP que expone las utilidades del Controller como herramientas remote_shell, remote_os_*, remote_upd, remote_upd, remote_down.

El paquete principal no tiene dependencias. El servidor MCP requiere el extra opcional [server] (mcp>=1.2,<2).

Related MCP server: Sky Windows Remote Executor

Arquitectura


Ambos endpoints comparten una única ranura de portapapeles con la última escritura como ganadora (last-writer-wins). El protocolo usa ARQ de parada y espera (stop-and-wait): el controlador escribe un comando, el agente envía el ACK inmediatamente, procesa el comando en un grupo de workers, y luego escribe una respuesta tipada (R o E) y la retransmite hasta que llega el ACK correspondiente del controlador. El controlador envía un comando a la vez y resuelve los futuros a medida que llegan las respuestas.

Formato de trama

CT1|<from>|<to>|<seq>|<type>|<payload>

Instalación

pip install cliptunnel-mcp          # core + cliptunnel-agent binary
pip install cliptunnel-mcp[server]  # adds cliptunnel-mcp server binary (mcp>=1.2,<2)

Ambos modos instalan puntos de entrada de consola:

Inicio rápido

Agentente (máquina remota)

La forma más sencilla de ejecutar el Agentente es el binario instalado:

cliptunnel-agent

Solución para antivirus / EDR (Windows): los puntos de entrada .exe sin firmar pueden ponerse en cuarentena. Usa python -m en su lugar: se ejecuta a través del intérprete de Python ya confiable, sin generar binario.

python -m cliptunnel_mcp.agent    # instead of cliptunnel-agent
python -m cliptunnel_mcp.server   # instead of cliptunnel-mcp

Esto construye un ClipboardTransport respaldado por el port de sistema (pbcopy/pbpaste en macOS, user32 en Windows, wl-copy/wl-paste en Wayland, xclip/xsel en X11) y conecta operations.dispatch como gestor de comandos. El Agentente vigila la ranura del portapapeles, confirma los comandos con ACK, los procesa en un equipo de trabajadores y escribe las respuestas. Pulso Ctrl+C para detener.

Controlador + servidor MCP (máquina del operador)

En el lado del operador, configura tu cliente MCP (Claude Desktop, Cursor, Pi, etc.) para lanzar el binario del servidor:

{
  "mcpServers": {
    "cliptunnel": {
      "command": "cliptunnel-mcp",
      "args": []
    }
  }
}

Si el binario de cliptunnel-mcp está bloqueado por el antivirus, usa python -m:

{
  "mcpServers": {
    "cliptunnel": {
      "command": "python",
      "args": ["-m", "cliptunnel_mcp.server"]
    }
  }
}

El binario del servidor inyecta un Controller respaldado por un ClipboardTransport y ejecuta la aplicación FastMCP sobre stdio. Todas las herramientas remote_* están disponibles de inmediato.

Nota: el servidor MCP requiere pip install cliptunnel-mcp[server].

Solo Controller (sin MCP)

Para uso programático sin un cliente MCP:

from cliptunnel_mcp.clipboard_transport import ClipboardTransport
from cliptunnel_mcp import Controller
import json

controller = Controller(transport=ClipboardTransport())

# Async — returns a Future
future = controller.send_command(json.dumps({"op": "shell", "cmd": "whoami"}))
result = future.result(timeout=30)

# Sync — blocks until response or timeout
output = controller.send_command_sync(json.dumps({"op": "fs.read", "path": "/etc/hostname"}))

Agentente programático

Si necesitas un gestor o transporte personalizado:

from cliptunnel_mcp.clipboard_transport import ClipboardTransport
from cliptunnel_mcp import Agent
from cliptunnel_mcp.operations import dispatch

agent = Agent(transport=ClipboardTransport(), handler=dispatch)
# Blocks until agent.close() — run in a thread or manage lifecycle yourself.

Superficie de la API

Controller

Es el extremo del lado del operador. Envía comandos de forma asíncrona, procesa uno a la vez y resuelve los futuros en cuanto llegan las respuestas.

Parámetros del constructor: transport (obligatorio), timeout, retries, poll_interval, ack_timeout, initial_seq, persist_seq, seq_store.

Agent

Agent es el extremo del lado remoto. Vigila la ranura, confirma los comandos de inmediato con ACK, los procesa en un grupo de workers y escribe una respuesta tipada a la vez con retransmisión.

Parámetros del constructor: transport (obligatorio), handler (obligatorio), poll_interval, max_workers, response_ack_timeout.

dispatch

El gestor por defecto del Agent. Analiza las cargas útiles JSON y las enruta a la operación correspondiente.

from cliptunnel_mcp.operations import dispatch

output, is_error = dispatch('{"op": "shell", "cmd": "echo hello"}')

Primitivas del protocolo

Protocolo de transporte

class Transport(Protocol):
    def read(self) -> str: ...
    def write(self, value: str) -> None: ...

class RevisionMonitor(Protocol):
    @property
    def revision(self) -> int: ...
    def wait_for_change(self, after: int, timeout: float = 1.0) -> int: ...

Un transporte debe implementar read/write (el último que escribe, gana). Si se implementa RevisionMonitor (o se exponen wait_for_revision / wait_for_change), se pueden usar esperas conscientes de los cambios en lugar de sondeo.

Operaciones

El gestor dispatch admite estas operaciones:

Herramientas MCP

El servidor expone 13 herramientas a través de stdio:

Ciclo de vida y semántica de coalescencia

• Un comando a la vez: el Controller despacha comandos de forma serial. El seq del comando pendiente se publica atómicamente con la escritura del slot, de modo que el lector nunca observa el comando antes que el despachador.

• ACK inmediato: el Agent confirma cada comando antes de procesarlo, liberando el slot para el Controller.

• Una respuesta a la vez: el Agent mantiene exactamente un sobre de respuesta pendiente. Un comando nuevo nunca confirma implícitamente una respuesta pendiente; solo el A(seq) correspondiente del Controller la libera.

• Retransmisión: ambos lados retransmiten al expirar el ACK. El Controller reintenta hasta retries veces (por defecto 3). El Agent retransmite la respuesta cada response_ack_timeout segundos (por defecto 1.0).

• Desduplicación: el SeqTracker del Agent rastrea el estado por seq (nuevo → procesando → hecho). Los comandos duplicados se confirman con ACK; los ya completados reproducen la respuesta tipada en caché; los en curso ya se están procesando.

• Protección contra mensajes obsoletos: el Controller omite cualquier R/E con seq <= min_seq — contenido de slot obsoleto de una sesión anterior.

• Seguro entre generaciones: todo el estado de detención y las colas son locales a cada instancia. Cerrar y abrir un nuevo Agent o Controller nunca deja hilos colgados.

• Escrituras espaciadas: el Controller impone un intervalo mínimo entre escrituras (2× el intervalo de sondeo) para que el Agent pueda leer cada mensaje antes de que sea sobrescrito.

Selección del backend

ClipTunnel incluye ClipboardTransport, un transporte respaldado por el portapapeles del sistema operativo. En Wayland usa wl-paste --watch para la detección de cambios basada en eventos (cero sondeo, cero CPU en reposo). En macOS, Windows y X11 sondea cada 100 ms con detección de cambios basada en hash. Implementa tanto Transport como RevisionMonitor, por lo que ambos extremos obtienen esperas conscientes de cambios. Los binarios cliptunnel-agent y cliptunnel-mcp lo usan automáticamente.

Para configuraciones personalizadas — una redirección de portapapeles de Citrix, un Gist compartido, una tubería de red — implementa el protocolo Transport (read() -> str, write(str) -> None) y opcionalmente RevisionMonitor (revision + wait_for_change). Inyéctalo directamente en Controller o Agent.

Soporte de plataformas

Desarrollo

# Create a virtual environment
uv venv && source .venv/bin/activate

# Install in development mode
uv pip install -e . pytest

# Run the test suite (161 tests)
python -m pytest -q
# or
python -m unittest discover -s tests -t .

# Bare mode — no install, just PYTHONPATH
PYTHONPATH=src:. python -m pytest -q

La suite de pruebas usa un doble de prueba ClipboardSlot determinista que modela el canal de último escritor gana con revisiones y esperas acotadas. No se necesita hardware de portapapeles.

Limitaciones

• Portapapeles solo texto: el protocolo transporta cadenas UTF-8. Los archivos binarios se codifican en base64, lo que aproximadamente duplica su tamaño en el cable.

• Slot único: el portapapeles contiene un valor a la vez. El protocolo ARQ serializa todo el tráfico a través de él, por lo que el rendimiento está limitado por la latencia de ida y vuelta del portapapeles.

• Sin cifrado: el formato en el cable es base64 plano. Si el portapapeles es observable, usa una capa de cifrado en tu transporte o manejador.

Licencia

MIT — consulta LICENSE.