MCP ToolHub

MCP ToolHub es un servidor local del Model Context Protocol, únicamente para stdio, que expone operaciones acotadas del sistema de archivos del espacio de trabajo, inspección de solo lectura de Git, ejecución estructurada de comandos y un registro de auditoría. Las operaciones de mutación del sistema de archivos y todos los comandos de shell externos seleccionados por el agente utilizan el modelo existente de aprobación humana fuera de banda.

ToolHub no expone ningún listener HTTP, SSE ni de otro tipo de red.

Características

• Lectura de archivos confinada al espacio de trabajo, listado de directorios, escrituras y parches

• Operaciones de estado y diff de Git de solo lectura

• Comandos de shell estructurados con clasificación de riesgo de denegación por defecto

• Solicitudes de aprobación atómicas, con caducidad y de un solo uso

• CLI de administrador confiable separada; no existe ninguna herramienta MCP de autoaprobación

• Eventos de auditoría en JSON Lines acotados y expurgados

• Compatibilidad con Windows y POSIX

Related MCP server: enterprise-agent-lab

Requisitos

• Python 3.12 o posterior (el CI valida actualmente 3.12 y 3.13)

• Un cliente MCP que admita servidores stdio

• git para las herramientas de Git y las solicitudes de shell de Git sujetas a aprobación

Instalación

Instale desde una copia del código fuente con uv:

uv tool install .

O compile e instale el wheel:

uv build
uv tool install dist/mcp_toolhub-0.1.0-py3-none-any.whl

La instalación proporciona dos ejecutables:

• mcp-toolhub — el servidor MCP stdio

• mcp-toolhub-admin — la CLI de aprobación humana confiable

Configuración en tiempo de ejecución

Raíz del espacio de trabajo

TOOLHUB_WORKSPACE_ROOT es obligatorio para mcp-toolhub serve y para la CLI de administrador. Debe contener una ruta absoluta a un directorio existente. ToolHub canonicaliza la ruta una vez y la congela durante toda la vida del proceso.

ToolHub no toma por defecto, deliberadamente, el directorio actual, la copia del código fuente ni el directorio de instalación.

Raíz de estado confiable

TOOLHUB_STATE_ROOT selecciona opcionalmente el directorio que contiene workspace-binding.json, approvals.json y audit.jsonl. Cuando se proporciona, debe ser absoluto. El directorio queda vinculado permanentemente, en su primer uso válido, a exactamente un espacio de trabajo canónico; reutilizarlo para otro espacio de trabajo falla de forma segura.

Cuando TOOLHUB_STATE_ROOT no está definido, ToolHub utiliza como base el directorio de estado por usuario apropiado para la plataforma de platformdirs. Cada espacio de trabajo canónico recibe un espacio de nombres independiente bajo workspaces/, denominado con un identificador SHA-256 determinista derivado de la ruta canónica del espacio de trabajo normalizada para la plataforma. El identificador evita colocar la ruta del espacio de trabajo en los nombres de directorio, pero es una separación de espacios de nombres, no un secreto de autenticación. Mover o renombrar un espacio de trabajo normalmente crea un nuevo espacio de nombres predeterminado.

El directorio de estado se crea según sea necesario, se canonicaliza y se congela junto con la configuración del espacio de trabajo. El inicio falla si la raíz de estado está dentro del espacio de trabajo. El servidor y la CLI de administrador deben ejecutarse como el mismo usuario y con la misma configuración de espacio de trabajo y estado para que compartan este estado.

Ejemplo en POSIX

export TOOLHUB_WORKSPACE_ROOT=/home/alice/projects/example
export TOOLHUB_STATE_ROOT=/home/alice/.local/state/mcp-toolhub
mcp-toolhub serve

Ejemplo en Windows PowerShell

$env:TOOLHUB_WORKSPACE_ROOT = "D:\work\example"
$env:TOOLHUB_STATE_ROOT = "$env:LOCALAPPDATA\mcp-toolhub"
mcp-toolhub serve

El servidor no escribe ningún banner ni texto de registro legible por humanos en stdout. Stdout está reservado exclusivamente para los mensajes del protocolo MCP. Los errores de configuración esperados se notifican de forma concisa en stderr y el proceso sale con un código distinto de cero.

