Tunnel Manager

CLI 또는 API | MCP | 에이전트

버전: 3.1.0

문서 — API, CLI, MCP 및 에이전트 인터페이스에서의 설치, 배포, 사용법에 대한 내용은 공식 문서에서 관리됩니다.

Related MCP server: mcp-ssh

개요

Tunnel Manager는 원격 호스트에 SSH 터널을 생성하고 에이전틱 AI 위한 MCP 서버로 호스팅하도록 설계된 프로덕션 등급의 에이전트 및 MCP(Model Context Protocol) 서버입니다.

핵심 기능

• 통합된 액션 라우팅 MCP 도구: 메서드를 최적화된 토글형 도구 모듈로 그룹화하여 LLM 컨텍스트에서 토큰 오버헤드를 최소화하고 도구 비대화를 제거합니다.

• 엔터프라이즈급 보안: Eunomia 정책, OIDC 토큰 위임, 세분화된 실행 컨텍스트 추적에 대한 포괄적인 지원을 제공합니다.

• 통합 그래프 에이전트: Agent Control Protocol(ACP) 및 표준 웹 인터페이스(AG-UI)를 지원하는 Pydantic AI 에이전트가 내장되어 있습니다.

• 네이티브 텔레메트리 및 추적: 별도 설정 없이 사용할 수 있는 OpenTelemetry 내보내기와 네이티브 Langfuse 추적을 제공합니다.

CLI 또는 API

이 에이전트는 원격 호스트에 SSH 터널을 생성하고 이를 에이전틱 AI용 MCP 서버로 호스팅하는 API를 래핑합니다. 프로그래밍 방식 또는 통합된 실행 진입점으로 상호 작용할 수 있습니다.

기본 API 래퍼 사용 방법, 확장 스키마 바인딩, 개발자 SDK 참조에 대한 자세한 지침은 docs/index.md에 있습니다.

MCP

이 MCP 서버는 동적 액션 라우팅 도구를 활용하여 토큰 오버헤드를 최적화하고 IDE 호환성을 극대화합니다.

사용 가능한 MCP 도구

실행 중인 MCP 서버에서 자동 생성되었습니다 — 직접 편집하지 마세요.

축약형 액션 라우팅 도구 (MCP_TOOL_MODE=condensed)

상세 1:1 API 매핑 도구 (MCP_TOOL_MODE=verbose 또는 both)

액션 라우팅 도구 8개 · 상세 1:1 도구 6개. 각 도구는 자신의 <DOMAIN>TOOL 토글이 false로 설정되지 않는 한 활성화되며, MCP_TOOL_MODE가 표면을 선택합니다 (**intent 기본값* — 동사형 도구 6개, 세분화된 도구 세트는 온디맨드로 · 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] 엑스트라를 설치하세요. 예제는 agent-utilities[mcp]를 통해 tunnel-manager[mcp]로 FastMCP/FastAPI를 추가하는 방식을 사용합니다. 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"
      }
    }
  }
}

또는 url을 지정하여 이미 배포된 Streamable-HTTP 인스턴스에 연결합니다:

