Turbot Guardrails Model Context Protocol (MCP) Server

Turbot Guardrails 模型上下文协议（MCP）服务

借助 Turbot Guardrails，释放 AI 驱动的云治理能力！此模型上下文协议（MCP）服务将 Claude 等 AI 助手连接到您的 Guardrails 数据，让您能够通过自然语言探索、分析和自动化管理整个云环境。

Guardrails MCP 搭建起 AI 助手与您的 Guardrails 环境之间的桥梁，支持通过自然语言：

• 使用 GraphQL 查询和分析云资源
• 列出并筛选资源、控制和策略类型
• 执行控制并查看合规性
• 探索 GraphQL 架构以编写自定义查询
• 使用 Nunjucks 处理模板，以实现动态配置

安装

先决条件

• Node.js v20 或更高版本
• 具有适当权限的 Turbot Guardrails API 密钥
• 您的 Guardrails 工作区端点 URL

配置

Guardrails MCP 支持两种身份验证方式。环境变量名称与 Turbot CLI 一致，因此已配置 CLI 的用户无需重新定义凭据。旧版 v0.1.x 名称仍可作为别名使用。

首选：Turbot CLI 配置档案

如果您使用 Turbot CLI，应该已经有一个包含命名配置档案的 credentials.yml 文件。按名称引用其中一个配置档案：

{
  "mcpServers": {
    "turbot-guardrails": {
      "command": "npx",
      "args": ["-y", "@turbot/guardrails-mcp"],
      "env": {
        "TURBOT_PROFILE": "your-profile-name"
      }
    }
  }
}

默认情况下，MCP 会读取 ~/.config/turbot/credentials.yml。如需使用其他位置，请设置 TURBOT_CLI_CREDENTIALS_PATH — ~ 会自动展开，因此在不经过 shell 的 JSON 配置中也可以使用 ~/Documents/turbot.yml。

credentials.yml 示例：

demo-acme:
  workspace: https://demo-acme.cloud.turbot.com
  accessKey: abcdefgh-1234-0808-wxyz-123456789012
  secretKey: hgfedcba-1234-0101-aaaa-aabbccddee00

备选：直接设置环境变量

在 MCP 服务配置中直接设置全部三个凭据变量：

{
  "mcpServers": {
    "turbot-guardrails": {
      "command": "npx",
      "args": ["-y", "@turbot/guardrails-mcp"],
      "env": {
        "TURBOT_WORKSPACE": "https://demo-acme.cloud.turbot.com",
        "TURBOT_ACCESS_KEY": "abcdefgh-1234-0808-wxyz-123456789012",
        "TURBOT_SECRET_KEY": "hgfedcba-1234-0101-aaaa-aabbccddee00"
      }
    }
  }
}

TURBOT_WORKSPACE 可接受工作区 URL，也可接受完整的 GraphQL 端点。如果缺少 /api/latest/graphql 后缀，系统会自动添加，并会规范化末尾的斜杠和空格。

如果同时设置两种方式，则直接凭据优先（与 Turbot CLI 的优先级一致）。至少有一个直接变量缺失时，才会使用配置档案。

向后兼容性（v0.1.x 环境变量名称）

现有 v0.1.x 配置无需更改即可继续使用。旧名称与 CLI 统一名称的对应关系如下：

CLI 统一名称（首选）	旧版别名（仍可接受）
TURBOT_PROFILE	TURBOT_CLI_PROFILE
TURBOT_WORKSPACE	TURBOT_GRAPHQL_ENDPOINT
TURBOT_ACCESS_KEY	TURBOT_ACCESS_KEY_ID
TURBOT_SECRET_KEY	TURBOT_SECRET_ACCESS_KEY

同一字段同时设置两个名称时，以 CLI 统一名称为准。新配置应使用 CLI 统一名称。

AI 助手设置

助手	配置文件位置	设置指南
Claude Desktop	claude_desktop_config.json	Claude Desktop MCP 指南 →
Cursor	~/.cursor/mcp.json	Cursor MCP 指南 →

保存配置文件并重启 AI 助手，使更改生效。

提示词指南

先询问有关 Guardrails 环境的问题，例如：

What AWS accounts can you see in Guardrails?

简单、具体的问题效果很好：

Show me all S3 buckets created in the last week

生成合规与安全报告：

List all EC2 instances that are non-compliant with our tagging standards

探索策略和控制类型：

Show me all policy types related to encryption
List all control types for S3 buckets

深入了解资源详情：

Show details for resource ID 1234567890

请记住：

• 明确指出您想要分析的资源、控制项或策略
• 使用类别、标题或标签进行筛选
• 先从简单的查询开始，再添加复杂条件
• 使用自然语言——大模型会处理 GraphQL 转换

功能

工具

核心查询与模板工具

• guardrails_query
  • 在 Guardrails 中运行任何只读 GraphQL 查询。
  • 输入：query（字符串，必填），variables（对象，可选）
