使用说明

地形提供者ContextForge

IBM ContextForge MCP网关管理的Terraform提供商。管理ContextForge MCP网关服务的虚拟服务器、网关、工具、资源、代理和提示。

当前版本：v0.3.0(更改日志.md)

概述

ContextForge Terraform Provider支持基础设施作为IBM ContextForge MCP网关资源的代码管理。提供程序使用Terraform插件框架构建，并与ContextForge MCP网关API通信。

有关ContextForge MCP网关的更多信息，请参阅官方文档.

建筑

提供程序是使用 Terraform插件框架 v1.16.1，并通过 go contextforge v0.8.1客户端库。这 internal/tfconv 该包处理客户端库的Go类型和Terraform插件框架类型之间的类型转换，包括异构映射、身份验证标头和RFC3339时间戳的转换。

需求

地形 >= 1.0
走 >=1.25（用于开发）
访问ContextForge MCP网关实例

快速开始

在您的Terraform配置中配置提供程序：

terraform {
  required_providers {
    contextforge = {
      source  = "registry.terraform.io/hashicorp/contextforge"
      version = "~> 0.2"
    }
  }
}

provider "contextforge" {
  address = "https://contextforge.example.com"
  token   = var.contextforge_token
}

设置环境变量：

export CONTEXTFORGE_ADDR="https://contextforge.example.com"
export CONTEXTFORGE_TOKEN="your-jwt-token"

创建资源：

resource "contextforge_server" "example" {
  name        = "my-mcp-server"
  description = "My MCP virtual server"
}

应用配置：

terraform init
terraform plan
terraform apply

提供程序配置

认证

提供程序支持两个配置属性：

address -（可选）ContextForge MCP网关地址URL（例如。， https://contextforge.example.com).这是一个带有方案、主机名和端口但没有路径的URL。也可以通过以下方式设置 CONTEXTFORGE_ADDR 环境变量。
token -（可选，敏感）JWT令牌，用于与ContextForge MCP网关进行身份验证。也可以通过以下方式设置 CONTEXTFORGE_TOKEN 环境变量。

这两个属性在提供程序配置块中都是可选的，但必须通过配置或环境变量进行设置。配置值优先于环境变量。

配置示例

terraform {
  required_providers {
    contextforge = {
      source  = "registry.terraform.io/hashicorp/contextforge"
      version = "~> 0.2"
    }
  }
}

provider "contextforge" {
  address = "https://contextforge.example.com"
  token   = var.contextforge_token
}

或者，使用环境变量：

export CONTEXTFORGE_ADDR="https://contextforge.example.com"
export CONTEXTFORGE_TOKEN="your-jwt-token"

terraform plan

数据源

contextforge_agent

通过ID检索有关现有ContextForge A2A代理的信息。

示例用法：

data "contextforge_agent" "example" {
  id = "agent-id-12345"
}

output "agent_info" {
  value = {
    name         = data.contextforge_agent.example.name
    endpoint_url = data.contextforge_agent.example.endpoint_url
    enabled      = data.contextforge_agent.example.enabled
  }
}

output "agent_metrics" {
  value = data.contextforge_agent.example.metrics
}

关键属性：

id -（必需）要检索的代理的唯一标识符
name -代理人姓名
description -代理描述
endpoint_url -代理端点URL
enabled -代理是否已启用
capabilities -代理功能（动态对象）
config -代理配置（动态对象）
metrics -带有性能指标（总请求数、成功请求数、失败请求数、故障率、响应时间）的嵌套对象
tags -代理标签
team_id -团队ID
visibility -可见性设置（公共、私人等）
created_at -代理创建时间戳
updated_at -代理上次更新时间戳

有关完整的属性参考，请参阅Terraform注册表文档。

contextforge_gateway

按ID检索有关现有ContextForge MCP网关的信息。

示例用法：

data "contextforge_gateway" "example" {
  id = "gateway-id-12345"
}

output "gateway_url" {
  value = data.contextforge_gateway.example.url
}

output "gateway_status" {
  value = {
    enabled   = data.contextforge_gateway.example.enabled
    reachable = data.contextforge_gateway.example.reachable
  }
}

关键属性：

id -（必填）要检索的网关的唯一标识符
name -网关名称
url -网关端点URL
transport -传输协议（SSE、HTTP、STDIO、STREAMABLEHTTP）
description -网关描述
enabled -网关是否启用
reachable -网关当前是否可访问
created_at -网关创建时间戳
updated_at -网关上次更新时间戳

有关完整的属性参考，请参阅Terraform注册表文档。

