使用说明

Terraform MCP服务器+合作伙伴管理资源

Terraform MCP服务器是一个模型上下文协议（MCP）服务器，提供与Terraform注册表API的无缝集成，实现高级基础设施即代码（IaC）开发的自动化和交互能力。

此分支使用合作伙伴管理的资源扩展了基础服务器 -通过AWS security Hub集成和HCP Terraform实现人工智能辅助的安全补救。

新增内容：合作伙伴管理的资源

┌─────────────────────────────────────────────────────────────────────────────────┐
│                    PARTNER-MANAGED RESOURCES WORKFLOW                            │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│  ┌──────────────┐                                      ┌──────────────┐         │
│  │ AWS Security │   Discover    ┌──────────────┐       │ HCP Terraform│         │
│  │     Hub      │──────────────▶│   MCP Server │──────▶│  (CLI-Driven │         │
│  │  (Findings)  │               │              │       │   Workspace) │         │
│  └──────────────┘               │  • Sync      │       └──────┬───────┘         │
│                                 │  • Analyze   │              │                  │
│  ┌──────────────┐               │  • Link      │              ▼                  │
│  │    Claude    │◀─────────────▶│  • Remediate │       ┌──────────────┐         │
│  │   Desktop    │   Converse    │              │       │     AWS      │         │
│  │  or CLI      │               └──────────────┘       │  Resources   │         │
│  └──────────────┘                                      │   (Fixed!)   │         │
│                                                        └──────────────┘         │
└─────────────────────────────────────────────────────────────────────────────────┘

关键能力

安全发现：自动从AWS安全中心提取调查结果
自动ARN→ 地形测绘：发现工作区，解析状态，并将ARN自动链接到Terraform地址
自动修复：通过HCP Terraform生成和应用Terraform修复程序
CLI驱动的工作流：适用于CLI驱动的工作区（通过API上载的配置）

自动资源映射的工作原理

当您提供HCP Terraform组织时，系统 自动发现并链接 资源：

sync_recommendations(terraform_org: "my-org")
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 1. DISCOVER WORKSPACES                                                   │
│    Lists all workspaces in your org (via HCP Terraform API)             │
└─────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 2. INDEX TERRAFORM STATE                                                 │
│    For each workspace, parses state and extracts cloud resource IDs:    │
│    - ARNs from aws_security_group, aws_instance, aws_s3_bucket, etc.    │
│    - Builds index: ARN → Terraform address                              │
│    Example: "arn:aws:ec2:...:sg-xxx" → "aws_security_group.web"         │
└─────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 3. SYNC & AUTO-LINK                                                      │
│    Fetches findings from Security Hub, matches ARNs to Terraform        │
│    Result: Each finding knows its Terraform resource automatically!     │
└─────────────────────────────────────────────────────────────────────────┘

无需手动链接！ 只需提供 terraform_org 并且系统处理映射。

支持的资源映射

自动发现系统支持以下AWS到Terraform资源映射：

AWS安全中心类型	地形资源类型
AwsEc2Instance	aws_instance
awsEc2安全组	aws_security_group
awsEc2卷	aws_ebs_volume
AwsEc2Vpc	aws_vpc
awsEc2子网	aws_subnet
awsEc2网络接口	aws_network_interface
AwsS3Bucket	aws_s3_bucket
awsIam用户	aws_iam_user
AwsIamRole	aws_iam_role
AwsIamPolicy	aws_iam_policy
awsIam访问密钥	aws_iam_access_key
awsLambda函数	aws_lambda_函数
AwsRdsDbInstance	aws_db_instance
AwsRdsDbCluster	aws_rds_cluster
AwsKmsKey	aws_kms_key
AwsSecretsManagerSecret	aws_secretsmanger_secret
AwsSqsQueue	aws_sqs_queue
AwsSnsTopic	aws_sns_topic
awsSns订阅	aws_sns_topic_subscription
aws_cloudfront_diistribution
AwsElbLoadBalancer	aws_elb
AwsElbv2LoadBalancer	aws_lb
awsApi网关RestApi	aws_api_gateway_rest_api
AwsDynamoDbTable	aws_dynamodb_table
awsElasticsearch域名	aws_elasticsearch_domain
AwsEksCluster	aws_eks_cluster
AwsEcsCluster	aws_ecs_cluster
AwsEcsService	aws_ecs_service