• guardrails_query_runnable
  • 针对特定可运行类型和资源运行 GraphQL 查询。
  • 输入：runnableTypeUri（字符串），resourceId（字符串），query（字符串），variables（对象，可选）
• guardrails_query_runnable_introspection
  • 检查可运行类型的架构。
  • 输入：runnableTypeUri（字符串），section（字符串，可选：'queryType'、'types'、'type'），typeName（字符串，若 section 为 'type' 则必填）
• guardrails_process_template
  • 使用提供的输入渲染 Nunjucks 模板。
  • 输入：template（字符串），input（对象，可选）

资源操作

• guardrails_resource_list
  • 列出资源，可选择添加筛选条件。
  • 输入：filter（字符串，可选）
• guardrails_resource_show
  • 显示特定资源的详情。
  • 输入：id（字符串）
• guardrails_resource_type_list
  • 列出资源类型，可选择添加筛选条件。
  • 输入：filter（字符串，可选）
• guardrails_resource_type_show
  • 显示特定资源类型的详情。
  • 输入：id（字符串）

控制操作

• guardrails_control_list
  • 列出控制项，可选择添加筛选条件。
  • 输入：filter（字符串，可选）
• guardrails_control_show
  • 显示特定控制项的详情。
  • 输入：id（字符串）
• guardrails_control_run
  • 按 ID 运行控制项。
  • 输入：controlId（字符串）
• guardrails_control_type_list
  • 列出控制类型，可选择添加筛选条件。
  • 输入：filter（字符串，可选）
• guardrails_control_type_show
  • 显示特定控制类型的详情。
  • 输入：id（字符串）

策略操作

• guardrails_policy_type_list
  • 列出策略类型，可选择添加筛选条件。
  • 输入：filter（字符串，可选）
• guardrails_policy_type_show
  • 显示特定策略类型的详情。
  • 输入：id（字符串）
• guardrails_policy_setting_list
  • 列出策略设置，可选择添加筛选条件。
  • 输入：filter（字符串，可选）
• guardrails_policy_setting_show
  • 显示特定策略设置的详情。
  • 输入：id（字符串）

开发

克隆与设置

1. 克隆仓库并进入目录：

   git clone https://github.com/turbot/guardrails-mcp.git
   cd guardrails-mcp
   

2. 安装依赖：

   npm install
   

3. 创建包含凭据的 .env 文件。您可以使用以下任一方式：

   首选方式 — Turbot CLI 配置文件：

   echo "TURBOT_PROFILE=your-profile-name" > .env
   

   备用方式 — 直接使用凭据：

   cat > .env <<'EOF'
   TURBOT_WORKSPACE=https://demo-acme.cloud.turbot.com
   TURBOT_ACCESS_KEY=your-access-key
   TURBOT_SECRET_KEY=your-secret-key
   EOF
   

4. 构建项目：

   npm run build
   

5. 如需在开发时自动重新编译：

   npm run watch
   

6. 若要在 Claude Desktop 中使用本地开发版本，请更新配置，使其指向构建后的 dist/index.js：

   {
     "mcpServers": {
       "turbot-guardrails": {
         "command": "node",
         "args": ["/full/path/to/guardrails-mcp/dist/index.js"],
         "env": {
           "TURBOT_PROFILE": "your-profile-name"
         }
       }
     }
   }
   

   将 /full/path/to/guardrails-mcp 替换为本地开发目录的绝对路径。

调试

• MCP Inspector
  • 使用 MCP Inspector 测试服务：

    npm run build
    npx @modelcontextprotocol/inspector node dist/index.js
    

故障排除

服务器会在启动时记录解析出的凭证方式，以便你确认使用了正确的方式：

Authenticated via Turbot CLI profile 'demo-acme' (from /Users/you/.config/turbot/credentials.yml)

或

Authenticated via direct environment variables

如果解析出的端点未使用 HTTPS，系统会记录一条警告，因为 Basic 身份验证凭证会以明文形式传输。

• 缺少凭证： 设置 TURBOT_PROFILE，或设置全部三个直接凭证变量（TURBOT_WORKSPACE、TURBOT_ACCESS_KEY、TURBOT_SECRET_KEY）。也接受旧版 v0.1.x 名称（TURBOT_CLI_PROFILE、TURBOT_GRAPHQL_ENDPOINT、TURBOT_ACCESS_KEY_ID、TURBOT_SECRET_ACCESS_KEY）。
• 找不到配置文件中的配置项： 确认配置名称与凭证文件中的某个条目匹配，并确认文件路径正确（默认为 ~/.config/turbot/credentials.yml）。
• 配置项缺少字段： credentials.yml 中的每个配置项都必须包含 workspace、accessKey 和 secretKey。
• 身份验证错误： 确保 API 密钥正确且拥有必要的权限。返回给 AI 助手的任何错误消息都会隐藏凭证值。
• 连接问题： 确认 Guardrails 端点 URL 正确。
• API 错误： 查看服务器日志，获取详细的 GraphQL 错误消息。