mikrus-mcp

Servidor MCP (Model Context Protocol) para gestionar servidores VPS a través de la API de mikr.us y servidores Linux remotos mediante SSH. Construido en Python, se ejecuta en cualquier lugar: localmente, en Docker o como integración de Claude Desktop.

GitHub
10
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Mikrus

CI AI Skills Python 3.12–3.14 Version 2.1.0 License: MIT

Un servidor Model Context Protocol endurecido para gestionar instancias VPS de mikr.us y hosts Linux remotos a través de SSH.

mikrus-mcp expone un conjunto acotado de capacidades de administración a través de una única ruta de invocación con políticas aplicadas. Soporta stdio local y Streamable HTTP autenticado solo en loopback, separa las operaciones de lectura de las mutaciones, vincula acciones privilegiadas a una identidad y recurso objetivo exactos, y mantiene la ejecución cruda de shell fuera de la superficie pública de MCP.

La versión 2.1 añade ejecución de programas SSH tipados y trabajos de proceso acotados. La versión 2.0 sigue siendo intencionalmente más estricta que la 1.x: se requiere Python 3.12+, se elimina el HTTP+SSE heredado, la verificación de host SSH está habilitada por defecto, las mutaciones requieren habilitación explícita de escritura y aprobaciones de corta duración en el servidor, y las herramientas de gestión heredadas amplias se han reemplazado con capacidades específicas de operación.

Contenido

Aspectos destacados

  • mikr.us + SSH — gestiona objetivos de la API de mikr.us y hosts Linux ordinarios accesibles por SSH desde el mismo servidor MCP.
  • Un núcleo de invocación — validación, autorización, vinculación de objetivos, aprobaciones, plazos, concurrencia, saneamiento, procedencia y clasificación de fallos se aplican en una única ruta propiedad de la aplicación.
  • Autorización en dos fases — las comprobaciones de selector y política de datos ocurren antes de la resolución del objetivo; las comprobaciones exactas de identidad y recurso del backend ocurren después de la resolución.
  • Mutaciones seguras por defecto — las escrituras están deshabilitadas por defecto, nunca se reintentan automáticamente y requieren una aprobación de un solo uso vinculada al principal, capacidad, identidad del objetivo resuelto, recurso y argumentos normalizados.
  • Identidad SSH verificada — la verificación de clave de host está habilitada por defecto; la identidad de mutación incluye la huella SHA-256 verificada de la clave de host.
  • Sin herramienta pública de shell crudo — las operaciones privilegiadas se exponen como herramientas acotadas y específicas de operación con validación.
  • Compilaciones reproducibles — se mantienen bloqueos de dependencias con hash confirmados para Linux x64 en CPython 3.12, 3.13 y 3.14.
  • Verificación exacta de artefactos — CI compila y ejercita la rueda exacta y el artefacto de contenedor Linux/amd64.
  • Procedencia en tiempo de ejecución — el descubrimiento de capacidades y los resultados exitosos exponen versión, fuente/compilación, artefacto, configuración y campos de generación de instancia cuando los proporciona el perfil de compilación/despliegue.
  • Autoridad de estándares fijada — los contratos del repositorio están alineados con la revisión estable fijada de ai-skills@main registrada en ai-skills.lock.yaml.

Requisitos

Para ejecución local:

  • Python 3.12, 3.13 o 3.14
  • una clave de API de mikr.us e identificador de servidor, o un host Linux accesible por SSH
  • para escrituras SSH: una clave de host verificada y un objetivo con los primitivos POSIX/Python requeridos

Se puede usar Docker en lugar de instalar Python directamente.

Inicio rápido

1. Clonar y crear un entorno

git clone https://github.com/paulomac1000/mikrus-mcp.git
cd mikrus-mcp

python3.12 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install .

Para el desarrollo del repositorio, use el bloqueo de desarrollo con hash confirmado en lugar de resolver dependencias ad hoc. Consulte Desarrollo.

2. Configurar un único servidor mikr.us

