shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

terry-form-mcp

Terry-Form MCP是一个连接AI助手与Terraform基础设施管理的桥梁，通过安全容器化环境执行Terraform命令，并集成语言服务器协议(LSP)提供智能开发能力。

article

README

🚀 Terry-Form MCP 集成 LSP

Terry-Form MCP 是一个模型控制协议（MCP）服务器，它允许 AI 助手通过使用 HashiCorp 官方 Terraform 镜像的安全容器化环境在本地执行 Terraform 命令。现在，该项目通过集成语言服务器协议（LSP），增强了智能 Terraform 开发能力。

image

🚀 快速开始

前提条件

  • 已安装并运行 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 管道，并采取相应的安全控制和状态管理措施。

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端