Terry-Form MCP with LSP Integration

Documentation Site:

https://aj-geddes.github.io/terry-form-mcp

Version 3.0.0 - Production-ready Terraform automation with comprehensive LSP integration and 25 MCP tools

A Model Control Protocol (MCP) server that enables AI assistants to execute Terraform commands locally through a secure, containerized environment using HashiCorp's official Terraform image. Now enhanced with Language Server Protocol (LSP) integration for intelligent Terraform development capabilities.

What is Terry-Form?

Terry-Form MCP is a bridge between AI language models and Terraform infrastructure management. It provides a safe, controlled way for AI assistants like Claude to:

Execute Terraform commands (init, validate, fmt, plan)
Provide intelligent code completion, documentation, and validation using LSP
Run operations in isolated Docker containers
Work with Terraform configurations in your local workspace
Pass variables dynamically to Terraform operations
Return structured JSON results for AI processing

Architecture

Component Architecture

flowchart LR
    %% Define nodes with improved styling
    Claude["AI Assistant\n(Claude)"]:::claude
    MCP["Terry-Form MCP\nServer"]:::server
    Container["Terraform Docker\nContainer"]:::container
    TF["Terraform CLI"]:::terraform
    TFLS["Terraform-LS\nLanguage Server"]:::lsp
    LocalTF[("Local Terraform\nConfigurations")]:::files
    
    %% Define connections
    Claude <---> MCP
    MCP <---> Container
    Container --> TF
    Container --> TFLS
    TF --- LocalTF
    TFLS --- LocalTF
    
    %% Define styles
    classDef claude fill:#9C27B0,stroke:#6A1B9A,color:#FFFFFF,stroke-width:2px
    classDef server fill:#2196F3,stroke:#0D47A1,color:#FFFFFF,stroke-width:2px
    classDef container fill:#F5F5F5,stroke:#333333,stroke-width:2px
    classDef terraform fill:#844FBA,stroke:#4C2889,color:#FFFFFF,stroke-width:2px
    classDef lsp fill:#4CAF50,stroke:#2E7D32,color:#FFFFFF,stroke-width:2px
    classDef files fill:#FFE0B2,stroke:#FB8C00,stroke-width:2px

    %% Add a title
    subgraph Terry-Form Component Architecture
    end

Data Flow and Security Architecture

flowchart LR
    %% Main components
    Claude["AI Assistant\n(Claude)"]:::claude
    
    %% Docker container with components
    subgraph Container["Docker Container"]
        MCP["Terry-Form MCP Server"]:::mcp
        TF["Terraform Engine"]:::terraform
        
        %% Operations subgraph
        subgraph Operations["Operations"]
            direction TB
            
            %% Allowed operations
            subgraph Allowed["✅ Allowed"]
                Init("init"):::safe
                Validate("validate"):::safe
                Format("fmt"):::safe
                Plan("plan"):::safe
                LSP("LSP"):::safe
            end
            
            %% Blocked operations
            subgraph Blocked["❌ Blocked"]
                Apply("apply"):::blocked
                Destroy("destroy"):::blocked
            end
        end
    end
    
    %% External components
    Files[("Local Files\n(/mnt/workspace)")]:::files
    External["Remote Services\n(State/Cloud APIs)"]:::external
    
    %% Connections
    Claude <--> MCP
    MCP --> TF
    TF --> Operations
    Files <--> Container
    Blocked -.- |"NO ACCESS"| External
    
    %% Styling
    classDef claude fill:#9C27B0,color:#FFFFFF,stroke-width:2px,font-weight:bold
    classDef mcp fill:#2196F3,color:#FFFFFF,stroke-width:2px,font-weight:bold
    classDef terraform fill:#844FBA,color:#FFFFFF,stroke-width:2px,font-weight:bold
    classDef files fill:#FF9800,color:#000000,stroke-width:2px,font-weight:bold
    classDef safe fill:#8BC34A,color:#000000,stroke-width:1px,font-weight:bold
    classDef blocked fill:#F44336,color:#FFFFFF,stroke-width:1px,font-weight:bold
    classDef external fill:#9E9E9E,color:#FFFFFF,stroke-width:1px,font-weight:bold
    
    style Container fill:#F5F5F5,stroke:#333333,stroke-width:3px
    style Operations fill:#FAFAFA,stroke:#616161,stroke-width:1px
    style Allowed fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px
    style Blocked fill:#FFEBEE,stroke:#C62828,stroke-width:2px

