AI导哈

Terraform执行服务

Terry-Form MCP是一个容器化的Terraform执行服务，通过Model Context Protocol为AI助手提供安全、结构化的Terraform访问能力。

  • by aj-geddes
  • Python
  • 本地部署
  • 10 星标
  • 更新于
在 GitHub 查看 aj-geddes/terry-form-mcp

使用说明

Terry Form MCP

通过模型上下文协议实现人工智能驱动的地形执行。

Terry Form MCP是一个集装箱 模型上下文协议 服务器，为克劳德等人工智能助手提供对Terraform的安全、结构化访问。它公开了25个MCP工具，涵盖了Terraform执行、LSP智能、GitHub集成和Terraform Cloud连接——所有这些工具都在Docker中运行，设计阻止了破坏性操作。

文档网站

仪表盘

内置的web仪表板提供实时服务器运行状况监控、工具类别概述和集成状态一目了然。实时状态每5秒自动刷新一次。

配置UI

选项卡式配置界面允许您管理服务器设置、集成、云提供商凭据和速率限制，所有这些都不需要接触配置文件。使用HAT堆栈（HTMX+Alpine.js+Tailwind CSS）构建。

GitHub集成 云提供商 费率限制

工具目录

交互式工具目录位于 /tools 列出了所有25个MCP工具，包括搜索、类别过滤和可扩展参数详细信息。也可作为原始JSON端点在 /api/tools 作为一种静态 tools.json 文件。

快速开始

先决条件

  • Docker已安装并正在运行
  • Python>=3.10（用于本地开发）

1.建造

scripts/build.sh      # Linux/macOS
scripts\build.bat     # Windows
# or directly:
docker build -t terry-form-mcp .

2.作为MCP服务器运行

docker run -it --rm \
  -v "$(pwd)":/mnt/workspace \
  terry-form-mcp

3.验证图像

scripts/verify.sh   # Runs 8 checks: Docker, image size, Terraform, terraform-ls, Python, files, tools, startup

环境变量

所有配置都是通过环境变量进行的。基本使用不需要配置文件。

服务器配置

变量 描述 默认值 必填
MCP_TRANSPORT 传输协议： stdio, sse，或 streamable-http stdio 没有
TERRY_HOST 服务器绑定地址（回退： HOST) 0.0.0.0 没有
TERRY_PORT 服务器端口（回退： PORT) 8000 没有
TERRY_FORM_API_KEY 用于前端身份验证的API密钥；如果未设置，则禁用身份验证 无 否
TERRY_CSRF_SECRET CSRF令牌秘密；如果未设置，则在重新启动时重新生成 随机 推荐
TERRY_WORKSPACE_ROOT Terraform工作区根目录 /mnt/workspace 没有
TERRY_CONFIG_PATH 配置文件路径 /app/config/terry-config.json 没有

地形

变量 描述 默认值 必填
MAX_OPERATION_TIMEOUT 地形命令超时（秒）（10–3600） 300 没有

语言服务器协议

变量 描述 默认值 必填
TERRY_TERRAFORM_LS_PATH 通往 terraform-ls 二进制 terraform-ls 没有
TERRY_LSP_TIMEOUT LSP请求超时（秒） 30 没有
TERRY_LSP_MAX_RESPONSE_BYTES 最大LSP响应大小（字节） 10485760 没有

GitHub集成

变量 描述 默认值 必填
GITHUB_APP_ID GitHub应用程序ID 无 适用于GitHub功能
GITHUB_APP_PRIVATE_KEY_PATH GitHub应用程序私钥文件的路径 无 GitHub功能
GITHUB_APP_PRIVATE_KEY GitHub应用程序私钥（内联PEM） 无 Alt到路径
GITHUB_APP_INSTALLATION_ID GitHub应用程序安装ID 无 否
GITHUB_APP_WEBHOOK_SECRET Webhook签名验证密钥 无 否

地形云

变量 描述 默认值 必填
TF_API_TOKEN Terraform Cloud API令牌 无 用于TF Cloud功能

速率限制

变量 描述 默认值 必填
TERRY_RATE_LIMIT_TERRAFORM 每分钟地形操作数 20 没有
TERRY_RATE_LIMIT_GITHUB GitHub每分钟操作数 30 没有
TERRY_RATE_LIMIT_TF_CLOUD 地形云每分钟运行次数 30 没有
TERRY_RATE_LIMIT_DEFAULT 默认每分钟速率限制 100 没有

云提供商通道

这些变量直接转发到Terraform子流程。将它们设置为与您的云提供商进行身份验证。

AWS： AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_DEFAULT_REGION, AWS_REGION, AWS_PROFILE

GCP： GOOGLE_CREDENTIALS, GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_PROJECT, GOOGLE_REGION, GOOGLE_ZONE

Azure： ARM_CLIENT_ID, ARM_CLIENT_SECRET, ARM_SUBSCRIPTION_ID, ARM_TENANT_ID

MCP客户端配置

将Terry Form添加到任何兼容MCP的客户端：

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

克劳德桌面（Windows）

{
  "mcpServers": {
    "terry": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "C:\\Users\\YourUsername\\terraform-projects:/mnt/workspace",
        "terry-form-mcp"
      ]
    }
  }
}

克劳德桌面（macOS）

{
  "mcpServers": {
    "terry": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YourUsername/terraform-projects:/mnt/workspace",
        "terry-form-mcp"
      ]
    }
  }
}

VSCode（使用工作空间变量）

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

工具（25）

