Terragrunt MCP Server

Terragrun MCP服务器

一个模型上下文协议（MCP）服务器，为VS Code中的GitHub Copilot等AI助手提供全面的Terragrun文档和工具集成。

概述

此MCP服务器使AI助手能够访问和搜索完整的Terragrun文档，为使用Terragrun配置、CLI命令和HCL语法提供智能帮助。它具有强大的缓存系统，具有网络弹性和多种回退机制。

新 多模式架构 代币开销减少60-94% 优化AI助手集成。选择适合您工作流程的模式：CORE（文档）、CONFIG（生成）、GUIDANCE（故障排除）、OBSERVABILITY（指标）或FULL（所有工具）。

特性

📚 文档访问

• 实时文档：在单个HTTP请求中通过llms.txt自动获取最新的Terragrun文档
• 索引搜索：元数据索引架构，可实现高效搜索，按需提供完整内容
• 智能缓存：两层缓存系统（内存+磁盘），24小时刷新周期
• 网络弹性：具有指数回退的重试机制（3次重试，最多延迟10秒）
• 多次倒退：网络→ 磁盘缓存→ 过期缓存→ 本地夹具（用于离线/CI使用）
• 快速搜索：元数据优先搜索（标题/节/URL），全文内容回退
• 有组织的部分：按类别浏览文档（入门、参考、功能等）
• 持久缓存：缓存在服务器重启后仍然存在（存储在 .cache/terragrunt-docs/)

看 延迟加载文档 有关性能优化的详细信息。

⚙️ 配置生成器

• 分层模板：基本（4-5个变量）和高级（9-12个变量）后端模板
• 多云支持：AWS S3、Azure Blob存储、GCP GCS后端
• 高级功能：KMS加密、跨帐户访问、托管身份、服务帐户模拟
• 芥末护发素：智能渲染仅包括提供的选项
• 两层验证：基于正则表达式（快速）+可选Terragrun CLI验证（准确）
• 自定义模板：使用特定于组织的模板进行扩展

看 高级后端模板 用于企业配置选项。

🔧 可用工具

8个综合工具 如需Terragrun的全面协助：

• 7核心工具 （工具1-7）：文档、功能、CLI、HCL参考、指南、配置生成、错误诊断
• 1个可观测性工具 （工具8）：服务器指标和监控

1. search_docs -统一文档搜索

满足所有文档搜索需求的统一工具——语义搜索、浏览部分、检索内容和查找代码示例。

• 参数:

- mode （字符串，可选）：操作模式- search, list, section，或 examples （默认值： search) - query （字符串，条件）：搜索查询文本（必填 search 模式，可选 examples) - section （字符串，条件）：节名称（必需 section 模式） - detailLevel （字符串，可选）： summary 或 full （默认值： summary) - 其他特定模式参数（页面、页面大小、限制、高级、类别等）

• 模式:

- 搜索：在所有文档中进行语义搜索 - 列表：列出可用的文档部分 - 部分：从特定部分获取文档 - 示例：查找代码示例和模式（支持高级精选示例）

• 用例：所有与文档相关的任务，包括搜索、浏览、部分检索和代码示例

2. function_reference -内置功能参考

获取函数详细信息或列出所有函数-Terragrun内置函数文档的统一工具。

• 获取模式 （当 function_name 提供）：

- function_name （string）：函数名（例如，“path_relater_to_include”、“get_env”） - mode （字符串，可选）：详细程度- summary 或 full （默认值： summary) - include_examples （布尔值，可选）：包括代码示例（默认值：true） - 退货：完整的函数元数据，包括签名、参数、返回类型、示例

• 列表模式 （当否 function_name):

- category （字符串，可选）：按类别筛选（例如，“路径”、“aws”、“环境”） - search （字符串，可选）：在函数名称和描述中搜索 - page （数字，可选）：页码（默认值：1） - pageSize （数字，可选）：每页结果（默认值：20） - 退货：具有名称、签名、类别和描述的函数数组

• 用例：查找特定功能、发现可用功能、按类别浏览

3. cli_reference -CLI命令参考

获取命令帮助或列出命令-Terragrunt CLI命令文档的统一工具。

• 获取模式 （当 command 提供）：

- command （string）：命令名称（例如，“plan”、“apply”、“run all”、“hclfmt”） - 退货：命令文档，包括用法、选项和示例

• 列表模式 （当否 command):

