特里表单MCP

Name: 特里表单MCP
Author: aj-geddes

作者：aj-geddes6 星标更新：2025-11-23

安装使用来源：spider==github.com

项目介绍

Terry-Form MCP with LSP Integration

文档站点：

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

版本 3.0.0 - 集成全面 LSP 的生产就绪 Terraform 自动化工具，包含 25 个 MCP 工具

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

Terry-Form 是什么？

Terry-Form MCP 是 AI 语言模型与 Terraform 基础设施管理之间的桥梁。它为像 Claude 这样的 AI 助手提供了安全、受控的方式：

执行 Terraform 命令（init，validate，fmt，plan）
使用 LSP 提供智能代码补全、文档和验证
在隔离的 Docker 容器中运行操作
处理本地工作区中的 Terraform 配置
动态传递变量给 Terraform 操作
返回结构化的 JSON 结果供 AI 处理

架构

组件架构

flowchart LR
    %% 定义节点并改进样式
    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
    
    %% 定义连接
    Claude <---> MCP
    MCP <---> Container
    Container --> TF
    Container --> TFLS
    TF --- LocalTF
    TFLS --- LocalTF
    
    %% 定义样式
    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

    %% 添加标题
    subgraph Terry-Form 组件架构
    end

数据流和安全架构

flowchart LR
    %% 主要组件
    Claude["AI 助手\n(Claude)"]:::claude
    
    %% 包含组件的 Docker 容器
    subgraph Container["Docker 容器"]
        MCP["Terry-Form MCP 服务器"]:::mcp
        TF["Terraform 引擎"]:::terraform
        
        %% 操作子图
        subgraph Operations["操作"]
            direction TB
            
            %% 允许的操作
            subgraph Allowed["✅ 允许"]
                Init("初始化"):::safe
                Validate("验证"):::safe
                Format("格式化"):::safe
                Plan("计划"):::safe
                LSP("LSP"):::safe
            end
            
            %% 阻止的操作
            subgraph Blocked["❌ 阻止"]
                Apply("应用"):::blocked
                Destroy("销毁"):::blocked
            end
        end
    end
    
    %% 外部组件
    Files[("本地文件\n(/mnt/workspace)")]:::files
    External["远程服务\n(状态/云API)"]:::external
    
    %% 连接
    Claude <--> MCP
    MCP --> TF
    TF --> Operations
    Files <--> Container
    Blocked -.- |"无访问"| External
    
    %% 样式
    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 基础服务器，完全集成了 LSP（25 个 MCP 工具）
terry-form-mcp.py: 核心的 Terraform 执行逻辑和子进程处理
terraform_lsp_client.py: 用于 terraform-ls 集成的 LSP 客户端实现
mcp_request_validator.py: 安全验证和输入净化
github_app_auth.py & github_repo_handler.py: GitHub 应用集成，用于仓库操作
Dockerfile: 生产就绪的容器，包含 Terraform v1.12+ 和 terraform-ls v0.33.2
Docker 容器: 预安装所有依赖项的隔离执行环境

特性

核心 Terraform 执行（原始特性）

init - 初始化 Terraform 工作目录
validate - 验证 Terraform 配置语法
fmt - 检查 Terraform 代码格式
plan - 生成并显示执行计划（支持变量）

智能 LSP 特性（新）

代码补全: 根据上下文建议 Terraform 资源、属性和值
悬停文档: 在光标位置即时获取 Terraform 元素的文档
高级验证: 详细诊断，精确错误位置和解释
基于 LSP 的格式化: 专业代码格式化，带有特定编辑建议
工作空间感知: 根据项目结构提供智能上下文

诊断工具（新）

环境诊断: 对 Terraform 和 LSP 设置进行全面检查
LSP 调试: 关于语言服务器的详细状态信息
工作空间分析: Terraform 项目的结构和准备情况评估
LSP 初始化: 对 LSP 客户端设置的手动控制
文件验证: Terraform 文件的语法和结构检查
工作空间设置: 自动创建结构良好的 Terraform 项目

安全特性

容器化执行: 所有 Terraform 命令都在隔离的 Docker 容器中运行
工作空间隔离: 操作限制在 /mnt/workspace 挂载点
无状态修改: 只读操作（计划、验证、格式化）
变量注入: 动态配置的安全参数传递

AI 集成

结构化输出: JSON 格式的结果供 AI 处理
错误处理: 详细的错误消息和返回码
批处理操作: 顺序执行多个 Terraform 动作
FastMCP 集成: 用于 AI 助手兼容性的标准 MCP 协议

快速开始

前提条件

已安装并运行 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))"

配置

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"
      ]
    }
  }
}

详细工具文档

核心 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 将执行以下操作...",
      "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": "未找到资源类型: 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** _块_\n\n一个资源块声明了给定类型的资源..."
    }
  }
}

`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,
      /* 更多能力 */