Tunnel Manager

CLI or API | MCP | Agent

Версия: 3.1.0

Документация — Установка, развёртывание, использование через API, CLI, MCP и агентные интерфейсы поддерживаются в официальной документации.

Related MCP server: mcp-ssh

Обзор

Tunnel Manager — это сервер Agent и Model Context Protocol (MCP) промышленного уровня, предназначенный для прямого взаимодействия с Create SSH Tunnels to your remote hosts and host as an MCP Server for Agentic AI!.

Ключевые возможности

• Консолидированные MCP-инструменты с маршрутизацией действий: Минимизирует накладные расходы на токены и устраняет раздувание инструментов в контекстах LLM, группируя методы в оптимизированные модули инструментов с возможностью переключения.

• Безопасность корпоративного уровня: Всесторонняя поддержка политик Eunomia, делегирования токенов OIDC и детального отслеживания контекста выполнения.

• Встроенный графовый агент: Встроенный агент Pydantic AI с поддержкой протокола управления агентами (ACP) и стандартных веб-интерфейсов (AG-UI).

• Встроенная телеметрия и трассировка: Готовые к использованию экспорты OpenTelemetry и встроенная трассировка Langfuse.

CLI or API

Этот агент оборачивает API Create SSH Tunnels to your remote hosts and host as an MCP Server for Agentic AI!. Вы можете взаимодействовать с ним программно или через встроенные точки входа выполнения.

Подробные инструкции по использованию базовых обёрток API, расширенных привязок схем и справочников SDK для разработчиков приведены в docs/index.md.

MCP

Этот сервер использует динамические инструменты с маршрутизацией действий для оптимизации накладных расходов на токены и максимальной совместимости с IDE.

Доступные MCP-инструменты

Автоматически сгенерировано из работающего MCP-сервера — не редактируйте вручную.

Сжатые инструменты с маршрутизацией действий (MCP_TOOL_MODE=condensed)

Подробные инструменты с сопоставлением 1:1 с API (MCP_TOOL_MODE=verbose или both)

8 инструментов с маршрутизацией действий · 6 подробных инструментов 1:1. Каждый включён, если его переключатель <DOMAIN>TOOL не установлен в false; MCP_TOOL_MODE выбирает поверхность (**intent по умолчанию* — шесть глагольных инструментов, детальный набор загружается по требованию · condensed с маршрутизацией действий · verbose 1:1 · both). Автоматически сгенерировано — не редактируйте.*

Подробные схемы инструментов, формы параметров и ограничения валидации приведены в docs/usage.md.

Динамический выбор и видимость инструментов

Этот MCP-сервер поддерживает динамический выбор набора инструментов и фильтрацию видимости во время выполнения. Это позволяет ограничить набор открытых инструментов, чтобы не раздувать контекстное окно LLM.

Вы можете настроить фильтрацию инструментов через несколько каналов ввода:

• Аргументы CLI: Передайте --tools или --toolsets (или их отключённые аналоги --disabled-tools и --disabled-toolsets) при запуске.

• Переменные окружения: Определите стандартные переменные окружения:

  • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS

  • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS

• Заголовки HTTP SSE-запросов: Передайте пользовательские заголовки при инициализации транспорта:

  • x-mcp-enabled-tools / x-mcp-disabled-tools

  • x-mcp-enabled-tags / x-mcp-disabled-tags

• Параметры запроса HTTP SSE: Добавьте параметры запроса непосредственно к URL вашего транспортного соединения:

  • ?tools=tool1,tool2

  • ?tags=tag1

При передаче строк запроса или параметров слой разрешения графа знаний без LLM (с использованием DynamicToolOrchestrator) сопоставляет намерения запроса с известными тегами, именами или описаниями инструментов, с безопасным резервным вариантом и автоматическим фоновым обновлением кэша каждые 24 часа.

Примеры конфигурации MCP

Установите дополнительный пакет [mcp], ориентированный на коннекторы. В примерах используется tunnel-manager[mcp] для добавления FastMCP / FastAPI через agent-utilities[mcp]; необходимое ядро Agent Utilities по-прежнему включает epistemic-graph[full]. Дополнительный пакет [agent-runtime] дополнительно включает оркестрацию моделей.

Транспорт stdio (локальные IDE — Cursor, Claude Desktop, VS Code)