Components

server_enhanced_with_lsp.py: Primary FastMCP-based server with complete LSP integration (25 MCP tools)
terry-form-mcp.py: Core Terraform execution logic and subprocess handling
terraform_lsp_client.py: LSP client implementation for terraform-ls integration
mcp_request_validator.py: Security validation and input sanitization
github_app_auth.py & github_repo_handler.py: GitHub App integration for repository operations
Dockerfile: Production-ready container with Terraform v1.12+ and terraform-ls v0.33.2
Docker Container: Isolated execution environment with all dependencies pre-installed

Features

Core Terraform Execution (Original Features)

init - Initialize Terraform working directory
validate - Validate Terraform configuration syntax
fmt - Check Terraform code formatting
plan - Generate and show execution plan (with variable support)

Intelligent LSP Features (New)

Code Completion: Context-aware suggestions for Terraform resources, attributes, and values
Hover Documentation: Instant documentation for Terraform elements at cursor position
Advanced Validation: Detailed diagnostics with precise error locations and explanations
LSP-based Formatting: Professional code formatting with specific edit suggestions
Workspace Awareness: Intelligent context based on your project structure

Diagnostic Tools (New)

Environment Diagnostics: Comprehensive checks for Terraform and LSP setup
LSP Debugging: Detailed status information about the Language Server
Workspace Analysis: Terraform project structure and readiness assessment
LSP Initialization: Manual control over LSP client setup
File Validation: Terraform file syntax and structure checking
Workspace Setup: Automated creation of properly structured Terraform projects

Security Features

Containerized Execution: All Terraform commands run in isolated Docker containers
Workspace Isolation: Operations restricted to /mnt/workspace mount point
No State Modification: Only read-only operations (plan, validate, fmt)
Variable Injection: Safe parameter passing for dynamic configurations

AI Integration

Structured Output: JSON-formatted results for AI processing
Error Handling: Detailed error messages and return codes
Batch Operations: Execute multiple Terraform actions in sequence
FastMCP Integration: Standard MCP protocol for AI assistant compatibility

Quick Start

Prerequisites

Docker installed and running
Python 3.8+ (for development/testing)
Access to Terraform configurations in your workspace

1. Build the Docker Image

# Build using the provided script (Linux/macOS)
./build.sh

# Or for Windows users
build.bat

# Alternatively, build directly with Docker
docker build -t terry-form-mcp .

2. Run as MCP Server

# Run as MCP server
docker run -it --rm \
  -v "$(pwd)":/mnt/workspace \
  terry-form-mcp

3. Test with Sample Data

# Create a test workspace
docker run -i --rm \
  -v "$(pwd)":/mnt/workspace \
  terry-form-mcp python3 -c "import json; print(json.dumps({'tool': 'terry_workspace_setup', 'arguments': {'path': 'test-project', 'project_name': 'test'}}))" | \
  docker run -i --rm \
  -v "$(pwd)":/mnt/workspace \
  terry-form-mcp

# Initialize the project
echo '{
  "tool": "terry",
  "arguments": {
    "actions": ["init"],
    "path": "test-project"
  }
}' | docker run -i --rm \
  -v "$(pwd)":/mnt/workspace \
  terry-form-mcp

4. Run Environment Check

# Check the environment for Terraform and LSP readiness
docker run -i --rm terry-form-mcp python3 -c "import json; import sys; sys.path.append('/app'); from server_enhanced_with_lsp import terry_environment_check; print(json.dumps(terry_environment_check(), indent=2))"

Configuration

MCP Server Configuration in IDE

Most IDEs that support MCP will have a configuration file or UI. Here's a generic configuration that works across platforms:

{
  "mcpServers": {
    "terry": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/your/workspace:/mnt/workspace",
        "terry-form-mcp"
      ]
    }
  }
}

Platform-Specific Configuration Examples

Claude Desktop (Windows)

