@downatthebottomofthemolehole/terraform-best-practices-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carl Dawson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# terraform-best-practices-mcp
+
+An MCP server that helps teams produce better Terraform by combining:
+
+- CLI analysis: `tflint`, `checkov`, `trivy`, `kics`, `infracost`
+- Best-practice retrieval from `terraform-best-practices.com`
+- Cloud provider guidance for `azure`, `aws`, and `gcp`
+- Terraform Registry guidance for providers/resources/modules
+
+## Tool Catalog
+
+- `run_tflint`
+- `run_checkov`
+- `run_trivy`
+- `run_kics`
+- `run_infracost`
+- `fetch_terraform_best_practices`
+- `fetch_provider_best_practices`
+- `fetch_terraform_registry_guidance`
+
+## Prerequisites
+
+- Node.js 24+
+- Optional CLIs available on `PATH` for command tools:
+  - `tflint`
+  - `checkov`
+  - `trivy`
+  - `kics`
+  - `infracost`
+
+If a CLI is missing, the server returns installation guidance instead of failing silently.
+
+## Setup
+
+```bash
+npm install
+npm run build
+```
+
+## Run
+
+```bash
+npm run dev
+```
+
+For production-style execution:
+
+```bash
+npm run build
+npm start
+```
+
+## Publish
+
+This package is configured for npm as:
+
+- `@downatthebottomofthemolehole/terraform-best-practices-mcp-server`
+
+To publish:
+
+```bash
+npm publish --access public
+```
+
+## MCP Configuration
+
+This project includes `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "terraform-best-practices-mcp": {
+      "type": "stdio",
+      "command": "npm",
+      "args": ["run", "dev"]
+    }
+  }
+}
+```
+
+Registry metadata files used by your other MCP repos are also included:
+
+- `mcp.json`
+- `server.json`
+
+## References
+
+- [MCP org](https://github.com/modelcontextprotocol)
+- [MCP docs](https://modelcontextprotocol.io/docs)
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+- [terraform-best-practices](https://www.terraform-best-practices.com/)
+- [Terraform Registry](https://registry.terraform.io/)

package/dist/index.js

@@ -0,0 +1,79 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { allTools } from "./tools/index.js";
+const server = new Server({
+    name: "terraform-best-practices-mcp",
+    version: "0.1.0"
+}, {
+    capabilities: {
+        tools: {}
+    }
+});
+const toolMap = new Map(allTools.map((tool) => [tool.name, tool]));
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: allTools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchemaJson
+        }))
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = toolMap.get(request.params.name);
+    if (!tool) {
+        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
+    }
+    const parsed = tool.inputSchema.safeParse(request.params.arguments ?? {});
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((issue) => {
+            const path = issue.path.length > 0 ? issue.path.join(".") : "input";
+            return `${path}: ${issue.message}`;
+        })
+            .join("; ");
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `Invalid arguments for ${tool.name}: ${issues}`
+                }
+            ]
+        };
+    }
+    try {
+        const text = await tool.run(parsed.data);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text
+                }
+            ]
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `Tool execution failed: ${message}`
+                }
+            ]
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("terraform-best-practices-mcp running on stdio");
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.stack ?? error.message : String(error);
+    console.error(`Fatal startup error: ${message}`);
+    process.exit(1);
+});

package/dist/lib/exec.js