{
  "mcpServers": {
    "tunnel-manager-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "tunnel-manager[mcp]",
        "tunnel-manager-mcp"
      ],
      "env": {
        "MCP_TOOL_MODE": "intent",
        "FILETOOL": "True",
        "HOSTTOOL": "True",
        "INGESTTOOL": "True",
        "INVENTORYTOOL": "True",
        "OPERATIONSTOOL": "True",
        "REMOTETOOL": "True",
        "SECURITYTOOL": "True",
        "SYSTEMTOOL": "True",
        "TUNNEL_IDENTITY_FILE": "~/.ssh/id_ed25519",
        "TUNNEL_INVENTORY_GROUP": "all",
        "TUNNEL_KG_INGEST": "true",
        "TUNNEL_KNOWN_HOSTS": "~/.ssh/known_hosts",
        "TUNNEL_MANAGER_HEALTH_AGGREGATE_S": "3600",
        "TUNNEL_MANAGER_HEALTH_INGEST": "true",
        "TUNNEL_MANAGER_HOSTS": "r510,r710,r820,rw710",
        "TUNNEL_MAX_THREADS": "6",
        "TUNNEL_PARALLEL": "False",
        "TUNNEL_REMOTE_PORT": "22"
      }
    }
  }
}

Ссылки на среду выполнения требуют лаунчера с поддержкой псевдонимов, такого как GraphOS. Другие лаунчеры должны опускать эти записи и внедрять разрешённые значения через свою собственную границу секретов среды выполнения.

Транспорт Streamable-HTTP (сетевой / производственный)

{
  "mcpServers": {
    "tunnel-manager-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "tunnel-manager[mcp]",
        "tunnel-manager-mcp",
        "--transport",
        "streamable-http",
        "--port",
        "8000"
      ],
      "env": {
        "TRANSPORT": "streamable-http",
        "HOST": "127.0.0.1",
        "PORT": "8000",
        "MCP_TOOL_MODE": "intent",
        "FILETOOL": "True",
        "HOSTTOOL": "True",
        "INGESTTOOL": "True",
        "INVENTORYTOOL": "True",
        "OPERATIONSTOOL": "True",
        "REMOTETOOL": "True",
        "SECURITYTOOL": "True",
        "SYSTEMTOOL": "True",
        "TUNNEL_IDENTITY_FILE": "~/.ssh/id_ed25519",
        "TUNNEL_INVENTORY_GROUP": "all",
        "TUNNEL_KG_INGEST": "true",
        "TUNNEL_KNOWN_HOSTS": "~/.ssh/known_hosts",
        "TUNNEL_MANAGER_HEALTH_AGGREGATE_S": "3600",
        "TUNNEL_MANAGER_HEALTH_INGEST": "true",
        "TUNNEL_MANAGER_HOSTS": "r510,r710,r820,rw710",
        "TUNNEL_MAX_THREADS": "6",
        "TUNNEL_PARALLEL": "False",
        "TUNNEL_REMOTE_PORT": "22"
      }
    }
  }
}

В качестве альтернативы подключитесь к предварительно развёрнутому экземпляру Streamable-HTTP по url:

{
  "mcpServers": {
    "tunnel-manager-mcp": {
      "url": "http://localhost:8000/tunnel-manager-mcp/mcp"
    }
  }
}

Запустите проверенный образ контейнера как дочерний процесс stdio с минимальными привилегиями (без прослушивателя или опубликованного порта):

docker run -i --rm \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --pids-limit=256 \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
  -e TRANSPORT=stdio \
  -e MCP_TOOL_MODE=intent \
  -e FILETOOL=True \
  -e HOSTTOOL=True \
  -e INGESTTOOL=True \
  -e INVENTORYTOOL=True \
  -e OPERATIONSTOOL=True \
  -e REMOTETOOL=True \
  -e SECURITYTOOL=True \
  -e SYSTEMTOOL=True \
  -e TUNNEL_IDENTITY_FILE=~/.ssh/id_ed25519 \
  -e TUNNEL_INVENTORY_GROUP=all \
  -e TUNNEL_KG_INGEST=true \
  -e TUNNEL_KNOWN_HOSTS=~/.ssh/known_hosts \
  -e TUNNEL_MANAGER_HEALTH_AGGREGATE_S=3600 \
  -e TUNNEL_MANAGER_HEALTH_INGEST=true \
  -e TUNNEL_MANAGER_HOSTS=r510,r710,r820,rw710 \
  -e TUNNEL_MAX_THREADS=6 \
  -e TUNNEL_PARALLEL=False \
  -e TUNNEL_REMOTE_PORT=22 \
  registry.example.invalid/tunnel-manager@sha256:<digest> tunnel-manager-mcp

Для контейнеризованного сетевого HTTP укажите аутентифицированный TLS-вход (или прямой серверный TLS), точный MCP_ALLOWED_HOSTS и точную политику CIDR доверенного прокси через профиль развёртывания, принадлежащий оператору. Генератор не создаёт неаутентифицированный не-loopback прослушиватель.