{
  "mcpServers": {
    "terry": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "C:\\Users\\YourUsername\\terraform-projects:/mnt/workspace",
        "terry-form-mcp"
      ]
    }
  }
}

Claude Desktop (macOS)

{
  "mcpServers": {
    "terry": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YourUsername/terraform-projects:/mnt/workspace",
        "terry-form-mcp"
      ]
    }
  }
}

Claude Desktop (Linux)

{
  "mcpServers": {
    "terry": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/YourUsername/terraform-projects:/mnt/workspace",
        "terry-form-mcp"
      ]
    }
  }
}

VSCode Extension (Generic)

For VSCode extensions that support MCP, add to settings.json:

{
  "mcp.servers": {
    "terry": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "${workspaceFolder}:/mnt/workspace",
        "terry-form-mcp"
      ]
    }
  }
}

Detailed Tool Documentation

Core Terraform Tool

`terry`

Executes Terraform commands in a containerized environment

terry(
    path: string,           // Required: Path to Terraform configuration directory
    actions: string[],      // Optional: List of actions to perform ["init", "validate", "fmt", "plan"]
    vars: object            // Optional: Key-value pairs for Terraform variables
)

Returns: JSON object with results for each action

{
  "terry-results": [
    {
      "success": true,
      "action": "plan",
      "stdout": "Terraform will perform the following actions...",
      "stderr": "",
      "returncode": 0
    }
  ]
}

LSP Intelligence Tools

`terraform_validate_lsp`

Validates Terraform files using LSP for detailed diagnostics

terraform_validate_lsp(
    file_path: string,      // Required: Path to Terraform file relative to workspace
    workspace_path: string  // Optional: Workspace directory (defaults to file's parent directory)
)

Returns: Validation results with diagnostics

{
  "terraform-ls-validation": {
    "file_path": "main.tf",
    "workspace_path": "/mnt/workspace/project",
    "success": true,
    "uri": "file:///mnt/workspace/project/main.tf",
    "diagnostics": [
      {
        "range": {
          "start": {"line": 15, "character": 10},
          "end": {"line": 15, "character": 20}
        },
        "severity": 1,
        "message": "Resource type not found: aws_instance"
      }
    ]
  }
}

`terraform_hover`

Gets documentation for Terraform elements at cursor position

terraform_hover(
    file_path: string,      // Required: Path to Terraform file relative to workspace
    line: number,           // Required: Line number (0-based)
    character: number,      // Required: Character position (0-based)
    workspace_path: string  // Optional: Workspace directory
)

Returns: Documentation for the element at cursor position

{
  "terraform-hover": {
    "file_path": "main.tf",
    "position": {"line": 14, "character": 15},
    "success": true,
    "hover": {
      "kind": "markdown",
      "value": "**resource** _Block_\n\nA resource block declares a resource of a given type..."
    }
  }
}

`terraform_complete`

Provides intelligent code completion suggestions

terraform_complete(
    file_path: string,      // Required: Path to Terraform file relative to workspace
    line: number,           // Required: Line number (0-based)
    character: number,      // Required: Character position (0-based)
    workspace_path: string  // Optional: Workspace directory
)

Returns: Completion suggestions for the cursor position

{
  "terraform-completions": {
    "file_path": "main.tf",
    "position": {"line": 20, "character": 0},
    "success": true,
    "completions": [
      {
        "label": "\"key\" = string",
        "kind": 10,
        "detail": "string",
        "insertTextFormat": 2,
        "textEdit": {
          "range": {
            "start": {"line": 20, "character": 0},
            "end": {"line": 20, "character": 0}
          },
          "newText": "\"${1:key}\" = "
        }
      }
    ]
  }
}

`terraform_format_lsp`

Formats Terraform files using LSP

terraform_format_lsp(
    file_path: string,      // Required: Path to Terraform file relative to workspace
    workspace_path: string  // Optional: Workspace directory
)

Returns: Formatting edits to apply

{
  "terraform-format": {
    "file_path": "main.tf",
    "success": true,
    "edits": [
      {
        "range": {
          "start": {"line": 17, "character": 0},
          "end": {"line": 18, "character": 0}
        },
        "newText": "\n"
      }
    ]
  }
}

