Architecture Overview

Terry-Form MCP is designed with security, modularity, and async execution at its core. This document provides a comprehensive overview of the system architecture.

System Architecture

graph TB
    subgraph "Client Layer"
        A[AI Assistant<br/>Claude]
        D[CI/CD Systems]
    end

    subgraph "Terry-Form MCP Core"
        E[FastMCP Server]
        G[Security Layer]

        subgraph "Execution Engine"
            I[Terraform Executor]
            J[Command Validator]
        end

        subgraph "Integration Layer"
            L[GitHub Handler]
            N[TF Cloud Client]
        end

        subgraph "Intelligence Layer"
            O[Analyzer]
            P[Security Scanner]
        end
    end

    subgraph "External Services"
        R[GitHub Repositories]
        S[Terraform Cloud]
        T[Cloud Providers]
    end

    A -->|MCP stdio| E
    D -->|MCP stdio| E

    E --> G

    G --> I
    G --> L
    G --> O

    I --> J
    J --> I

    L --> R
    N --> S
    I --> T

    O --> P

    style G fill:#ff9999
    style J fill:#ff9999

Core Components

1. Protocol Layer

The protocol layer handles MCP stdio communication between AI assistants and the Terry-Form server. All 25 tools are registered via @mcp.tool() decorators on the FastMCP server.

sequenceDiagram
    participant Client as AI Assistant
    participant MCP as FastMCP Server
    participant Security as Security Layer
    participant Executor as Terraform Executor

    Client->>MCP: MCP Tool Request (stdio)
    MCP->>Security: Validate Request
    Security->>Security: Check Permissions
    Security->>Security: Sanitize Input
    Security-->>MCP: Validated Request
    MCP->>Executor: Execute Command
    Executor->>Executor: Run Terraform
    Executor-->>MCP: Result
    MCP-->>Client: MCP Response (stdio)

2. Security Architecture

Security is implemented in multiple layers, enforced by mcp_request_validator.py:

graph LR
    subgraph "Security Layers"
        A[Input Validation]
        B[Path Traversal Protection]
        C[Command Injection Prevention]
        D[Action Whitelisting]
        E[Workspace Isolation]
        F[Rate Limiting]
    end

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F

Key Security Features:

3. Execution Engine

The execution engine manages Terraform operations safely:

stateDiagram-v2
    [*] --> Idle
    Idle --> Validating: Receive Request
    Validating --> Preparing: Valid Request
    Validating --> Error: Invalid Request
    Preparing --> Executing: Setup Complete
    Executing --> Processing: Command Running
    Processing --> Success: Command Success
    Processing --> Failed: Command Failed
    Success --> Idle: Return Result
    Failed --> Idle: Return Error
    Error --> Idle: Return Error

Forced Environment Variables:

All Terraform subprocess calls include these environment variables to ensure safe automated execution:

4. Data Flow

graph TD
    subgraph "Request Flow"
        A[MCP Tool Request] --> B{Request Type}
        B -->|Terraform Op| C[Terraform Handler]
        B -->|GitHub Op| D[GitHub Handler]
        B -->|TF Cloud Op| E[Cloud Handler]
        B -->|LSP Op| X[LSP Client]

        C --> F[Validation]
        D --> F
        E --> F
        X --> F

        F --> G{Valid?}
        G -->|Yes| H[Execute]
        G -->|No| I[Reject]

        H --> J[Process Result]
        J --> K[Format Response]
        K --> L[Return to Client]
        I --> L
    end

Deployment Architecture

Docker Deployment

The container is built on hashicorp/terraform:1.12 (Alpine-based) and runs as non-root user terraform (UID 1001). Communication uses MCP stdio – there are no exposed ports.

graph TB
    subgraph "Docker Container"
        A[FastMCP Server]
        B[Python 3.10+]
        C[Terraform 1.12]
        D[terraform-ls 0.38.5]
        E[Git Client]
    end

    subgraph "Volume Mounts"
        F["/mnt/workspace"]
    end

    A --> F

Running the container:

docker run -i --rm \
  -v "$(pwd):/mnt/workspace" \
  terry-form-mcp:latest

The -i flag enables stdin for MCP stdio communication. The workspace volume mount at /mnt/workspace provides access to Terraform configuration files.

Integration Architecture

GitHub App Integration

sequenceDiagram
    participant User as AI Assistant
    participant TerryForm as Terry-Form
    participant GitHub
    participant Workspace as /mnt/workspace

    User->>TerryForm: Clone Repository
    TerryForm->>GitHub: Authenticate (JWT)
    GitHub-->>TerryForm: Installation Token
    TerryForm->>GitHub: Clone Repo
    GitHub-->>TerryForm: Repository Data
    TerryForm->>Workspace: Store Terraform Files
    TerryForm-->>User: Success

Terraform Cloud Integration

Terry-Form MCP includes 4 Terraform Cloud tools for managing workspaces and runs through the TFC API.

LSP Intelligence

The terraform-ls integration provides 5 tools for code intelligence:

The LSP client wraps terraform-ls 0.38.5 as an async subprocess. The first call may take 1-2 seconds for LSP initialization.

Tool Categories

Terry-Form MCP exposes 25 tools organized into categories:

Category Count Description
Core Terraform 4 init, validate, fmt, plan
LSP Intelligence 5 Hover, completions, diagnostics, formatting, symbols
Diagnostics 6 LSP diagnostics, file analysis, workspace inspection
Security 2 Security scanning, best practice recommendations
GitHub 4 Repository cloning, file extraction
Terraform Cloud 4 Workspace and run management

Next Steps