export MIKRUS_API_KEY='replace-me'
export MIKRUS_SERVER_NAME='srv123'

La forma de servidor único es la configuración más pequeña. Para SSH o múltiples objetivos use MCP_SERVERS; hay ejemplos a continuación.

3. Iniciar el servidor MCP

.venv/bin/python -m mikrus_mcp

stdio es el transporte predeterminado, por lo que este comando es adecuado para clientes MCP de escritorio que lanzan el servidor como subproceso.

4. Compilar y ejecutar con Docker

docker build -t mikrus-mcp:2.1.0 .

docker run --rm \
  -e MIKRUS_API_KEY='replace-me' \
  -e MIKRUS_SERVER_NAME='srv123' \
  mikrus-mcp:2.1.0

Las imágenes de lanzamiento publicadas se promocionan por digest inmutable. Prefiera una etiqueta de lanzamiento o digest sobre una etiqueta móvil sin fijar en producción.

Configuración del cliente MCP

Una configuración típica de cliente de escritorio puede lanzar el proyecto directamente a través de Python:

{
  "mcpServers": {
    "mikrus": {
      "command": "/absolute/path/to/mikrus-mcp/.venv/bin/python",
      "args": ["-m", "mikrus_mcp"],
      "env": {
        "MIKRUS_API_KEY": "replace-me",
        "MIKRUS_SERVER_NAME": "srv123"
      }
    }
  }
}

Use rutas absolutas. Las aplicaciones GUI frecuentemente se inician con un directorio de trabajo diferente al de su shell.

Para clientes basados en Docker, apunte el comando MCP a docker run y pase las credenciales a través de un archivo de entorno o mecanismo secreto en lugar de incrustar credenciales de larga duración en la configuración del cliente.

Herramientas disponibles

El catálogo soportado es consciente de la configuración. Las herramientas que no se aplican a ningún backend configurado, carecen del almacén de trabajos duraderos, o son mutaciones deshabilitadas por política se omiten de la lista pública de herramientas y permanecen visibles en el catálogo de capacidades con una razón de inactividad.

Descubrimiento

HerramientaTipoDescripción
list_configured_serversLecturaLista los objetivos configurados y su estado de conexión actual.
describe_mikrus_capabilitiesLecturaDevuelve el catálogo de capacidades soportadas y los metadatos de política.

Herramientas de API de mikr.us

Estas capacidades requieren al menos un objetivo mikrus configurado.

HerramientaTipoDescripción
get_server_infoLecturaInformación básica del VPS como RAM, disco, vencimiento y estado del servidor.
list_serversLecturaLista los servidores asociados con la cuenta de mikr.us.
get_server_statsLecturaRecupera estadísticas de recursos y tiempo de ejecución.
restart_serverMutaciónReinicia el VPS seleccionado.
get_logsLecturaObtiene registros recientes de tareas de mikr.us.
get_log_by_idLecturaObtiene un registro de tarea por ID.
boost_serverMutaciónSolicita el aumento temporal de recursos soportado.
get_db_infoLectura sensibleRecupera información de conexión de base de datos; los campos de credenciales están protegidos por el saneador de respuestas.
get_portsLecturaMuestra los puertos asignados.
get_cloudLecturaMuestra los servicios en la nube asociados con la cuenta.
assign_domainMutaciónAsigna un dominio o subdominio generado a un puerto.

Herramientas de sistema Linux

Estas capacidades operan a través de la abstracción de backend configurada y están disponibles donde el objetivo las soporta.