类别 工具 计数
核心地形 terry, terry_version, terry_environment_check, terry_workspace_list 4
LSP情报 terraform_validate_lsp, terraform_hover, terraform_complete, terraform_format_lsp, terraform_lsp_status 5
诊断 terry_lsp_debug, terry_workspace_info, terry_lsp_init, terry_file_check, terry_workspace_setup, terry_analyze 6
安全 terry_security_scan, terry_recommendations 2
GitHub github_clone_repo, github_list_terraform_files, github_get_terraform_config, github_prepare_workspace 4
地形云 tf_cloud_list_workspaces, tf_cloud_get_workspace, tf_cloud_list_runs, tf_cloud_get_state_outputs 4

核心地形

# Initialize and validate a project
terry(path="infrastructure/aws", actions=["init", "validate"])

# Plan with variables
terry(path="environments/prod", actions=["plan"], vars={"instance_count": "3", "region": "us-east-1"})

仅 init, validate, fmt，以及 plan 是允许的。 apply 和 destroy 被封锁。

LSP情报

# Code completions
terraform_complete(file_path="main.tf", line=10, character=0)

# Hover documentation
terraform_hover(file_path="main.tf", line=15, character=12)

# Detailed validation with error locations
terraform_validate_lsp(file_path="main.tf")

# Format a file
terraform_format_lsp(file_path="main.tf")

由...驱动 terraform-ls v0.38.5--提供上下文感知的补全、内联文档和具有精确源位置的诊断。

GitHub集成

# Clone a repo and prepare it for Terraform operations
github_clone_repo(owner="myorg", repo="infrastructure")
github_prepare_workspace(owner="myorg", repo="infrastructure", config_path="environments/prod")

安全扫描

# Scan for hardcoded credentials, missing encryption, overly permissive policies
terry_security_scan(path="my-project")

# Get actionable improvement recommendations
terry_recommendations(path="my-project")

建筑

┌─────────────┐     MCP Protocol     ┌──────────────────────────────────────┐
│ AI Assistant │ ◄──────────────────► │  Terry-Form MCP Server               │
│ (Claude)     │                      │                                      │
└─────────────┘                      │  ┌─────────────┐  ┌──────────────┐  │
                                     │  │ Terraform    │  │ terraform-ls │  │
                                     │  │ CLI 1.12     │  │ LSP 0.38.5   │  │
                                     │  └──────┬───────┘  └──────┬───────┘  │
                                     │         │                 │          │
                                     │         ▼                 ▼          │
                                     │  ┌──────────────────────────────┐   │
                                     │  │   /mnt/workspace (isolated)   │   │
                                     │  └──────────────────────────────┘   │
                                     └──────────────────────────────────────┘
                                              Docker Container

关键组件

文件 目的
src/server_enhanced_with_lsp.py 主FastMCP服务器——注册所有25个工具
src/terry-form-mcp.py 核心Terraform子流程执行
src/terraform_lsp_client.py 异步LSP客户端包装 terraform-ls
src/mcp_request_validator.py 输入净化、路径遍历预防、速率限制
src/github_repo_handler.py 克隆存储库并提取Terraform文件
src/github_app_auth.py GitHub应用程序JWT/OAuth身份验证
src/frontend/ HAT堆栈web UI（仪表板+配置）

前端堆栈

内置的web UI使用 HAT堆栈:

  • HTMX 2.0——不完全重新加载的部分页面更新
  • **A.**lpine.js 3.14——标签和吐司的轻量级客户端反应
  • Tailwind CSS——暗模式优先实用样式

与一起运行时，可在服务器根目录访问 streamable-http 或 sse 运输。

安全模型

Terry Form采用四层深度防御：

层 保护
集装箱隔离 所有执行都在临时Docker容器中。没有主机访问权限。
操作许可清单 只有 init, validate, fmt, plan不 apply/destroy.
工作区隔离 所有文件操作仅限于 /mnt/workspace。路径遍历被阻止。
输入验证 JSON模式强制、变量净化、每个类别的速率限制。

强制环境变量： TF_IN_AUTOMATION=true, TF_INPUT=false, CHECKPOINT_DISABLE=true.

使用Web UI运行

要使用仪表板和配置UI，请使用HTTP传输运行：

# Local
MCP_TRANSPORT=streamable-http HOST=0.0.0.0 PORT=8000 python3 src/server_enhanced_with_lsp.py

# Docker
docker run -it --rm \
  -p 8000:8000 \
  -v "$(pwd)":/mnt/workspace \
  -e MCP_TRANSPORT=streamable-http \
  terry-form-mcp

然后打开 http://localhost:8000 在您的浏览器中。

配置选项卡

选项卡 它配置了什么
服务器 传输模式、主机、端口、API密钥
GitHub 应用ID、安装ID、私钥路径、webhook密钥
地形云 API令牌
云提供商 AWS、GCP和Azure凭据
速率限制 每类请求限制（立即适用）
地形选项 日志级别，操作超时

集装箱详情

建立在 hashicorp/terraform:1.12 （基于阿尔卑斯山，~150MB）。包括：

  • Terraform CLI 1.12
  • terraform-ls v0.38.5用于LSP支持
  • Python 3.12与FastMCP 3.0+
  • 以非root用户身份运行 terraform （UID 1001）

发展

# Install dependencies
pip install -r requirements.txt

# Run locally
python3 src/server_enhanced_with_lsp.py

# Code quality
black .       # Format (88-char line limit)
flake8 .      # Lint
mypy src/*.py # Type check

局限性

  • 无状态修改 — apply 和 destroy 被故意封锁
  • 仅字符串变量 --CLI直通不支持复杂变量类型
  • LSP冷启动 --第一次LSP操作需要1-2秒进行初始化
  • 本地执行 --专为开发工作流程而非生产CI/CD而设计

许可证

麻省理工学院

相关 MCP