Skip to content

architecture.md

Latest commit

 

History

History
89 lines (67 loc) · 4.44 KB

architecture.md

File metadata and controls

89 lines (67 loc) · 4.44 KB

System Architecture: Troubleshoot MCP Server

Overview

The Troubleshoot MCP Server is a Model Context Protocol (MCP) server that enables AI agents to interact with Kubernetes support bundles generated by the Troubleshoot tool. It provides a bridge between AI models and the data contained in support bundles, allowing exploration of cluster state and logs without requiring the entire bundle to be loaded into context.

Components

MCP Protocol Handler (server.py)

Handles communication between AI models and the server using the FastMCP implementation of the Model Context Protocol standard. Responsible for processing requests, executing the appropriate functions, and formatting responses. Each tool is implemented as a separate async function decorated with @mcp.tool().

Bundle Manager (bundle.py)

Manages the lifecycle of support bundles, including downloading, extraction, and initialization using sbctl. It creates and maintains the Kubernetes API server emulation, handles process management, and provides diagnostics when the API server has issues.

Command Executor (kubectl.py)

Executes kubectl commands against the initialized support bundle's API server and processes the results for consumption by AI models. Handles validation, execution, and formatting of kubectl command output.

File Explorer (files.py)

Provides file system operations for exploring and examining the contents of support bundles, including listing directories, reading files, and searching through files. Includes security checks to prevent directory traversal and access to files outside the bundle.

Container Runtime (Dockerfile)

Packages the server and its dependencies in a Docker container for consistent deployment and execution across environments.

Data Flow

  1. Initialization Flow:

    • AI model requests bundle initialization with source location via initialize_bundle tool
    • Bundle Manager validates sbctl availability
    • Bundle Manager downloads or locates the bundle
    • Bundle Manager uses sbctl to extract and initialize the bundle
    • Bundle Manager sets up the Kubernetes API server
    • Bundle Manager verifies API server availability and gathers diagnostic info
    • MCP Protocol Handler returns initialization status and diagnostics if needed

  2. Command Execution Flow:

    • AI model sends kubectl command request via kubectl tool
    • MCP Protocol Handler validates request
    • Command Executor checks API server availability
    • Command Executor runs the command against the API server
    • Command Executor formats the output (JSON or text)
    • MCP Protocol Handler returns the results with command metadata

  3. File Operation Flow:

    • AI model requests file operation via list_files, read_file, or grep_files tools
    • MCP Protocol Handler validates request
    • File Explorer checks bundle initialization and path validity
    • File Explorer performs the operation (list, read, or search)
    • File Explorer formats the results with appropriate metadata
    • MCP Protocol Handler returns the formatted results

Error Handling

The system implements robust error handling across all components:

  1. Bundle Manager Errors:

    • Authentication failures with sbctl token
    • Bundle extraction issues
    • API server availability issues with diagnostics
    • Process management failures

  2. Command Executor Errors:

    • Invalid or unsupported kubectl commands
    • API server connectivity issues
    • Command execution failures with detailed error messages

  3. File Explorer Errors:

    • Path validation errors (directory traversal attempts)
    • File not found or path not accessible
    • Binary file handling with appropriate content display

Deployment Model

The system is deployed as a containerized application using Docker. The container exposes an interface for MCP communication (stdin/stdout) and mounts volumes for persistent storage of support bundles.

Key environment variables:

  • SBCTL_TOKEN: Authentication token for accessing bundles
  • MCP_BUNDLE_STORAGE: Directory to use for bundle storage
  • MCP_LOG_LEVEL: Logging verbosity control

Technologies

  • Python 3.11+: Primary implementation language
  • FastMCP: For implementing the Model Context Protocol
  • sbctl: For managing and serving support bundles
  • kubectl: For interacting with the Kubernetes API server
  • Docker: For containerization
  • uv: For Python package management
  • pytest: For testing
  • black/ruff: For code formatting and linting