HerramientaTipoDescripción
read_fileLectura sensibleLee un archivo de texto acotado de una ruta permitida.
write_fileMutaciónEscribe atómicamente un archivo usando recorrido de directorio sin seguimiento.
get_service_statusLecturaInspecciona un servicio systemd.
change_service_stateMutaciónInicia, detiene, reinicia, habilita o deshabilita un servicio validado.
analyze_diskLecturaInspecciona el uso del sistema de archivos.
check_portLecturaComprueba si un puerto TCP está escuchando e identifica el proceso propietario cuando está disponible.
list_processesLectura sensibleLista procesos usando un contrato de salida acotado.
terminate_processMutaciónTermina un objetivo de proceso validado.
update_systemMutaciónEjecuta el flujo de trabajo de actualización del sistema soportado.
list_directoryLectura sensibleLista un directorio validado.
tail_fileLectura sensibleLee la cola acotada de un archivo de texto.
search_in_filesLectura sensibleBusca dentro de una ruta validada.
execute_programMutaciónEjecuta un ejecutable aprobado con argv tipados, cwd opcional y stdin opcional a través de un objetivo SSH.
start_programMutaciónInicia un programa tipado aprobado y devuelve un manejador de trabajo de proceso acotado en proceso.
get_program_statusLecturaInspecciona el estado de un trabajo de programa tipado propio.
get_program_resultLecturaRecupera el resultado terminal de un trabajo de programa tipado propio.
cancel_programMutaciónCancela un trabajo de programa tipado propio en cola o en ejecución.
remote_job_startMutaciónInicia un trabajo duradero respaldado por SSH usando una clave de idempotencia.
remote_job_statusLecturaInspecciona un trabajo remoto duradero por ID de trabajo vinculado al propietario.
remote_job_waitLecturaEspera en el servidor por progreso acotado de trabajo remoto o estado terminal.
remote_job_resultLecturaRecupera el resultado de un trabajo remoto duradero.
remote_job_outputLecturaLee stdout o stderr acotados usando un cursor explícito.
remote_job_cancelMutaciónCancela el grupo de procesos remoto exacto después de la validación de identidad PID e informa si la terminación fue verificada.
file_patch_atomicMutaciónReemplaza un archivo regular solo cuando su digest SHA-256 actual coincide con expected_digest (comparar-y-intercambiar; seguro binario vía base64; serializado por un bloqueo de asesoramiento local al host entre escritores de mikrus-mcp).
cron_listLecturaInforma perfiles cron propios con su estado de crontab instalado y digest de marcador.
cron_upsertMutaciónProyecta idempotentemente un perfil cron propio en el crontab instalado.
cron_removeMutaciónElimina exactamente el marcador y el par de líneas generado para un perfil cron propio.
docker_runtime_snapshotLectura sensibleDevuelve una instantánea semántica acotada de un servicio o contenedor compose.
docker_recreate_planLectura sensibleCalcula un plan de recreación semántico canónico con un recibo de plan acotado y un registro expirado en el servidor.
docker_recreate_applyMutaciónAplica un plan de recreación verificado; informa ALREADY_APPLIED cuando el estado ya coincide.
service_waitLecturaEspera en el servidor por preparación acotada del servicio compose.
get_memory_infoLecturaMuestra el uso de memoria.
get_network_infoLectura sensibleMuestra interfaces de red y sockets en escucha.
get_process_treeLectura sensibleMuestra el árbol de procesos.

Herramientas de Docker

HerramientaTipoDescripción
list_docker_containersLectura sensibleLista contenedores y estado actual.
get_docker_logsLectura sensibleObtiene registros recientes acotados para un contenedor.
get_docker_statsLecturaMuestra estadísticas de recursos del contenedor.

Herramientas de diario

HerramientaTipoDescripción
get_journal_logsLectura sensibleObtiene salida de diario acotada para una unidad.
find_system_errorsLectura sensibleEncuentra eventos de diario recientes a nivel de error.
search_journal_logsLectura sensibleBusca en la salida del diario un término acotado.

El acceso al diario depende de los permisos de la cuenta remota. Se puede usar un sudo_password configurado cuando la cuenta no está ya autorizada para leer el diario; la contraseña se envía por stdin del proceso en lugar de interpolarse en el comando shell.

Configuración multi-servidor

Establezca MCP_SERVERS a un objeto JSON con clave por el alias público del objetivo.

Ejemplo mixto mikr.us + SSH

