herdr-mcp

Un servidor MCP que permite a un agente de codificación controlar una sesión de terminal de Herdr en ejecución: listar workspaces (espacios de trabajo), pestañas, paneles y agentes; leer la salida de los paneles; enviar prompts a otros agentes; enviar pulsaciones de teclas; ejecutar comandos; esperar a alcanzar un estado o una salida; y dividir o cerrar paneles.

Es un puente stdio ligero. Cada herramienta invoca la CLI herdr como subproceso, que ya habla con la API de socket de Herdr y responde con sobres JSON. No hay demonio, ni puerto, ni archivo de configuración, ni autenticación.

Requisitos

• herdr instalado y en el PATH (o define HERDR_BIN con su ruta completa).

• Una sesión de Herdr en ejecución. El servidor habla con la sesión que la CLI herdr resuelva desde el entorno (HERDR_SOCKET_PATH / HERDR_SESSION).

• Python 3.12+ y uv.

Related MCP server: HT MCP Server

Ejecución

Desde una copia local:

uv run herdr-mcp

Directamente desde GitHub, sin copia local:

uvx --from git+https://github.com/aelaguiz/herdr-mcp herdr-mcp

El proceso sirve MCP a través de stdio, por lo que no imprime nada en stdout; los registros van a stderr (HERDR_MCP_LOG_LEVEL=DEBUG para el trazado de los argumentos).

Configuración del cliente

Claude Code:

claude mcp add herdr -- uvx --from git+https://github.com/aelaguiz/herdr-mcp herdr-mcp

JSON mcpServers genérico (Claude Desktop, Cursor, Codex y similares):

{
  "mcpServers": {
    "herdr": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/aelaguiz/herdr-mcp", "herdr-mcp"],
      "env": {}
    }
  }
}

Como alternativa, desde una copia local:

{
  "mcpServers": {
    "herdr": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/herdr-mcp", "herdr-mcp"]
    }
  }
}

Herramientas

Los ids de los paneles tienen la forma w17:p1, los ids de las pestañas w17:t1 y los ids de los workspaces w17. Las herramientas de agente aceptan un id de panel o un nombre de agente. Cada herramienta devuelve el objeto result analizado del sobre JSON de herdr; read_pane devuelve texto plano.

Los fallos de la CLI (panel desconocido, timeout, socket muerto) se devuelven como errores de herramienta MCP con el propio código de error y mensaje de herdr, de modo que el modelo pueda corregirse solo.

Seguridad

Sin autenticación, sin sandbox, solo stdio local. Cualquier cliente que pueda iniciar este servidor puede ejecutar comandos arbitrarios en los paneles de tu terminal y leer todo lo que aparece en pantalla, incluido lo que esté mostrando un panel de agente. Conéctalo únicamente a clientes de confianza en tu propia máquina.

Entorno

Todo lo demás del entorno se transfiere sin cambios, que es como la CLI encuentra el socket correcto de la sesión.

Desarrollo

uv sync
uv run pytest -q

Las pruebas unitarias ejercitan el servidor a través del cliente en memoria del SDK contra un backend simulado herdr, por lo que nunca tocan una sesión real.