`terraform_lsp_status`

Checks the status of the terraform-ls Language Server

terraform_lsp_status()

Returns: Current status of the LSP client

{
  "terraform-ls-status": {
    "status": "active",
    "initialized": true,
    "capabilities": {
      "textDocumentSync": { /* LSP capabilities */ },
      "completionProvider": { /* ... */ },
      "hoverProvider": true,
      /* more capabilities */
    },
    "workspace_root": "/mnt/workspace"
  }
}

Diagnostic Tools

`terry_environment_check`

Checks the environment for Terraform and LSP readiness

terry_environment_check()

Returns: Comprehensive environment information

{
  "terry-environment": {
    "environment": {
      "working_directory": "/app",
      "user": "unknown",
      "path": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
      "workspace_mount": true
    },
    "terraform": {
      "available": true,
      "path": "/bin/terraform",
      "version": "Terraform v1.12.1\non linux_amd64"
    },
    "terraform_ls": {
      "available": true,
      "path": "/usr/local/bin/terraform-ls",
      "version": "0.33.2\nplatform: linux/amd64\ngo: go1.22.4\ncompiler: gc"
    },
    "container": {
      "is_docker": true,
      "hostname": "ff057bf241c4"
    }
  }
}

`terry_lsp_debug`

Provides detailed debugging information for the LSP integration

terry_lsp_debug()

Returns: LSP debugging information

{
  "terry-lsp-debug": {
    "terraform_ls_binary": {
      "available": true,
      "version": "0.33.2\nplatform: linux/amd64\ngo: go1.22.4\ncompiler: gc",
      "error": null
    },
    "lsp_client": {
      "exists": true,
      "initialized": true,
      "workspace_root": "/mnt/workspace/project",
      "process_active": true
    },
    "terraform_ls_help": {
      "available": true,
      "output": "Usage: terraform-ls serve [options]..."
    }
  }
}

`terry_workspace_info`

Analyzes Terraform workspace structure and readiness

terry_workspace_info(
    path: string = "."      // Optional: Path to analyze (defaults to current directory)
)

Returns: Workspace analysis

{
  "terry-workspace": {
    "path_info": {
      "full_path": "/mnt/workspace/project",
      "relative_path": "project",
      "exists": true,
      "is_directory": true
    },
    "terraform_files": ["main.tf", "variables.tf", "outputs.tf"],
    "terraform_state": {
      "initialized": true,
      "terraform_dir_exists": true,
      "state_file_exists": true
    },
    "common_files": {
      "main.tf": true,
      "variables.tf": true,
      "outputs.tf": true,
      "providers.tf": false,
      "terraform.tf": false,
      "versions.tf": false
    },
    "lsp_readiness": {
      "has_terraform_files": true,
      "has_main_tf": true,
      "is_initialized": true,
      "recommended_actions": []
    }
  }
}

`terry_lsp_init`

Manually initializes the LSP client for a workspace

terry_lsp_init(
    workspace_path: string  // Required: Path to workspace directory
)

Returns: LSP initialization results

{
  "terry-lsp-init": {
    "success": true,
    "workspace": "/mnt/workspace/project",
    "capabilities": { /* LSP capabilities */ },
    "message": "LSP client initialized successfully"
  }
}

`terry_file_check`

Checks a Terraform file for syntax and structure issues

terry_file_check(
    file_path: string       // Required: Path to Terraform file
)

Returns: File analysis results

{
  "terry-file-check": {
    "file_path": "main.tf",
    "full_path": "/mnt/workspace/project/main.tf",
    "exists": true,
    "is_file": true,
    "readable": true,
    "size": 450,
    "syntax_check": {
      "has_content": true,
      "has_terraform_block": true,
      "has_resource_block": true,
      "has_data_block": false,
      "line_count": 25
    }
  }
}

`terry_workspace_setup`

Creates a properly structured Terraform workspace

terry_workspace_setup(
    path: string,           // Required: Path where to create workspace
    project_name: string = "terraform-project" // Optional: Project name
)

Returns: Setup results