export MCP_SERVERS='{
  "vps": {
    "type": "mikrus",
    "key": "replace-me",
    "srv": "srv123"
  },
  "host": {
    "type": "ssh",
    "host": "server.example.com",
    "port": 22,
    "user": "admin",
    "ssh_key": "/home/me/.ssh/id_ed25519",
    "known_hosts_file": "/home/me/.ssh/known_hosts"
  }
}'
export MCP_DEFAULT_SERVER='vps'

Campos de objetivo SSH

CampoRequeridoPredeterminadoNotas
typesí—Debe ser "ssh".
hostsí—Nombre de host o dirección IP.
portno22Puerto TCP, 1–65535.
usernorootNombre de usuario SSH.
passwordno—Autenticación por contraseña. Prefiera la autenticación por clave cuando sea posible.
ssh_keyno—Archivo de clave privada existente; debe estar protegido contra acceso de grupo/otros.
ssh_certno—Certificado SSH opcional.
sudo_passwordno—Contraseña opcional para comandos sudo -S específicos de operación.
known_hosts_filenoPolítica predeterminada de AsyncSSHArchivo known_hosts explícito opcional.
timeoutno30Entrada de tiempo de espera de conexión/operación, 1–300 segundos.
verify_host_keynotrueLa verificación de clave de host está habilitada por defecto.
Deshabilitar la verificación de host SSH requiere MCP_ALLOW_INSECURE_SSH=1 y está limitado a uso de desarrollo de solo lectura. El inicio falla si las escrituras están habilitadas mientras un objetivo SSH tiene la verificación de host deshabilitada.

Trabajos remotos duraderos

Establezca una ruta de almacenamiento absoluta controlada por el operador para activar la familia de capacidades remote_job_*. El archivo se crea con permisos privados y se actualiza mediante reemplazo atómico acotado:

export MCP_REMOTE_JOB_STORE_FILE="$PWD/.mikrus-remote-jobs.json"

La capacidad permanece inactiva cuando esta configuración está ausente o cuando no hay ningún objetivo SSH configurado. La cancelación verifica la terminación de los procesos descendientes después del kill e informa un campo terminated honesto; un inicio cuyo resultado fue ambiguo se reconcilia una vez contra el registro remoto en lugar de mostrar el timeout bruto (una búsqueda irrecuperable muestra AMBIGUOUS_OUTCOME). Los registros de trabajos expiran después de un horizonte de retención de 7 días (REMOTE_JOB_RETENTION_SECONDS = 604800); los registros expirados se limpian en la siguiente lectura del registro.

Perfiles Cron

Establezca una ruta de almacenamiento absoluta controlada por el operador para activar la familia de capacidades cron_list, cron_upsert y cron_remove:

export MCP_CRON_PROFILE_STORE_FILE="$PWD/.mikrus-cron-profiles.json"
export MCP_DOCKER_PLAN_STORE_FILE="$PWD/.mikrus-docker-plans.json"

