Terry-Form MCP 是一个模型控制协议(MCP)服务器,它允许 AI 助手通过使用 HashiCorp 官方 Terraform 镜像的安全容器化环境在本地执行 Terraform 命令。现在,该项目通过集成语言服务器协议(LSP),增强了智能 Terraform 开发能力。
# 使用提供的脚本构建(Linux/macOS)
./build.sh
# 或者 Windows 用户使用
build.bat
# 也可以直接使用 Docker 构建
docker build -t terry-form-mcp .
# 作为 MCP 服务器运行
docker run -it --rm \
-v "$(pwd)":/mnt/workspace \
terry-form-mcp
# 创建一个测试工作区
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
# 检查 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))"
init
- 初始化 Terraform 工作目录validate
- 验证 Terraform 配置语法fmt
- 检查 Terraform 代码格式plan
- 生成并显示执行计划(支持变量)/mnt/workspace
挂载点pip install fastmcp asyncio
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 客户端
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"])
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
}
]
}
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
terry
和 LSP 工具本项目采用 MIT 许可证,详情请参阅 LICENSE 文件。
大多数支持 MCP 的 IDE 都有配置文件或 UI。以下是一个跨平台通用的配置:
{
"mcpServers": {
"terry": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "/path/to/your/workspace:/mnt/workspace",
"terry-form-mcp"
]
}
}
}
{
"mcpServers": {
"terry": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "C:\\Users\\YourUsername\\terraform-projects:/mnt/workspace",
"terry-form-mcp"
]
}
}
}
{
"mcpServers": {
"terry": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "/Users/YourUsername/terraform-projects:/mnt/workspace",
"terry-form-mcp"
]
}
}
}
{
"mcpServers": {
"terry": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "/home/YourUsername/terraform-projects:/mnt/workspace",
"terry-form-mcp"
]
}
}
}
对于支持 MCP 的 VSCode 扩展,在 settings.json 中添加以下内容:
{
"mcp.servers": {
"terry": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "${workspaceFolder}:/mnt/workspace",
"terry-form-mcp"
]
}
}
}
LSP 集成相对于基本的 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
Docker 容器化
只读文件系统挂载
/mnt/workspace
操作限制
网络隔离
输入验证
安全执行模式
LSP 未初始化
terry_environment_check()
检查容器中是否有 terraform-lsterry_lsp_init(workspace_path="your-project")
手动初始化Docker 挂载问题
LSP 功能无法正常工作
terraform_lsp_status()
检查 LSP 状态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 操作,请使用适当的 CI/CD 管道,并采取相应的安全控制和状态管理措施。