资源如何匹配：系统从Terraform状态中提取云资源ID，并使用ARN将其与安全中心的发现进行匹配。对于每种资源类型，都会检查这些属性（按顺序）：

地形资源	ID属性（优先级顺序）
aws_instance	arn，id
aws_s3_bucket	arn、bucket、id
aws_security_group	arn，id
aws_lambda_function	arn，函数名
aws_db_instance	arn、id、标识符
aws_iam_role	arn、id、名称
aws_iam_user	arn、id、名称
aws_kms_key	arn，key_id，id
aws_lb/aws_alb	arn，id
aws_autoscaling_group	arn、id、名称
（其他）	arn，id

CLI驱动与VCS驱动的工作区

此扩展专为 CLI驱动的工作区 哪里：

Terraform配置通过HCP Terraform API直接上传
运行是以编程方式触发的（不是通过Git提交）
AI助手管理配置生命周期

CLI-Driven Workflow (Supported):
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ Download    │───▶│ Generate    │───▶│ Upload New  │───▶│ Create &    │
│ Current     │    │ Fix Code    │    │ Config      │    │ Apply Run   │
│ Config      │    │             │    │ Version     │    │             │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

VCS-Driven Workflow (Experimental - via GitHub PR):
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ Clone       │───▶│ Generate    │───▶│ Create PR   │───▶│ Merge &     │
│ Repository  │    │ Fix Code    │    │ on GitHub   │    │ Auto-Apply  │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

特性

双重运输支持：具有可配置端点的Stdio和StreamableHTTP传输
地形注册表集成：与提供者、模块和策略的公共Terraform注册表API直接集成
HCP平台和平台企业支持：完整的工作区管理、组织/项目列表和私有注册表访问
工作区操作：创建、更新、删除支持变量、标记和运行管理的工作区
合作伙伴管理的资源：安全建议同步、分析和自动修复

安全说明： 在此阶段，MCP服务器仅供本地使用。如果使用StreamableHTTP传输，请始终配置MCP_ALLOWED_ORIGINS环境变量，以限制仅访问受信任的源。

安全说明： 根据查询，MCP服务器可能会向MCP客户端和LLM公开某些Terraform数据。不要将MCP服务器与不受信任的MCP客户端或LLM一起使用。

注意： MCP服务器提供的输出和建议是动态生成的，可能因查询、模型和连接的MCP客户端而异。用户在实施之前应彻底审查所有输出/建议。

快速入门（合作伙伴管理资源）

1.构建服务器

git clone <repository>
cd cc-partner-managed-resources
go build -o terraform-mcp-server ./cmd/terraform-mcp-server

2.配置克劳德桌面

macOS: ~/.config/claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "terraform": {
      "command": "/absolute/path/to/terraform-mcp-server",
      "args": ["--toolsets=partner,terraform"],
      "env": {
        "TFE_TOKEN": "your-hcp-terraform-token",
        "TFE_ADDRESS": "https://app.terraform.io",
        "AWS_ACCESS_KEY_ID": "your-aws-access-key",
        "AWS_SECRET_ACCESS_KEY": "your-aws-secret-key",
        "AWS_REGION": "us-west-2",
        "ENABLE_TF_OPERATIONS": "true"
      }
    }
  }
}

3.与Claude一起使用

User: "Configure AWS Security Hub for us-west-2"
User: "Sync security recommendations"
User: "Show me HIGH severity findings"
User: "Remediate the SSH security group finding"

可用工具集

工具集	描述	用例
`registry`	公共地形注册表	搜索提供者、模块、文档
`registry-private`	私有注册表访问	私有模块和提供程序
`terraform`	HCP地形操作	工作区管理、运行、状态
`partner`	合作伙伴管理的资源	安全建议、补救措施
`all`	所有工具集结合在一起	功能齐全
`default`	注册表+地形	标准用法

合作伙伴工具集-工具参考

配置工具

工具	说明
`configure_aws_security_hub`	将AWS Security Hub设置为推荐源
`configure_aws_recommendations`	设置AWS计算优化器（成本优化）
`list_recommendation_sources`	列出所有已配置的源

发现工具

工具	说明
`sync_recommendations`	从配置的源中提取最新发现
`list_recommendations`	使用过滤器进行查询（严重性、类别、状态）
`get_recommendation`	获取特定发现的完整细节