Автоматически сгенерировано из считываемой из кода поверхности окружения (MCP_TOOL_MODE + переменные пакета) — не редактируйте.

Дополнительные варианты развёртывания

tunnel-manager может работать как локальный процесс stdio или контейнер, либо за удалённой сетевой границей. Руководство по развёртыванию содержит подробный транспортный контракт.

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

• Удалённый URL — подключитесь через аутентифицированный HTTPS-вход, предоставленный оператором. Сохраните его URL, ссылки на исходящую идентичность, профиль доверия и точный MCP_ALLOWED_HOSTS в AgentConfig.

Инвентарь

tunnel-manager работает с единым общим YAML-инвентарём, который сопоставляет короткие псевдонимы хостов (например, edge-node) с их данными SSH-подключения. Каждая поверхность экосистемы читает тот же файл — API HostManager, CLI tunnel-manager, MCP-сервер, container-manager-mcp (его псевдонимы хостов cm_*) и навык ssh-bootstrap — так что вы определяете свой парк хостов один раз.

• Расположение — ~/.config/agent-utilities/inventory.yml (предпочтителен .yml). Устаревший inventory.yaml по тому же пути по-прежнему читается, если .yml не существует, поэтому существующие установки продолжают работать. Переопределите с помощью TUNNEL_INVENTORY.

• Управляйте им с помощью подкоманды inventory:

  tunnel-manager inventory init     # write a commented inventory.yml template (--force to overwrite)
  tunnel-manager inventory doctor   # validate hosts/groups; --fix migrates legacy .yaml -> .yml
  tunnel-manager inventory show     # print the resolved path + host/group summary

Полная схема, все поля хоста, шаблон для копирования и параметры переопределения приведены в Руководстве по инвентарю.

Переменные окружения

Переменные окружения пакета

Наследуемые переменные agent-utilities (применяются к каждому коннектору)

44 пакетных + 14 наследуемых переменных. Автоматически сгенерировано из .env.example + общий набор agent-utilities — не редактируйте.

Каждая переменная, которую читает сервер, сгруппирована по назначению. См. .env.example для стартовой точки копирования-вставки.

SSH-подключение и учётные данные

Инвентаризация и параллелизм

MCP-сервер / транспорт

Переключатели инструментов

Каждый инструмент с маршрутизацией действий можно отключить индивидуально с помощью его переменной окружения-переключателя (установите значение false). Полный список приведён в таблице Доступные MCP-инструменты выше (HOSTTOOL, REMOTETOOL, INVENTORYTOOL, OPERATIONSTOOL, SYSTEMTOOL, FILETOOL, SECURITYTOOL).

Телеметрия и управление

Среда выполнения агента (только полная среда выполнения [agent])

Агент

Этот репозиторий содержит полностью интегрированного Pydantic AI Graph Agent. Он взаимодействует по протоколу Agent Control Protocol (ACP) и бесшовно работает с Agent Web UI (AG-UI) и терминальным интерфейсом.

Запуск CLI агента

Чтобы запустить интерактивного агента в командной строке:

# Set credentials
export TUNNEL_IDENTITY_FILE="your_value"
export DEBUG="your_value"
export PYTHONUNBUFFERED="your_value"

# Run the agent server
tunnel-manager-agent --provider openai --model-id gpt-4o

Оркестрация Docker Compose

Следующий файл docker/agent.compose.yml настраивает совместную работу Agent, Web UI и Terminal Interface:

version: '3.8'

services:
  tunnel-manager-mcp:
    image: example/tunnel-manager:mcp
    container_name: tunnel-manager-mcp
    hostname: tunnel-manager-mcp
    restart: always
    env_file:
      - ../.env
    environment:
      - PYTHONUNBUFFERED=1
      - HOST=0.0.0.0
      - PORT=8000
      - TRANSPORT=streamable-http
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  tunnel-manager-agent:
    image: example/tunnel-manager@sha256:<digest>
    container_name: tunnel-manager-agent
    hostname: tunnel-manager-agent
    restart: always
    depends_on:
      - tunnel-manager-mcp
    env_file:
      - ../.env
    command: [ "tunnel-manager-agent" ]
    environment:
      - PYTHONUNBUFFERED=1
      - HOST=0.0.0.0
      - PORT=9002
      - MCP_URL=http://tunnel-manager-mcp:8000/mcp
      - PROVIDER=${PROVIDER:-openai}
      - MODEL_ID=${MODEL_ID:-gpt-4o}
      - ENABLE_WEB_UI=True
      - ENABLE_OTEL=True
    ports:
      - "9002:9002"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:9002/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Подробные объяснения архитектуры узлов графа, настройки пользовательских навыков и руководства по трассировкам агента доступны в docs/deployment.md.

