Tunnel Manager

CLI oder API | MCP | Agent

Version: 3.1.0

Dokumentation — Installation, Bereitstellung, Nutzung über die API, CLI und MCP sowie Agent-Schnittstellen werden in der offiziellen Dokumentation gepflegt.

Related MCP server: mcp-ssh

Überblick

Tunnel Manager ist ein produktionsreifer Agent- und Model Context Protocol (MCP)-Server, der direkt mit Create SSH Tunnels zu Ihren Remote-Hosts interagiert und als MCP-Server für Agentic AI fungiert!.

Hauptfunktionen

• Konsolidierte aktionsgesteuerte MCP-Tools: Minimiert Token-Overhead und eliminiert Tool-Aufblähung in LLM-Kontexten, indem Methoden in optimierte, umschaltbare Tool-Module gruppiert werden.

• Unternehmensgerechte Sicherheit: Umfassende Unterstützung für Eunomia-Richtlinien, OIDC-Token-Delegation und granulare Ausführungskontextverfolgung.

• Integrierter Graph-Agent: Eingebauter Pydantic-AI-Agent, der das Agent Control Protocol (ACP) und standardmäßige Web-Schnittstellen (AG-UI) unterstützt.

• Native Telemetrie & Tracing: Out-of-the-box OpenTelemetry-Exporte und natives Langfuse-Tracing.

CLI oder API

Dieser Agent kapselt die Create SSH Tunnels zu Ihren Remote-Hosts und hostet als MCP-Server für Agentic AI! API. Sie können programmatisch oder über die integrierten Ausführungs-Einstiegspunkte mit ihm interagieren.

Detaillierte Anweisungen zur Verwendung der zugrunde liegenden API-Wrapper, erweiterten Schema-Bindungen und Entwickler-SDK-Referenzen finden Sie in docs/index.md.

MCP

Dieser Server verwendet dynamische aktionsgesteuerte Tools, um den Token-Overhead zu optimieren und die IDE-Kompatibilität zu maximieren.

Verfügbare MCP-Tools

Automatisch vom Live-MCP-Server generiert — nicht von Hand bearbeiten.

Kondensierte aktionsgesteuerte Tools (MCP_TOOL_MODE=condensed)

Ausführliche 1:1-API-zugeordnete Tools (MCP_TOOL_MODE=verbose oder both)

8 aktionsgesteuerte(s) Tool(s) · 6 ausführliche 1:1-Tool(s). Jedes ist aktiviert, es sei denn, sein <DOMAIN>TOOL-Schalter ist auf false gesetzt; MCP_TOOL_MODE wählt die Oberfläche (**intent Standard* — die sechs Verb-Tools, granulare Menge bei Bedarf geladen · condensed aktionsgesteuert · verbose 1:1 · both). Automatisch generiert — nicht bearbeiten.*

Detaillierte Tool-Schemas, Parameterformen und Validierungsbeschränkungen sind in docs/usage.md erhalten.

Dynamische Tool-Auswahl und Sichtbarkeit

Dieser MCP-Server unterstützt die dynamische Auswahl des Toolsets und die Sichtbarkeitsfilterung zur Laufzeit. Dadurch können Sie die Menge der verfügbaren Tools einschränken, um eine Aufblähung des LLM-Kontextfensters zu verhindern.

Sie können die Tool-Filterung über mehrere Eingabekanäle konfigurieren:

• CLI-Argumente: Übergeben Sie --tools oder --toolsets (oder deren deaktivierte Gegenstücke --disabled-tools und --disabled-toolsets) beim Start.

• Umgebungsvariablen: Definieren Sie standardmäßige Umgebungsvariablen:

  • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS

  • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS

• HTTP-SSE-Anfrageheader: Übergeben Sie benutzerdefinierte Header während der Transportinitialisierung:

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

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

• HTTP-SSE-Anfrageabfrageparameter: Fügen Sie Abfrageparameter direkt an Ihre Transportverbindungs-URL an:

  • ?tools=tool1,tool2

  • ?tags=tag1

Wenn Abfragezeichenfolgen oder -parameter bereitgestellt werden, gleicht eine LLM-freie Knowledge-Graph-Auflösungsschicht (unter Verwendung von DynamicToolOrchestrator) Abfrageabsichten mit bekannten Tool-Tags, -Namen oder -Beschreibungen ab, mit sicherem Fallback und automatischer 24-Stunden-Hintergrund-Cache-Aktualisierung.

MCP-Konfigurationsbeispiele

Installieren Sie das verbindungsorientierte [mcp]-Extra. Beispiele verwenden tunnel-manager[mcp], um FastMCP / FastAPI über agent-utilities[mcp] hinzuzufügen; der erforderliche Agent-Utilities-Kern trägt weiterhin epistemic-graph[full]. Das [agent-runtime]-Extra aktiviert zusätzlich die Modellorchestrierung.

stdio-Transport (lokale IDEs — 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"
      }
    }
  }
}