- category （字符串，可选）：按类别筛选(main, backend, stack, catalog, discovery, configuration, shortcut) - search （字符串，可选）：在命令名称和描述中搜索 - page （数字，可选）：页码（默认值：1） - pageSize （数字，可选）：每页命令数（默认值：20） - 退货：包含名称、类别和描述的命令数组

• 用例：学习命令语法，了解命令选项，CLI故障排除，发现可用命令

4. get_hcl_config_reference -HCL配置参考

获取中使用的HCL配置块的文档 terragrunt.hcl 文件夹。

• 参数:

- config （字符串，可选）：块名称（例如，“terraform”、“remote_state”、“dependency”、“inputs”、“generate”、“locals”） - category （字符串，可选）：按类别过滤块(core, modules, generation, execution, iam, terraform) - listBlocks （布尔值，可选）：列出所有可用的HCL块（默认值：false）

• 退货：HCL块文档，包括语法、属性、示例和使用模式
• 用例：编写terragrunt.hcl文件，了解配置选项，发现可用块

5. get_guidance -最佳实践与比较

获取Terragrun使用的最佳实践、比较或模式。

• 参数:

- query （字符串，可选）：主题、比较或场景 - type （字符串，可选）：引导类型- best-practices, comparison，或 pattern - mode （字符串，可选）：详细程度- summary 或 full （默认值： summary) - level （字符串，可选）：经验级别- beginner, intermediate，或 advanced - listAll （布尔值，可选）：列出所有可用的指导（默认值：false）

• 退货：具有优先级、基本原理、示例、反模式、权衡和经验说明的结构化建议
• 用例学习最佳实践，理解模式，避免常见陷阱，比较方法，获得经验适当的指导

示例提示：

"What are the best practices for state management?"
"Compare different approaches for module organization"
"Show me beginner-level dependency management practices"
"What patterns should I use for CI/CD with Terragrunt?"

6. build_config -生成或写入Terragrun配置

生成或写入或生成+写入Terragrun配置-用于配置管理的统一工具。

• 生成模式 （当 useCase 提供，没有 content):

- useCase （string）：配置类型- remote_state, provider_generation, dependencies, hooks，或 inputs - options （对象）：模板变量（因用例和后端而异） - backend （字符串，可选）：remote_state的后端类型- s3, azurerm，或 gcs - tier （字符串，可选）：模板层- essential, advanced，或 complete （默认值： essential) - strictValidation （布尔值，可选）：启用严格验证（默认值：false） - 退货：生成的HCL配置及其说明和后续步骤

• 写模式 （当 content 提供）：

- content （string）：要写入的HCL内容 - path （string）：应写入配置的文件路径 - overwrite （布尔值，可选）：允许覆盖现有文件（默认值：false） - createBackup （布尔值，可选）：覆盖前创建备份（默认值：true） - createParentDirs （布尔值，可选）：如果缺少，则创建父目录（默认值：true） - 退货：使用文件路径写入确认

• 生成+写入模式 （当 useCase + write=true + path):

- 结合两种模式-在一次操作中生成配置和写入磁盘 - 退货：生成配置+写入确认

• 安全：默认情况下禁用文件写入，需要显式配置（请参阅 文件编写指南)
• 用例：快速项目设置、学习HCL语法、最佳实践配置、保存生成的配置、自动化配置更新

示例提示：

"Generate a terragrunt config for S3 remote state in us-east-1"
"Write this configuration to /home/user/terraform/terragrunt.hcl"
"Generate and save an Azure backend configuration to my project"
"Show me how to set up dependencies between terragrunt modules"

7. diagnose_terragrunt_error -错误诊断和故障排除

诊断Terragrun错误消息，并获取可操作的解决方案、调试步骤和相关文档链接。

• 参数:

- error_message （string，必填）：来自Terragrun的用于诊断的错误消息 - command （字符串，可选）：运行的命令（例如，“应用”、“计划”） - version （字符串，可选）：Terragrun版本 - os （字符串，可选）：操作系统 - filePath （字符串，可选）：发生错误的文件路径 - module （字符串，可选）：模块名称 - backend （字符串，可选）：后端类型 - maxMatches （数字，可选）：要返回的最大匹配项数（默认值：3） - minConfidence （数字，可选）：最小置信度分数0-1（默认值：0.3） - enableFuzzyMatching （布尔值，可选）：启用模糊匹配（默认值：true） - enrichWithDocs （布尔值，可选）：丰富文档来源的解决方案（默认值：false）

