srv-explore

Интерфейс, позволяющий агенту безопасно работать и собирать информацию на сервере. Рядом с данными, логами и сервисами.

Explore-агент живёт на удалённом сервере за MCP-интерфейсом: подключаешься к нему из локального кодового агента и работаешь как со скиллом. Read-only держит не промпт, а окружение — песочница без прав записи — и плагины, выдающие контролируемый доступ к системам (docker, web) и данным (БД, кеши, файлы).

Сервис слушает только loopback: и инженер, и админ ходят через SSH-туннель, публичного порта нет. Ставится и обновляется деплой-воркфлоу, от остального проекта не зависит.

На что это похоже в работе

srv_explore("почему nginx отдаёт 502 последний час?")
  → agent: tail -n 200 /var/log/nginx/error.log | grep 502
            docker logs --since 1h api | tail -50
  → upstream api:8080 connection refused, контейнер api рестартовал 4 раза за час

Запрос — цель словами, не команда: чем смотреть, агент решает сам, а в ответе видно, какие команды он выполнил. Если команда известна заранее, второй инструмент выполняет её без агента — быстро и без токенов модели:

srv_explore_cmd("docker ps --format '{{.Names}} {{.Status}}'")
  → api Up 3 minutes
    db  Up 6 days

Related MCP server: masaro-infra-mcp

Зачем это нужно

Быстрый старт

1. Поставить — деплой-воркфлоу

Actions → «Deploy srv-explore (host service)», выбрать environment. Воркфлоу копирует бандл на сервер и гоняет install.sh — идемпотентно. Руками (sudo bash srv_explore/install.sh) — только для отладки.

Требования: Linux с systemd и cgroup v2, root, apt-get (Debian/Ubuntu) — python3 доустановится сам. В environment нужны SSH_HOST / SSH_USER (variables) и SSH_KEY + CLAUDE_CODE_OAUTH_TOKEN (secrets).

Если API модели заблокирован для хоста по гео (напр. РФ-адрес → api.anthropic.com отдаёт 403) — задать secret SRV_EXPLORE_UPSTREAM_PROXY (http://[user:pass@]host:port): tinyproxy пустит через него только домены из SRV_EXPLORE_UPSTREAM_DOMAINS (по умолчанию api.anthropic.com), остальной egress агента идёт напрямую. Доменный allowlist остаётся на месте и проверяется до пересылки. Пусто — прямой выход.

Админ-токен генерится на сервере при первой установке, в лог Actions не попадает:

ssh root@<host> grep SRV_EXPLORE_ADMIN_TOKEN /etc/srv-explore/env

Перевыпустить: удалить эту строку и запустить деплой снова.

2. Выдать доступ инженеру

Админка на loopback, поэтому через туннель:

ssh -N -L 8765:localhost:8765 root@<host>     # держать открытым
# → http://localhost:8765/admin, вставить админ-токен

«Пользователи» → Добавить: метка + публичный SSH-ключ инженера. Вернётся srvx_-токен — отдать инженеру. Удаление пользователя снимает и ключ, и все его токены разом.

3. Инженеру — страница агента

Отдай инженеру токен и ссылку http://localhost:8765/ (по его туннелю). Там всё остальное: quick start подключения, принципы работы, свой доступ, вопросы к серверу из браузера.

ssh-keygen -t ed25519 -f your_ssh_key -N ""           # публичную часть — админу
ssh -N -L 8765:localhost:8765 srvx-tunnel@<host> -i your_ssh_key
claude mcp add --scope local --transport http srv-explore http://localhost:8765/mcp \
  --header "Authorization: Bearer srvx_..."

--scope local (дефолт, можно опустить) кладёт сервер в ~/.claude.json — приватно, не в репозиторий, только для этого проекта. Токен персональный (на твой SSH-ключ) — делить и коммитить его нельзя, поэтому конфиг местный, а не общий .mcp.json. Сервер активируется при следующем запуске claude; проверить — claude mcp list.

Имя srv-explore в команде — произвольное. На каждый сервер дай своё (dev-explorer, prod-explorer) и свой локальный порт туннеля (8765, 8766, с тем же портом в --transport http … localhost:<порт>/mcp) — тогда несколько серверов живут рядом.

Как устроено

flowchart TB
  subgraph server["Remote server"]
    subgraph svc["systemd service · root"]
      MCP["mcp_server.py · MCP · /admin · /"]
      PROV["provision.py · plugin install"]
      ST[("StateDir · tokens · plugins · creds")]
    end
    subgraph box["Sandbox · srvx-agent, no privileges"]
      W["agent_worker.py · Claude Agent SDK"]
      G["guard.py · command hygiene"]
    end
    PX["docker-socket-proxy · POST=0"]
    TP["tinyproxy · domain allowlist"]
    RES[("files · logs · docker · DB")]
  end
  MCP -->|"systemd-run --uid · RO-FS · egress firewall"| W
  MCP -.->|"creds of enabled plugins"| W
  W --> G --> RES
  W -->|docker| PX --> RES
  W -->|"model API"| TP
  PROV --> ST
  MCP --> ST

Плагины

Плагин — один файл в src/srv_explore/plugins/, который даёт агенту безопасный доступ к одному ресурсу: docker, postgres, redis, mongo, rabbitmq. Он создаёт отдельный доступ без права записи и обязан это доказать: последний шаг установки пытается что-нибудь записать и должен получить отказ. Всё выключено по умолчанию, включает администратор.

Как ими пользоваться и как написать свой — PLUGINS.md; часть «написать свой» можно целиком отдать кодовому агенту как задание.

Collaboration requests

• Структура плагина — как сделать универсальнее/понятнее.

• Больше плагинов — расширить набор ресурсов, к которым агент получает безопасный доступ.

• Упростить процедуру доступа. Цепочка «ключ → админ добавляет юзера → токен → туннель → mcp add» рабочая, но шагов много. Хочется её упростить — меньше ручных действий у инженера и у админа.