Comandos

mcp-toolhub --version
mcp-toolhub serve
python -m mcp_toolhub serve

mcp-toolhub-admin --help
mcp-toolhub-admin list
mcp-toolhub-admin approve REQUEST_ID
mcp-toolhub-admin reject REQUEST_ID

El comando de administrador está orientado a humanos y puede escribir salida normal en stdout. No es un proceso de transporte MCP.

Configuración del cliente MCP

La clave de configuración externa exacta varía según el cliente. Una entrada de stdio típica en POSIX es:

{
  "mcpServers": {
    "toolhub": {
      "command": "mcp-toolhub",
      "args": ["serve"],
      "env": {
        "TOOLHUB_WORKSPACE_ROOT": "/home/alice/projects/example",
        "TOOLHUB_STATE_ROOT": "/home/alice/.local/state/mcp-toolhub"
      }
    }
  }
}

Las rutas de Windows requieren escape JSON:

{
  "mcpServers": {
    "toolhub": {
      "command": "mcp-toolhub",
      "args": ["serve"],
      "env": {
        "TOOLHUB_WORKSPACE_ROOT": "D:\\work\\example",
        "TOOLHUB_STATE_ROOT": "C:\\Users\\alice\\AppData\\Local\\mcp-toolhub"
      }
    }
  }
}

Utilice una ruta de ejecutable absoluta si el cliente MCP no hereda el PATH del shell.

Inventario de herramientas

El servidor de producción expone exactamente estas 12 herramientas MCP:

• toolhub.ping

• toolhub.audit_recent

• filesystem.list_directory

• filesystem.read_file

• filesystem.write_file

• filesystem.write_file_approved

• filesystem.apply_patch

• filesystem.apply_patch_approved

• git.status

• git.diff

• shell.run

• shell.run_approved

No existe ninguna herramienta MCP de administración, aprobación ni rechazo.

Flujo de aprobación humana

1. Una mutación MCP o una solicitud de shell externa devuelve un ID de solicitud pendiente.

2. El administrador ejecuta mcp-toolhub-admin list con el mismo espacio de trabajo y entorno de estado que el servidor.

3. Para la aprobación, el administrador ejecuta mcp-toolhub-admin approve REQUEST_ID.

4. La CLI muestra la solicitud protegida y exige que el operador escriba exactamente APPROVE.

5. El llamador MCP invoca la herramienta _approved correspondiente con el ID de solicitud. El consumo correcto es atómico y de un solo uso.

Para las solicitudes de shell, la pantalla de aprobación incluye el programa original, el ejecutable resuelto canónico, el SHA-256, el tamaño en bytes, cwd y los valores de los argumentos con escape JSON por separado. No representa los argumentos como una cadena de comando de shell ambigua.

Modelo de seguridad y limitaciones

Comandos de shell estructurados

shell.run utiliza una política de denegación por defecto para comandos. LOW se limita a las funciones intrínsecas exactas de ToolHub, actualmente la consulta de la versión de Python en ejecución. LOW nunca busca en PATH y nunca crea un subproceso externo. Git genérico, intérpretes de shell, scripts batch de Windows, el lanzador py y los programas desconocidos nunca son LOW.

Todo comando de shell externo es MEDIUM o HIGH y requiere una aprobación de administrador fuera de banda. La aprobación captura instantáneas inmutables del programa, los argumentos, cwd, timeout, el espacio de trabajo y el ejecutable principal. Una solicitud de shell aprobada se consume de forma atómica antes de la validación de la instantánea; cualquier fallo posterior la consume permanentemente, por lo que un reintento requiere una nueva aprobación.

Inmediatamente antes del lanzamiento de subprocess, ToolHub valida la ruta canónica, el tamaño y el SHA-256 del ejecutable principal. La ejecución utiliza esa ruta absoluta con shell=False. Esto es una identidad del ejecutable principal validada inmediatamente antes del lanzamiento, no una garantía criptográfica de los bytes exactos que el sistema operativo mapea finalmente.

ToolHub garantiza:

• LOW nunca crea un subproceso externo.

• Toda ejecución de shell externa requiere aprobación MEDIUM o HIGH.