Los perfiles son registros duraderos vinculados al propietario con un cronograma tipado de cinco campos, un ejecutable en lista blanca, argumentos tipados y asignaciones de entorno acotadas opcionales. La proyección en el crontab instalado usa una línea de comentario marcador (# mikrus-mcp:<profile_id>:sha256=<digest>) seguida de exactamente una línea de cron generada cuyos argumentos están estrictamente escapados con comillas simples; las cadenas de comandos arbitrarias nunca se serializan. Las actualizaciones de crontab vuelven a leer el archivo inmediatamente antes de la instalación y fallan con CONCURRENT_MODIFICATION cuando cambió concurrentemente. Todas las líneas de crontab que no son de perfil se conservan byte por byte, y las capacidades de cron permanecen inactivas cuando la configuración está ausente o no hay ningún objetivo SSH configurado. Las instalaciones y lecturas de crontab se serializan mediante un bloqueo de asesoramiento local al host (~/.mikrus-mcp/locks/crontab.lock) para que los escritores de mikrus-mcp nunca se intercalen; los escritores concurrentes que no son de mikrus quedan fuera de esa garantía y aún son detectados por la relectura inmediata previa a la instalación (CONCURRENT_MODIFICATION).

La misma familia de bloqueos de asesoramiento (~/.mikrus-mcp/locks/cas.lock) cubre file_patch_atomic: la lectura del digest, la comparación, la escritura del archivo temporal y el renombrado mantienen el bloqueo, haciendo que la comparación-y-cambio sea atómica entre todos los escritores de mikrus-mcp en el host. Los escritores que no son de mikrus quedan fuera de la garantía; la condición previa del digest aún los detecta al inicio de la operación.

Docker y Compose

Las capacidades docker_runtime_snapshot, docker_recreate_plan, docker_recreate_apply y service_wait gestionan servicios de compose sobre un objetivo SSH sin shell. docker_recreate_plan resuelve la identidad del proyecto compose desde las etiquetas de contenedor en vivo (nunca un nombre base de directorio), lee el estado deseado mediante docker compose config y devuelve un plan semántico canónico vinculado por un recibo plan:v1:sha256:.... El plan persiste en un almacén de registros duradero del lado del servidor (habilitado por MCP_DOCKER_PLAN_STORE_FILE, una ruta absoluta controlada por el operador con permisos privados; los registros expiran después de 300 segundos), por lo que apply deriva cada entrada de estado deseado del registro almacenado en lugar de los argumentos de invocación. Los valores de entorno se usan para la comparación de apply pero nunca se devuelven al modelo — solo las claves de entorno son visibles.

docker_recreate_plan además registra si el contenedor en vivo lleva deriva solo de tiempo de ejecución relativa a compose (campos como entorno aplicado en tiempo de ejecución o etiquetas que el archivo compose no declara). La planificación con allow_runtime_drift=true registra aceptación explícita; de lo contrario, docker_recreate_apply rechaza la mutación con RECREATE_CONFIG_DRIFT y el operador debe replanificar para aceptar perder esa configuración solo de tiempo de ejecución.

docker_recreate_apply toma solo el servicio y plan_receipt; un registro faltante o expirado es PLAN_STALE. El registro almacenado clasifica la deriva: campos deseados por compose cambiados desde la planificación → PLAN_STALE; el digest de imagen se movió en una etiqueta implícitamente fijada → IMAGE_DRIFT; el digest se movió bajo una imagen explícitamente fijada → PLAN_STALE. El comportamiento es idéntico de fallo cerrado: se requiere replanificación. Cuando el estado semántico en vivo ya es igual al estado deseado por compose, apply informa ALREADY_APPLIED sin recrear. El apply en sí es la secuencia de argv acotada docker compose -p <project> -f <files>... up -d --no-deps --force-recreate <service>; sigue una única verificación de inspección, y una espera de preparación es obligatoria: el valor predeterminado es healthy cuando el contenedor recreado define un healthcheck y running en caso contrario, con un presupuesto de 15 segundos; readiness y timeout_seconds (5–25) son solo de ajuste. Una espera fallida muestra su error tipado con applied=true en el mensaje — la recreación se ejecutó, así que reconcilie en lugar de reintentar a ciegas. service_wait sondea docker inspect dentro de una invocación auxiliar acotada e informa READINESS_TIMEOUT o HEALTH_FAILED como errores de clase de lectura; con un plan_receipt verifica que el registro exista antes de esperar.

Campos de objetivo mikr.us

CampoRequeridoPredeterminadoNotas
typesí—Debe ser "mikrus".
keysí—Clave API.
srvsí—ID de servidor mikr.us estable.
api_urlnohttps://api.mikr.usDebe usar HTTPS.

Si MCP_DEFAULT_SERVER se omite, el primer objetivo configurado se usa como selector predeterminado.

Autorización y aprobaciones

Modelo de alcance

El predeterminado de operador único integrado incluye estos ejes de política de lectura:

tool:*
target:*
target-id:*
resource:*
data:*

Las mutaciones además requieren su alcance de capacidad y write:server.

Si establece MCP_ALLOWED_SCOPES usted mismo, reemplaza el conjunto predeterminado. Una anulación heredada de tool:*,target:* es por lo tanto intencionalmente insuficiente para operaciones respaldadas por objetivo después de la fase de autorización de identidad resuelta.

Las familias de alcance importantes son:

  • tool:<capability> — permite la capacidad en sí.
  • target:<selector> — permite el alias de objetivo público configurado antes de la resolución del objetivo.
  • target-id:<resolved-identity> — permite la identidad de backend resuelta exacta.
  • resource:<capability>:sha256:<digest> — permite un recurso normalizado exacto; resource:* es el perfil comodín explícito.
  • data:<classification> — permite la clase de confidencialidad del manifiesto; data:* es el perfil comodín explícito.
  • write:server — habilita la autorización de mutación cuando la política de escritura del proceso también está habilitada.

Habilitando mutaciones

Las mutaciones requieren tanto la política del proceso como un registro de aprobación de corta duración coincidente:

export MCP_WRITE_ENABLED=true
export MCP_APPROVAL_FILE="$PWD/.mikrus-approvals.json"

Los registros de aprobación se crean desde el shell del operador de confianza, no por el modelo. El auxiliar resuelve el objetivo antes de persistir el registro; para SSH esto vincula la huella de clave de host verificada actual.

Forma general:

.venv/bin/python scripts/approval.py \
  --file "$MCP_APPROVAL_FILE" \
  --capability '<capability>' \
  --principal '<principal>' \
  --server '<configured-alias>' \
  --resource '<normalized-resource>' \
  --arguments-json '<JSON object without server>' \
  --ttl-seconds 60

Las aprobaciones expiran rápidamente (predeterminado 60 segundos, máximo 300 segundos), se consumen una vez y se comparan contra principal, capacidad, identidad de objetivo resuelta exacta, recurso y digest de argumento normalizado.

Transportes

stdio

stdio es el transporte predeterminado y recomendado para integraciones de escritorio locales:

export MCP_TRANSPORT=stdio
.venv/bin/python -m mikrus_mcp

El tráfico del protocolo es dueño de stdout; los diagnósticos se escriben en stderr.

HTTP transmisible

HTTP transmisible está deliberadamente restringido a direcciones de loopback literales y requiere un archivo de token portador protegido.

umask 077
python -c 'import secrets; print(secrets.token_urlsafe(48))' > .mcp-http-token
chmod 600 .mcp-http-token

export MCP_TRANSPORT=streamable-http
export MCP_HOST=127.0.0.1
export MCP_PORT=8000
export MCP_HTTP_BEARER_TOKEN_FILE="$PWD/.mcp-http-token"

.venv/bin/python -m mikrus_mcp

Los clientes se conectan a http://127.0.0.1:8000/mcp con Authorization: Bearer <token>.

La exposición HTTP remota/pública no es parte del perfil de seguridad compatible. El puente HTTP+SSE heredado de dos extremos y el puente REST no autenticado se eliminaron en 2.0.

Formato de resultado

Los resultados de aplicación usan un sobre estructurado de éxito/error e incluyen metadatos de correlación/procedencia.

Éxito representativo:

{
  "success": true,
  "data": {
    "param_ram": "1024"
  },
  "_meta": {
    "request_id": "6a5c...",
    "capability": "get_server_info",
    "capability_version": "2.1.0",
    "source": "mikrus-mcp",
    "artifact": "mikrus-mcp==2.1.0",
    "target": "srv123",
    "target_identity": "mikrus:srv123",
    "backend": "mikrus",
    "duration_ms": 42
  }
}

Fallo representativo:

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "request rate limit exceeded",
    "retryable": true,
    "retry_after_seconds": 2.0
  },
  "_meta": {
    "request_id": "9b8f...",
    "capability": "get_server_info",
    "source": "mikrus-mcp"
  }
}