@@ -0,0 +1,86 @@
+import { spawn } from "node:child_process";
+const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_MAX_OUTPUT_BYTES = 2_000_000;
+export class CommandNotFoundError extends Error {
+    constructor(command) {
+        super(`Command not found: ${command}`);
+        this.name = "CommandNotFoundError";
+    }
+}
+export async function runCommand(command, args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd,
+            env: options.env ?? process.env,
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let outputTruncated = false;
+        let killIssued = false;
+        let settled = false;
+        const finish = (done) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            done();
+        };
+        const stopProcess = () => {
+            if (killIssued || child.killed) {
+                return;
+            }
+            killIssued = true;
+            child.kill("SIGTERM");
+        };
+        const appendOutput = (current, chunk) => {
+            const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+            const next = current + text;
+            if (Buffer.byteLength(next, "utf8") > maxOutputBytes) {
+                outputTruncated = true;
+                stopProcess();
+                return next.slice(0, maxOutputBytes);
+            }
+            return next;
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            stopProcess();
+        }, timeoutMs);
+        child.stdout?.on("data", (chunk) => {
+            stdout = appendOutput(stdout, chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr = appendOutput(stderr, chunk);
+        });
+        child.once("error", (error) => {
+            finish(() => {
+                if (error.code === "ENOENT") {
+                    reject(new CommandNotFoundError(command));
+                    return;
+                }
+                reject(error);
+            });
+        });
+        child.once("close", (code) => {
+            finish(() => {
+                resolve({
+                    command,
+                    args,
+                    cwd,
+                    exitCode: code ?? -1,
+                    stdout: stdout.trim(),
+                    stderr: stderr.trim(),
+                    timedOut,
+                    outputTruncated
+                });
+            });
+        });
+    });
+}

package/dist/lib/http.js

@@ -0,0 +1,19 @@
+export async function fetchText(url, timeoutMs = 15_000) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            signal: controller.signal,
+            headers: {
+                "user-agent": "terraform-best-practices-mcp/0.1.0"
+            }
+        });
+        if (!response.ok) {
+            throw new Error(`Request failed with status ${response.status}`);
+        }
+        return await response.text();
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/dist/lib/text.js

@@ -0,0 +1,39 @@
+export function toPlainText(value) {
+    return value
+        .replace(/<script[\s\S]*?<\/script>/gi, " ")
+        .replace(/<style[\s\S]*?<\/style>/gi, " ")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&nbsp;/gi, " ")
+        .replace(/&amp;/gi, "&")
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;/gi, "'")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+export function keywordSnippet(text, keywords, maxChars = 2_000) {
+    const cleaned = text.trim();
+    if (!cleaned) {
+        return "";
+    }
+    if (!keywords.length) {
+        return cleaned.slice(0, maxChars);
+    }
+    const loweredKeywords = keywords
+        .map((keyword) => keyword.trim().toLowerCase())
+        .filter((keyword) => keyword.length > 0);
+    const sentences = cleaned.split(/(?<=[.!?])\s+/);
+    const matches = sentences.filter((sentence) => {
+        const lowered = sentence.toLowerCase();
+        return loweredKeywords.some((keyword) => lowered.includes(keyword));
+    });
+    const source = matches.length > 0 ? matches : sentences;
+    let output = "";
+    for (const sentence of source) {
+        const candidate = output ? `${output} ${sentence}` : sentence;
+        if (candidate.length > maxChars) {
+            break;
+        }
+        output = candidate;
+    }
+    return output || cleaned.slice(0, maxChars);
+}

package/dist/tools/common.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+export const commandToolInputSchema = z.object({
+    path: z.string().min(1).default("."),
+    extraArgs: z.array(z.string().min(1)).max(50).default([]),
+    timeoutMs: z.number().int().positive().max(600_000).optional()
+});
+export const commandToolInputJsonSchema = {
+    type: "object",
+    properties: {
+        path: {
+            type: "string",
+            description: "Terraform project path to scan.",
+            default: "."
+        },
+        extraArgs: {
+            type: "array",
+            items: {
+                type: "string"
+            },
+            description: "Extra CLI arguments.",
+            default: []
+        },
+        timeoutMs: {
+            type: "integer",
+            description: "Optional command timeout in milliseconds.",
+            minimum: 1,
+            maximum: 600000
+        }
+    },
+    additionalProperties: false
+};
+const installHints = {
+    tflint: "Install tflint from https://github.com/terraform-linters/tflint and ensure `tflint` is on PATH.",
+    checkov: "Install checkov with `pip install checkov` and ensure `checkov` is on PATH.",
+    trivy: "Install trivy from https://github.com/aquasecurity/trivy and ensure `trivy` is on PATH.",
+    kics: "Install kics from https://github.com/Checkmarx/kics and ensure `kics` is on PATH.",
+    infracost: "Install infracost from https://www.infracost.io/docs/ and ensure `infracost` is on PATH."
+};
+export function missingCliMessage(command) {
+    return [`Required CLI not found: ${command}`, installHints[command]].join("\n");
+}
+export function formatCommandExecution(result) {
+    const lines = [
+        `Command: ${result.command} ${result.args.join(" ")}`.trim(),
+        `Working directory: ${result.cwd}`,
+        `Exit code: ${result.exitCode}`,
+        `Timed out: ${result.timedOut ? "yes" : "no"}`,
+        `Output truncated: ${result.outputTruncated ? "yes" : "no"}`
+    ];
+    if (result.stdout) {
+        lines.push("", "stdout:", result.stdout);
+    }
+    if (result.stderr) {
+        lines.push("", "stderr:", result.stderr);
+    }
+    if (!result.stdout && !result.stderr) {
+        lines.push("", "No command output was produced.");
+    }
+    return lines.join("\n");
+}