{
  "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 정책을 제공하세요. 생성자는 인증되지 않은 비루프백 리스너를 생성하지 않습니다.

코드 내에서 읽혀진 환경 표면(MCP_TOOL_MODE + 패키지 변수)에서 자동 생성됩니다 — 직접 편집하지 마세요.

추가 배포 옵션

tunnel-manager는 로컬 stdio 프로세스나 컨테이너로 실행되거나 원격 네트워크 경계 뒤에서 실행할 수 있습니다. 배포 가이드에 자세한 전송 지침이 있습니다.

• 로컬 컨테이너 — 리뷰된 불변 이미지를 리스너나 공개 포트가 없는 최소 권한 stdio 하위 프로세스로 실행합니다.

• 원격 URL — 운영자가 제공한 인증된 HTTPS 인그레스를 통해 연결합니다. URL, 아웃바운드 이름 참조, 신뢰 프로필, 정확한 MCP_ALLOWED_HOSTS를 AgentConfig에 유지합니다.

인벤토리

tunnel-manager는 짧은 호스트 별칭(예: edge-node)을 SSH 연결 세부 정보에 연결하는 하나의 단일 읽기 공용 YAML 인벤토리를 기반으로 실행됩니다. 모든 생태계 화면(HostManager API, tunnel-manager CLI, MCP 서버, container-manager-mcp의 cm_* 호스트 별칭, 그리고 ssh-bootstrap 스킬)은 동일한 파일을 읽으므로, 박스는 클러스터를 한 번만 정의하면 됩니다.

• 위치 — ~/.config/agent-utilities/inventory.yml(.yml 선호). .yml이 없으면 같은 경로의 레거시 inventory.yaml도 계속 읽어 기존 설치를 유지합니다. 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 그래프 에이전트를 제공합니다. 에이전트 제어 프로토콜(ACP) 및 에이전트 웹 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은 에이전트, 웹 UI 및 터미널 인터페이스를 함께 구성합니다:

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을 준수하는 토큰 교환으로 웹 UI / ACP → 에이전트 → MCP로 인증 사용자 자격 증명을 전달합니다.

• 범위 지정 자격 증명: 실행 컨텍스트는 특정 호출자 ID로 제한됩니다.

런타임 보안 그리드

설치

실행하려는 항목에 맞는 엑스트라를 선택하세요:

# 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 vs :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은 공동 배치된 :mcp 사이드카와 함께 에이전트(immutable agent digest)를 실행합니다.

지식 그래프 데이터베이스 (epistemic-graph)

[mcp]와 [agent] 모두 필수 Agent Utilities 코어 종속성(epistemic-graph[full])을 통해 epistemic-graph 엔진을 포함합니다. [mcp] 엑스트라는 서버를 커넥터 중심으로 유지하고, [agent]는 모델 오케스트레이션을 추가로 활성화합니다. 로컬 배포는 번들 엔진을 사용할 수 있습니다. 프로덕션 또는 공유 상태의 경우 epistemic-graph를 전용 데이터베이스 서비스로 실행하고 런타임이 이를 사용하도록 구성하세요. 배포 레시피(단일 노드 + Raft HA), 연결 구성 및 아키텍처 다이어그램은 epistemic-graph 배포 가이드에 문서화되어 있습니다.

문서

전체 문서는 공식 문서 사이트로 게시되며 설치, 배포 및 일상적인 운영에 대한 권장 참조 자료입니다.

AGENTS.md는 표준 기여자/에이전트 지침입니다.

유지관리자

프로젝트 기여자 팀이 유지관리합니다. 패키지 메타데이터는 개인 식별 정보 대신 역할 주소를 의도적으로 사용합니다.

기여

기여를 환영합니다! 풀 리퀘스트를 제출하기 전에 로컬 검사를 실행하여 코드 품질을 확인해 주세요:

• ruff format .를 사용하여 코드 서식 지정

• ruff check .를 사용하여 코드 린트

• mypy .를 사용하여 타입 안전성 검증

• pytest를 사용하여 테스트 스위트 실행

agent-utilities-deployment로 배포

이 패키지를 통합된 agent-utilities-deployment 워크플로로 프로비저닝하세요. 설치된 패키지, 편집 가능한 소스, 또는 불변 컨테이너 경로를 선택하고, AgentConfig에 런타임 비밀 및 TLS 프로필 참조만 기록하며, doctor, 등록, 정책, 관찰 가능성, 롤백 게이트를 실행합니다. 에이전트에게 **"agent-utilities-deployment로 tunnel-manager 배포"**를 요청하세요.

저장소에는 배포 프로필, 자격 증명 값, 인증서 경로, 또는 환경별 엔드포인트가 포함되어 있지 않습니다. 런타임에 AgentConfig와 구성된 비밀 공급자를 통해 이를 제공하세요.

관리되는 기능 계약

이 패키지는 참조 워크플로로 유지되는 전문 절차와 함께 간결한 표준 스킬 표면을 제공합니다. 현재 MCP 도구, 스킬 메타데이터, connector_manifest.yml, 온톨로지, 매핑, 셰이프, 픽스처, 마이그레이션, 도구 스키마 지문, 인증 메타데이터는 하나의 버전 관리되는 기능 계약을 구성합니다. 이들을 함께 검증하고, 오래된 도구 이름이나 과거의 작업별 스킬 래퍼에 의존하지 마세요.

런타임 엔드포인트, 자격 증명, 인증서 신뢰, 테넌트 ID, 보존, 관찰 가능성 정책은 배포 입력이며 패키징된 값이 아닙니다. 네트워크 전송, 커넥터 수집, GraphOS 위임, 또는 트레이스 내보내기를 활성화하기 전에 구성, 신뢰 및 개인정보 보호를 참조하세요.