Безопасность и управление

Стандартные параметры безопасности полностью поддерживаются, поскольку система построена непосредственно на корпоративном ядре agent-utilities:

Контроль доступа и применение политик

• Политики Eunomia: детальная авторизация инструментов на основе политик. Поддерживает режимы none, локальный embedded (mcp_policies.json) или централизованный remote.

• Делегирование токенов OIDC: соответствует обмену токенами RFC 8693 для передачи аутентифицирующих учётных данных пользователя от Web UI / ACP → Agent → MCP.

• Ограниченные учётные данные: контекст выполнения ограничен конкретной идентичностью вызывающего.

Сетка безопасности времени выполнения

Установка

Выберите дополнительный пакет, соответствующий тому, что вы хотите запустить:

# Connector-focused MCP server (includes the shared graph engine)
uv pip install "tunnel-manager[mcp]"

# Agent runtime (adds model orchestration to the shared graph engine)
uv pip install "tunnel-manager[agent]"

# Everything (development)
uv pip install "tunnel-manager[all]"      # or: python -m pip install "tunnel-manager[all]"

Образы контейнеров (:mcp и :agent)

Один многоступенчатый docker/Dockerfile собирает два образа подходящего размера, выбираемых с помощью --target:

docker build --target mcp   -t example/tunnel-manager:mcp    docker/   # connector-focused MCP server
docker build --target agent -t example/tunnel-manager:agent-local docker/   # agent runtime

docker/mcp.compose.yml запускает ориентированный на коннекторы сервер :mcp; docker/agent.compose.yml запускает агента (immutable agent digest) с совместно размещённым сайдкаром :mcp.

База данных графа знаний (epistemic-graph)

Оба варианта [mcp] и [agent] включают движок epistemic-graph через обязательную зависимость ядра Agent Utilities (epistemic-graph[full]). Дополнительный пакет [mcp] сохраняет сервер ориентированным на коннекторы; [agent] дополнительно включает оркестрацию моделей. Для локальных развёртываний можно использовать встроенный движок. Для продакшена или общего состояния запускайте epistemic-graph как выделенный сервис базы данных и настройте среду выполнения для его использования. Рецепты развёртывания (один узел + Raft HA), конфигурация подключения и диаграммы архитектуры описаны в руководстве по развёртыванию epistemic-graph.

Документация

Полная документация опубликована на официальном сайте документации и является рекомендуемым справочником по установке, развёртыванию и повседневной эксплуатации.

AGENTS.md — это каноническое руководство для контрибьюторов/агентов.

Сопровождающие

Поддерживается командой контрибьюторов проекта. В метаданных пакета намеренно используется ролевой адрес, а не личная идентичность.

Вклад

Вклад приветствуется! Пожалуйста, обеспечьте качество кода, выполнив локальные проверки перед отправкой pull request:

• Форматируйте код с помощью ruff format .

• Проверяйте код линтером с помощью ruff check .

• Проверяйте типовую безопасность с помощью mypy .

• Выполняйте тестовые наборы с помощью pytest

Развёртывание с помощью agent-utilities-deployment

Подготовьте этот пакет с помощью консолидированного рабочего процесса agent-utilities-deployment. Он выбирает путь установленного пакета, редактируемого исходного кода или неизменяемого контейнера; записывает в AgentConfig только ссылки на секреты времени выполнения и TLS-профили; и выполняет проверки doctor, регистрации, политики, наблюдаемости и отката. Попросите вашего агента «deploy tunnel-manager with agent-utilities-deployment».

Репозиторий не содержит профиля развертывания, значений учетных данных, путей к сертификатам или конечных точек, зависящих от окружения. Предоставьте их во время выполнения через AgentConfig и настроенный поставщик секретов.

Контракт управляемых возможностей

Этот пакет поставляется с компактной канонической поверхностью навыков, а специализированные процедуры хранятся в виде связанных рабочих процессов. Текущие инструменты MCP, метаданные навыков, connector_manifest.yml, онтология, сопоставления, формы, фикстуры, миграции, отпечатки схем инструментов и метаданные сертификации образуют единый версионируемый контракт возможностей. Проверяйте их вместе; не полагайтесь на устаревшие имена инструментов или исторические обертки навыков для отдельных задач.

Конечные точки времени выполнения, учетные данные, доверие к сертификатам, идентичность арендатора, политика хранения и наблюдаемости являются входными данными развертывания и никогда не являются упакованными значениями. См. Конфигурация, доверие и конфиденциальность перед включением сетевого транспорта, приема коннекторов, делегирования GraphOS или экспорта трассировок.