Laufzeitreferenzen erfordern einen alias-bewussten Launcher wie GraphOS. Andere Launcher müssen diese Einträge weglassen und die aufgelösten Werte über ihre eigene Laufzeit-Geheimnisgrenze injizieren.

Streamable-HTTP-Transport (vernetzt / Produktion)

{
  "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"
      }
    }
  }
}

Alternativ können Sie eine Verbindung zu einer bereits bereitgestellten Streamable-HTTP-Instanz per url herstellen:

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

Führen Sie ein überprüftes Container-Image als stdio-Kind mit geringsten Rechten aus (kein Listener oder veröffentlichter Port):

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

Für containerisiertes Netzwerk-HTTP stellen Sie einen authentifizierten TLS-Ingress (oder direkten Server-TLS), exakte MCP_ALLOWED_HOSTS und eine exakte Trusted-Proxy-CIDR-Richtlinie über das vom Betreiber verwaltete Bereitstellungsprofil bereit. Der Generator gibt keinen nicht authentifizierten Nicht-Loopback-Listener aus.

Automatisch aus der codegelesenen Env-Oberfläche (MCP_TOOL_MODE + Paketvariablen) generiert — nicht bearbeiten.

Zusätzliche Bereitstellungsoptionen

tunnel-manager kann als lokaler stdio-Prozess oder Container oder hinter einer entfernten Netzwerkgrenze ausgeführt werden. Der Bereitstellungsleitfaden enthält den detaillierten Transportvertrag.

• Lokaler Container — starten Sie ein überprüftes unveränderliches Image als stdio-Kind mit geringsten Rechten, ohne Listener oder veröffentlichten Port.

• Remote-URL — verbinden Sie sich über einen vom Betreiber bereitgestellten authentifizierten HTTPS-Ingress. Bewahren Sie dessen URL, ausgehende Identitätsreferenzen, Vertrauensprofil und exakte MCP_ALLOWED_HOSTS in AgentConfig auf.

Inventar

tunnel-manager arbeitet mit einem einzigen gemeinsamen YAML-Inventar, das kurze Host- Aliasse (z. B. edge-node) ihren SSH-Verbindungsdetails zuordnet. Jede Ökosystemoberfläche liest dieselbe Datei — die HostManager-API, die tunnel-manager-CLI, den MCP-Server, container-manager-mcp (seine cm_*-Host-Aliasse) und die ssh-bootstrap-Fähigkeit — so definieren Sie Ihre Flotte einmal.

• Speicherort — ~/.config/agent-utilities/inventory.yml (.yml bevorzugt). Eine ältere inventory.yaml am selben Pfad wird weiterhin gelesen, wenn keine .yml vorhanden ist, sodass bestehende Installationen weiter funktionieren. Überschreiben mit TUNNEL_INVENTORY.

• Verwalten Sie es mit dem Unterbefehl 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

Das vollständige Schema, jedes Host-Feld, die Kopier-Einfüge-Vorlage und Überschreibungsoptionen finden Sie im Inventar-Leitfaden.

Umgebungsvariablen

Paket-Umgebungsvariablen

Geerbte Agent-Utilities-Variablen (gelten für jeden Connector)

44 Paket- + 14 geerbte Variable(n). Automatisch generiert aus .env.example + dem gemeinsamen Agent-Utilities-Satz — nicht bearbeiten.

Jede Variable, die der Server liest, nach Zweck gruppiert. Siehe .env.example für einen Copy-Paste-Ausgangspunkt.

SSH-Verbindung & Anmeldedaten

Inventar & Parallelität

MCP-Server / Transport

Werkzeugumschalter

Jedes aktionsgesteuerte Werkzeug kann einzeln über seine Umschalt-Umgebungsvariable deaktiviert werden (auf false setzen). Die vollständige Liste finden Sie in der Tabelle Verfügbare MCP-Werkzeuge oben (HOSTTOOL, REMOTETOOL, INVENTORYTOOL, OPERATIONSTOOL, SYSTEMTOOL, FILETOOL, SECURITYTOOL).

Telemetrie & Governance

Agent-Laufzeit (nur vollständige [agent]-Laufzeit)

Agent

Dieses Repository enthält einen vollständig integrierten Pydantic-AI-Graph-Agenten. Er kommuniziert über das Agent Control Protocol (ACP) und interagiert nahtlos mit der Agent Web UI (AG-UI) sowie der Terminal-Schnittstelle.

Agent-CLI ausführen

So starten Sie den interaktiven Agenten über die Befehlszeile:

# 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-Orchestrierung

Die folgende docker/agent.compose.yml konfiguriert den Agenten, die Weboberfläche und die Terminal-Schnittstelle gemeinsam:

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"

Detaillierte Erläuterungen zur Grapharchitektur, benutzerdefinierte Fähigkeitskonfigurationen und Anleitungen zu agentischen Abläufen finden Sie in docs/deployment.md.

Sicherheit & Governance

