synapse-mcp 1.0.0 → 1.0.2

package/dist/types.d.ts

@@ -1,93 +1,721 @@
+/**
+ * Configuration for connecting to a Docker host in a multi-host homelab setup.
+ * Supports SSH tunneling, HTTP/HTTPS connections, and local socket connections.
+ *
+ * @example
+ * ```typescript
+ * const config: HostConfig = {
+ *   name: "homelab-main",
+ *   host: "192.168.1.100",
+ *   protocol: "ssh",
+ *   sshUser: "admin",
+ *   sshKeyPath: "/home/user/.ssh/id_rsa",
+ *   tags: ["production", "homelab"]
+ * };
+ * ```
+ */
 export interface HostConfig {
+    /** Unique identifier for this host */
     name: string;
+    /** Hostname or IP address of the Docker host */
     host: string;
+    /** Port number for the connection (defaults based on protocol) */
     port?: number;
+    /** Connection protocol (ssh is recommended for security) */
     protocol: "http" | "https" | "ssh";
+    /** SSH username for SSH protocol connections */
     sshUser?: string;
+    /** Path to SSH private key for authentication */
     sshKeyPath?: string;
+    /** Allow root SSH access (required for systems like Unraid that only support root) */
+    allowRoot?: boolean;
+    /** Path to Docker socket for direct API access */
     dockerSocketPath?: string;
+    /** Tags for filtering and organizing hosts */
     tags?: string[];
+    /** Custom paths to search for docker-compose.yml files */
+    composeSearchPaths?: string[];
 }
+/**
+ * Detailed information about a Docker container.
+ * Returned from Docker API queries and used throughout the system.
+ *
+ * @example
+ * ```typescript
+ * const container: ContainerInfo = {
+ *   id: "abc123def456",
+ *   name: "web-server",
+ *   image: "nginx:latest",
+ *   state: "running",
+ *   status: "Up 2 hours",
+ *   created: "2026-02-01T10:30:00Z",
+ *   ports: [],
+ *   labels: { "app": "nginx" },
+ *   hostName: "homelab-main"
+ * };
+ * ```
+ */
 export interface ContainerInfo {
+    /** Docker container ID (shortened hash) */
     id: string;
+    /** Container name (without leading slash) */
     name: string;
+    /** Docker image name and tag */
     image: string;
+    /** Current container lifecycle state */
     state: "running" | "paused" | "exited" | "created" | "restarting" | "removing" | "dead";
+    /** Human-readable status string (e.g., "Up 2 hours", "Exited (0) 5 minutes ago") */
     status: string;
+    /** ISO 8601 timestamp when container was created */
     created: string;
+    /** Port mappings for this container */
     ports: PortBinding[];
+    /** Container labels (key-value metadata) */
     labels: Record<string, string>;
+    /** Name of the host where this container is running */
     hostName: string;
 }
+/**
+ * Port mapping between container and host network.
+ * Represents a published port from a Docker container.
+ */
 export interface PortBinding {
+    /** Port number inside the container */
     containerPort: number;
+    /** Port number on the host machine (if published) */
     hostPort?: number;
+    /** Network protocol for this port binding */
     protocol: "tcp" | "udp";
+    /** Host IP address to bind to (defaults to 0.0.0.0 if not specified) */
     hostIp?: string;
 }
+/**
+ * Real-time resource usage statistics for a running container.
+ * Used for monitoring and alerting on container performance.
+ *
+ * @example
+ * ```typescript
+ * const stats: ContainerStats = {
+ *   containerId: "abc123",
+ *   containerName: "web-server",
+ *   cpuPercent: 15.5,
+ *   memoryUsage: 536870912,      // 512 MB
+ *   memoryLimit: 1073741824,     // 1 GB
+ *   memoryPercent: 50.0,
+ *   networkRx: 1048576,           // 1 MB
+ *   networkTx: 524288,            // 512 KB
+ *   blockRead: 2097152,           // 2 MB
+ *   blockWrite: 1048576           // 1 MB
+ * };
+ * ```
+ */
 export interface ContainerStats {
+    /** Docker container ID */
     containerId: string;
+    /** Container name */
     containerName: string;
+    /** CPU usage as a percentage (0-100+) */
     cpuPercent: number;
+    /** Current memory usage in bytes */
     memoryUsage: number;
+    /** Memory limit in bytes (container or host limit) */
     memoryLimit: number;
+    /** Memory usage as a percentage of limit (0-100) */
     memoryPercent: number;
+    /** Total bytes received over network */
     networkRx: number;
+    /** Total bytes transmitted over network */
     networkTx: number;
+    /** Total bytes read from block devices */
     blockRead: number;
+    /** Total bytes written to block devices */
     blockWrite: number;
 }