package/dist/tools/fetch_provider_best_practices.js

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import { fetchText } from "../lib/http.js";
+import { keywordSnippet, toPlainText } from "../lib/text.js";
+const providerSources = {
+    azure: {
+        url: "https://learn.microsoft.com/azure/developer/terraform/overview",
+        practices: [
+            "Use managed identity or workload identity instead of static credentials.",
+            "Keep state in Azure Storage with blob versioning and lease locking.",
+            "Model least-privilege RBAC for service principals and managed identities.",
+            "Prefer provider aliases for multi-subscription or multi-tenant deployments.",
+            "Use consistent resource tags for ownership, environment, and cost center.",
+            "Use Azure Verified Modules where possible for baseline guardrails."
+        ]
+    },
+    aws: {
+        url: "https://docs.aws.amazon.com/prescriptive-guidance/latest/terraform-aws-provider-best-practices/introduction.html",
+        practices: [
+            "Use dedicated IAM roles for Terraform runs and avoid long-lived keys.",
+            "Separate state by account/environment with DynamoDB locking for S3 state.",
+            "Pin provider and module versions for reproducible plans.",
+            "Adopt tagging standards for cost allocation and inventory automation.",
+            "Use data sources carefully and avoid hidden cross-account dependencies.",
+            "Enforce security controls through policy and static analysis in CI."
+        ]
+    },
+    gcp: {
+        url: "https://cloud.google.com/docs/terraform/best-practices",
+        practices: [
+            "Use dedicated service accounts with least privilege and short-lived auth.",
+            "Store state in versioned GCS buckets with access controls.",
+            "Organize modules around folders/projects to match GCP hierarchy.",
+            "Use explicit dependency modeling for APIs and IAM propagation-sensitive resources.",
+            "Standardize labels for environment, ownership, and compliance.",
+            "Run policy checks and drift detection as part of CI/CD workflows."
+        ]
+    }
+};
+export const fetchProviderBestPracticesInputSchema = z.object({
+    provider: z.enum(["azure", "aws", "gcp"]),
+    topic: z.string().min(2).max(120).optional(),
+    liveFetch: z.boolean().default(true)
+});
+export const fetchProviderBestPracticesInputJsonSchema = {
+    type: "object",
+    properties: {
+        provider: {
+            type: "string",
+            enum: ["azure", "aws", "gcp"],
+            description: "Cloud provider to retrieve Terraform best practices for."
+        },
+        topic: {
+            type: "string",
+            description: "Optional focus area, for example state, IAM, modules, networking, or cost."
+        },
+        liveFetch: {
+            type: "boolean",
+            description: "When true, attempts to fetch and summarize the linked provider guidance page.",
+            default: true
+        }
+    },
+    required: ["provider"],
+    additionalProperties: false
+};
+function filteredPractices(practices, topic) {
+    if (!topic) {
+        return practices;
+    }
+    const lowered = topic.toLowerCase();
+    const filtered = practices.filter((practice) => practice.toLowerCase().includes(lowered));
+    return filtered.length > 0 ? filtered : practices;
+}
+export const fetchProviderBestPracticesTool = {
+    name: "fetch_provider_best_practices",
+    description: "Fetch Terraform best-practice guidance for Azure, AWS, or GCP from curated checks and optional live provider docs summaries.",
+    inputSchema: fetchProviderBestPracticesInputSchema,
+    inputSchemaJson: fetchProviderBestPracticesInputJsonSchema,
+    run: async (input) => {
+        const source = providerSources[input.provider];
+        const topic = input.topic?.trim();
+        const practices = filteredPractices(source.practices, topic);
+        const lines = [
+            `Provider: ${input.provider}`,
+            `Primary source: ${source.url}`,
+            "Curated provider checklist:",
+            ...practices.map((practice, index) => `${index + 1}. ${practice}`)
+        ];
+        if (!input.liveFetch) {
+            lines.push("", "Live fetch disabled. Returning curated guidance only.");
+            return lines.join("\n");
+        }
+        try {
+            const html = await fetchText(source.url);
+            const snippet = keywordSnippet(toPlainText(html), topic ? [topic, input.provider] : [input.provider, "terraform", "state", "security", "module"], 1800);
+            lines.push("", "Live excerpt:", snippet || "No matching live excerpt found.");
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            lines.push("", `Live fetch unavailable: ${reason}`);
+        }
+        return lines.join("\n");
+    }
+};