{
  "terry-workspace-setup": {
    "success": true,
    "workspace_path": "/mnt/workspace/project",
    "project_name": "my-terraform-project",
    "created_files": ["main.tf", "variables.tf", "outputs.tf"],
    "message": "Workspace setup complete. Created 3 files."
  }
}

Additional Tools

`terry_version`

Get Terraform and server version information

terry_version()

Returns: Version details

{
  "terry-version": {
    "server_version": "3.0.0",
    "terraform_version": "1.12.0",
    "terraform_ls_version": "0.33.2",
    "python_version": "3.12.11"
  }
}

`terry_workspace_list`

List all Terraform workspaces in the mounted directory

terry_workspace_list()

Returns: List of all workspaces

{
  "terry-workspaces": {
    "workspaces": [
      {
        "path": "project1",
        "initialized": true,
        "has_terraform_files": true,
        "file_count": 5
      }
    ],
    "total_count": 1
  }
}

`terry_analyze`

Analyze Terraform configuration for best practices

terry_analyze(
    path: string  // Required: Path to Terraform configuration
)

Returns: Best practices analysis

{
  "terry-analyze": {
    "path": "/mnt/workspace/project",
    "analysis": {
      "structure": "good",
      "recommendations": [
        "Consider adding outputs.tf for better documentation",
        "Add version constraints in terraform block"
      ],
      "issues_found": 2,
      "files_analyzed": 3
    }
  }
}

`terry_recommendations`

Get improvement recommendations for Terraform code

terry_recommendations(
    path: string  // Required: Path to Terraform configuration
)

Returns: Actionable recommendations

{
  "terry-recommendations": {
    "recommendations": [
      {
        "type": "security",
        "priority": "high",
        "message": "Use variables for sensitive values",
        "file": "main.tf",
        "line": 15
      }
    ]
  }
}

`terry_security_scan`

Scan Terraform configuration for security issues

terry_security_scan(
    path: string  // Required: Path to Terraform configuration
)

Returns: Security scan results

{
  "terry-security-scan": {
    "path": "/mnt/workspace/project",
    "findings": [
      {
        "severity": "medium",
        "rule": "Hardcoded credentials detected",
        "file": "main.tf",
        "line": 23,
        "remediation": "Use variables or secrets management"
      }
    ],
    "total_findings": 1,
    "critical": 0,
    "high": 0,
    "medium": 1,
    "low": 0
  }
}

GitHub Integration Tools

`github_clone_repo`

Clone or update a GitHub repository

github_clone_repo(
    owner: string,         // Required: Repository owner
    repo: string,          // Required: Repository name
    branch: string = null, // Optional: Branch to clone
    force: boolean = false // Optional: Force update if exists
)

Returns: Clone operation result

{
  "github-clone": {
    "success": true,
    "owner": "myorg",
    "repo": "infrastructure",
    "branch": "main",
    "local_path": "/mnt/workspace/github-repos/myorg/infrastructure",
    "action": "cloned"
  }
}

`github_list_terraform_files`

List Terraform files in a GitHub repository

github_list_terraform_files(
    owner: string,           // Required: Repository owner
    repo: string,            // Required: Repository name
    path: string = "",       // Optional: Path within repo
    pattern: string = "*.tf" // Optional: File pattern
)

Returns: List of Terraform files

{
  "terraform_files": [
    "environments/prod/main.tf",
    "environments/prod/variables.tf",
    "modules/vpc/main.tf"
  ],
  "count": 3
}

`github_get_terraform_config`

Get information about Terraform configuration in a repository

github_get_terraform_config(
    owner: string,      // Required: Repository owner
    repo: string,       // Required: Repository name
    config_path: string // Required: Path to Terraform config
)

Returns: Configuration details

{
  "config_info": {
    "path": "environments/prod",
    "files": ["main.tf", "variables.tf", "outputs.tf"],
    "modules_used": ["vpc", "eks"],
    "providers": ["aws", "kubernetes"]
  }
}

`github_prepare_workspace`

Prepare a Terraform workspace from a GitHub repository

github_prepare_workspace(
    owner: string,                 // Required: Repository owner
    repo: string,                  // Required: Repository name
    config_path: string,           // Required: Path to config in repo
    workspace_name: string = null  // Optional: Custom workspace name
)

