Architecture

Technical architecture documentation for Terry-Form MCP

Architecture Documentation

Explore the technical architecture of Terry form mcp.

graph TB
    subgraph External
        A[AI Assistants]
        C[CI/CD Systems]
    end

    subgraph "Terry-Form MCP"
        D[FastMCP Server]
        E[Security Layer]
        F[Execution Engine]
        G[Integration Layer]
    end

    subgraph Infrastructure
        H[Cloud Providers]
        I[Terraform State]
        J[Git Repositories]
    end

    A -->|MCP stdio| D
    C -->|MCP stdio| D
    D --> E
    E --> F
    E --> G
    F --> H
    F --> I
    G --> J

Architecture Documents

Architecture Overview

High-level architecture of Terry-Form MCP

Key Architectural Principles

Security First

Every component is designed with security as the primary concern. Defense in depth with multiple validation layers, path traversal protection, command injection prevention, and action whitelisting. Destructive operations (apply, destroy) are permanently blocked.

Modular Design

Components are loosely coupled with clear responsibilities. The core Terraform executor, LSP client, GitHub handler, and security validator are independent modules registered through a single FastMCP entry point.

Async Throughout

The server uses asyncio with FastMCP. All 25 tool handlers are async, enabling non-blocking I/O for Terraform subprocess execution, LSP communication, and external API calls.

Component Overview

Protocol Layer

Handles MCP stdio communication between AI assistants and the server

  • MCP stdio transport
  • Tool registration via @mcp.tool()
  • Request/response formatting

Security Layer

Enforces security policies across all operations

  • Input validation and sanitization
  • Path traversal protection
  • Rate limiting (20/30/100 req/min)

Execution Engine

Manages Terraform operations safely within Docker

  • Terraform subprocess execution
  • Workspace isolation at /mnt/workspace
  • Command whitelisting (init, validate, fmt, plan only)

Integration Layer

Connects to external services

  • GitHub API and App authentication
  • Terraform Cloud workspaces and runs
  • terraform-ls for LSP intelligence

Deployment Architecture

Single Instance

Run as a Docker container connected to AI assistants via MCP stdio.

graph LR
    A[AI Assistant] -->|MCP stdio| B[Docker Container]
    B --> C["/mnt/workspace"]

Technology Stack

Layer Technology Purpose
Runtime Python 3.10+ Core application
Protocol FastMCP 3.0+ MCP server implementation
IaC Terraform 1.12 Infrastructure management
LSP terraform-ls 0.38.5 Code intelligence
Container Docker (hashicorp/terraform:1.12) Packaging and isolation

Next Steps