package/dist/tools/fetch_terraform_best_practices.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { fetchText } from "../lib/http.js";
+import { keywordSnippet, toPlainText } from "../lib/text.js";
+const sourceUrl = "https://www.terraform-best-practices.com/";
+const curatedPractices = [
+    "Pin Terraform and provider versions to avoid unexpected upgrades.",
+    "Keep modules small and focused, with clear inputs and outputs.",
+    "Use remote state with locking and encryption enabled.",
+    "Adopt a consistent naming convention for resources, variables, and outputs.",
+    "Prefer `for_each` over `count` for stable resource addressing.",
+    "Use `validation` blocks for variables and preconditions on critical resources.",
+    "Separate environments by state/workspace boundaries to reduce blast radius.",
+    "Treat plans as review artifacts in CI before apply.",
+    "Store secrets in dedicated secret managers instead of plaintext variables.",
+    "Use policy-as-code and linting in CI (tflint/checkov/trivy/kics).",
+    "Document each module with usage examples and constraints.",
+    "Continuously track cost drift with tools such as infracost."
+];
+export const fetchTerraformBestPracticesInputSchema = z.object({
+    topic: z.string().min(2).max(120).optional(),
+    liveFetch: z.boolean().default(true)
+});
+export const fetchTerraformBestPracticesInputJsonSchema = {
+    type: "object",
+    properties: {
+        topic: {
+            type: "string",
+            description: "Optional topic filter such as state, modules, security, or naming."
+        },
+        liveFetch: {
+            type: "boolean",
+            description: "When true, attempts to fetch and summarize live content from terraform-best-practices.com.",
+            default: true
+        }
+    },
+    additionalProperties: false
+};
+function filterPractices(topic) {
+    if (!topic) {
+        return curatedPractices;
+    }
+    const loweredTopic = topic.toLowerCase();
+    const filtered = curatedPractices.filter((practice) => practice.toLowerCase().includes(loweredTopic));
+    return filtered.length > 0 ? filtered : curatedPractices;
+}
+export const fetchTerraformBestPracticesTool = {
+    name: "fetch_terraform_best_practices",
+    description: "Fetch Terraform best-practice guidance from curated checks and optional live summaries from terraform-best-practices.com.",
+    inputSchema: fetchTerraformBestPracticesInputSchema,
+    inputSchemaJson: fetchTerraformBestPracticesInputJsonSchema,
+    run: async (input) => {
+        const topic = input.topic?.trim();
+        const practices = filterPractices(topic);
+        const lines = [
+            `Source: ${sourceUrl}`,
+            "Curated Terraform best-practice checklist:",
+            ...practices.map((practice, index) => `${index + 1}. ${practice}`)
+        ];
+        if (!input.liveFetch) {
+            lines.push("", "Live fetch disabled. Returning curated guidance only.");
+            return lines.join("\n");
+        }
+        try {
+            const html = await fetchText(sourceUrl);
+            const text = toPlainText(html);
+            const snippet = keywordSnippet(text, topic
+                ? [topic]
+                : ["state", "module", "provider", "security", "variable", "output", "version"], 1800);
+            lines.push("", "Live excerpt:", snippet || "No matching live excerpt found.");
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            lines.push("", `Live fetch unavailable: ${reason}`);
+        }
+        return lines.join("\n");
+    }
+};