contextforge_mpt

按ID检索有关现有ContextForge提示的信息。

示例用法：

data "contextforge_prompt" "example" {
  id = 123
}

output "prompt_info" {
  value = {
    name      = data.contextforge_prompt.example.name
    template  = data.contextforge_prompt.example.template
    is_active = data.contextforge_prompt.example.is_active
  }
}

output "prompt_arguments" {
  value = data.contextforge_prompt.example.arguments
}

output "prompt_metrics" {
  value = data.contextforge_prompt.example.metrics
}

关键属性：

id -（必填）要检索的提示的唯一标识符（整数）
name -提示名称
description -提示说明
template -带有参数占位符的提示模板
arguments -提示参数/参数列表（名称、描述、必填）
is_active -提示是否处于活动状态
tags -提示标签
metrics -具有性能指标的嵌套对象（总执行次数、成功执行次数、失败执行次数、故障率、响应时间）
team_id -团队ID
team -团队名称
owner_email -所有者电子邮件地址
visibility -可见性设置（公共、私人等）
created_at -提示创建时间戳
updated_at -提示上次更新时间戳

有关完整的属性参考，请参阅Terraform注册表文档。

contextforge_source

按ID检索有关现有ContextForge资源的信息。

示例用法：

data "contextforge_resource" "example" {
  id = "1"
}

output "resource_info" {
  value = {
    name      = data.contextforge_resource.example.name
    uri       = data.contextforge_resource.example.uri
    is_active = data.contextforge_resource.example.is_active
  }
}

output "resource_metrics" {
  value = data.contextforge_resource.example.metrics
}

关键属性：

id -（必需）要检索的资源的唯一标识符
uri -资源URI
name -资源名称
description -资源描述
mime_type -资源的MIME类型
size -资源大小（字节）
is_active -资源是否处于活动状态
metrics -具有性能指标的嵌套对象（总执行次数、成功执行次数、失败执行次数、故障率、响应时间）
tags -资源标签
team_id -团队ID
visibility -可见性设置（公共、私人等）
created_at -资源创建时间戳
updated_at -资源上次更新时间戳

有关完整的属性参考，请参阅Terraform注册表文档。

contextforge_server

按ID检索有关现有ContextForge服务器的信息。

示例用法：

data "contextforge_server" "example" {
  id = "server-id-12345"
}

output "server_status" {
  value = {
    name      = data.contextforge_server.example.name
    is_active = data.contextforge_server.example.is_active
  }
}

output "server_metrics" {
  value = data.contextforge_server.example.metrics
}

关键属性：

id -（必需）要检索的服务器的唯一标识符
name -服务器名称
description -服务器描述
icon -服务器图标（URL或数据类型）
is_active -服务器是否处于活动状态
associated_tools -关联的工具ID
associated_resources -关联的资源ID
associated_prompts -相关提示ID
associated_a2a_agents -关联的A2A代理ID
metrics -具有性能指标的嵌套对象（总执行次数、成功执行次数、失败执行次数、故障率、响应时间）
created_at -服务器创建时间戳
updated_at -服务器上次更新时间戳

有关完整的属性参考，请参阅Terraform注册表文档。

contextforge_team

按ID检索有关现有ContextForge团队的信息。

示例用法：

data "contextforge_team" "example" {
  id = "team-id-12345"
}

output "team_info" {
  value = {
    name         = data.contextforge_team.example.name
    slug         = data.contextforge_team.example.slug
    is_personal  = data.contextforge_team.example.is_personal
    is_active    = data.contextforge_team.example.is_active
    member_count = data.contextforge_team.example.member_count
  }
}

关键属性：

id -（必填）要检索的团队的唯一标识符
name -团队名称
slug -Team slug（URL友好标识符）
description -团队描述
is_personal -这是否是一个个人团队
visibility -可见性设置（公共、私人等）
max_members -团队中允许的最大成员数
member_count -团队当前成员人数
is_active -团队是否活跃
created_by -创建团队的用户的电子邮件地址
created_at -团队创建时间戳（RFC3339格式）
updated_at -团队上次更新时间戳（RFC3339格式）

有关完整的属性参考，请参阅Terraform注册表文档。

contextforge_tool

按ID检索有关现有ContextForge工具的信息。

示例用法：

data "contextforge_tool" "example" {
  id = "tool-id-12345"
}

output "tool_info" {
  value = {
    name    = data.contextforge_tool.example.name
    enabled = data.contextforge_tool.example.enabled
  }
}

