Tunnel Manager

CLI または API | MCP | エージェント

バージョン: 3.1.0

ドキュメント — API、CLI、MCP、そしてエージェントインターフェースにわたるインストール、デプロイ、使用法は、 公式ドキュメント に管理されています。

Related MCP server: mcp-ssh

概要

Tunnel Manager は、リモートホストへのSSHトンネルを作成し、Agentic AI向けのMCPサーバーとしてホストするために直接インターフェースする、本番グレードのエージェントおよび Model Context Protocol (MCP) サーバーです。

主要な機能

• 統合されたアクションルーティングMCPツール: メソッドを最適化されたトグル可能なツールモジュールにグループ化することで、LLMコンテキストにおけるトークンオーバーヘッドを最小化し、ツールの肥大化を排除します。

• エンタープライズグレードのセキュリティ: Eunomiaポリシー、OIDCトークン委任、および詳細な実行コンテキスト追跡を包括的にサポートします。

• 統合グラフエージェント: Agent Control Protocol (ACP) と標準Webインターフェース (AG-UI) をサポートする組み込みのPydantic AIエージェント。

• ネイティブテレメトリとトレーシング: すぐに使えるOpenTelemetryエクスポートとネイティブのLangfuseトレーシング。

CLI または API

このエージェントは、リモートホストへのSSHトンネルを作成し、Agentic AI向けのMCPサーバーとしてホストするAPIをラップしています。プログラム的にも、統合された実行エントリポイントを介しても操作できます。

基盤となる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 デフォルト* — 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] エクストラをインストールします。 例では tunnel-manager[mcp] を使用して、 agent-utilities[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、送信ID参照、信頼プロファイル、正確な 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 推奨)。同じパスにある従来の 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

完全なスキーマ、すべてのホストフィールド、コピーペーストテンプレート、上書きオプションは、 インベントリガイド にあります。

環境変数

パッケージ環境変数

継承されたエージェントユーティリティ変数（すべてのコネクタに適用）

パッケージ44個 + 継承変数14個。.env.example + 共有エージェントユーティリティセットから自動生成 — 編集しないでください。

サーバーが読み取るすべての変数を目的別にグループ化しています。コピー＆ペースト用の出発点として .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) およびターミナルインターフェースとシームレスに連携します。

Agent 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、ターミナルインターフェースをまとめて設定します：

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トークンデリゲーション： Web UI / ACP → Agent → MCP の認証ユーザー資格情報のフローに対応したRFC 8693トークン交換に準拠。

• スコープ付き資格情報： 実行コンテキストは特定の呼び出し元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）

1つのマルチステージdocker/Dockerfileが、--targetで選択される2つの適切なサイズのイメージをビルドします：

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は正規のコントリビューター/エージェントガイダンスです。

メンテナー

プロジェクトのコントリビューターチームによって保守されています。パッケージメタデータは、個人のIDではなく意図的にロールアドレスを使用しています。

コントリビュート

コントリビューションを歓迎します！プルリクエストを送信する前に、ローカルチェックを実行してコード品質を確保してください：

• ruff format .でコードをフォーマット

• ruff check .でコードをリント

• mypy .で型安全性を検証

• pytestでテストスイートを実行

agent-utilities-deploymentでデプロイ

このパッケージを統合された agent-utilities-deployment ワークフローでプロビジョニングしてください。インストール済みパッケージ、編集可能ソース、またはイミュータブルコンテナのパスを選択し、AgentConfig にはランタイムのシークレットと TLS プロファイルの参照のみを記録し、doctor、登録、ポリシー、可観測性、ロールバックのゲートを実行します。エージェントに 「tunnel-manager を agent-utilities-deployment でデプロイ」 と依頼してください。

リポジトリには、デプロイプロファイル、認証情報の値、証明書パス、環境固有のエンドポイントは埋め込まれていません。これらは実行時に AgentConfig と設定済みのシークレットプロバイダーを通じて提供してください。

管理対象ケイパビリティ契約

このパッケージは、専門手順を参照ワークフローとして保持した、コンパクトな標準スキルサーフェスを提供します。現在の MCP ツール、スキルメタデータ、connector_manifest.yml、オントロジー、マッピング、シェイプ、フィクスチャ、マイグレーション、ツールスキーマのフィンガープリント、および認証メタデータは、1 つのバージョン管理されたケイパビリティ契約を構成します。これらをまとめて検証してください。古いツール名や過去のタスク別スキルラッパーに依存しないでください。

ランタイムのエンドポイント、認証情報、証明書の信頼、テナント ID、保持、および可観測性ポリシーはデプロイ時の入力であり、パッケージ化された値になることはありません。ネットワークトランスポート、コネクタの取り込み、GraphOS 委任、またはトレースエクスポートを有効にする前に、構成、信頼、およびプライバシー を参照してください。