package/dist/tools/fetch_terraform_registry_guidance.js

@@ -0,0 +1,112 @@
+import { z } from "zod";
+import { fetchText } from "../lib/http.js";
+import { keywordSnippet, toPlainText } from "../lib/text.js";
+const defaultRegistryUrl = "https://registry.terraform.io/";
+const registryPractices = [
+    "Pin provider and module versions instead of using unbounded constraints.",
+    "Prefer well-maintained modules with clear versioning and examples.",
+    "Read provider resource docs for force-recreate fields and lifecycle behavior.",
+    "Use module inputs/outputs intentionally and avoid overexposing internals.",
+    "Validate required providers and Terraform versions in every module.",
+    "Track breaking changes across provider major versions before upgrades."
+];
+export const fetchTerraformRegistryGuidanceInputSchema = z.object({
+    provider: z.string().min(1).max(120).optional(),
+    resource: z.string().min(1).max(120).optional(),
+    module: z.string().min(1).max(240).optional(),
+    topic: z.string().min(2).max(120).optional(),
+    liveFetch: z.boolean().default(true)
+});
+export const fetchTerraformRegistryGuidanceInputJsonSchema = {
+    type: "object",
+    properties: {
+        provider: {
+            type: "string",
+            description: "Optional provider name, for example aws, azurerm, or google."
+        },
+        resource: {
+            type: "string",
+            description: "Optional resource type used with provider, for example s3_bucket or resource_group."
+        },
+        module: {
+            type: "string",
+            description: "Optional module path in the form namespace/name/provider."
+        },
+        topic: {
+            type: "string",
+            description: "Optional topic filter for the summary output."
+        },
+        liveFetch: {
+            type: "boolean",
+            description: "When true, fetches and summarizes selected Terraform Registry pages.",
+            default: true
+        }
+    },
+    additionalProperties: false
+};
+function selectPractices(topic) {
+    if (!topic) {
+        return registryPractices;
+    }
+    const lowered = topic.toLowerCase();
+    const filtered = registryPractices.filter((item) => item.toLowerCase().includes(lowered));
+    return filtered.length > 0 ? filtered : registryPractices;
+}
+function buildRegistryUrls(input) {
+    const urls = [];
+    const modulePath = input.module?.trim();
+    if (modulePath) {
+        urls.push(`https://registry.terraform.io/modules/${encodeURI(modulePath)}`);
+    }
+    const provider = input.provider?.trim();
+    const resource = input.resource?.trim();
+    if (provider && resource) {
+        urls.push(`https://registry.terraform.io/providers/hashicorp/${encodeURIComponent(provider)}/latest/docs/resources/${encodeURIComponent(resource)}`);
+    }
+    if (urls.length === 0) {
+        urls.push(defaultRegistryUrl);
+    }
+    return urls;
+}
+export const fetchTerraformRegistryGuidanceTool = {
+    name: "fetch_terraform_registry_guidance",
+    description: "Fetch Terraform Registry best-practice guidance with optional provider/resource/module context.",
+    inputSchema: fetchTerraformRegistryGuidanceInputSchema,
+    inputSchemaJson: fetchTerraformRegistryGuidanceInputJsonSchema,
+    run: async (input) => {
+        const topic = input.topic?.trim();
+        const practices = selectPractices(topic);
+        const urls = buildRegistryUrls(input);
+        const lines = [
+            `Registry source: ${defaultRegistryUrl}`,
+            "Curated Terraform Registry checklist:",
+            ...practices.map((practice, index) => `${index + 1}. ${practice}`)
+        ];
+        if (!input.liveFetch) {
+            lines.push("", "Live fetch disabled. Returning curated guidance only.");
+            return lines.join("\n");
+        }
+        const keywords = [
+            ...(topic ? [topic] : []),
+            ...(input.provider ? [input.provider] : []),
+            ...(input.resource ? [input.resource] : []),
+            ...(input.module ? [input.module] : []),
+            "terraform",
+            "version",
+            "provider",
+            "module"
+        ];
+        for (const url of urls) {
+            try {
+                const html = await fetchText(url);
+                const snippet = keywordSnippet(toPlainText(html), keywords, 1400);
+                lines.push("", `Live excerpt (${url}):`, snippet || "No matching live excerpt found.");
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                lines.push("", `Live fetch unavailable for ${url}: ${reason}`);
+            }
+        }
+        return lines.join("\n");
+    }
+};