output "tool_input_schema" {
  value = data.contextforge_tool.example.input_schema
}

关键属性：

id -（必填）要检索的工具的唯一标识符
name -工具名称
description -工具说明
input_schema -JSON模式定义工具输入参数
enabled -工具是否启用
tags -工具标签
team_id -团队ID
visibility -可见性设置（公共、私人等）
created_at -工具创建时间戳
updated_at -工具上次更新时间戳

有关完整的属性参考，请参阅Terraform注册表文档。

资源

提供程序支持以下托管资源的完整CRUD操作。

contextforge_agent（资源）

管理ContextForge A2A（代理到代理）代理资源。

示例用法：

resource "contextforge_agent" "example" {
  name         = "my-agent"
  endpoint_url = "https://agent.example.com/api"
  description  = "My A2A agent"
  enabled      = true
  tags         = ["production", "a2a"]
}

所需属性：

name -代理人姓名
endpoint_url -代理端点URL

可选属性：

description -代理描述
agent_type -代理类型
protocol_version -协议版本
config -代理配置（动态对象）
auth_type -身份验证类型
enabled -代理是否已启用
tags -标签列表
team_id -团队ID
visibility -可见性设置

只读属性：

id -代理唯一标识符
slug -URL友好标识符
capabilities -代理功能（动态对象）
reachable -代理是否可访问
metrics -性能指标对象
created_at, updated_at -时间戳

contextforge_gateway（资源）

管理ContextForge MCP网关资源。

示例用法：

resource "contextforge_gateway" "example" {
  name        = "my-gateway"
  url         = "http://localhost:8080/sse"
  transport   = "SSE"
  description = "My MCP gateway"
  enabled     = true
  tags        = ["production"]
}

所需属性：

name -网关名称
url -网关终结点URL（必须可访问）
transport -传输协议（SSE、HTTP、STDIO、STREAMABLEHTTP）

可选属性：

description -网关描述
enabled -网关是否启用
auth_type -身份验证类型
auth_username, auth_password -基本身份验证凭据
auth_token -承载令牌身份验证
auth_header_key, auth_header_value -自定义标头身份验证
oauth_config -OAuth配置（动态对象）
tags -标签列表
team_id -团队ID
visibility -可见性设置

只读属性：

id -网关唯一标识符
slug -URL友好标识符
reachable -网关是否可达
capabilities -网关功能（动态对象）
created_at, updated_at, last_seen -时间戳

contextforge_source（资源）

管理ContextForge资源实体。

示例用法：

resource "contextforge_resource" "example" {
  uri         = "config://app/settings"
  name        = "app-settings"
  content     = jsonencode({ theme = "dark", language = "en" })
  description = "Application settings"
  mime_type   = "application/json"
  tags        = ["config"]
}

所需属性：

uri -资源URI
name -资源名称
content -资源内容（只读，API不返回）

可选属性：

description -资源描述
mime_type -资源的MIME类型
tags -标签列表
team_id -团队ID（只能在创建时设置）
visibility -可见性设置（只能在创建时设置）

只读属性：

id -资源唯一标识符
size -资源大小（字节）
is_active -资源是否处于活动状态
metrics -性能指标对象
created_at, updated_at -时间戳

contextforge_server（资源）

管理ContextForge虚拟服务器资源。

示例用法：

resource "contextforge_server" "example" {
  name        = "my-server"
  description = "My MCP virtual server"
  icon        = "https://example.com/icon.png"
  tags        = ["production"]

  associated_tools     = ["tool-id-1", "tool-id-2"]
  associated_resources = ["resource-id-1"]
  associated_prompts   = ["prompt-id-1"]
}

所需属性：

name -服务器名称

可选属性：

description -服务器描述
icon -服务器图标URL
associated_tools -相关工具ID列表
associated_resources -关联资源ID列表
associated_prompts -相关提示ID列表
associated_a2a_agents -关联的A2A代理ID列表
tags -标签列表
team_id -团队ID
visibility -可见性设置

只读属性：

id -服务器唯一标识符
is_active -服务器是否处于活动状态
metrics -性能指标对象（总执行次数、成功执行次数、失败执行次数、故障率、响应时间）
created_at, updated_at -时间戳

contextforge_tool（资源）

管理ContextForge工具资源。

示例用法：

resource "contextforge_tool" "example" {
  name        = "my-tool"
  description = "My MCP tool"
  enabled     = true
  tags        = ["utility"]

  input_schema = jsonencode({
    type = "object"
    properties = {
      message = {
        type        = "string"
        description = "The message to process"
      }
    }
    required = ["message"]
  })
}

