Terry Form MCP

🚀 Terry-Form MCP 集成 LSP

Terry-Form MCP 是一個模型控制協議（MCP）服務器，它允許 AI 助手通過使用 HashiCorp 官方 Terraform 鏡像的安全容器化環境在本地執行 Terraform 命令。現在，該項目通過集成語言服務器協議（LSP），增強了智能 Terraform 開發能力。

🚀 快速開始

前提條件

• 已安裝並運行 Docker
• Python 3.8 及以上版本（用於開發/測試）
• 可以訪問工作區中的 Terraform 配置

1. 構建 Docker 鏡像

# 使用提供的腳本構建（Linux/macOS）
./build.sh

# 或者 Windows 用戶使用
build.bat

# 也可以直接使用 Docker 構建
docker build -t terry-form-mcp .

2. 作為 MCP 服務器運行

# 作為 MCP 服務器運行
docker run -it --rm \
  -v "$(pwd)":/mnt/workspace \
  terry-form-mcp

3. 使用示例數據進行測試

# 創建一個測試工作區
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

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

4. 運行環境檢查

# 檢查 Terraform 和 LSP 環境是否準備就緒
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))"

✨ 主要特性

核心 Terraform 執行（原有特性）

• init - 初始化 Terraform 工作目錄
• validate - 驗證 Terraform 配置語法
• fmt - 檢查 Terraform 代碼格式
• plan - 生成並顯示執行計劃（支持變量）

智能 LSP 特性（新增）

• 代碼補全：為 Terraform 資源、屬性和值提供上下文感知的建議
• 懸停文檔：在光標位置即時顯示 Terraform 元素的文檔
• 高級驗證：提供詳細的診斷信息，包括精確的錯誤位置和解釋
• 基於 LSP 的格式化：提供專業的代碼格式化和具體的編輯建議
• 工作區感知：根據項目結構提供智能上下文

診斷工具（新增）

• 環境診斷：全面檢查 Terraform 和 LSP 的設置
• LSP 調試：提供語言服務器的詳細狀態信息
• 工作區分析：評估 Terraform 項目的結構和準備情況
• LSP 初始化：手動控制 LSP 客戶端的設置
• 文件驗證：檢查 Terraform 文件的語法和結構
• 工作區設置：自動創建結構合理的 Terraform 項目

安全特性

• 容器化執行：所有 Terraform 命令在隔離的 Docker 容器中運行
• 工作區隔離：操作限制在 /mnt/workspace 掛載點
• 無狀態修改：僅支持只讀操作（plan、validate、fmt）
• 變量注入：安全地傳遞參數以實現動態配置

AI 集成

• 結構化輸出：以 JSON 格式輸出結果，便於 AI 處理
• 錯誤處理：提供詳細的錯誤消息和返回碼
• 批量操作：按順序執行多個 Terraform 操作
• FastMCP 集成：採用標準 MCP 協議，與 AI 助手兼容

📦 安裝指南

本地開發設置

1. 克隆倉庫
2. 安裝依賴：

   pip install fastmcp asyncio
   

3. 在本地運行增強服務器：

   python3 server_enhanced_with_lsp.py
   

構建自定義鏡像

修改 Dockerfile 以自定義容器：

# 進行自定義修改後構建
docker build -t terry-form-mcp-custom .

💻 使用示例

基礎用法

// 初始化並驗證 Terraform 項目
terry(
    path="infrastructure/aws",
    actions=["init", "validate"]
)

高級用法

帶變量的基礎設施規劃

// 帶變量進行規劃
terry(
    path="environments/production",
    actions=["plan"],
    vars={
        "instance_count": "3",
        "environment": "prod",
        "region": "us-east-1"
    }
)

LSP 驅動的智能開發

// 為工作區初始化 LSP 客戶端
terry_lsp_init(
    workspace_path="modules/vpc"
)

// 獲取資源的文檔
terraform_hover(
    file_path="modules/vpc/main.tf",
    line=15,
    character=12
)

// 獲取代碼補全建議
terraform_complete(
    file_path="modules/vpc/variables.tf",
    line=8,
    character=0
)

// 使用詳細診斷信息驗證文件
terraform_validate_lsp(
    file_path="modules/vpc/outputs.tf"
)

// 格式化文件
terraform_format_lsp(
    file_path="modules/vpc/main.tf"
)

環境和工作區設置

// 檢查環境準備情況
terry_environment_check()