+/**
+ * Result of executing a command inside a Docker container.
+ * Contains output streams and exit status.
+ */
+export interface ContainerExecResult {
+    /** Standard output stream from the command */
+    stdout: string;
+    /** Standard error stream from the command */
+    stderr: string;
+    /** Exit code from the command (0 indicates success) */
+    exitCode: number;
+}
+/**
+ * Process list from inside a Docker container.
+ * Result of running 'ps' or equivalent process listing command.
+ */
+export interface ContainerProcessList {
+    /** Column headers for the process list (e.g., ["PID", "USER", "CMD"]) */
+    titles: string[];
+    /** Process data rows, each row matching the titles columns */
+    processes: string[][];
+}
+/**
+ * Single log entry from a Docker container.
+ * Structured format for container log messages with metadata.
+ */
 export interface LogEntry {
+    /** ISO 8601 timestamp when the log was generated */
     timestamp: string;
+    /** Output stream that produced this log entry */
     stream: "stdout" | "stderr";
+    /** Log message content */
     message: string;
 }
+/**
+ * Aggregated health information for a service/container.
+ * Used for monitoring dashboards and health check endpoints.
+ *
+ * @example
+ * ```typescript
+ * const health: ServiceHealth = {
+ *   name: "web-server",
+ *   host: "homelab-main",
+ *   containerId: "abc123",
+ *   state: "running",
+ *   uptime: "2 days",
+ *   restartCount: 0,
+ *   healthStatus: "healthy",
+ *   lastHealthCheck: "2026-02-03T10:30:00Z"
+ * };
+ * ```
+ */
 export interface ServiceHealth {
+    /** Service/container name */
     name: string;
+    /** Host where the service is running */
     host: string;
+    /** Docker container ID */
     containerId: string;
+    /** Current container state */
     state: string;
+    /** Human-readable uptime duration */
     uptime: string;
+    /** Number of times the container has restarted */
     restartCount: number;
+    /** Docker health check status (if health check is configured) */
     healthStatus?: "healthy" | "unhealthy" | "starting" | "none";
+    /** ISO 8601 timestamp of the last health check */
     lastHealthCheck?: string;
 }
 export declare enum ResponseFormat {
     JSON = "json",
     MARKDOWN = "markdown"
 }
+/**
+ * Metadata for paginated API responses.
+ * Provides information about the current page and navigation.
+ */
 export interface PaginationMeta {
+    /** Total number of items available across all pages */
     total: number;
+    /** Number of items in the current page */
     count: number;
+    /** Current offset position in the full result set */
     offset: number;
+    /** Whether more items are available after this page */
     hasMore: boolean;
+    /** Offset value to use for fetching the next page */
     nextOffset?: number;
 }
+/**
+ * Generic wrapper for paginated API responses.
+ * Contains items for the current page and pagination metadata.
+ *
+ * @typeParam T - Type of items in the paginated list
+ *
+ * @example
+ * ```typescript
+ * const response: PaginatedResponse<ContainerInfo> = {
+ *   items: [container1, container2, container3],
+ *   pagination: {
+ *     total: 50,
+ *     count: 3,
+ *     offset: 0,
+ *     hasMore: true,
+ *     nextOffset: 3
+ *   }
+ * };
+ * ```
+ */
 export interface PaginatedResponse<T> {
+    /** Array of items for the current page */
     items: T[];
+    /** Pagination metadata for navigation */
     pagination: PaginationMeta;
 }
+/**
+ * Connection status and summary for a Docker host.
+ * Used in overview dashboards and health monitoring.
+ *
+ * @example
+ * ```typescript
+ * const status: HostStatus = {
+ *   name: "homelab-main",
+ *   host: "192.168.1.100",
+ *   connected: true,
+ *   containerCount: 15,
+ *   runningCount: 12,
+ * };
+ * ```
+ */
 export interface HostStatus {
+    /** Host identifier */
     name: string;
+    /** Hostname or IP address */
     host: string;
+    /** Whether the host is currently reachable */
     connected: boolean;
+    /** Total number of containers on this host */
     containerCount: number;
+    /** Number of containers currently running */
     runningCount: number;
+    /** Error message if connection failed */
     error?: string;
 }