Direkt aufgebaut auf dem unternehmensreifen agent-utilities-Kern werden die folgenden Standard-Sicherheitsparameter vollständig unterstützt:

Zugriffskontrolle & Richtliniendurchsetzung

• Eunomia-Richtlinien: Fein granulierte, richtliniengesteuerte Werkzeugautorisierung. Unterstützt none, lokale embedded-Richtlinien (mcp_policies.json) oder zentralisierte remote-Modi.

• OIDC-Token-Delegierung: Konform mit RFC 8693-Tokenaustausch zur Übertragung von Benutzeranmeldeinformationen von Web-UI / ACP → Agent → MCP.

• Bereichsbegrenzte Anmeldeinformationen: Der Ausführungskontext ist auf die Identität des jeweiligen Aufrufers beschränkt.

Laufzeitsicherheitsraster

Installation

Wählen Sie das Extra, das zu Ihrem Einsatzszenario passt:

# 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]"

Container-Images (:mcp vs. :agent)

Ein mehrstufiges docker/Dockerfile erstellt zwei passend dimensionierte Images, ausgewählt über --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 betreibt den verbindungsorientierten :mcp-Server; docker/agent.compose.yml betreibt den Agenten (unveränderlicher Agent-Digest) mit einem gemeinsam platzierten :mcp-Sidecar.

Wissensgraph-Datenbank (epistemic-graph)

Sowohl [mcp] als auch [agent] enthalten die epistemic-graph-Engine über die erforderliche Agent-Utilities-Kernabhängigkeit (epistemic-graph[full]). Das [mcp]-Extra hält den Server verbindungsorientiert; [agent] aktiviert zusätzlich die Modellorchestrierung. Lokale Bereitstellungen können die gebündelte Engine verwenden. Für Produktionsumgebungen oder gemeinsamen Zustand betreiben Sie epistemic-graph als dedizierten Datenbankdienst und konfigurieren die Laufzeit entsprechend. Bereitstellungsrezepte (Einzelknoten + Raft-HA), Verbindungskonfiguration und Architekturdiagramme sind im epistemic-graph-Bereitstellungshandbuch dokumentiert.

Dokumentation

Die vollständige Dokumentation ist als offizielle Dokumentationsseite veröffentlicht und dient als empfohlene Referenz für Installation, Bereitstellung und den täglichen Betrieb.

AGENTS.md ist die maßgebliche Anleitung für Mitwirkende und Agenten.

Betreuer

Gepflegt vom Projekt-Mitwirkendenteam. Die Paketmetadaten verwenden bewusst eine Rollenadresse anstelle einer persönlichen Identität.

Mitwirken

Beiträge sind willkommen! Bitte stellen Sie die Codequalität sicher, indem Sie vor dem Einreichen von Pull Requests lokale Prüfungen ausführen:

• Formatieren Sie den Code mit ruff format .

• Linten Sie den Code mit ruff check .

• Validieren Sie die Typsicherheit mit mypy .

• Führen Sie die Testsuite mit pytest aus

Bereitstellung mit agent-utilities-deployment

Stellen Sie dieses Paket mit dem konsolidierten agent-utilities-deployment-Workflow bereit. Er wählt einen Pfad für installierte Pakete, bearbeitbare Quellen oder unveränderliche Container; zeichnet nur Laufzeit-Geheimnis- und TLS-Profil-Referenzen in AgentConfig auf; und führt Arzt-, Registrierungs-, Richtlinien-, Beobachtbarkeits- und Rollback-Gates aus. Bitten Sie Ihren Agenten, "deploy tunnel-manager with agent-utilities-deployment" auszuführen.

Das Repository enthält kein Bereitstellungsprofil, keinen Anmeldedatenwert, keinen Zertifikatspfad und keinen umgebungsspezifischen Endpunkt. Stellen Sie diese zur Laufzeit über AgentConfig und den konfigurierten Geheimnisanbieter bereit.

Vertrag über die verwaltete Fähigkeit

Dieses Paket bietet eine kompakte kanonische Skill-Oberfläche mit spezialisierten Verfahren, die als referenzierte Workflows geführt werden. Die aktuellen MCP-Tools, Skill-Metadaten, connector_manifest.yml, Ontologie, Zuordnungen, Formen, Fixtures, Migrationen, Tool-Schema-Fingerabdrücke und Zertifizierungsmetadaten bilden einen versionierten Fähigkeitsvertrag. Validieren Sie sie gemeinsam; verlassen Sie sich nicht auf veraltete Tool-Namen oder historische aufgabenspezifische Skill-Wrapper.

Laufzeit-Endpunkte, Anmeldedaten, Zertifikatsvertrauen, Mandantenidentität, Aufbewahrung und Beobachtbarkeitsrichtlinie sind Bereitstellungseingaben und niemals verpackte Werte. Siehe Konfiguration, Vertrauen und Datenschutz, bevor Sie einen Netzwerktransport, Connector-Ingestion, GraphOS-Delegation oder Trace-Export aktivieren.