// 創建新的 Terraform 工作區
terry_workspace_setup(
    path="new-project",
    project_name="aws-vpc-module"
)

// 分析工作區結構
terry_workspace_info(
    path="existing-project"
)

// 檢查特定文件
terry_file_check(
    file_path="existing-project/main.tf"
)

全面的開發工作流程

// 步驟 1: 創建工作區
terry_workspace_setup(path="new-aws-project", project_name="aws-infra")

// 步驟 2: 檢查工作區結構
terry_workspace_info(path="new-aws-project")

// 步驟 3: 初始化 Terraform
terry(path="new-aws-project", actions=["init"])

// 步驟 4: 初始化 LSP
terry_lsp_init(workspace_path="new-aws-project")

// 步驟 5: 在開發過程中獲取代碼補全
terraform_complete(file_path="new-aws-project/main.tf", line=10, character=0)

// 步驟 6: 格式化文件
terraform_format_lsp(file_path="new-aws-project/main.tf")

// 步驟 7: 使用詳細診斷信息進行驗證
terraform_validate_lsp(file_path="new-aws-project/main.tf")

// 步驟 8: 規劃基礎設施
terry(path="new-aws-project", actions=["plan"])

📚 詳細文檔

核心 Terraform 工具

terry

在容器化環境中執行 Terraform 命令

terry(
    path: string,           // 必需：Terraform 配置目錄的路徑
    actions: string[],      // 可選：要執行的操作列表 ["init", "validate", "fmt", "plan"]
    vars: object            // 可選：Terraform 變量的鍵值對
)

返回值：每個操作結果的 JSON 對象

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

LSP 智能工具

terraform_validate_lsp

使用 LSP 驗證 Terraform 文件以獲取詳細診斷信息

terraform_validate_lsp(
    file_path: string,      // 必需：相對於工作區的 Terraform 文件路徑
    workspace_path: string  // 可選：工作區目錄（默認為文件的父目錄）
)

返回值：包含診斷信息的驗證結果