Returns: Prepared workspace details

{
  "workspace_prepared": {
    "success": true,
    "workspace_path": "/mnt/workspace/myorg-infrastructure-prod",
    "config_path": "environments/prod",
    "ready_for_terraform": true
  }
}

Terraform Cloud Tools

Note: These tools currently return mock data for demonstration purposes.

`tf_cloud_list_workspaces`

List Terraform Cloud workspaces in an organization

tf_cloud_list_workspaces(
    organization: string  // Required: TF Cloud organization name
)

Returns: List of workspaces (mock data)

{
  "workspaces": [
    {
      "id": "ws-example-1",
      "name": "production",
      "terraform_version": "1.5.0",
      "locked": false
    }
  ]
}

`tf_cloud_get_workspace`

Get detailed workspace information

tf_cloud_get_workspace(
    organization: string,  // Required: Organization name
    workspace: string      // Required: Workspace name
)

`tf_cloud_list_runs`

List recent runs for a workspace

tf_cloud_list_runs(
    organization: string,  // Required: Organization name
    workspace: string,     // Required: Workspace name
    limit: number = 10     // Optional: Number of runs to return
)

`tf_cloud_get_state_outputs`

Get state outputs from a workspace

tf_cloud_get_state_outputs(
    organization: string,  // Required: Organization name
    workspace: string      // Required: Workspace name
)

Usage Examples

Basic Terraform Execution

// Initialize and validate a Terraform project
terry(
    path="infrastructure/aws",
    actions=["init", "validate"]
)

Infrastructure Planning with Variables

// Plan with variables
terry(
    path="environments/production",
    actions=["plan"],
    vars={
        "instance_count": "3",
        "environment": "prod",
        "region": "us-east-1"
    }
)

LSP-Powered Intelligent Development

// Initialize LSP client for a workspace
terry_lsp_init(
    workspace_path="modules/vpc"
)

// Get documentation for a resource
terraform_hover(
    file_path="modules/vpc/main.tf",
    line=15,
    character=12
)

// Get code completion suggestions
terraform_complete(
    file_path="modules/vpc/variables.tf",
    line=8,
    character=0
)

// Validate a file with detailed diagnostics
terraform_validate_lsp(
    file_path="modules/vpc/outputs.tf"
)

// Format a file
terraform_format_lsp(
    file_path="modules/vpc/main.tf"
)

Environment and Workspace Setup

// Check environment readiness
terry_environment_check()

// Create a new Terraform workspace
terry_workspace_setup(
    path="new-project",
    project_name="aws-vpc-module"
)

// Analyze workspace structure
terry_workspace_info(
    path="existing-project"
)

// Check specific file
terry_file_check(
    file_path="existing-project/main.tf"
)

Comprehensive Development Workflow

// Step 1: Create a workspace
terry_workspace_setup(path="new-aws-project", project_name="aws-infra")

// Step 2: Check workspace structure
terry_workspace_info(path="new-aws-project")

// Step 3: Initialize Terraform
terry(path="new-aws-project", actions=["init"])

// Step 4: Initialize LSP
terry_lsp_init(workspace_path="new-aws-project")

// Step 5: Get code completion as you develop
terraform_complete(file_path="new-aws-project/main.tf", line=10, character=0)

// Step 6: Format the file
terraform_format_lsp(file_path="new-aws-project/main.tf")

// Step 7: Validate with detailed diagnostics
terraform_validate_lsp(file_path="new-aws-project/main.tf")

// Step 8: Plan the infrastructure
terry(path="new-aws-project", actions=["plan"])

Key Advantages of LSP Integration

The LSP integration provides several significant advantages over the basic Terraform execution:

Intelligent Code Assistance: Get real-time documentation, completions, and validation as you develop, reducing errors and speeding up development.
Enhanced Diagnostics: Receive detailed diagnostic information with precise locations and explanations, making it easier to fix issues.
Provider-Aware: LSP understands your provider context, offering provider-specific completions and documentation.
Workspace Context: LSP maintains awareness of your entire project structure, enabling smarter suggestions and validations.
Development Speed: Reduce the feedback loop between writing code and validating it, speeding up infrastructure development.
Resource Discovery: Easily discover available resources, attributes, and valid values through intelligent completions.
Documentation at Cursor: Get instant access to Terraform documentation right where you need it, without leaving your editor.
Professional Formatting: Ensure consistent code style with LSP-powered formatting that follows HashiCorp's conventions.
Comprehensive Tooling: The combination of execution and intelligence tools provides a complete Terraform development environment.
AI Assistant Integration: Enables AI assistants to provide much higher quality Terraform assistance with real-time intelligence.

