terragrunt-mcp-server: Instructions file for GitHub Copilot

Terragrunt MCP Server - AI Assistant Guide

Architecture

MCP server (stdio transport) providing Terragrunt documentation to AI assistants. Tool-only architecture — 8 tools in FULL mode, subsetted via 5 server modes (FULL, CORE, CONFIG, GUIDANCE, OBSERVABILITY).

src/index.ts              # Entry point — TerragruntMCPServer class, stdio transport
src/handlers/tools.ts     # ToolHandler: all 8 tool schemas + executeTool() switch (~2600 lines)
src/modes/config.ts       # ServerMode enum, MODE_CONFIGS (tool lists + dependency lists per mode)
src/terragrunt/           # Domain managers — each owns one concern (docs, functions, CLI, etc.)
src/types/                # Shared interfaces (hcl-blocks, templates, metrics, mcp)

Manager wiring: ToolHandler.initializeManagers() conditionally instantiates managers based on shouldLoadDependency(dep, mode). Managers that need doc access take TerragruntDocsManager as a constructor param. Mode configs in src/modes/config.ts declare which dependencies each mode needs.

ES Module critical rule: This project uses "type": "module". All imports MUST use .js extensions:

import { ToolHandler } from './handlers/tools.js';  // ✓
import { ToolHandler } from './handlers/tools';     // ✗ Runtime crash

Key Patterns

Multi-tier cache (DocsManager src/terragrunt/docs.ts): In-memory Map → LRU search cache → Disk .cache/terragrunt-docs/ (gzip-compressed) → Network (llms.txt from docs.terragrunt.com) → Fixture fallback (fixtures/terragrunt-docs-fixture.json).

Case-insensitive lookups: Managers use private normalizeKey(name: string): string with Map<string, T> for cache keys. Follow this pattern in any new manager (see src/terragrunt/functions.ts, src/terragrunt/best-practices.ts).

MCP error handling — never throw: Always return valid MCP responses with error info in the payload:

try { return { data: await operation() }; }
catch (error) { console.error('...', error); return { data: [], error: 'message' }; }