-export interface ComposeProject {
+export interface ComposeProjectSummary {
     name: string;
     host: string;
     services: string[];
     status: "running" | "partial" | "stopped";
     configPath?: string;
 }
+/**
+ * Information about a Docker image on a host.
+ * Includes metadata and usage information.
+ *
+ * @example
+ * ```typescript
+ * const image: ImageInfo = {
+ *   id: "sha256:abc123...",
+ *   tags: ["nginx:latest", "nginx:1.25"],
+ *   size: 142606336,  // bytes
+ *   created: "2026-01-15T08:00:00Z",
+ *   containers: 2,
+ *   hostName: "homelab-main"
+ * };
+ * ```
+ */
 export interface ImageInfo {
+    /** Docker image ID (full SHA256 hash) */
     id: string;
+    /** Image tags (repository:tag format) */
     tags: string[];
+    /** Image size in bytes */
     size: number;
+    /** ISO 8601 timestamp when image was created */
     created: string;
+    /** Number of containers using this image */
     containers: number;
+    /** Name of the host where this image exists */
     hostName: string;
 }
+/**
+ * Information about a Docker network.
+ * Represents a network configuration on a Docker host.
+ *
+ * @example
+ * ```typescript
+ * const network: DockerNetworkInfo = {
+ *   id: "abc123def456",
+ *   name: "my-network",
+ *   driver: "bridge",
+ *   scope: "local",
+ *   created: "2026-02-01T10:00:00Z",
+ *   internal: false,
+ *   attachable: true,
+ *   ingress: false,
+ *   hostName: "homelab-main"
+ * };
+ * ```
+ */
+export interface DockerNetworkInfo {
+    /** Docker network ID */
+    id: string;
+    /** Network name */
+    name: string;
+    /** Network driver type (e.g., "bridge", "overlay", "host") */
+    driver: string;
+    /** Network scope ("local", "swarm", or "global") */
+    scope: string;
+    /** ISO 8601 timestamp when network was created */
+    created?: string;
+    /** Whether the network is internal (isolated from external networks) */
+    internal?: boolean;
+    /** Whether manually-started containers can attach to this network */
+    attachable?: boolean;
+    /** Whether this is the cluster-wide ingress network */
+    ingress?: boolean;
+    /** Name of the host where this network exists */
+    hostName: string;
+}
+/**
+ * Information about a Docker volume.
+ * Represents persistent storage managed by Docker.
+ *
+ * @example
+ * ```typescript
+ * const volume: DockerVolumeInfo = {
+ *   name: "postgres-data",
+ *   driver: "local",
+ *   scope: "local",
+ *   mountpoint: "/var/lib/docker/volumes/postgres-data/_data",
+ *   createdAt: "2026-02-01T10:00:00Z",
+ *   labels: { "app": "database" },
+ *   hostName: "homelab-main"
+ * };
+ * ```
+ */
+export interface DockerVolumeInfo {
+    /** Volume name */
+    name: string;
+    /** Volume driver (e.g., "local", "nfs") */
+    driver: string;
+    /** Volume scope ("local" or "global") */
+    scope: string;
+    /** Filesystem path where the volume is mounted on the host */
+    mountpoint?: string;
+    /** ISO 8601 timestamp when volume was created */
+    createdAt?: string;
+    /** Volume labels (key-value metadata) */
+    labels?: Record<string, string>;
+    /** Name of the host where this volume exists */
+    hostName: string;
+}
+/**
+ * Docker Compose project information.
+ * Represents a complete Compose stack with its services and configuration.
+ *
+ * @example
+ * ```typescript
+ * const project: ComposeProject = {
+ *   name: "webapp",
+ *   status: "running",
+ *   configFiles: ["/home/user/webapp/docker-compose.yml"],
+ *   services: [
+ *     { name: "web", status: "running", health: "healthy" },
+ *     { name: "db", status: "running" }
+ *   ],
+ *   host: "homelab-main"
+ * };
+ * ```
+ */
+export interface ComposeProject {
+    /** Project name (derived from directory or set in compose file) */
+    name: string;
+    /** Overall status of all services in the project */
+    status: "running" | "partial" | "stopped" | "unknown";
+    /** Paths to compose configuration files used by this project */
+    configFiles: string[];
+    /** List of services defined in this project */
+    services: ComposeServiceInfo[];
+    /** Name of the host where this project is deployed */
+    host?: string;
+}
+/**
+ * Information about a single service within a Docker Compose project.
+ * Includes runtime status and port publishing information.
+ *
+ * @example
+ * ```typescript
+ * const service: ComposeServiceInfo = {
+ *   name: "web",
+ *   status: "running",
+ *   health: "healthy",
+ *   publishers: [
+ *     { publishedPort: 8080, targetPort: 80, protocol: "tcp" }
+ *   ]
+ * };
+ * ```
+ */
+export interface ComposeServiceInfo {
+    /** Service name as defined in compose file */
+    name: string;
+    /** Current service status (e.g., "running", "exited", "created") */
+    status: string;
+    /** Health check status if configured */
+    health?: string;
+    /** Exit code if the service has stopped */
+    exitCode?: number;
+    /** Published port mappings for this service */
+    publishers?: Array<{
+        /** Port number exposed on the host */
+        publishedPort: number;
+        /** Port number inside the container */
+        targetPort: number;
+        /** Network protocol ("tcp" or "udp") */
+        protocol: string;
+    }>;
+}
+/**
+ * Options for listing Docker images.
+ * Controls filtering behavior when querying images across hosts.
+ */
+export interface ListImagesOptions {
+    /** If true, only return dangling (untagged) images */
+    danglingOnly?: boolean;
+}
+/**
+ * Docker system information response.
+ * Contains version, platform, and resource summary for a Docker host.
+ *
+ * @example
+ * ```typescript
+ * const info: DockerSystemInfo = {
+ *   dockerVersion: "24.0.7",
+ *   apiVersion: "1.43",
+ *   os: "Ubuntu 22.04.3 LTS",
+ *   arch: "x86_64",
+ *   kernelVersion: "6.17.0-12-generic",
+ *   cpus: 16,
+ *   memoryBytes: 34359738368,
+ *   storageDriver: "overlay2",
+ *   rootDir: "/var/lib/docker",
+ *   containersTotal: 25,
+ *   containersRunning: 18,
+ *   containersPaused: 0,
+ *   containersStopped: 7,
+ *   images: 42
+ * };
+ * ```
+ */
+export interface DockerSystemInfo {
+    /** Docker daemon version string */
+    dockerVersion: string;
+    /** Docker API version */
+    apiVersion: string;
+    /** Operating system name and version */
+    os: string;
+    /** CPU architecture (e.g., "x86_64", "aarch64") */
+    arch: string;
+    /** Linux kernel version */
+    kernelVersion: string;
+    /** Number of CPU cores available */
+    cpus: number;
+    /** Total memory in bytes */
+    memoryBytes: number;
+    /** Storage driver in use (e.g., "overlay2", "aufs") */
+    storageDriver: string;
+    /** Docker data root directory */
+    rootDir: string;
+    /** Total number of containers (all states) */
+    containersTotal: number;
+    /** Number of containers currently running */
+    containersRunning: number;
+    /** Number of containers currently paused */
+    containersPaused: number;
+    /** Number of containers currently stopped */
+    containersStopped: number;
+    /** Total number of images stored */
+    images: number;
+}
+/**
+ * Docker disk usage response.
+ * Provides detailed breakdown of disk space used by Docker resources.
+ *
+ * @example
+ * ```typescript
+ * const usage: DockerDiskUsage = {
+ *   images: {
+ *     total: 50,
+ *     active: 25,
+ *     size: 10737418240,
+ *     reclaimable: 5368709120
+ *   },
+ *   containers: {
+ *     total: 30,
+ *     running: 20,
+ *     size: 1073741824,
+ *     reclaimable: 536870912
+ *   },
+ *   volumes: {
+ *     total: 15,
+ *     active: 10,
+ *     size: 2147483648,
+ *     reclaimable: 1073741824
+ *   },
+ *   buildCache: {
+ *     total: 100,
+ *     size: 3221225472,
+ *     reclaimable: 2147483648
+ *   },
+ *   totalSize: 17179869184,
+ *   totalReclaimable: 9126805504
+ * };
+ * ```
+ */
+export interface DockerDiskUsage {
+    /** Image storage statistics */
+    images: {
+        /** Total number of images */
+        total: number;
+        /** Number of images in use by containers */
+        active: number;
+        /** Total size of all images in bytes */
+        size: number;
+        /** Reclaimable space from unused images in bytes */
+        reclaimable: number;
+    };
+    /** Container storage statistics */
+    containers: {
+        /** Total number of containers */
+        total: number;
+        /** Number of running containers */
+        running: number;
+        /** Total size of container writable layers in bytes */
+        size: number;
+        /** Reclaimable space from stopped containers in bytes */
+        reclaimable: number;
+    };
+    /** Volume storage statistics */
+    volumes: {
+        /** Total number of volumes */
+        total: number;
+        /** Number of volumes in use by containers */
+        active: number;
+        /** Total size of all volumes in bytes */
+        size: number;
+        /** Reclaimable space from unused volumes in bytes */
+        reclaimable: number;
+    };
+    /** Build cache statistics */
+    buildCache: {
+        /** Total number of build cache entries */
+        total: number;
+        /** Total size of build cache in bytes */
+        size: number;
+        /** Reclaimable space from build cache in bytes */
+        reclaimable: number;
+    };
+    /** Total disk space used by Docker in bytes */
+    totalSize: number;
+    /** Total reclaimable disk space in bytes */
+    totalReclaimable: number;
+}
+/**
+ * Result of a Docker prune operation.
+ * Contains statistics about space reclaimed and items deleted.
+ *
+ * @example
+ * ```typescript
+ * const result: PruneResult = {
+ *   type: "images",
+ *   spaceReclaimed: 1073741824,  // 1 GB
+ *   itemsDeleted: 5,
+ *   details: ["sha256:abc123...", "sha256:def456..."]
+ * };
+ * ```
+ */
+export interface PruneResult {
+    /** Type of resource that was pruned */
+    type: string;
+    /** Amount of disk space reclaimed in bytes */
+    spaceReclaimed: number;
+    /** Number of items deleted during prune */
+    itemsDeleted: number;
+    /** Optional array of deleted item identifiers */
+    details?: string[];
+}
+/**
+ * Raw Docker container listing info from the Docker API.
+ * Project-level type to avoid leaking dockerode's Docker.ContainerInfo into public interfaces.
+ *
+ * This represents the data returned by `docker.listContainers()` and is used
+ * in container-to-host lookups and caching.
+ */
+export interface DockerRawContainerInfo {
+    /** Full container ID hash */
+    Id: string;
+    /** Container names (with leading slash, e.g., ["/my-container"]) */
+    Names: string[];
+    /** Image name used by the container */
+    Image: string;
+    /** Image ID hash */
+    ImageID: string;
+    /** Container command */
+    Command: string;
+    /** Creation timestamp (Unix epoch) */
+    Created: number;
+    /** Container state (e.g., "running", "exited") */
+    State: string;
+    /** Human-readable status string */
+    Status: string;
+    /** Port mappings */
+    Ports: Array<{
+        IP?: string;
+        PrivatePort: number;
+        PublicPort?: number;
+        Type: string;
+    }>;
+    /** Container labels */
+    Labels: Record<string, string>;
+    /** Mount points */
+    Mounts: Array<{
+        Type: string;
+        Name?: string;
+        Source: string;
+        Destination: string;
+        Driver?: string;
+        Mode: string;
+        RW: boolean;
+    }>;
+}
+/**
+ * Raw Docker container inspection info from the Docker API.
+ * Project-level type to avoid leaking dockerode's Docker.ContainerInspectInfo into public interfaces.
+ *
+ * This represents the detailed data returned by `container.inspect()` and is used
+ * in the inspect handler and formatters.
+ */
+export interface DockerRawContainerInspectInfo {
+    /** Full container ID hash */
+    Id: string;
+    /** Container name (with leading slash) */
+    Name: string;
+    /** ISO 8601 creation timestamp */
+    Created: string;
+    /** Number of times the container has been restarted */
+    RestartCount: number;
+    /** Container state information */
+    State: {
+        Status: string;
+        Running: boolean;
+        Paused: boolean;
+        Restarting: boolean;
+        OOMKilled: boolean;
+        Dead: boolean;
+        Pid: number;
+        ExitCode: number;
+        Error: string;
+        StartedAt: string;
+        FinishedAt: string;
+    };
+    /** Container configuration */
+    Config: {
+        Image: string;
+        Cmd: string[] | null;
+        WorkingDir: string;
+        Env: string[] | null;
+        Labels: Record<string, string> | null;
+    };
+    /** Network settings */
+    NetworkSettings: {
+        Ports: Record<string, Array<{
+            HostIp: string;
+            HostPort: string;
+        }> | null>;
+        Networks: Record<string, unknown>;
+    };
+    /** Mount points */
+    Mounts: Array<{
+        Type: string;
+        Source: string;
+        Destination: string;
+        Mode: string;
+        RW: boolean;
+    }>;
+}
 //# sourceMappingURL=types.d.ts.map