This server provides AI assistants with comprehensive Terragrunt documentation, configuration generation, troubleshooting, and observability capabilities.
Search documentation – Search Terragrunt docs, list sections, retrieve section content, and find code examples.
Look up functions – Get details or list Terragrunt built-in functions by category or search.
Reference CLI commands – Get command help or list Terragrunt CLI commands by category.
Reference HCL blocks – Get syntax, attributes, and examples for terragrunt.hcl blocks like remote_state, dependency, generate, and terraform.
Get guidance – Retrieve best practices, comparisons, and DRY patterns tailored to experience level.
Generate and write configurations – Create or save Terragrunt HCL for remote state backends (S3, Azure, GCS), provider generation, dependencies, hooks, and inputs.
Diagnose errors – Analyze Terragrunt/Terraform error messages and get root cause analysis, solutions, and documentation links.
Monitor the server – View metrics such as cache hit rates, tool invocation counts, response times, and memory usage.
Integrates with GitHub Copilot in VS Code to provide Terragrunt documentation, configuration generation, and troubleshooting assistance directly within the IDE.
Provides comprehensive documentation, configuration generation, error diagnosis, and guidance for Terraform and Terragrunt, enabling AI assistants to manage Terraform configurations and workflows.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Terragrunt MCP Server generate a basic AWS backend configuration for Terragrunt"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that provides comprehensive Terragrunt documentation and tooling integration for AI assistants like GitHub Copilot in VS Code.
This MCP server enables AI assistants to access and search the complete Terragrunt documentation, providing intelligent assistance for working with Terragrunt configurations, CLI commands, and HCL syntax. It features a robust caching system with network resilience and multiple fallback mechanisms.
New: Multi-mode architecture with 60-94% token overhead reduction for optimized AI assistant integration. Choose the mode that fits your workflow: CORE (docs), CONFIG (generation), GUIDANCE (troubleshooting), OBSERVABILITY (metrics), or FULL (all tools).
Related MCP server: Terraform Cloud MCP Server
Live Documentation: Automatically fetches the latest Terragrunt documentation via llms.txt in a single HTTP request
Indexed Search: Metadata-indexed architecture for efficient search with full content available on demand
Smart Caching: Two-tier caching system (in-memory + disk) with 24-hour refresh cycle
Network Resilience: Retry mechanism with exponential backoff (3 retries, up to 10s delay)
Multiple Fallbacks: Network → Disk cache → Stale cache → Local fixture (for offline/CI use)
Fast Search: Metadata-first search (title/section/URL) with full-text content fallback
Organized Sections: Browse documentation by categories (getting-started, reference, features, etc.)
Persistent Cache: Cache survives server restarts (stored in .cache/terragrunt-docs/)
See Lazy Loading Documentation for performance optimization details.
Tiered Templates: Essential (4-5 vars) and Advanced (9-12 vars) backend templates
Multi-Cloud Support: AWS S3, Azure Blob Storage, GCP GCS backends
Advanced Features: KMS encryption, cross-account access, managed identity, service account impersonation
Mustache Conditionals: Smart rendering includes only provided options
Two-Tier Validation: Regex-based (fast) + optional Terragrunt CLI validation (accurate)
Custom Templates: Extend with organization-specific templates
See Advanced Backend Templates for enterprise configuration options.
8 consolidated tools for comprehensive Terragrunt assistance:
7 core tools (tools 1-7): Documentation, functions, CLI, HCL reference, guidance, config generation, error diagnosis
1 observability tool (tool 8): Server metrics and monitoring
search_docs - Unified Documentation SearchUnified tool for all documentation search needs - semantic search, browsing sections, retrieving content, and finding code examples.
Parameters:
mode (string, optional): Operation mode - search, list, section, or examples (default: search)
query (string, conditional): Search query text (required for search mode, optional for examples)
section (string, conditional): Section name (required for section mode)
detailLevel (string, optional): summary or full (default: summary)
Additional mode-specific parameters (page, pageSize, limit, advanced, category, etc.)
Modes:
search: Semantic search across all documentation
list: List available documentation sections
section: Get docs from a specific section
examples: Find code examples and patterns (supports advanced curated examples)
Use cases: All doc-related tasks including search, browsing, section retrieval, and code examples
function_reference - Built-in Function ReferenceGet function details OR list all functions - unified tool for Terragrunt built-in function documentation.
Get Mode (when function_name provided):
function_name (string): Function name (e.g., "path_relative_to_include", "get_env")
mode (string, optional): Detail level - summary or full (default: summary)
include_examples (boolean, optional): Include code examples (default: true)
Returns: Complete function metadata including signature, parameters, return type, examples
List Mode (when no function_name):
category (string, optional): Filter by category (e.g., "path", "aws", "environment")
search (string, optional): Search in function names and descriptions
page (number, optional): Page number (default: 1)
pageSize (number, optional): Results per page (default: 20)
Returns: Array of functions with name, signature, category, and description
Use cases: Looking up specific functions, discovering available functions, browsing by category
cli_reference - CLI Command ReferenceGet command help OR list commands - unified tool for Terragrunt CLI command documentation.
Get Mode (when command provided):
command (string): Command name (e.g., "plan", "apply", "run", "hcl fmt", "browse")
Returns: Command documentation with usage, options, and examples
List Mode (when no command):
category (string, optional): Filter by category (main, backend, stack, catalog, discovery, configuration, shortcut)
search (string, optional): Search in command names and descriptions
page (number, optional): Page number (default: 1)
pageSize (number, optional): Commands per page (default: 20)
Returns: Array of commands with name, category, and description
Use cases: Learning command syntax, understanding command options, CLI troubleshooting, discovering available commands
get_hcl_config_reference - HCL Configuration ReferenceGet documentation for HCL configuration blocks used in terragrunt.hcl files.
Parameters:
config (string, optional): Block or attribute name (e.g., "terraform", "remote_state", "exclude", "errors", "unit", "stack", "terragrunt_version_constraint")
category (string, optional): Filter blocks by category (core, modules, generation, execution, iam, terraform)
listBlocks (boolean, optional): List all available HCL blocks (default: false)
Returns: HCL block documentation with syntax, attributes, examples, and usage patterns
Use cases: Writing terragrunt.hcl files, understanding configuration options, discovering available blocks
get_guidance - Best Practices & ComparisonsGet best practices, comparisons, or patterns for Terragrunt usage.
Parameters:
query (string, optional): Topic, comparison, or scenario
type (string, optional): Guidance type - best-practices, comparison, or pattern
mode (string, optional): Detail level - summary or full (default: summary)
level (string, optional): Experience level - beginner, intermediate, or advanced
listAll (boolean, optional): List all available guidance (default: false)
Returns: Structured recommendations with priority, rationale, examples, antipatterns, tradeoffs, and experience notes
Use cases: Learning best practices, understanding patterns, avoiding common pitfalls, comparing approaches, getting experience-appropriate guidance
Example prompts:
"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?"build_config - Generate or Write Terragrunt ConfigurationGenerate OR write OR generate+write Terragrunt configurations - unified tool for configuration management.
Generate Mode (when useCase provided, no content):
useCase (string): Configuration type - remote_state, provider_generation, dependencies, hooks, inputs, or cicd
options (object): Template variables (varies by use case and backend)
backend (string, optional): For remote_state, the backend type - s3, azurerm, or gcs. For cicd, the platform - github-actions, gitlab, or azure-devops
tier (string, optional): Template tier - essential, advanced, or complete (default: essential)
strictValidation (boolean, optional): Enable strict validation (default: false)
Returns: Generated HCL configuration with explanation and next steps
Write Mode (when content provided):
content (string): HCL content to write
path (string): File path where config should be written
overwrite (boolean, optional): Allow overwriting existing files (default: false)
createBackup (boolean, optional): Create backup before overwrite (default: true)
createParentDirs (boolean, optional): Create parent directories if missing (default: true)
Returns: Write confirmation with file path
Generate+Write Mode (when useCase + write=true + path):
Combines both modes - generates configuration and writes to disk in one operation
Returns: Generated config + write confirmation
Preview/Diff (any mode):
preview (boolean, optional): Dry-run. Never writes; returns what would be written plus targetExists, wouldOverwrite, wouldBackup, and a unified diff (default: false)
compareWith (string, optional): Path of an existing file to diff the result against. In preview mode it defaults to path. Without preview, a write still happens and the response includes the diff against the pre-write content
compareWith reads are restricted to the allowed directories, the same security model as writes
Returns: diff (unified) and, in preview mode, a preview block; no file is written when preview is true
Security: File writing disabled by default, requires explicit configuration (see File Writing Guide)
Use cases: Quick project setup, learning HCL syntax, best practice configurations, saving generated configs, automating configuration updates
Example prompts:
"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"diagnose_terragrunt_error - Error Diagnosis and TroubleshootingDiagnose Terragrunt error messages and get actionable solutions, debugging steps, and relevant documentation links.
Parameters:
error_message (string, required): The error message from Terragrunt to diagnose
command (string, optional): Command that was run (e.g., "apply", "plan")
version (string, optional): Terragrunt version
os (string, optional): Operating system
filePath (string, optional): File path where error occurred
module (string, optional): Module name
backend (string, optional): Backend type
maxMatches (number, optional): Maximum matches to return (default: 3)
minConfidence (number, optional): Minimum confidence score 0-1 (default: 0.3)
enableFuzzyMatching (boolean, optional): Enable fuzzy matching (default: true)
enrichWithDocs (boolean, optional): Enrich with documentation-sourced solutions (default: false)
Returns: Matches with confidence scores, solutions, debugging steps, related errors, and documentation links (110 error patterns across 12 categories)
Use cases: Troubleshooting errors, getting actionable solutions, finding relevant documentation
Example prompts:
"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"See the Troubleshooting Guide for detailed usage examples and best practices.
get_server_metrics - Server Metrics and MonitoringRetrieve comprehensive performance metrics for the MCP server, including tool execution times, cache statistics, and error tracking.
Parameters:
format (string, optional): Output format - "json" or "text" (default: "json")
filter (string, optional): Filter metrics by tool name prefix
reset (boolean, optional): Reset metrics after retrieval (default: false)
Returns: Performance metrics including:
Tool execution counts and timings (min/max/avg latency)
Error rates and error types by tool
Cache hit/miss ratios and efficiency
Memory and performance trends
Use cases: Performance monitoring, debugging slow operations, capacity planning, identifying optimization opportunities
Example prompts:
"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"See the Metrics Collection Guide for detailed usage, reporting, and export options.
For complete tool documentation and examples, see Available Tools.
Complete documentation overview with section breakdown
Individual documentation pages as separate resources
Section-based documentation collections
All content accessible through VS Code and Copilot
The Terragrunt MCP Server supports 5 operational modes to optimize token usage and reduce overhead for specific workflows. Each mode loads only the tools and dependencies needed for its use case.
Mode | Tools | Token Overhead | Memory | Managers | Use Case |
FULL | 8 | 2,441 (baseline) | 0.20 MB | 12/12 | All features, backward compatible |
CORE | 4 | 965 (-60%) | 0.19 MB | 4/12 | Documentation & reference lookups |
CONFIG | 2 | 640 (-74%) | 0.08 MB | 6/12 | Configuration generation |
GUIDANCE | 2 | 683 (-72%) | 0.13 MB | 4/12 | Troubleshooting & best practices |
OBSERVABILITY | 1 | 155 (-94%) | 0.04 MB | 0/12 | Metrics & monitoring only |
Use CORE mode when:
Looking up documentation quickly
Exploring CLI commands and functions
Learning Terragrunt basics
Need reference information
Use CONFIG mode when:
Generating Terragrunt configurations
Working with HCL templates
CI/CD automation pipelines
Template-based workflows
Use GUIDANCE mode when:
Debugging errors
Getting best practices advice
Troubleshooting deployments
Learning patterns and comparisons
Use OBSERVABILITY mode when:
Monitoring server performance
Tracking usage metrics
Minimal deployment footprint
Metrics-only workflows
Use FULL mode when:
Need multiple tool categories
Exploratory workflows
Backward compatibility required
Uncertain which tools needed
Verified performance metrics:
Token reduction: 60-94% vs FULL mode
Memory savings: 5-80% vs baseline
Manager efficiency: 50-100% reduction
Startup time: 1-4ms (negligible)
Lazy loading: Confirmed working
See MODE_PERFORMANCE_VERIFIED.md for detailed benchmarks.
The easiest way to get started is using the pre-built Docker image:
# 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 upSee the Docker Deployment Guide for detailed instructions.
Clone the repository
Install dependencies:
npm installBuild the server:
npm run buildFULL mode (all tools, default):
{
"mcp.servers": {
"terragrunt": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v", "mcp-cache:/app/.cache",
"olofdevopsninja/terragrunt-mcp-server:latest"
]
}
}
}Specialized modes (optimized for specific use cases):
{
"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"
]
}
}
}FULL mode:
{
"mcp.servers": {
"terragrunt": {
"command": "node",
"args": ["dist/index.js"],
"cwd": "/absolute/path/to/terragrunt-mcp-server"
}
}
}Specialized modes using CLI wrappers:
{
"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"
}
}
}Alternative: Direct mode flag:
{
"mcp.servers": {
"terragrunt-core": {
"command": "node",
"args": ["dist/index.js", "--mode", "core"],
"cwd": "/absolute/path/to/terragrunt-mcp-server"
}
}
}Restart VS Code to activate the MCP server
Verify installation: Ask GitHub Copilot: "Search Terragrunt docs for getting started"
Once configured, interact with Terragrunt documentation directly through Copilot in VS Code. The server provides intelligent context for all your Terragrunt questions.
"Search for Terragrunt documentation about dependencies"
"Show me the getting started guide for Terragrunt"
"What are the available configuration options in Terragrunt?"
"How do I use remote state with Terragrunt?"
"Find documentation about Terragrunt generate blocks"
"What options are available for the terragrunt plan command?"
"How do I use terragrunt run --all?"
"Show me help for the hcl fmt command"
"How do I validate Terragrunt inputs?"
"Show me how to configure the terraform block in terragrunt.hcl"
"What are the available remote_state options?"
"How do I use the dependency block?"
"What attributes can I use in the inputs block?"
"Show me examples of using dependencies in Terragrunt"
"Find code snippets for remote state configuration"
"What are some examples of before_hook usage?"
"Show me how to use generate blocks with examples"
"Show me documentation for the path_relative_to_include function"
"What parameters does get_env accept?"
"List all AWS-related Terragrunt functions"
"What built-in functions are available for working with files?"
"Search for functions related to environment variables"
"How do I use find_in_parent_folders?"
"Compare different approaches for Terragrunt module organization"
"Show me best practices for Terragrunt project structure"
"Explain the difference between dependency and dependencies blocks"
"What's the recommended way to handle environment-specific configurations?"
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 filesrc/index.ts: Main entry point that initializes the MCP server with stdio transport
src/handlers/tools.ts: Implements all 8 consolidated tools for documentation access
src/terragrunt/docs.ts: Core documentation manager with caching, retry logic, and fallbacks
test/: Comprehensive test suite with unit, integration, and performance tests
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 testsThe project includes comprehensive test coverage (363 tests):
Unit Tests (160 tests): Core functionality validation
Functions Manager (21 tests)
Docs Manager (67 tests)
Error Handling (24 tests)
Resource Handler (24 tests)
Tool Handler (24 tests)
Integration Tests (164 tests): End-to-end tool and resource testing
Functions Tools Integration (23 tests)
MCP Protocol Compliance (68 tests)
Edge Case Validation (48 tests)
Server Integration (24 tests)
Functions Tools (legacy .js) (1 test)
Performance Tests (39 tests): Benchmark critical operations
Large result sets, search performance, concurrent operations
Cache efficiency, memory usage monitoring
Function lookup performance benchmarks
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 testsTwo CI/CD workflows are available:
Automatic Tests (.github/workflows/test.yml):
Runs on all pull requests
Tests on Node.js 18 and 20
Generates coverage reports
Uses npm caching for speed
Manual Tests (.github/workflows/manual-test.yml):
Manual trigger via GitHub UI
Choose specific test suite:
All tests
Unit tests
Integration tests
Performance tests
Edge case tests
MCP protocol tests
Error handling tests
Uploads test artifacts
Generates test summaries
For detailed testing information, see:
For cutting a release, see the Releasing Guide.
Build and run in Docker for isolated testing:
# 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:downSee DOCKER.md for detailed Docker usage.
See CONTRIBUTING.md for development guidelines and contribution process.
This server implements the Model Context Protocol (MCP) using the official SDK (@modelcontextprotocol/sdk). It provides:
Stdio Transport: Direct integration with VS Code and other MCP clients
Tool Handlers: Eight consolidated tools for comprehensive Terragrunt assistance
Tool-Only Architecture: Simplified design with no MCP resources (v0.5.0+)
Prompt Handlers: Future support for guided workflows
The TerragruntDocsManager implements a sophisticated multi-tier caching strategy:
In-Memory Cache: Fast access to frequently used documentation
Disk Cache: Persistent storage in .cache/terragrunt-docs/ (~1.1MB)
24-Hour Expiry: Automatic refresh to keep documentation current
Stale Cache Fallback: Uses expired cache when network fails
Local Fixture: Embedded documentation for complete offline support
Built-in retry mechanism with exponential backoff:
3 retry attempts with increasing delays (1s → 2s → 4s)
10-second maximum delay to prevent excessive waiting
Graceful degradation through multiple fallback layers
CI/Test-friendly with deterministic fixture fallback
Uses Cheerio to parse the official Terragrunt documentation site:
Extracts all documentation pages from https://docs.terragrunt.com/
Preserves document structure (sections, titles, URLs)
Cleans HTML content for better AI consumption
Updates automatically based on cache expiry
See CHANGELOG.md for detailed version history and migration guides.
Current Version: 0.5.0
8 consolidated tools (simplified from 11)
Tool-only architecture (resources removed)
Multi-tier caching with network resilience
Docker support
Comprehensive test coverage
This project is licensed under the MIT License. See the LICENSE file for details.
Generate or write Terragrunt HCL configuration files (terragrunt.hcl). Use cases: remote_state backends (S3, GCS, Azure), provider generation, dependency blocks, hooks, inputs, and cicd (CI/CD-ready config for GitHub Actions, GitLab, Azure DevOps).
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | File path | |
| tier | No | Template tier | essential |
| write | No | Write to disk | |
| backend | No | For remote_state, the backend type (s3, azurerm, gcs). For cicd, the platform (github-actions, gitlab, azure-devops). | |
| content | No | HCL content to write | |
| options | No | Template variables | |
| preview | No | Dry-run: never write; return what would be written plus a diff and overwrite/backup info | |
| useCase | No | Use case | |
| overwrite | No | Allow overwrite | |
| compareWith | No | Path of an existing file to diff the result against (defaults to path in preview mode) | |
| createBackup | No | Create backup | |
| createParentDirs | No | Create parent dirs | |
| strictValidation | No | Strict validation |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does acknowledge the tool can 'write' HCL files to disk, which signals mutating capabilities, but it never states the default behavior (generate vs. write), the output/return shape, overwrite/backup implications, or the role of preview/diff. The description is not misleading but is thin on behavioral context for a mutation-capable tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-structured sentences with zero waste: the first front-loads the core purpose (generate/write terragrunt.hcl), the second efficiently enumerates the supported use cases in a scannable list. Every phrase carries information, and no sentence is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 13-parameter tool with no output schema and no annotations, this description is only partially complete. It nails the purpose and use cases but omits default mode (write=false, preview=false per schema), what the function returns (generated HCL preview? diff?), and the destructive implications of writing over files. The schema covers parameters, but the mutation risk and lack of output schema leave important gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 even without parameter info in the description. The description adds some organizing value by mapping use cases to backend/platform categories (e.g., remote_state → S3/GCS/Azure, cicd → GitHub Actions/GitLab/Azure DevOps), which aligns with the useCase and backend enums, but it does not substantially extend what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Generate or write') and a specific resource ('Terragrunt HCL configuration files (terragrunt.hcl)') and immediately distinguishes the tool from all siblings (get_server_metrics, search_docs, function_reference, get_hcl_config_reference, diagnose_terragrunt_error) by establishing it as the config-generation tool. The enumerated use cases (remote_state backends, provider generation, dependency blocks, hooks, inputs, cicd) make its scope concrete and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear use-case context, listing exact scenarios like remote_state backends (S3, GCS, Azure) and CI/CD platforms (GitHub Actions, GitLab, Azure DevOps), so an agent knows when this tool is the right one. However, it provides no explicit exclusions or mention of alternatives among siblings — e.g., when the agent should prefer get_hcl_config_reference, cli_reference, or get_guidance instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current Terragrunt CLI command help (run --all, browse, plan, apply, hcl validate, etc.) or list commands by category.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number | |
| search | No | Search query | |
| command | No | Command name | |
| category | No | Category filter | |
| pageSize | No | Commands per page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains what the tool does but does not disclose behaviors such as pagination, network/read-only nature, return format, or side effects. The presence of page/pageSize hints at pagination, but the description does not confirm it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that gets to the point quickly. It includes a small list of command examples, which adds specificity without excessive verbosity. The structure is front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a reference tool with 5 parameters and no output schema or annotations, the description is adequate but leaves gaps: it does not explain return structure, pagination behavior, or how search/category interact. An agent could call it, but would benefit from more behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters have descriptive comments in the schema. The description adds a few command examples and the concept of categories but does not explain how parameters like search or pageSize behave beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), a clear resource ('current Terragrunt CLI command help'), and provides concrete examples of commands (--all, browse, plan, apply, hcl validate). It clearly differentiates from sibling tools like function_reference and get_hcl_config_reference, which cover different reference domains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving Terragrunt CLI command help or listing commands by category, but it does not explicitly state when to prefer this tool over alternatives or mention any exclusions. There is no comparison to siblings, so guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Diagnose Terragrunt and Terraform error messages with root cause analysis and solutions. Handles dependency cycles, state lock errors, provider issues, and HCL syntax problems.
| Name | Required | Description | Default |
|---|---|---|---|
| os | No | Operating system | |
| module | No | Module name | |
| backend | No | Backend type | |
| command | No | Command run | |
| version | No | Terragrunt version | |
| filePath | No | File path | |
| maxMatches | No | Max matches | |
| error_message | Yes | Error message | |
| minConfidence | No | Min confidence | |
| enrichWithDocs | No | Include debugging steps and documentation links in response | |
| enableFuzzyMatching | No | Fuzzy matching | |
| includeDestructiveCommands | No | Include destructive |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions 'root cause analysis and solutions' but does not disclose whether the tool is read-only, requires authentication, or any side effects. For a diagnostic tool, more behavioral context (e.g., does it modify state?) is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and scope. No redundant words. Efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 12 parameters and no output schema, the description lacks information about return format, how to interpret confidence or maxMatches, and how parameters are used in analysis. It is incomplete for effective use without reference to external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 12 parameters have descriptions), so baseline is 3. The tool description does not add extra meaning beyond the schema's minimal parameter labels (e.g., 'Error message'). It provides no additional guidance on how parameters affect diagnosis.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool diagnoses Terragrunt and Terraform errors with root cause analysis and solutions, listing specific error types (dependency cycles, state lock errors, etc.). This distinguishes it from sibling tools like 'cli_reference' or 'search_docs', which are not diagnostic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists specific error types handled (dependency cycles, state lock errors, provider issues, HCL syntax problems), giving clear context for when to use the tool. However, it does not explicitly state when not to use it or compare to siblings, so a perfect score is not warranted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Terragrunt built-in function details (find_in_parent_folders, dependency, read_terragrunt_config, etc.) or list all available functions by category.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Detail level | summary |
| page | No | Page number | |
| search | No | Search query | |
| category | No | Category filter | |
| pageSize | No | Results per page | |
| function_name | No | Function name | |
| include_examples | No | Include examples |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the tool gets or lists data, implying a read-only operation, but does not disclose any other behavioral traits such as side effects, authentication needs, or performance characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that efficiently conveys the tool's core functionality. It is well-structured and front-loaded, with no superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 7 parameters and no output schema, the description is brief and does not explain return values, pagination behavior, or how parameters interact. The tool is relatively complex, but the description does not compensate for the missing output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The tool description adds no additional meaning beyond the schema, achieving baseline. It does not help further clarify parameter combinations or advanced usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves details of Terragrunt built-in functions or lists them by category, with specific examples. It distinguishes the tool's focus on functions from siblings like cli_reference or get_hcl_config_reference, though not explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, contexts, or exclude scenarios, leaving the agent to infer from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Terragrunt best practices, block comparisons (dependency vs dependencies), DRY patterns, or experiment status (type=experiments lists active/completed experiments and how to enable them) for infrastructure-as-code organization.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Detail level | summary |
| type | No | Guidance type | |
| level | No | Experience level | |
| query | No | Topic, comparison, or scenario | |
| listAll | No | List all available |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral disclosure. It does add real behavioral detail: type=experiments 'lists active/completed experiments and how to enable them,' and comparisons are returned for specific constructs. But it doesn't disclose output format, default behavior with no arguments, or side effects (if any), leaving some behavior implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, dense sentence that front-loads the main action and categories. Every phrase contributes — examples are embedded parenthetically rather than expanding length, and there is no filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description captures the core purpose and one parameter nuance, and schema covers defaults and enum values. Still, with no output schema and no annotations, it leaves gaps: no indication of what a response looks like, how 'summary' vs 'full' affects results, or what happens when invoked with no parameters. These gaps are not fatal because the tool is a simple guidance lookup, but they prevent a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters, so baseline is 3. The description adds value beyond the schema by clarifying the 'experiments' type (returns status plus enablement instructions) and giving tangible examples for 'comparison' (dependency vs dependencies). This enriches parameter meaning beyond enum labels.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb ('Get') and enumerates distinct guidance domains: best practices, block comparisons, DRY patterns, and experiment status, with an inlined example (dependency vs dependencies). This makes the tool's content scope clear, though it doesn't explicitly differentiate from sibling documentation/reference tools like search_docs or function_reference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the right context — Terragrunt IaC organization guidance — and gives a concrete invocation hint for type=experiments. However, it never states when not to use this tool or points to alternatives among the siblings, so the guidance is contextful but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current Terragrunt HCL block and attribute documentation with syntax and examples, including stacks, feature flags, exclusions, error handling, catalogs, and engines.
| Name | Required | Description | Default |
|---|---|---|---|
| config | No | Block name | |
| category | No | Category filter | |
| listBlocks | No | List all blocks |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only says 'Get' and fails to mention whether the tool is read-only, requires authentication, or how it handles errors or return output. This is a significant gap for a documentation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and resource before listing covered topics. There is no redundancy or irrelevant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description does not clarify how the optional parameters interact (e.g., whether listBlocks overrides config) or what the return structure looks like, especially given there is no output schema. Agents may struggle to know how to call it effectively without more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented. The description adds no extra parameter-specific meaning, but the schema alone is sufficient, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves Terragrunt HCL block and attribute documentation with syntax and examples, and lists specific content areas (stacks, feature flags, etc.). This distinguishes it from sibling reference tools like function_reference and cli_reference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool compared to alternatives such as search_docs or function_reference. No conditions, exclusions, or prerequisite context are provided, leaving the agent to infer usage from the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Terragrunt MCP server metrics: cache hit rates, tool invocation counts, response times, and memory usage for observability.
| Name | Required | Description | Default |
|---|---|---|---|
| reset | No | Reset after get | |
| filter | No | Filter pattern | |
| format | No | Output format | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It lists the metrics returned but does not explain whether retrieval is expensive, if counters are reset (despite a 'reset' parameter in schema), or any side effects. The tool's behavior beyond basic retrieval is unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of 20 words covering the key purpose and metrics. Every word adds value, and there is no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and three parameters, the description is incomplete. It does not explain the output format beyond listing metrics, nor does it describe parameters like 'filter' or 'reset'. An agent would need to infer or experiment to understand behavior fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for its three parameters (filter, format, reset), but the tool description adds no additional meaning. It does not connect the listed metrics to the 'filter' parameter or explain the 'reset' behavior. Baseline is 3 due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: retrieving Terragrunt MCP server metrics including cache hit rates, invocation counts, response times, and memory usage for observability. It distinguishes itself from sibling tools like build_config or diagnose_terragrunt_error by focusing on server performance data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or scenarios to avoid. The phrase 'for observability' implies context but lacks actionable direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Terragrunt documentation for HCL blocks, CLI commands, functions, and IaC patterns. Modes: search, list sections, get section content, or find code examples.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | search: full-text query | list: browse sections | section: get content by name | examples: code samples | search |
| page | No | Page number | |
| limit | No | Max results | |
| query | No | Search query | |
| section | No | Section name | |
| advanced | No | Return advanced examples | |
| category | No | Filter by category | |
| pageSize | No | Results per page | |
| detailLevel | No | Detail level | summary |
| listCategories | No | List categories |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must bear full burden. It describes modes but does not disclose behavioral traits like error behavior, rate limits, authentication needs, or what happens on empty results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with a list of modes. No unnecessary words or repetition. Efficiently front-loads the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters and no output schema, description adequately covers modes but lacks guidance on how parameters interact (e.g., which parameters are needed for each mode). Could be more complete but is not severely lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description needs to add minimal value. The description adds mode names but does not clarify parameter dependencies per mode (e.g., which parameters are required for each mode). Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool searches Terragrunt documentation for HCL blocks, CLI commands, functions, and IaC patterns, listing specific modes. It distinguishes from sibling tools like cli_reference or function_reference by its general scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage through mode listing but does not explicitly state when to use this tool versus more specific sibling tools (e.g., cli_reference). No when-not-to-use or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.2.0build_config4 fields changedInput schema / properties / backend / descriptionPrevious value: -"Backend type"New value: +"For remote_state, the backend type (s3, azurerm, gcs). For cicd, the platform (github-actions, gitlab, azure-devops)."Input schema / properties / compareWithAdded value: +{
+ "description": "Path of an existing file to diff the result against (defaults to path in preview mode)",
+ "type": "string"
+}Input schema / properties / previewAdded value: +{
+ "default": false,
+ "description": "Dry-run: never write; return what would be written plus a diff and overwrite/backup info",
+ "type": "boolean"
+}Input schema / properties / useCase / enumPrevious value: -[
- "remote_state",
- "provider_generation",
- "dependencies",
- "hooks",
- "inputs"
-]New value: +[
+ "remote_state",
+ "provider_generation",
+ "dependencies",
+ "hooks",
+ "inputs",
+ "cicd"
+]get_guidance1 field changedInput schema / properties / type / enumPrevious value: -[
- "best-practices",
- "comparison",
- "pattern"
-]New value: +[
+ "best-practices",
+ "comparison",
+ "pattern",
+ "experiments"
+]v1.1.0build_configcli_referencediagnose_terragrunt_errorfunction_referenceget_guidanceget_hcl_config_referenceget_server_metricssearch_docsScored across 8 tools
Most tools are distinct, but search_docs explicitly covers HCL blocks, CLI commands, and functions, overlapping with function_reference, cli_reference, and get_hcl_config_reference. The more specific reference tools remain identifiable, though an agent could easily pick the wrong one for a given documentation lookup.
The naming pattern is mixed: get_server_metrics, get_hcl_config_reference, and get_guidance use a get_ prefix, while function_reference and cli_reference drop the verb, and search_docs/build_config/diagnose_terragrunt_error use different verb styles. The names are still readable and mostly signal their purpose, but there is no consistent verb_noun convention.
Eight tools is a well-scoped set for a Terragrunt-oriented server covering documentation, references, guidance, config generation, error diagnosis, and observability. Each tool appears to justify its place without redundancy or bloat.
The server covers Terragrunt documentation, function/CLI/HCL references, best practices, config generation, and error diagnosis, which covers the apparent domain well. Minor gaps exist, such as no tool to read/validate an existing terragrunt.hcl or execute Terragrunt commands, but these are not clearly required by the server's stated purpose.
Unified API to query AWS, GCP, Azure and generate Terraform/CLI execution kits for AI agents.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Versioned documentation registry and semantic search for AI tools and coding assistants.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