• 退货：与置信度评分、解决方案、调试步骤、相关错误和文档链接相匹配（7个类别中的66个错误模式）
• 用例：排除错误，获得可操作的解决方案，查找相关文档

示例提示：

"I'm getting this error: Error acquiring the state lock"
"Help me fix: Backend configuration changed since last init"
"Diagnose this terragrunt error and tell me how to fix it"

看 故障排除指南 了解详细的使用示例和最佳实践。

8. get_server_metrics -服务器指标和监控

检索MCP服务器的全面性能指标，包括工具执行时间、缓存统计信息和错误跟踪。

• 参数:

- format （字符串，可选）：输出格式-“json”或“text”（默认：“json”） - filter （字符串，可选）：按工具名称前缀过滤指标 - reset （布尔值，可选）：检索后重置指标（默认值：false）

• 退货：性能指标包括：

- 工具执行计数和时间（最小/最大/平均延迟） - 按工具分类的错误率和错误类型 - 缓存命中率和效率 - 内存和性能趋势

• 用例：性能监控、调试慢速操作、容量规划、识别优化机会

示例提示：

"Show me server metrics in text format"
"Get metrics for all 'get_' tools only"
"What's the cache hit rate and average latency?"
"Show me metrics and reset them after"

看 指标收集指南 有关详细的使用、报告和导出选项。

______________________________________________________________________

有关完整的工具文档和示例，请参阅 可用工具.

📖 资源

• 完整的文档概述，包括章节细分
• 单独的文档页面作为单独的资源
• 基于章节的文件收集
• 所有内容均可通过VS Code和Copilot访问

服务器模式

Terragrun MCP服务器支持 5种操作模式 优化令牌使用并减少特定工作流的开销。每种模式只加载其用例所需的工具和依赖项。

模式概述

快速模式选择

在以下情况下使用CORE模式：

• 快速查找文档
• 探索CLI命令和功能
• 学习Terragrun基础知识
• 需要参考信息

在以下情况下使用CONFIG模式：

• 生成Terragrun配置
• 使用HCL模板
• CI/CD自动化流水线
• 基于模板的工作流

在以下情况下使用GUIDANCE模式：

• 调试错误
• 获取最佳实践建议
• 部署故障排除
• 学习模式和比较

在以下情况下使用可观察性模式：

• 监控服务器性能
• 跟踪使用指标
• 最小的部署占用空间
• 仅度量工作流程

在以下情况下使用FULL模式：

• 需要多个工具类别
• 探索性工作流程
• 需要向后兼容性
• 不确定需要哪些工具

模式性能

已验证的性能指标：

• 代币减少：60-94%与完全模式
• 节省内存：与基线相比为5-80%
• 管理者效率：减少50-100%
• 启动时间：1-4ms（可忽略不计）
• 延迟加载：已确认工作

看 模式_性能_验证.md 详细的基准测试。

安装

选项1：使用Docker（推荐）

最简单的入门方法是使用预构建的Docker镜像：

# Pull the latest image
docker pull olofdevopsninja/terragrunt-mcp-server:latest

# Run with Docker
docker run -i olofdevopsninja/terragrunt-mcp-server:latest

# Or use docker-compose
docker-compose up

看 详细说明。

选项2：来源

1. 克隆存储库

1. 安装依赖项：

   npm install

1. 构建服务器：

   npm run build

VS代码配置

使用Docker Hub镜像（推荐）

全模式（所有工具，默认）：

{
  "mcp.servers": {
    "terragrunt": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "mcp-cache:/app/.cache",
        "olofdevopsninja/terragrunt-mcp-server:latest"
      ]
    }
  }
}

专用模式（针对特定用例进行了优化）：

{
  "mcp.servers": {
    "terragrunt-docs": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "mcp-cache:/app/.cache",
        "olofdevopsninja/terragrunt-mcp-server:latest",
        "--mode", "core"
      ]
    },
    "terragrunt-config": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "mcp-cache:/app/.cache",
        "olofdevopsninja/terragrunt-mcp-server:latest",
        "--mode", "config"
      ]
    }
  }
}

使用本地构建

完整模式：

{
  "mcp.servers": {
    "terragrunt": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/terragrunt-mcp-server"
    }
  }
}

使用CLI包装器的专用模式：