package/dist/tools/index.js

@@ -0,0 +1,18 @@
+import { fetchProviderBestPracticesTool } from "./fetch_provider_best_practices.js";
+import { fetchTerraformBestPracticesTool } from "./fetch_terraform_best_practices.js";
+import { fetchTerraformRegistryGuidanceTool } from "./fetch_terraform_registry_guidance.js";
+import { runCheckovTool } from "./run_checkov.js";
+import { runInfracostTool } from "./run_infracost.js";
+import { runKicsTool } from "./run_kics.js";
+import { runTflintTool } from "./run_tflint.js";
+import { runTrivyTool } from "./run_trivy.js";
+export const allTools = [
+    runTflintTool,
+    runCheckovTool,
+    runTrivyTool,
+    runKicsTool,
+    runInfracostTool,
+    fetchTerraformBestPracticesTool,
+    fetchProviderBestPracticesTool,
+    fetchTerraformRegistryGuidanceTool
+];

package/dist/tools/run_checkov.js

@@ -0,0 +1,23 @@
+import { CommandNotFoundError, runCommand } from "../lib/exec.js";
+import { commandToolInputJsonSchema, commandToolInputSchema, formatCommandExecution, missingCliMessage } from "./common.js";
+export const runCheckovInputSchema = commandToolInputSchema;
+export const runCheckovTool = {
+    name: "run_checkov",
+    description: "Run checkov over a Terraform directory.",
+    inputSchema: runCheckovInputSchema,
+    inputSchemaJson: commandToolInputJsonSchema,
+    run: async (input) => {
+        try {
+            const result = await runCommand("checkov", ["-d", input.path, ...input.extraArgs], {
+                timeoutMs: input.timeoutMs
+            });
+            return formatCommandExecution(result);
+        }
+        catch (error) {
+            if (error instanceof CommandNotFoundError) {
+                return missingCliMessage("checkov");
+            }
+            throw error;
+        }
+    }
+};

package/dist/tools/run_infracost.js

@@ -0,0 +1,23 @@
+import { CommandNotFoundError, runCommand } from "../lib/exec.js";
+import { commandToolInputJsonSchema, commandToolInputSchema, formatCommandExecution, missingCliMessage } from "./common.js";
+export const runInfracostInputSchema = commandToolInputSchema;
+export const runInfracostTool = {
+    name: "run_infracost",
+    description: "Run infracost breakdown for a Terraform directory.",
+    inputSchema: runInfracostInputSchema,
+    inputSchemaJson: commandToolInputJsonSchema,
+    run: async (input) => {
+        try {
+            const result = await runCommand("infracost", ["breakdown", "--path", input.path, "--format", "json", ...input.extraArgs], {
+                timeoutMs: input.timeoutMs
+            });
+            return formatCommandExecution(result);
+        }
+        catch (error) {
+            if (error instanceof CommandNotFoundError) {
+                return missingCliMessage("infracost");
+            }
+            throw error;
+        }
+    }
+};

package/dist/tools/run_kics.js

@@ -0,0 +1,23 @@
+import { CommandNotFoundError, runCommand } from "../lib/exec.js";
+import { commandToolInputJsonSchema, commandToolInputSchema, formatCommandExecution, missingCliMessage } from "./common.js";
+export const runKicsInputSchema = commandToolInputSchema;
+export const runKicsTool = {
+    name: "run_kics",
+    description: "Run kics IaC scanning against Terraform code.",
+    inputSchema: runKicsInputSchema,
+    inputSchemaJson: commandToolInputJsonSchema,
+    run: async (input) => {
+        try {
+            const result = await runCommand("kics", ["scan", "-p", input.path, ...input.extraArgs], {
+                timeoutMs: input.timeoutMs
+            });
+            return formatCommandExecution(result);
+        }
+        catch (error) {
+            if (error instanceof CommandNotFoundError) {
+                return missingCliMessage("kics");
+            }
+            throw error;
+        }
+    }
+};