补救工具

工具	说明
`link_recommendation_resource`	地图查找到Terraform资源地址
`remediate_recommendation`	生成修复程序并通过HCP Terraform应用
`preview_remediation`	预览更改而不应用
`apply_remediation`	应用以前预览的更改

资源管理工具

工具	说明
`register_resources`	在合作伙伴注册表中注册Terraform资源
`resolve_resources`	将ARN解析为Terraform地址
`get_resource_state`	获取资源的当前地形状态
`get_drift_status`	检查基础设施漂移

工具工作流序列

合作伙伴工具遵循特定的工作流程顺序：

1. Configure     →  2. Sync         →  3. Review       →  4. Remediate
   ─────────        ──────────         ────────          ─────────────
   configure_aws_   sync_              list_             remediate_
   security_hub     recommendations    recommendations   recommendation
   (or configure_   (with terraform_   get_              (or preview_ +
   aws_             org for auto-      recommendation    apply_
   recommendations) discovery)                           remediation)

笔记：

sync_recommendations 和 terraform_org 自动发现并链接资源
通过手动链接 link_recommendation_resource 仅在自动发现失败时才需要（例如，无法识别的ARN格式）
使用 preview_remediation 在应用之前查看更改

环境变量

核心变量

变量	描述	默认值
`TFE_ADDRESS`	HCP地形或TFE地址	`https://app.terraform.io`
`TFE_TOKEN`	Terraform Enterprise API令牌	（必需）
`TFE_SKIP_TLS_VERIFY`	跳过TLS验证	`false`
`ENABLE_TF_OPERATIONS`	启用地形操作	`false`

合作伙伴变量

变量	描述	默认值
`AWS_ACCESS_KEY_ID`	AWS访问密钥	（合作伙伴需要）
`AWS_SECRET_ACCESS_KEY`	AWS密钥	（合作伙伴需要）
`AWS_REGION`	AWS区域	`us-west-2`
`GITHUB_TOKEN`	GitHub令牌（用于VCS工作流）	（可选）

传输变量

变量	描述	默认值
`TRANSPORT_MODE`	`stdio` 或 `streamable-http`	`stdio`
`TRANSPORT_HOST`	HTTP服务器主机	`127.0.0.1`
`TRANSPORT_PORT`	HTTP服务器端口	`8080`
`MCP_ENDPOINT`	HTTP端点路径	`/mcp`

测试

E2E测试套件

全面的E2E测试环境可在 test-e2e-remediation/:

cd test-e2e-remediation/scripts

# Configure credentials
cp env.sh.template env.sh
# Edit env.sh with your credentials

# Run MCP CLI test (no Claude Desktop required)
source env.sh
python3 mcp-full-test.py

# Or run the full infrastructure test
./01-setup-workspace.sh
./02-deploy-infrastructure.sh
# ... (see test-e2e-remediation/README.md)

看 test-e2-mediation/README.md 完整的测试文档，包括：

MCP CLI测试（无克劳德桌面）
Claude桌面测试，带有逐步提示
验证测试结果

示例：安全补救工作流

┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 1: Configure                                                            │
│ > configure_aws_security_hub(region: "us-west-2", categories: ["security"]) │
│ ✓ Configured AWS Security Hub (us-west-2)                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│ Step 2: Sync with Auto-Discovery                                             │
│ > sync_recommendations(terraform_org: "my-org")  ← Enables auto-linking!    │
│ ✓ Synced 20 findings from AWS Security Hub                                  │
│ ✓ Indexed 5 workspaces with 47 resources                                    │
│ ✓ Auto-linked 3 recommendations to Terraform                                │
├─────────────────────────────────────────────────────────────────────────────┤
│ Step 3: List (already linked!)                                               │
│ > list_recommendations(severity: "high", managed_only: true)                │
│ ✓ [HIGH] EC2.19 - Security group allows SSH from 0.0.0.0/0                  │
│   Resource: sg-096b4ac3e0159bed6                                            │
│   Terraform: aws_security_group.vulnerable  ← Auto-linked!                  │
├─────────────────────────────────────────────────────────────────────────────┤
│ Step 4: Remediate (no manual linking needed!)                                │
│ > remediate_recommendation(rec_id, confirm: true)                           │
│ ✓ Run created: run-wQvXTgsbk9MXQd5r                                         │
│ ✓ Status: applied                                                            │
│ ✓ SSH CIDR changed: 0.0.0.0/0 → 10.0.0.0/8                                  │
└─────────────────────────────────────────────────────────────────────────────┘