{
  "mcp.servers": {
    "terragrunt-docs": {
      "command": "node",
      "args": ["bin/terragrunt-mcp-core"],
      "cwd": "/absolute/path/to/terragrunt-mcp-server"
    },
    "terragrunt-config": {
      "command": "node",
      "args": ["bin/terragrunt-mcp-config"],
      "cwd": "/absolute/path/to/terragrunt-mcp-server"
    }
  }
}

替代方案：直接模式标志：

{
  "mcp.servers": {
    "terragrunt-core": {
      "command": "node",
      "args": ["dist/index.js", "--mode", "core"],
      "cwd": "/absolute/path/to/terragrunt-mcp-server"
    }
  }
}

1. 重新启动VS代码 激活MCP服务器

1. 验证安装：询问GitHub Copilot： *“搜索Terragrun文档以了解入门信息”*

使用GitHub Copilot

配置后，直接通过VS Code中的Copilot与Terragrun文档交互。服务器为您的所有Terragrun问题提供智能上下文。

按类别提示示例

一般文档搜索

• *“搜索有关依赖关系的Terragrun文档”*
• *“给我看看Terragrun的入门指南”*
• *“Terragrun中有哪些可用的配置选项？”*
• *“我如何使用Terragrun的远程状态？”*
• *“查找有关Terragrun生成块的文档”*

CLI命令帮助

• *“Terragrun计划命令有哪些可用选项？”*
• *“我该如何使用Terragrun run all？”*
• *“显示hclfmt命令的帮助”*
• *“terragrun验证输入的作用是什么？”*

HCL配置参考

• *“演示如何在terragrunt.hcl中配置地形块”*
• *“有哪些可用的remote_state选项？”*
• *“我如何使用依赖块？”*
• *“我可以在输入块中使用哪些属性？”*

代码示例

• *“展示在Terragrun中使用依赖关系的示例”*
• *“查找远程状态配置的代码段”*
• *“before_hook用法的一些例子是什么？”*
• *“用示例演示如何使用生成块”*

内置功能

• *“显示path_relater_to_include函数的文档”*
• *“get_env接受哪些参数？”*
• *“列出所有与AWS相关的Terragrun函数”*
• *“有哪些内置函数可用于处理文件？”*
• *“搜索与环境变量相关的函数”*
• *“如何使用find_in_parent_folder？”*

高级用法

• *“比较Terragrun模块组织的不同方法”*
• *“向我展示Terragrun项目结构的最佳实践”*
• *“解释依赖块和依赖块之间的区别”*
• *“处理特定于环境的配置的推荐方法是什么？”*

项目结构

terragrunt-mcp-server/
├── src/
│   ├── index.ts                 # MCP server entry point
│   ├── handlers/
│   │   ├── tools.ts             # Tool execution handlers (7 consolidated tools)
│   │   └── prompts.ts           # Prompt templates (future)
│   ├── terragrunt/
│   │   ├── docs.ts              # Documentation fetching and caching
│   │   ├── functions.ts         # Built-in functions manager
│   │   ├── cli-commands.ts      # CLI commands manager
│   │   ├── hcl-blocks.ts        # HCL configuration blocks manager
│   │   ├── best-practices.ts    # Best practices analyzer
│   │   ├── generator.ts         # Configuration generator
│   │   ├── file-writer.ts       # Secure file writing
│   │   ├── error-patterns.ts    # Error diagnosis patterns
│   │   ├── config.ts            # Configuration management
│   │   └── utils.ts             # Utility functions
│   └── types/
│       ├── mcp.ts               # MCP protocol type definitions
│       └── terragrunt.ts        # Terragrunt-specific types
├── test/
│   ├── unit/                    # Unit tests (Vitest)
│   ├── integration/             # Integration tests
│   ├── performance/             # Performance benchmarks
│   └── edge-cases/              # Edge case validation
├── fixtures/
│   └── terragrunt-docs-fixture.json  # Offline documentation cache
├── .cache/                      # Auto-generated cache (gitignored)
│   └── terragrunt-docs/
│       ├── docs-cache.json      # Cached documentation (~1.1MB)
│       └── metadata.json        # Cache timestamps
├── docs/                        # Comprehensive documentation
├── schemas/                     # JSON schemas
├── package.json                 # Node.js dependencies
├── tsconfig.json                # TypeScript configuration
└── README.md                    # This file

关键文件

