tunnel-manager AGENTS.md

AGENTS.md

Claude Code loads this file via CLAUDE.md (@AGENTS.md import) — the two stay in sync. Edit this file, not CLAUDE.md.

Tech Stack & Architecture

• Language/Version: Python 3.10+
• Core Libraries: agent-utilities, fastmcp, paramiko, pydantic-ai
• Key principles: Functional patterns, Pydantic for data validation, asynchronous tool execution.
• Architecture:
  • mcp_server.py: Main MCP server entry point and tool registration for SSH tunnel operations.
  • agent_server.py: Pydantic AI agent definition and logic for tunnel management.
  • tunnel_manager.py: Core SSH tunnel functionality including HostManager and Tunnel classes.
  • operation_manager.py: Enhanced operation tracking with streaming progress and cancellation.
  • system_intelligence.py: Remote system discovery and intelligence gathering.
  • advanced_file_manager.py: Advanced file operations including recursive ops, search, monitoring, and backup.
  • security_auditor.py: Security and compliance auditing capabilities.
  • tests/: Comprehensive test suite for tunnel management and MCP server functionality.

Architecture Diagram

graph TD
    User([User/A2A]) --> Server[A2A Server / FastAPI]
    Server --> Agent[Pydantic AI Agent]
    Agent --> MCP[MCP Server / FastMCP]
    MCP --> Tunnel[Tunnel Manager]
    Tunnel --> SSH[SSH Connections]
    SSH --> RemoteHosts[Remote Hosts]
    MCP --> HostManager[Host Manager]
    HostManager --> Inventory[Inventory Files]
    MCP --> OperationManager[Operation Manager]
    MCP --> SystemIntelligence[System Intelligence]
    MCP --> AdvancedFileManager[Advanced File Manager]
    MCP --> SecurityAuditor[Security Auditor]
    OperationManager --> Tunnel
    SystemIntelligence --> Tunnel
    AdvancedFileManager --> Tunnel
    SecurityAuditor --> Tunnel

Workflow Diagram

sequenceDiagram
    participant U as User
    participant S as Server
    participant A as Agent
    participant T as MCP Tool
    participant TM as Tunnel Manager
    participant SSH as SSH Connection
    participant RH as Remote Host

    U->>S: Request
    S->>A: Process Query
    A->>T: Invoke Tool
    T->>TM: Execute Operation
    TM->>SSH: Connect
    SSH->>RH: Execute Command/Transfer
    RH-->>SSH: Result
    SSH-->>TM: Output
    TM-->>T: Result
    T-->>A: Tool Result
    A-->>S: Final Response
    S-->>U: Output