Security Considerations

Security Architecture

Terry-Form MCP implements a robust security model with multiple layers of protection:

flowchart TB
    %% Define external nodes
    Requests["AI Assistant\nTool Requests"]:::external
    Execution["Secure Terraform\nExecution"]:::execution
    
    %% Security Layers Group
    subgraph SecurityLayers["Security Architecture"]
        direction TB
        
        %% Layer 1
        subgraph L1["Layer 1: Physical Isolation"]
            direction LR
            Docker["Docker Containerization"]:::layer1
        end
        
        %% Layer 2
        subgraph L2["Layer 2: Access Control"]
            direction LR
            ReadOnly["Read-Only File System Mount"]:::layer2
            NoNetwork["No External Network Access"]:::layer2
        end
        
        %% Layer 3
        subgraph L3["Layer 3: Operation Restrictions"]
            direction LR
            SafeOpsOnly["Safe Operations Only\n(init, validate, fmt, plan)"]:::layer3
            NoStateModification["No State Modification"]:::layer3
        end
        
        %% Layer 4
        subgraph L4["Layer 4: Input Validation"]
            direction LR
            PathValidation["Path Validation\n& Sanitization"]:::layer4
            VariableSanitization["Variable Input Sanitization"]:::layer4
        end
        
        %% Define internal connections
        L1 --> L2
        L2 --> L3
        L3 --> L4
    end
    
    %% Define external connections
    Requests --> SecurityLayers
    SecurityLayers --> Execution
    
    %% Define styles
    classDef external fill:#9C27B0,stroke:#6A1B9A,color:#FFFFFF,stroke-width:2px
    classDef execution fill:#4CAF50,stroke:#2E7D32,color:#FFFFFF,stroke-width:2px
    classDef layer1 fill:#E8F4FF,stroke:#1976D2,stroke-width:2px
    classDef layer2 fill:#E5FFE8,stroke:#43A047,stroke-width:2px
    classDef layer3 fill:#FFF4E8,stroke:#FB8C00,stroke-width:2px
    classDef layer4 fill:#F8E8FF,stroke:#7B1FA2,stroke-width:2px
    
    %% Group styles
    style SecurityLayers fill:#F5F5F5,stroke:#333333,stroke-width:2px
    style L1 fill:#E8F4FF,stroke:#1976D2,stroke-width:1px
    style L2 fill:#E5FFE8,stroke:#43A047,stroke-width:1px
    style L3 fill:#FFF4E8,stroke:#FB8C00,stroke-width:1px
    style L4 fill:#F8E8FF,stroke:#7B1FA2,stroke-width:1px

Safe Operations Only

No Apply/Destroy: Only read-only operations are supported
No State Access: Cannot modify Terraform state files
Container Isolation: All execution happens in ephemeral containers

Security Measures

Docker Containerization
- Complete isolation from host system
- Ephemeral containers with no persistent state
- No privileged access or capabilities
Read-Only File System Mount
- Local Terraform files mounted as read-only
- Container cannot modify host files
- Workspace isolation to /mnt/workspace only
Operation Restrictions
- Only safe operations allowed (init, validate, fmt, plan)
- No state-modifying operations (apply, destroy)
- No remote state access or modification
Network Isolation
- No outbound network connectivity
- Cannot access cloud provider APIs
- Cannot access remote Terraform state
Input Validation
- Path validation to prevent path traversal
- Variable sanitization to prevent injection attacks
- JSON request validation and schema enforcement
Safe Execution Patterns
- Subprocess execution with timeouts
- Error handling and resource cleanup
- Structured output validation

Best Practices