package/dist/tools/run_tflint.js

@@ -0,0 +1,24 @@
+import { CommandNotFoundError, runCommand } from "../lib/exec.js";
+import { commandToolInputJsonSchema, commandToolInputSchema, formatCommandExecution, missingCliMessage } from "./common.js";
+export const runTflintInputSchema = commandToolInputSchema;
+export const runTflintTool = {
+    name: "run_tflint",
+    description: "Run tflint against a Terraform project directory.",
+    inputSchema: runTflintInputSchema,
+    inputSchemaJson: commandToolInputJsonSchema,
+    run: async (input) => {
+        try {
+            const result = await runCommand("tflint", [...input.extraArgs], {
+                cwd: input.path,
+                timeoutMs: input.timeoutMs
+            });
+            return formatCommandExecution(result);
+        }
+        catch (error) {
+            if (error instanceof CommandNotFoundError) {
+                return missingCliMessage("tflint");
+            }
+            throw error;
+        }
+    }
+};

package/dist/tools/run_trivy.js

@@ -0,0 +1,23 @@
+import { CommandNotFoundError, runCommand } from "../lib/exec.js";
+import { commandToolInputJsonSchema, commandToolInputSchema, formatCommandExecution, missingCliMessage } from "./common.js";
+export const runTrivyInputSchema = commandToolInputSchema;
+export const runTrivyTool = {
+    name: "run_trivy",
+    description: "Run trivy config scanning against Terraform code.",
+    inputSchema: runTrivyInputSchema,
+    inputSchemaJson: commandToolInputJsonSchema,
+    run: async (input) => {
+        try {
+            const result = await runCommand("trivy", ["config", input.path, ...input.extraArgs], {
+                timeoutMs: input.timeoutMs
+            });
+            return formatCommandExecution(result);
+        }
+        catch (error) {
+            if (error instanceof CommandNotFoundError) {
+                return missingCliMessage("trivy");
+            }
+            throw error;
+        }
+    }
+};

package/dist/tools/types.js

@@ -0,0 +1 @@
+export {};

package/mcp.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.DownAtTheBottomOfTheMoleHole/terraform-best-practices",
+  "description": "MCP server for Terraform best-practice guidance, linting, security scanning, and cost insights",
+  "repository": {
+    "url": "https://github.com/DownAtTheBottomOfTheMoleHole/terraform-best-practices-mcp",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@downatthebottomofthemolehole/terraform-best-practices-mcp-server",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@downatthebottomofthemolehole/terraform-best-practices-mcp-server",
+  "version": "0.1.0",
+  "mcpName": "io.github.DownAtTheBottomOfTheMoleHole/terraform-best-practices",
+  "description": "MCP server for Terraform cost, lint, security, and cloud best-practice guidance.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "terraform-best-practices-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*",
+    "mcp.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "mcp": {
+    "name": "terraform-best-practices",
+    "description": "Terraform best-practice, security, lint, and cost analysis via MCP"
+  },
+  "keywords": [
+    "mcp",
+    "terraform",
+    "best-practices",
+    "infracost",
+    "tflint",
+    "checkov",
+    "trivy",
+    "kics",
+    "azure",
+    "aws",
+    "gcp"
+  ],
+  "author": "Carl Dawson",
+  "repository": "https://github.com/DownAtTheBottomOfTheMoleHole/terraform-best-practices-mcp",
+  "homepage": "https://github.com/DownAtTheBottomOfTheMoleHole/terraform-best-practices-mcp",
+  "bugs": {
+    "url": "https://github.com/DownAtTheBottomOfTheMoleHole/terraform-best-practices-mcp/issues"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "lint": "eslint --ext .ts src tests",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.27.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "25.3.5",
+    "@typescript-eslint/eslint-plugin": "8.56.1",
+    "@typescript-eslint/parser": "8.56.1",
+    "eslint": "8.57.1",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3",
+    "vitest": "4.0.18"
+  },
+  "license": "MIT"
+}