Los metadatos solo se incluyen cuando son seguros y realmente conocidos. Por ejemplo, un fallo de autorización previo a la resolución no revela la identidad resuelta del backend.

Los perfiles de compilación y despliegue proporcionan procedencia inmutable a través del sello _build_provenance.json integrado, escrito por scripts/stamp_build_provenance.py a partir de las entradas --source-revision, --build-id, --built-at y --config-revision; packageContentDigest se calcula desde el paquete sellado durante el sellado. En tiempo de ejecución solo se leen dos variables de entorno: MIKRUS_MCP_CONFIG_REVISION (anula el configRevision sellado) y MIKRUS_MCP_DEPLOYMENT_RECEIPT_FILE (ruta del recibo de despliegue). El sourceRevision, buildId, packageContentDigest y builtAt sellados se informan en el descubrimiento de capacidades y en los metadatos de resultados exitosos; no pueden inyectarse mediante variables de entorno ni inferirse de un checkout montado. Compila wheels mediante scripts/build_wheel.py --provenance stamped|unstamped para que el sello no pueda quedar obsoleto silenciosamente.

Los límites de resultados se aplican contra el sobre de aplicación serializado, incluidos los metadatos, en lugar de solo el valor anidado data.

Modelo de seguridad

mikrus-mcp es un servicio de administración privilegiado. Trate su entorno de proceso, archivo de token portador, claves SSH, registro de aprobaciones y credenciales de objetivo como secretos.