项目结构

cc-partner-managed-resources/
├── cmd/terraform-mcp-server/     # Main server binary
├── pkg/
│   ├── partner/                  # Partner package
│   │   ├── recommendation_types.go    # Data structures
│   │   ├── recommendation_source.go   # Source interface
│   │   ├── recommendation_registry.go # Session storage
│   │   ├── code_generator.go          # Terraform fix generation
│   │   └── sources/
│   │       └── aws_security_hub.go    # AWS Security Hub source
│   ├── tools/partner/            # MCP tool implementations
│   ├── toolsets/                 # Toolset definitions
│   └── client/                   # Session and client management
├── test-e2e-remediation/         # E2E test environment
│   ├── terraform/                # Vulnerable test infrastructure
│   ├── scripts/                  # Test scripts (CLI + Claude Desktop)
│   └── docs/                     # Test documentation and results
└── README.md                     # This file

代码生成

基于HCL的修改（当前实施）

修复代码生成器(pkg/partner/code_generator.go)用途 HashiCorp hclwrite 图书馆 正确操作HCL AST：

// Parse HCL content
file, diags := hclwrite.ParseConfig([]byte(content), "main.tf", hcl.InitialPos)

// Find and modify resource blocks
resourceBlock := findResourceBlock(body, "aws_security_group", "vulnerable")

// Find nested blocks with criteria matching (e.g., ingress with from_port=22)
for _, block := range body.Blocks() {
    if block.Type() == "ingress" && blockMatchesCriteria(block, {"from_port": "22"}) {
        block.Body().SetAttributeValue("cidr_blocks", cty.ListVal(...))
    }
}

// Output preserves formatting
return string(file.Bytes())

什么效果好：

正确的HCL AST解析和序列化
嵌套块处理（入口/出口规则、元数据选项、版本配置）
选择性块修改（例如，仅SSH入口，而非HTTPS）
类型感知属性设置（列表、布尔值、字符串、数字）
保留格式和结构
如果HCL解析失败，则回退到字符串替换

支持的修复程序：

检查ID	查找	已应用修复
EC2.19	SSH打开到0.0.0.0/0	`cidr_blocks = ["10.0.0.0/8"]`
EC2.18	RDP打开到0.0.0.0/0	`cidr_blocks = ["10.0.0.0/8"]`
EC2.3/EC2.7	EBS/EC2未加密	`encrypted = true`
EC2.8	不需要IMDSv2	`http_tokens = "required"`
S3.14	版本控制已禁用	`status = "Enabled"`
成本	实例过大	`instance_type = "m5.large"`

未来改进

可插拔修复策略
- 将修复模式定义为配置/插件
- 允许每个组织自定义补救规则
- 支持特定于组织的安全策略
试运行验证
- 跑 terraform validate 上传前生成的代码
- 在创建运行之前捕获语法错误
其他推荐来源
- AWS Trusted Advisor（需要业务支持计划）
- AWS计算优化器（成本优化-部分实施）
- 第三方安全平台

未充分利用的功能

这些功能已实现，但可能不常用：

特性	工具/参数	说明
`managed_only`	`list_recommendations`	仅筛选到Terraform管理的资源
`force_refresh`	`sync_recommendations`	强制重新同步，即使最近已同步
`preview_only`	`remediate_recommendation`	预览更改而不应用
`VCS workflow`	`apply_remediation`	创建GitHub PR，而不是直接上传

原始Terraform MCP服务器文档

先决条件

确保码头工人已安装并正在运行，以便在容器化环境中使用服务器。
安装一个支持模型上下文协议（MCP）的AI助手。

命令行选项

# Stdio mode
terraform-mcp-server stdio [--log-file /path/to/log] [--toolsets <toolsets>] [--tools <tools>]

# StreamableHTTP mode
terraform-mcp-server streamable-http [--transport-port 8080] [--transport-host 127.0.0.1] [--mcp-endpoint /mcp] [--log-file /path/to/log] [--toolsets <toolsets>] [--tools <tools>]

说明