• El agente no puede reemplazar el programa, los argumentos, cwd ni el timeout aprobados.

• Las aprobaciones son atómicas, con caducidad y de un solo uso.

• Las instantáneas del espacio de trabajo y del ejecutable principal son obligatorias y fallan de forma segura.

• La identidad canónica y el hash del ejecutable principal se vuelven a validar inmediatamente antes del lanzamiento.

• Las rutas del sistema de archivos permanecen dentro del límite congelado del espacio de trabajo.

• Las rutas de mutación rechazan el cruce de enlaces simbólicos y aplican comprobaciones de concurrencia de expected_hash cuando corresponde.

ToolHub no garantiza:

• La identidad exacta de los bytes frente a un adversario local concurrente del sistema de archivos durante la estrecha condición de carrera final entre la comprobación y la ejecución.

• La identidad de las DLL, los intérpretes, los ayudantes, los complementos, los archivos de configuración, las dependencias seleccionadas por el entorno o los procesos descendientes.

• Que los bytes del ejecutable aprobado sean benignos, estén firmados o provengan de un editor de confianza.

La pantalla de aprobación del administrador expone la ruta canónica protegida, el hash, el tamaño, cwd y los límites exactos de los argumentos con escape JSON. Los eventos de auditoría legibles por el agente omiten los directorios de los ejecutables externos y conservan el nombre base, el hash, el tamaño, el ámbito y la correlación con el ID de solicitud.

Comportamiento de auditoría

Los eventos de auditoría se añaden a audit.jsonl bajo la raíz de estado confiable. Contienen metadatos acotados, expurgan argumentos secretos reconocibles y almacenan recuentos de caracteres de stdout/stderr en lugar de la salida bruta del proceso. Los fallos de escritura de la auditoría no son fatales para la ejecución de las herramientas.

Desarrollo

Instale todas las dependencias de ejecución y de desarrollo bloqueadas:

uv sync --all-groups

Ejecute las comprobaciones requeridas:

uv run ruff check .
uv run ruff format --check .
uv run python -m compileall -q src/mcp_toolhub
uv run pytest -q
uv build
git diff --check

Para aplicar el formato deliberadamente:

uv run ruff format .

Prueba de humo del artefacto

Después de uv build, ejecute el controlador de prueba de humo multiplataforma con un entorno virtual fuera de la copia del código fuente.

POSIX:

uv run python scripts/artifact_smoke.py --dist-dir dist --venv /tmp/mcp-toolhub-wheel-env --repository .

Windows PowerShell:

uv run python scripts/artifact_smoke.py --dist-dir dist --venv "$env:TEMP\mcp-toolhub-wheel-env" --repository .

El controlador inspecciona el contenido del wheel, instala solo el wheel en el entorno aislado, verifica el comportamiento de consola/versión y ejecuta, desde fuera del repositorio, las pruebas de initialize, list_tools, ping, acceso al espacio de trabajo configurado, configuración no válida y estado compartido servidor/administrador.

Solución de problemas

• TOOLHUB_WORKSPACE_ROOT is required: añada una ruta absoluta de un espacio de trabajo existente al entorno del cliente MCP.

• El espacio de trabajo no es un directorio: cree el directorio o corrija la ruta.

• La raíz de estado debe estar fuera del espacio de trabajo: mueva TOOLHUB_STATE_ROOT a un directorio confiable al que las herramientas del sistema de archivos de MCP no puedan acceder.

• El espacio de nombres de estado pertenece a otro espacio de trabajo: seleccione un TOOLHUB_STATE_ROOT explícito diferente; los enlaces nunca se reasignan silenciosamente.

• El cliente informa de un JSON stdio no válido: verifique que los envoltorios y los scripts de inicio no impriman banners ni registros en stdout.

• El administrador no puede ver una solicitud: confirme que el servidor y el administrador se ejecutan como el mismo usuario con configuraciones idénticas de espacio de trabajo y raíz de estado.

• El ejecutable cambió después de la aprobación: solicite una nueva aprobación; las aprobaciones consumidas o invalidadas nunca se reproducen.

El ToolHub de producción no expone deliberadamente ninguna superficie HTTP, SSE, de red pública, de servidor de autenticación, de orquestación de contenedores ni de alojamiento en la nube.