Los trabajos de programa tipados permanecen acotados y locales al proceso. Cuando MCP_REMOTE_JOB_STORE_FILE está configurado, las herramientas remote_job_* usan un recibo duradero vinculado al propietario y un auxiliar JSON-stdin del lado SSH; estado, espera, resultado, cursores de salida y cancelación no requieren bucles sleep del lado del modelo ni arqueología de PID. La ruta de almacenamiento debe ser una ruta de archivo absoluta controlada por el operador. Las mutaciones de trabajos remotos aún requieren habilitación de escritura y aprobación de una sola vez.

Valores predeterminados clave:

  • sin respaldo de un objetivo fallido a otro objetivo configurado;
  • verificación de clave de host SSH habilitada por defecto;
  • HTTP transmisible autenticado solo-loopback;
  • mutaciones deshabilitadas a menos que MCP_WRITE_ENABLED=true;
  • aprobaciones de una sola vez del lado del servidor para cada mutación pública;
  • sin reintentos automáticos de mutación después de timeout, desconexión, límite de tasa o finalización ambigua;
  • sin herramienta pública de comandos arbitrarios;
  • ejecución de programas tipados solo-SSH, vinculada a aprobación, y envía valores controlados por el usuario como stdin del auxiliar en lugar de texto de comando de shell;
  • escrituras de archivos remotos sin seguimiento seguras para componentes;
  • comportamiento acotado de solicitud, respuesta, salida, concurrencia y plazo;
  • campos de respuesta sensibles saneados antes de la serialización visible al modelo.

Lea SECURITY.md antes de habilitar escrituras o desplegar el servidor fuera de un entorno desechable.

Desarrollo

El repositorio mantiene bloqueos de desarrollo Linux x64 con hash para cada línea de Python compatible. Para la línea predeterminada 3.12:

python3.12 -m venv .venv
.venv/bin/python -m pip install "pip==26.1.2"
.venv/bin/python -m pip install --require-hashes -r requirements-dev-linux-x64-py312.lock
.venv/bin/python -m pip install --no-deps .

Ejecute la puerta rápida sin credenciales:

.venv/bin/python scripts/core_gate.py

Ejecute la puerta completa del repositorio local:

.venv/bin/python scripts/ci.py

Ejecute una prueba enfocada:

.venv/bin/python -m pytest tests/unit/test_kernel.py -q

Compile el wheel (las compilaciones selladas se niegan a ejecutarse cuando las fuentes son más nuevas que el sello de compilación integrado; las compilaciones sin sello eliminan el sello primero):