{
  "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

獲取光標位置的 Terraform 元素的文檔

terraform_hover(
    file_path: string,      // 必需：相對於工作區的 Terraform 文件路徑
    line: number,           // 必需：行號（從 0 開始）
    character: number,      // 必需：字符位置（從 0 開始）
    workspace_path: string  // 可選：工作區目錄
)

返回值：光標位置元素的文檔

{
  "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

提供智能代碼補全建議

terraform_complete(
    file_path: string,      // 必需：相對於工作區的 Terraform 文件路徑
    line: number,           // 必需：行號（從 0 開始）
    character: number,      // 必需：字符位置（從 0 開始）
    workspace_path: string  // 可選：工作區目錄
)

返回值：光標位置的補全建議

{
  "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

使用 LSP 格式化 Terraform 文件

terraform_format_lsp(
    file_path: string,      // 必需：相對於工作區的 Terraform 文件路徑
    workspace_path: string  // 可選：工作區目錄
)

返回值：要應用的格式化編輯

{
  "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

檢查 terraform-ls 語言服務器的狀態

terraform_lsp_status()

返回值：LSP 客戶端的當前狀態

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

診斷工具

terry_environment_check

檢查 Terraform 和 LSP 環境是否準備就緒

terry_environment_check()

返回值：全面的環境信息

{
  "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

提供 LSP 集成的詳細調試信息

terry_lsp_debug()

返回值：LSP 調試信息

{
  "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

分析 Terraform 工作區的結構和準備情況

terry_workspace_info(
    path: string = "."      // 可選：要分析的路徑（默認為當前目錄）
)

返回值：工作區分析結果

{
  "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

手動為工作區初始化 LSP 客戶端

terry_lsp_init(
    workspace_path: string  // 必需：工作區目錄的路徑
)

返回值：LSP 初始化結果

{
  "terry-lsp-init": {
    "success": true,
    "workspace": "/mnt/workspace/project",
    "capabilities": { /* LSP 功能 */ },
    "message": "LSP 客戶端初始化成功"
  }
}

terry_file_check

檢查 Terraform 文件的語法和結構問題

terry_file_check(
    file_path: string       // 必需：Terraform 文件的路徑
)

返回值：文件分析結果

{
  "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

創建結構合理的 Terraform 工作區

terry_workspace_setup(
    path: string,           // 必需：創建工作區的路徑
    project_name: string = "terraform-project" // 可選：項目名稱
)

返回值：設置結果

{
  "terry-workspace-setup": {
    "success": true,
    "workspace_path": "/mnt/workspace/project",
    "project_name": "my-terraform-project",
    "created_files": ["main.tf", "variables.tf", "outputs.tf"],
    "message": "工作區設置完成。創建了 3 個文件。"
  }
}

🔧 技術細節

組件架構

flowchart LR
    %% Define nodes with improved styling
    Claude["AI 助手\n(Claude)"]:::claude
    MCP["Terry-Form MCP\n服務器"]:::server
    Container["Terraform Docker\n容器"]:::container
    TF["Terraform CLI"]:::terraform
    TFLS["Terraform-LS\n語言服務器"]:::lsp
    LocalTF[("本地 Terraform\n配置")]:::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 組件架構
    end

數據流和安全架構

flowchart LR
    %% Main components
    Claude["AI 助手\n(Claude)"]:::claude
    
    %% Docker container with components
    subgraph Container["Docker 容器"]
        MCP["Terry-Form MCP 服務器"]:::mcp
        TF["Terraform 引擎"]:::terraform
        
        %% Operations subgraph
        subgraph Operations["操作"]
            direction TB
            
            %% Allowed operations
            subgraph Allowed["✅ 允許"]
                Init("init"):::safe
                Validate("validate"):::safe
                Format("fmt"):::safe
                Plan("plan"):::safe
                LSP("LSP"):::safe
            end
            
            %% Blocked operations
            subgraph Blocked["❌ 禁止"]
                Apply("apply"):::blocked
                Destroy("destroy"):::blocked
            end
        end
    end
    
    %% External components
    Files[("本地文件\n(/mnt/workspace)")]:::files
    External["遠程服務\n(狀態/雲 API)"]:::external
    
    %% Connections
    Claude <--> MCP
    MCP --> TF
    TF --> Operations
    Files <--> Container
    Blocked -.- |"無訪問權限"| 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

組件

• server_enhanced_with_lsp.py：基於 FastMCP 的服務器，同時提供 terry 和 LSP 工具
• terry-form-mcp.py：核心 Terraform 執行邏輯和子進程處理
• terraform_lsp_client.py：用於 terraform-ls 集成的 LSP 客戶端實現
• Dockerfile_enhanced_lsp：集成了 Python、FastMCP 和 terraform-ls 的 HashiCorp Terraform 鏡像
• Docker 容器：預安裝了 Terraform 和 terraform-ls 的隔離執行環境

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

變更日誌

v2.0.0

• 增加了全面的語言服務器協議（LSP）集成
• 實現了智能代碼補全、文檔和驗證功能
• 新增 6 個用於環境和工作區分析的診斷工具
• 增強了 Docker 鏡像，集成了 terraform-ls
• 改進了錯誤處理和工作區管理

v1.0.0

• 初始版本，支持基本的 Terraform 操作
• 集成 FastMCP
• 採用 Docker 容器化
• 支持 init、validate、fmt 和 plan 操作

⚙️ 配置

IDE 中的 MCP 服務器配置

大多數支持 MCP 的 IDE 都有配置文件或 UI。以下是一個跨平臺通用的配置：

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

特定平臺的配置示例

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 擴展（通用）

對於支持 MCP 的 VSCode 擴展，在 settings.json 中添加以下內容：

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

🔑 LSP 集成的主要優勢

LSP 集成相對於基本的 Terraform 執行提供了幾個顯著的優勢：

1. 智能代碼輔助：在開發過程中提供實時文檔、補全和驗證，減少錯誤並加快開發速度。
2. 增強的診斷功能：提供詳細的診斷信息，包括精確的位置和解釋，便於解決問題。
3. 提供者感知：LSP 理解提供者上下文，提供特定於提供者的補全和文檔。
4. 工作區上下文：LSP 能夠感知整個項目結構，提供更智能的建議和驗證。
5. 開發速度：減少編寫代碼和驗證代碼之間的反饋循環，加快基礎設施開發。
6. 資源發現：通過智能補全輕鬆發現可用的資源、屬性和有效值。
7. 光標處的文檔：在需要的地方即時訪問 Terraform 文檔，無需離開編輯器。
8. 專業格式化：確保代碼風格一致，遵循 HashiCorp 的約定。
9. 綜合工具集：執行工具和智能工具的結合提供了完整的 Terraform 開發環境。
10. AI 助手集成：使 AI 助手能夠利用實時智能提供更高質量的 Terraform 協助。

🛡️ 安全考慮

安全架構

Terry-Form MCP 實現了一個強大的安全模型，具有多層保護：

flowchart TB
    %% Define external nodes
    Requests["AI 助手\n工具請求"]:::external
    Execution["安全的 Terraform\n執行"]:::execution
    
    %% Security Layers Group
    subgraph SecurityLayers["安全架構"]
        direction TB
        
        %% Layer 1
        subgraph L1["第 1 層：物理隔離"]
            direction LR
            Docker["Docker 容器化"]:::layer1
        end
        
        %% Layer 2
        subgraph L2["第 2 層：訪問控制"]
            direction LR
            ReadOnly["只讀文件系統掛載"]:::layer2
            NoNetwork["無外部網絡訪問"]:::layer2
        end
        
        %% Layer 3
        subgraph L3["第 3 層：操作限制"]
            direction LR
            SafeOpsOnly["僅允許安全操作\n(init, validate, fmt, plan)"]:::layer3
            NoStateModification["無狀態修改"]:::layer3
        end
        
        %% Layer 4
        subgraph L4["第 4 層：輸入驗證"]
            direction LR
            PathValidation["路徑驗證\n& 清理"]:::layer4
            VariableSanitization["變量輸入清理"]:::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

僅支持安全操作

• 無 apply/destroy 操作：僅支持只讀操作
• 無狀態訪問：不能修改 Terraform 狀態文件
• 容器隔離：所有執行都在臨時容器中進行

安全措施

1. Docker 容器化

   • 與主機系統完全隔離
   • 臨時容器，無持久狀態
   • 無特權訪問或權限

2. 只讀文件系統掛載

   • 本地 Terraform 文件以只讀方式掛載
   • 容器不能修改主機文件
   • 工作區隔離到 /mnt/workspace

3. 操作限制

   • 僅允許安全操作（init、validate、fmt、plan）
   • 無狀態修改操作（apply、destroy）
   • 無遠程狀態訪問或修改

4. 網絡隔離

   • 無出站網絡連接
   • 不能訪問雲提供商 API
   • 不能訪問遠程 Terraform 狀態

5. 輸入驗證

   • 路徑驗證，防止路徑遍歷攻擊
   • 變量清理，防止注入攻擊
   • JSON 請求驗證和模式強制

6. 安全執行模式

   • 子進程執行設置超時
   • 錯誤處理和資源清理
   • 結構化輸出驗證

最佳實踐

• 在規劃之前始終驗證配置
• 使用具體的變量值，避免使用敏感的默認值
• 在生產環境中監控容器資源使用情況
• 定期更新 HashiCorp Terraform 基礎鏡像
• 使用 LSP 驗證工具儘早發現問題

🐞 故障排除

常見問題

1. LSP 未初始化

   • 使用 terry_environment_check() 檢查容器中是否有 terraform-ls
   • 確保工作區有有效的 Terraform 文件
   • 使用 terry_lsp_init(workspace_path="your-project") 手動初始化

2. Docker 掛載問題

   • 驗證 Docker 掛載配置中的路徑
   • 確保主機上的工作區目錄存在
   • 檢查主機目錄的文件權限

3. LSP 功能無法正常工作

   • 使用 terraform_lsp_status() 檢查 LSP 狀態
   • 確保使用的是增強版鏡像（terry-form-mcp-lsp-enhanced）
   • 驗證文件路徑是否相對於工作區正確指定

4. Terraform 執行錯誤

   • 首先使用 terry(path="your-project", actions=["init"]) 初始化工作區
   • 使用 terraform_validate_lsp(file_path="main.tf") 檢查語法錯誤
   • 驗證提供者配置和所需變量

調試模式

啟用詳細輸出以進行故障排除：

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

🚧 侷限性

• 只讀操作：不能執行 apply 或 destroy 命令
• 無狀態管理：不能訪問或修改 Terraform 狀態
• 僅本地執行：專為本地開發工作流程設計
• 變量類型：命令行僅支持字符串變量
• LSP 初始化：首次 LSP 操作可能需要幾秒鐘才能初始化

🆘 支持

如果遇到問題、有疑問或想要貢獻代碼，請：

• 在 GitHub 倉庫中創建 issue
• 遵循貢獻指南
• 檢查現有 issue 以查找類似問題

⚠️ 重要提示

本工具專為開發和測試工作流程設計。對於生產環境的 Terraform 操作，請使用適當的 CI/CD 管道，並採取相應的安全控制和狀態管理措施。