• src/index.ts：使用stdio传输初始化MCP服务器的主入口点
• src/handlers/tools.ts：实施所有8个用于文档访问的整合工具
• src/terragrunt/docs.ts：具有缓存、重试逻辑和回退功能的核心文档管理器
• test/：包含单元、集成和性能测试的全面测试套件

发展

可用脚本

npm run build          # Compile TypeScript to dist/
npm run dev            # Run in development mode with ts-node
npm start              # Run compiled server from dist/
npm run lint           # Check code style with ESLint
npm run lint:fix       # Auto-fix linting issues
npm test               # Run all tests (Jest)
npm run test:server    # Run integration tests

测试

该项目包括全面的测试覆盖（363次测试）：

• 单元测试 （160次测试）：核心功能验证

- 功能管理器（21个测试） - 文档管理器（67项测试） - 错误处理（24次测试） - 资源处理程序（24个测试） - 工具处理器（24次测试）

• 集成测试 （164次测试）：端到端工具和资源测试

- 功能工具集成（23项测试） - MCP协议合规性（68项测试） - 边缘案例验证（48次测试） - 服务器集成（24次测试） - 函数工具（legacy.js）（1个测试）

• 性能测试 （39项测试）：基准关键操作

- 大型结果集、搜索性能、并发操作 - 缓存效率、内存使用监控 - 函数查找性能基准测试

在本地运行测试

npm test                          # Run all tests (~92 seconds)
npm run test:server              # Integration tests only
npm test -- test/unit            # Unit tests only
npm test -- test/performance     # Performance benchmarks
npm test -- test/integration     # All integration tests

GitHub操作工作流

有两个CI/CD工作流可用：

1. 自动测试 (.github/workflows/test.yml):

- 对所有拉取请求运行 - Node.js 18和20的测试 - 生成覆盖率报告 - 使用npm缓存提高速度

1. 手动测试 (.github/workflows/manual-test.yml):

- 通过GitHub UI手动触发 - 选择特定的测试套件： - 所有测试 - 单元测试 - 集成测试 - 性能测试 - 边缘案例测试 - MCP协议测试 - 错误处理测试 - 上传测试工件 - 生成测试摘要

测试文档

有关详细的测试信息，请参阅：

• 性能测试指南
• 边缘案例测试指南
• MCP协议合规性

Docker支持

在Docker中构建和运行以进行隔离测试：

# Build Docker image
npm run docker:build

# Run with docker-compose
npm run docker:compose:up
npm run docker:compose:logs
npm run docker:compose:down

看 医生.md 了解Docker的详细用法。

贡献

看 贡献.md 制定指导方针和贡献过程。

技术架构

MCP协议实现

此服务器实现 模型上下文协议（MCP） 使用官方SDK(@modelcontextprotocol/sdk).它提供：

• 标准运输：与VS Code和其他MCP客户端直接集成
• 工具操作员八个综合工具，用于Terragrun的全面援助
• 仅工具架构：无MCP资源的简化设计（v0.5.0+）
• 提示处理程序：未来对引导式工作流程的支持

文档缓存系统

这 TerragruntDocsManager 实现了复杂的多层缓存策略：

1. 内存缓存：快速访问常用文档
2. 磁盘缓存：持久存储在 .cache/terragrunt-docs/ （约110万桶）
3. 24小时到期：自动刷新以保持文档最新
4. 过期缓存回退：网络故障时使用过期的缓存
5. 本地固定装置：嵌入式文档，提供完整的离线支持

网络弹性

内置指数回退重试机制：

• 3次重试尝试 随着延迟的增加（1秒→ 2s → 4s)
• 最大延迟10秒 防止过度等待
• 优雅降级 通过多个回退层
• CI/测试友好 具有确定性夹具回退

Web剪贴

使用Cheerio解析Terragrun官方文档网站：

• 从以下位置提取所有文档页面 https://terragrunt.gruntwork.io/docs/
• 保留文档结构（节、标题、URL）
• 清理HTML内容以更好地使用AI
• 根据缓存过期自动更新

版本历史记录

看 更改日志.md 获取详细的版本历史和迁移指南。

当前版本: 0.5.0

• 8个整合工具（从11个简化）
• 纯工具架构（资源已删除）
• 具有网络弹性的多层缓存
• Docker支持
• 全面的测试覆盖率

许可证

该项目根据MIT许可证获得许可。看 许可证 文件以获取详细信息。

相关资源

• 模型上下文协议文档
• Terragrun官方文件
• 安装指南

-