Always validate configurations before planning
Use specific variable values rather than sensitive defaults
Monitor container resource usage in production
Regularly update the HashiCorp Terraform base image
Use the LSP validation tools to catch issues early

Troubleshooting

Common Issues

LSP Not Initializing
- Check if terraform-ls is available in the container with terry_environment_check()
- Ensure the workspace has valid Terraform files
- Manually initialize with terry_lsp_init(workspace_path="your-project")
Docker Mount Issues
- Verify the path in your Docker mount configuration
- Ensure the workspace directory exists on your host machine
- Check file permissions on the host directory
LSP Features Not Working
- Check LSP status with terraform_lsp_status()
- Verify that you're using the enhanced image (terry-form-mcp-lsp-enhanced)
- Check if the file path is correctly specified relative to workspace
Terraform Execution Errors
- Initialize the workspace first with terry(path="your-project", actions=["init"])
- Check for syntax errors with terraform_validate_lsp(file_path="main.tf")
- Verify provider configurations and required variables

Debug Mode

Enable verbose output for troubleshooting:

docker run -it --rm \
  -v "$(pwd)":/mnt/workspace \
  -e TF_LOG=DEBUG \
  -e PYTHONUNBUFFERED=1 \
  terry-form-mcp

Development

Local Development Setup

Clone the repository
Install dependencies:
```
pip install fastmcp asyncio
```
Run the enhanced server locally:
```
python3 server_enhanced_with_lsp.py
```

Building Custom Images

Modify the Dockerfile to customize the container:

# Build with custom modifications
docker build -t terry-form-mcp-custom .

Testing

Test the LSP features:

# Test LSP client initialization
python3 -c "import terraform_lsp_client; import asyncio; asyncio.run(terraform_lsp_client.get_lsp_client('/path/to/workspace'))"

# Test with Docker
docker run -i --rm \
  -v "$(pwd):/mnt/workspace" \
  terry-form-mcp \
  python3 -c "import json; print(json.dumps({'tool': 'terraform_lsp_status'}))"

Project Structure

terry-form-mcp/
├── server_enhanced_with_lsp.py   # Main MCP server (imports all modules below)
├── terraform_lsp_client.py       # LSP client for terraform-ls integration
├── mcp_request_validator.py      # Security validation and input sanitization
├── github_app_auth.py            # GitHub App OAuth authentication
├── github_repo_handler.py        # GitHub repository operations
├── Dockerfile                    # Production container build configuration
├── build.sh                      # Build script (Linux/macOS)
├── build.bat                     # Build script (Windows)
├── verify.sh                     # Verification script for Docker image
├── requirements.txt              # Python dependencies
├── QUICKSTART.md                 # Quick start guide
├── examples/                     # Usage examples and documentation
│   └── README.md                 # Examples documentation
├── docs/                         # Jekyll documentation site
│   ├── index.md                  # Documentation homepage
│   ├── getting-started.md        # Quick start guide
│   └── api.md                    # API reference
├── test-terraform-project/       # Sample Terraform project for testing
│   └── main.tf                   # Example Terraform configuration
├── README.md                     # This file - complete documentation
├── CHANGELOG.md                  # Version history
├── CONTRIBUTING.md               # Contribution guidelines
└── LICENSE                       # MIT License

Limitations

Read-Only Operations: Cannot execute apply or destroy commands
No State Management: Cannot access or modify Terraform state
Local Execution Only: Designed for local development workflows
Variable Types: Only string variables are supported via command line
LSP Initialization: First LSP operation may take a few seconds to initialize

Support

For issues, questions, or contributions:

Create an issue in the GitHub repository
Follow the contributing guidelines
Check existing issues for similar problems

License

MIT License - see LICENSE file for details.

Changelog

v2.0.0

Added comprehensive Language Server Protocol (LSP) integration
Implemented intelligent code completion, documentation, and validation
Added 6 new diagnostic tools for environment and workspace analysis
Enhanced Docker image with terraform-ls
Improved error handling and workspace management

v1.0.0

Initial release with basic Terraform operations
FastMCP integration
Docker containerization
Support for init, validate, fmt, and plan actions

Note: This tool is designed for development and testing workflows. For production Terraform operations, use proper CI/CD pipelines with appropriate security controls and state management.