所需属性：

name -工具名称

可选属性：

description -工具说明
input_schema -JSON模式定义工具输入参数（动态）
enabled -工具是否启用
tags -标签列表
team_id -团队ID
visibility -可见性设置

只读属性：

id -工具唯一标识符
created_at, updated_at -时间戳

发展

先决条件

走 >= 1.25
地形 >= 1.0
uvx （用于集成测试）
jq （用于集成测试脚本）

构建供应商

生成提供程序二进制文件：

make build

这将创建 terraform-provider-contextforge 项目根目录中的二进制文件。

安装以促进当地发展

将提供程序安装到您本地的Terraform插件目录：

make install

这将构建并复制提供程序二进制文件到 $GOPATH/bin.

持续集成

该项目使用GitHub Actions进行自动化测试。工作流在以下平台上运行：

推至 master 分支
拉取请求

工作流作业：

单元测试 -运行单元测试并验证提供程序构建是否成功
验收测试 -运行完整的集成测试生命周期：
- 使用启动本地ContextForge网关 uvx
- 运行验收测试 TF_ACC=1
- 清理网关和测试工件

看 .github/workflows/test.yml 以获取完整的工作流配置。

测试

单元测试

运行单元测试套件：

make test

集成测试

集成测试需要一个正在运行的ContextForge MCP网关实例。测试基础架构使用以下方式自动管理本地网关 uvx 和那个 mcp-contextforge-gateway 包裹。

运行完整的集成测试生命周期：

make integration-test-all

该目标：

在上启动本地ContextForge网关 http://localhost:8000
生成用于身份验证的JWT令牌
创建测试资源（网关、服务器、工具、资源、团队、代理、提示）
使用运行集成测试 TF_ACC=1
测试完成后拆除网关

手动集成测试工作流程：

# Start the gateway
make integration-test-setup

# Run integration tests
make integration-test

# Stop the gateway
make integration-test-teardown

集成测试基础设施：

集成测试设置脚本创建了一个完整的测试环境：

ContextForge网关 -在端口8000上启动网关
- 创建管理员用户(admin@test.local)
- 生成7天到期的JWT令牌
- 令牌存储在 tmp/contextforge-test-token.txt
- 网关PID输入 tmp/contextforge-test.pid
- 登录 tmp/contextforge-test.log
MCP时间服务器 -在端口8002上启动测试MCP服务器
- 为网关连接验证提供真正的MCP端点
- 用途 mcp-server-time 通过 mcpgateway.translate 包装器
- PID存储在 tmp/time-server.pid
测试资源 -为验收测试创建测试实体
- 测试网关、服务器、工具、资源、团队、代理和提示
- ID保存到 tmp/contextforge-test-*-id.txt 文件

生成文件目标

目标	描述
`build`	构建提供程序二进制文件
`install`	在本地安装提供程序以进行手动测试
`test`	运行单元测试
`clean`	清理构建工件和dist目录
`integration-test-setup`	启动本地ContextForge网关进行集成测试
`integration-test-teardown`	停止本地ContextForge网关并清理
`integration-test`	运行集成测试（需要运行网关）
`integration-test-all`	运行完整的集成测试生命周期（设置->测试->拆卸）
`help`	显示帮助信息

贡献

欢迎捐款。贡献时：

跟随 Go风格指南
确保所有测试通过(make test)
运行集成测试(make integration-test-all)
对提交消息使用常规提交格式
根据需要更新文档

文档：

看 CLAUDE.md 了解详细的体系结构、实现模式和开发人员指南
看更改日志.md 查看版本历史记录和发行说明

依赖关系：

Terraform插件框架 v1.16.1
go contextforge v0.8.1-用于ContextForge MCP网关的Go客户端库

使用说明

地形提供者ContextForge

目录

概述

建筑

需求

快速开始

提供程序配置

认证

配置示例

数据源

contextforge_agent

contextforge_gateway

contextforge_mpt

contextforge_source

contextforge_server

contextforge_team

contextforge_tool

资源

contextforge_agent（资源）

contextforge_gateway（资源）

contextforge_source（资源）

contextforge_server（资源）

contextforge_tool（资源）

发展

先决条件

构建供应商

安装以促进当地发展

持续集成

测试

单元测试

集成测试

生成文件目标

贡献

相关 MCP

Primavera P6 XER文件解析服务器

Terraform Registry MCP 服务器

Kubernetes资源管理工具

Magic-API开发MCP服务

MCP服务器创建工具

Heroku平台MCP服务器