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
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
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
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
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.