.venv/bin/python scripts/build_wheel.py --provenance stamped
# or, for an unstamped local wheel:
.venv/bin/python scripts/build_wheel.py --provenance unstamped

requirements-runtime.in y requirements-dev.in son entradas editadas por humanos. Los archivos requirements-*-linux-x64-py3*.lock son gráficos hash exactos generados y no deben editarse a mano.

La CI alojada además valida la matriz de Python compatible, manifiestos, documentación, política de seguridad estática, comportamiento exacto del wheel, transportes MCP oficiales, bloqueos de dependencias y comportamiento del contenedor Linux/amd64.

Arquitectura

MCP client
   |
   |  stdio / authenticated loopback Streamable HTTP
   v
MCP registration + transport boundary
   |
   v
InvocationKernel
   |-- argument validation
   |-- principal / selector authorization
   |-- target resolution
   |-- resolved identity / resource authorization
   |-- write policy + one-time approval
   |-- deadline + concurrency policy
   |-- adapter execution
   |-- sanitization + provenance + structured errors
   |
   v
TargetRegistry
   |                    |
   v                    v
mikr.us API adapter   SSH adapter

Los adaptadores de backend no poseen la política MCP. Los envoltorios de transporte no eluden el kernel. El registro de herramientas públicas se deriva del catálogo de manifiestos activo propiedad de la aplicación.

Para el ciclo de vida completo y el modelo de fallos, vea docs/architecture.md.

Solución de problemas

Falta una herramienta en list_tools

Los catálogos compatibles y activos son intencionalmente diferentes. Una capacidad puede estar inactiva porque:

  • ningún backend configurado la soporta;
  • las escrituras están deshabilitadas;
  • otra política de proceso hace que la capacidad no esté disponible.

Inspeccione describe_mikrus_capabilities / capabilities://catalog para conocer la razón de inactividad.

AUTHORIZATION_FAILED después de actualizar desde 1.x

Si configuras explícitamente MCP_ALLOWED_SCOPES, verifica que incluya los ejes de autorización resueltos. El valor predeterminado de 2.0 es:

tool:*,target:*,target-id:*,resource:*,data:*

Las mutaciones además necesitan el alcance de herramienta relevante más write:server, la habilitación de escritura de procesos y una aprobación coincidente.

SSH se niega a iniciar o conectarse

La verificación del host está habilitada de forma predeterminada. Asegúrate de que el host remoto esté presente en la política efectiva de known_hosts o establece un known_hosts_file válido. No deshabilites la verificación para implementaciones con escritura habilitada.

health://ready informa que no está listo

El objetivo predeterminado configurado es una dependencia obligatoria de preparación. El inicio en sí es diferido, por lo que el objetivo puede estar inicialmente en not_connected; la preparación se vuelve verdadera solo después de una conexión exitosa al objetivo predeterminado.

La mutación devuelve AMBIGUOUS_OUTCOME

No reintentes a ciegas. La solicitud puede haber llegado al backend antes del fallo de transporte o plazo. Primero reconcilia el estado remoto, luego emite una nueva aprobación solo si realmente se requiere otra mutación.

HTTP transmisible rechaza el archivo de token

El archivo de token debe ser un archivo regular, sin enlaces simbólicos, propiedad del usuario del proceso, no accesible por el grupo u otros usuarios, y contener un token de al menos 32 caracteres.

Estándares y migración

El repositorio fija la autoridad exacta de AI Skills en ai-skills.lock.yaml. El contrato de arquitectura MCP se basa en el punto de entrada estable mcp-server-architect/STANDARD.md.

El CI del repositorio emite evidencia estructural contra la autoridad fijada. La evidencia estructural no es lo mismo que la aceptación independiente de producción; la evidencia de sistemas reales específica de la implementación y la revisión independiente siguen siendo puertas separadas.

Para los cambios disruptivos de 1.x → 2.0 y el procedimiento de reversión, consulta MIGRATION.md.

Referencias adicionales:

Licencia

MIT