Getting Started with Terry-Form MCP

Welcome to Terry-Form MCP! This guide will help you get up and running quickly.

Prerequisites

Before you begin, ensure you have the following installed:

Docker (recommended) or Python 3.9+
Terraform (if running locally)
An AI assistant that supports MCP (Claude, etc.)
A workspace directory for your Terraform configurations

Installation Options

Option 1: Docker (Recommended)

Docker provides the easiest and most secure way to run Terry-Form MCP.

# Clone the repository
git clone https://github.com/aj-geddes/terry-form-mcp.git
cd terry-form-mcp

# Build the image
./build.sh

# Run the server (MCP uses stdio, not HTTP)
docker run -it --rm \
  -v "$(pwd)":/mnt/workspace \
  terry-form-mcp:latest

Note: This server uses stdio transport for MCP protocol, not HTTP. It should be invoked by your MCP client (e.g., Claude Desktop), not run as a daemon.

Option 2: Local Development

For development or testing:

# Clone the repository
git clone https://github.com/aj-geddes/terry-form-mcp.git
cd terry-form-mcp

# Install dependencies
pip install -r requirements.txt

# Run the server directly
python3 server_enhanced_with_lsp.py

Configuration

1. AI Assistant Configuration

Configure your AI assistant to use Terry-Form MCP. For Claude Desktop, edit your claude_desktop_config.json:

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

2. Environment Variables

Key environment variables:

Variable	Description	Required
`WORKSPACE_ROOT`	Root directory for Terraform files	Yes
`TERRAFORM_CLOUD_TOKEN`	Terraform Cloud API token	No
`GITHUB_APP_ID`	GitHub App ID for repo integration	No
`GITHUB_APP_PRIVATE_KEY`	GitHub App private key	No
`LOG_LEVEL`	Logging level (INFO, DEBUG)	No

3. Security Configuration

Terry-Form MCP includes several security features by default:

# Security settings (built-in)
security:
  allowed_actions:
    - init
    - validate
    - plan
    - fmt
  blocked_actions:
    - apply
    - destroy
  path_validation: strict
  input_sanitization: enabled

Your First Terraform Operation

1. Create a Simple Configuration

Create a file workspace/main.tf:

terraform {
  required_version = ">= 1.0"
}

variable "project_name" {
  description = "Name of the project"
  type        = string
  default     = "my-first-project"
}

output "project_info" {
  value = "Project: ${var.project_name}"
}

2. Use Terry-Form with Your AI Assistant

Ask your AI assistant:

Can you help me validate and plan my Terraform configuration in the workspace directory?

The assistant will use Terry-Form MCP to:

Initialize the Terraform workspace
Validate the configuration
Generate an execution plan
Provide feedback and recommendations

3. Example Response

{
  "terry-results": [
    {
      "action": "init",
      "success": true,
      "stdout": "Terraform has been successfully initialized!"
    },
    {
      "action": "validate",
      "success": true,
      "stdout": "Success! The configuration is valid."
    },
    {
      "action": "plan",
      "success": true,
      "plan_summary": {
        "add": 0,
        "change": 0,
        "destroy": 0
      }
    }
  ]
}

Common Use Cases

Managing Multiple Environments

# Development environment
terry path: "environments/dev" actions: ["plan"] vars: {"env": "development"}

# Production environment  
terry path: "environments/prod" actions: ["plan"] vars: {"env": "production"}

Working with Modules

# workspace/modules/vpc/main.tf
module "vpc" {
  source = "./modules/vpc"
  
  cidr_block = var.vpc_cidr
  environment = var.environment
}

GitHub Integration

If you’ve configured GitHub App integration:

# Clone and analyze a repository
github_clone_repo owner: "myorg" repo: "infrastructure"

# List Terraform files
github_list_terraform_files owner: "myorg" repo: "infrastructure"

Web Dashboard

Access the web dashboard at http://localhost:3000 to:

Monitor Terraform operations in real-time
View workspace status
Check system health
Review operation history

graph LR
    A[Browser] -->|HTTP| B[Web Dashboard]
    B --> C[Terry-Form Server]
    C --> D[Terraform Operations]
    C --> E[Workspace Files]

Troubleshooting

Common Issues

Permission Denied
Ensure the workspace directory has proper permissions: chmod -R 755 /path/to/workspace

Terraform Not Found
If using Docker, Terraform is included. For local setup: brew install terraform or apt-get install terraform

MCP Connection Failed
Check that Docker is running and the container started successfully: docker logs terry-form

Debug Mode

Enable debug logging for troubleshooting:

docker run -d \
  -e LOG_LEVEL=DEBUG \
  -v /path/to/workspace:/mnt/workspace \
  aj-geddes/terry-form-mcp:latest

Best Practices

Use Version Control: Always version control your Terraform configurations
Plan Before Apply: Review plans carefully before applying changes
Use Workspaces: Separate environments using Terraform workspaces
Secure Secrets: Use environment variables or secret management tools
Regular Backups: Backup your state files regularly

Next Steps

Now that you have Terry-Form MCP running:

📖 Read the Architecture Overview
🔒 Review the Security Guide
📚 Explore Available Tutorials

Getting Help

🎉 Congratulations!
You've successfully set up Terry-Form MCP. Start exploring its features and automate your infrastructure with confidence!