MCP服务器的默认说明位于 cmd/terraform-mcp-server/instructions.md，如果这些似乎不适合您组织的Terraform实践，或者如果MCP服务器产生了不准确的响应，请用您自己的说明替换它们，并重建容器或二进制文件。

安装

与Visual Studio代码一起使用

将以下JSON块添加到VS Code中的用户设置（JSON）文件中。您可以按 Ctrl + Shift + P 和打字 Preferences: Open User Settings (JSON).

{
  "mcp": {
    "servers": {
      "terraform": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "-e", "TFE_TOKEN=${input:tfe_token}",
          "-e", "TFE_ADDRESS=${input:tfe_address}",
          "hashicorp/terraform-mcp-server"
        ]
      }
    }
  }
}

使用Claude Desktop

{
  "mcpServers": {
    "terraform": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TFE_ADDRESS=<<PASTE_TFE_ADDRESS_HERE>>",
        "-e", "TFE_TOKEN=<<PASTE_TFE_TOKEN_HERE>>",
        "hashicorp/terraform-mcp-server"
      ]
    }
  }
}

使用Claude代码

claude mcp add terraform -s user -t stdio -- docker run -i --rm hashicorp/terraform-mcp-server

从源代码安装

go install github.com/hashicorp/terraform-mcp-server/cmd/terraform-mcp-server@latest

在本地构建Docker镜像

git clone https://github.com/hashicorp/terraform-mcp-server.git
cd terraform-mcp-server
make docker-build

# Run in stdio mode
docker run -i --rm terraform-mcp-server:dev

# Run in streamable-http mode
docker run -p 8080:8080 --rm -e TRANSPORT_MODE=streamable-http -e TRANSPORT_HOST=0.0.0.0 terraform-mcp-server:dev

# Filter tools (optional)
docker run -i --rm terraform-mcp-server:dev --toolsets=registry,terraform

可用工具

在此处查看可用工具

工具筛选

控制可用的工具 --toolsets （团体）或 --tools （个人）：

# Enable tool groups
terraform-mcp-server --toolsets=registry,terraform,partner

# Enable specific tools only
terraform-mcp-server --tools=search_providers,get_provider_details,list_workspaces

运输支持

1.标准运输（默认）

使用JSON-RPC消息的标准输入/输出通信。非常适合当地发展。

2.可流式HTTP传输

现代基于HTTP的传输支持直接HTTP请求和服务器发送事件（SSE）流。

端点: http://{hostname}:8080/mcp
健康检查: http://{hostname}:8080/health

发展

先决条件

去（检查 go.mod 特定版本的文件）
Docker（可选，用于容器构建）

可用的生成命令

命令	描述
`make build`	构建二进制文件
`make test`	运行所有测试
`make test-e2e`	运行端到端测试
`make docker-build`	构建Docker镜像
`make run-http`	在本地运行HTTP服务器
`make clean`	删除构建工件

许可证

此项目根据MPL-2.0开源许可证的条款获得许可。请参考许可证提交完整条款的文件。

支持

有关错误报告和功能请求，请在GitHub上打开问题。

使用说明

Terraform MCP服务器+合作伙伴管理资源

新增内容：合作伙伴管理的资源

关键能力

自动资源映射的工作原理

支持的资源映射

CLI驱动与VCS驱动的工作区

特性

快速入门（合作伙伴管理资源）

1.构建服务器

2.配置克劳德桌面

3.与Claude一起使用

可用工具集

合作伙伴工具集-工具参考

配置工具

发现工具

补救工具

资源管理工具

工具工作流序列

环境变量

核心变量

合作伙伴变量

传输变量

测试

E2E测试套件

示例：安全补救工作流

项目结构

代码生成

基于HCL的修改（当前实施）

未来改进

未充分利用的功能

原始Terraform MCP服务器文档

先决条件

命令行选项

说明

安装

与Visual Studio代码一起使用

使用Claude Desktop

使用Claude代码

从源代码安装

在本地构建Docker镜像

可用工具

工具筛选

运输支持

1.标准运输（默认）

2.可流式HTTP传输

发展

先决条件

可用的生成命令

许可证

支持

相关 MCP

Terraform Registry MCP 服务器

图像生成服务器

CDK最佳实践服务

Terraform MCP 服务器

AWS MCP 服务器套件

GCP资源管理工具