mcp-server-terraform 0.1.0

package/src/index.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerPlanTool } from "./tools/plan.js";
+import { registerApplyTool } from "./tools/apply.js";
+import { registerDestroyTool } from "./tools/destroy.js";
+import { registerInitTool } from "./tools/init.js";
+import { registerValidateTool } from "./tools/validate.js";
+import { registerStateListTool } from "./tools/state-list.js";
+import { registerStateShowTool } from "./tools/state-show.js";
+import { registerFmtTool } from "./tools/fmt.js";
+import { registerOutputTool } from "./tools/output.js";
+import { registerImportTool } from "./tools/import.js";
+
+const server = new McpServer({
+  name: "terraform-mcp-server",
+  version: "0.1.0",
+});
+
+registerPlanTool(server);
+registerApplyTool(server);
+registerDestroyTool(server);
+registerInitTool(server);
+registerValidateTool(server);
+registerStateListTool(server);
+registerStateShowTool(server);
+registerFmtTool(server);
+registerOutputTool(server);
+registerImportTool(server);
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Terraform MCP Server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/src/terraform.ts

@@ -0,0 +1,49 @@
+import { execFile, ExecFileOptions } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export interface TerraformResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+}
+
+export async function runTerraform(
+  args: string[],
+  options: {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeout?: number;
+  } = {}
+): Promise<TerraformResult> {
+  const { cwd = process.cwd(), env, timeout = 120000 } = options;
+
+  try {
+    const result = await execFileAsync("terraform", args, {
+      cwd,
+      timeout,
+      maxBuffer: 10 * 1024 * 1024, // 10MB
+      env: env ? { ...process.env, ...env } : undefined,
+    });
+    return {
+      stdout: result.stdout,
+      stderr: result.stderr,
+      exitCode: 0,
+    };
+  } catch (error: any) {
+    return {
+      stdout: error.stdout || "",
+      stderr: error.stderr || error.message,
+      exitCode: error.code ?? 1,
+    };
+  }
+}
+
+export function formatResult(result: TerraformResult): string {
+  const parts: string[] = [];
+  if (result.stdout.trim()) parts.push(result.stdout.trim());
+  if (result.stderr.trim()) parts.push(`STDERR:\n${result.stderr.trim()}`);
+  if (result.exitCode !== 0) parts.push(`Exit code: ${result.exitCode}`);
+  return parts.join("\n\n") || "No output.";
+}

package/src/tools/apply.ts

@@ -0,0 +1,33 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { runTerraform, formatResult } from "../terraform.js";
+
+export function registerApplyTool(server: McpServer) {
+  server.tool(
+    "terraform_apply",
+    "Apply Terraform changes to create, update, or destroy infrastructure resources.",
+    {
+      directory: z.string().describe("Working directory containing Terraform files"),
+      auto_approve: z.boolean().optional().describe("Skip interactive approval (default: false — requires confirmation)"),
+      target: z.string().optional().describe("Target specific resource"),
+      var_file: z.string().optional().describe("Path to variables file"),
+      vars: z.record(z.string()).optional().describe("Variable values to pass"),
+    },
+    async ({ directory, auto_approve, target, var_file, vars }) => {
+      const args = ["apply", "-no-color"];
+      if (auto_approve) args.push("-auto-approve");
+      if (target) args.push("-target", target);
+      if (var_file) args.push("-var-file", var_file);
+      if (vars) {
+        for (const [key, value] of Object.entries(vars)) {
+          args.push("-var", `${key}=${value}`);
+        }
+      }
+      const result = await runTerraform(args, { cwd: directory });
+      return {
+        content: [{ type: "text", text: formatResult(result) }],
+        isError: result.exitCode !== 0,
+      };
+    }
+  );
+}

package/src/tools/destroy.ts

@@ -0,0 +1,33 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { runTerraform, formatResult } from "../terraform.js";
+
+export function registerDestroyTool(server: McpServer) {
+  server.tool(
+    "terraform_destroy",
+    "Destroy all Terraform-managed infrastructure. Use with caution — this removes real resources.",
+    {
+      directory: z.string().describe("Working directory containing Terraform files"),
+      auto_approve: z.boolean().optional().describe("Skip interactive approval (default: false)"),
+      target: z.string().optional().describe("Target specific resource to destroy"),
+      var_file: z.string().optional().describe("Path to variables file"),
+      vars: z.record(z.string()).optional().describe("Variable values to pass"),
+    },
+    async ({ directory, auto_approve, target, var_file, vars }) => {
+      const args = ["destroy", "-no-color"];
+      if (auto_approve) args.push("-auto-approve");
+      if (target) args.push("-target", target);
+      if (var_file) args.push("-var-file", var_file);
+      if (vars) {
+        for (const [key, value] of Object.entries(vars)) {
+          args.push("-var", `${key}=${value}`);
+        }
+      }
+      const result = await runTerraform(args, { cwd: directory });
+      return {
+        content: [{ type: "text", text: formatResult(result) }],
+        isError: result.exitCode !== 0,
+      };
+    }
+  );
+}

package/src/tools/fmt.ts

@@ -0,0 +1,25 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { runTerraform, formatResult } from "../terraform.js";
+
+export function registerFmtTool(server: McpServer) {
+  server.tool(
+    "terraform_fmt",
+    "Reformat Terraform configuration files to canonical style (consistent indentation and alignment).",
+    {
+      directory: z.string().describe("Working directory containing Terraform files"),
+      check: z.boolean().optional().describe("Check if files are formatted (don't modify, just report)"),
+      recursive: z.boolean().optional().describe("Process files in subdirectories"),
+    },
+    async ({ directory, check, recursive }) => {
+      const args = ["fmt", "-no-color"];
+      if (check) args.push("-check");
+      if (recursive) args.push("-recursive");
+      const result = await runTerraform(args, { cwd: directory });
+      return {
+        content: [{ type: "text", text: formatResult(result) }],
+        isError: result.exitCode !== 0,
+      };
+    }
+  );
+}

package/src/tools/import.ts

@@ -0,0 +1,25 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { runTerraform, formatResult } from "../terraform.js";
+
+export function registerImportTool(server: McpServer) {
+  server.tool(
+    "terraform_import",
+    "Import an existing infrastructure resource into Terraform state. Maps a real-world resource to a Terraform resource address.",
+    {
+      directory: z.string().describe("Working directory containing Terraform files"),
+      resource_address: z.string().describe("Terraform resource address (e.g., aws_instance.web)"),
+      resource_id: z.string().describe("ID of the existing resource to import (e.g., i-1234567890abcdef0)"),
+    },
+    async ({ directory, resource_address, resource_id }) => {
+      const result = await runTerraform(
+        ["import", "-no-color", resource_address, resource_id],
+        { cwd: directory }
+      );
+      return {
+        content: [{ type: "text", text: formatResult(result) }],
+        isError: result.exitCode !== 0,
+      };
+    }
+  );
+}

package/src/tools/init.ts

@@ -0,0 +1,31 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { runTerraform, formatResult } from "../terraform.js";
+
+export function registerInitTool(server: McpServer) {
+  server.tool(
+    "terraform_init",
+    "Initialize a Terraform working directory. Downloads providers, modules, and configures the backend.",
+    {
+      directory: z.string().describe("Working directory containing Terraform files"),
+      upgrade: z.boolean().optional().describe("Upgrade providers and modules to latest compatible versions"),
+      reconfigure: z.boolean().optional().describe("Reconfigure the backend (discard previous state)"),
+      backend_config: z.record(z.string()).optional().describe("Backend configuration values"),
+    },
+    async ({ directory, upgrade, reconfigure, backend_config }) => {
+      const args = ["init", "-no-color"];
+      if (upgrade) args.push("-upgrade");
+      if (reconfigure) args.push("-reconfigure");
+      if (backend_config) {
+        for (const [key, value] of Object.entries(backend_config)) {
+          args.push("-backend-config", `${key}=${value}`);
+        }
+      }
+      const result = await runTerraform(args, { cwd: directory });
+      return {
+        content: [{ type: "text", text: formatResult(result) }],
+        isError: result.exitCode !== 0,
+      };
+    }
+  );
+}

package/src/tools/output.ts

@@ -0,0 +1,25 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { runTerraform, formatResult } from "../terraform.js";
+
+export function registerOutputTool(server: McpServer) {
+  server.tool(
+    "terraform_output",
+    "Show output values from the Terraform state. Outputs are defined in output blocks and often contain important resource attributes.",
+    {
+      directory: z.string().describe("Working directory containing Terraform files"),
+      name: z.string().optional().describe("Show a specific output by name"),
+      json: z.boolean().optional().describe("Output in JSON format"),
+    },
+    async ({ directory, name, json }) => {
+      const args = ["output", "-no-color"];
+      if (json) args.push("-json");
+      if (name) args.push(name);
+      const result = await runTerraform(args, { cwd: directory });
+      return {
+        content: [{ type: "text", text: formatResult(result) }],
+        isError: result.exitCode !== 0,
+      };
+    }
+  );
+}

package/src/tools/plan.ts

@@ -0,0 +1,33 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { runTerraform, formatResult } from "../terraform.js";
+
+export function registerPlanTool(server: McpServer) {
+  server.tool(
+    "terraform_plan",
+    "Preview changes Terraform will make to infrastructure without applying them. Shows added, changed, and destroyed resources.",
+    {
+      directory: z.string().describe("Working directory containing Terraform files"),
+      destroy: z.boolean().optional().describe("If true, show destroy plan instead of normal plan"),
+      target: z.string().optional().describe("Target specific resource (e.g., aws_instance.web)"),
+      var_file: z.string().optional().describe("Path to variables file"),
+      vars: z.record(z.string()).optional().describe("Variable values to pass (e.g., region=us-east-1)"),
+    },
+    async ({ directory, destroy, target, var_file, vars }) => {
+      const args = ["plan", "-no-color"];
+      if (destroy) args.push("-destroy");
+      if (target) args.push("-target", target);
+      if (var_file) args.push("-var-file", var_file);
+      if (vars) {
+        for (const [key, value] of Object.entries(vars)) {
+          args.push("-var", `${key}=${value}`);
+        }
+      }
+      const result = await runTerraform(args, { cwd: directory });
+      return {
+        content: [{ type: "text", text: formatResult(result) }],
+        isError: result.exitCode !== 0,
+      };
+    }
+  );
+}

package/src/tools/state-list.ts

@@ -0,0 +1,23 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { runTerraform, formatResult } from "../terraform.js";
+
+export function registerStateListTool(server: McpServer) {
+  server.tool(
+    "terraform_state_list",
+    "List all resources tracked in the Terraform state file.",
+    {
+      directory: z.string().describe("Working directory containing Terraform files"),
+      id_pattern: z.string().optional().describe("Filter resources by ID pattern (supports glob)"),
+    },
+    async ({ directory, id_pattern }) => {
+      const args = ["state", "list", "-no-color"];
+      if (id_pattern) args.push(id_pattern);
+      const result = await runTerraform(args, { cwd: directory });
+      return {
+        content: [{ type: "text", text: formatResult(result) }],
+        isError: result.exitCode !== 0,
+      };
+    }
+  );
+}

package/src/tools/state-show.ts

@@ -0,0 +1,21 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { runTerraform, formatResult } from "../terraform.js";
+
+export function registerStateShowTool(server: McpServer) {
+  server.tool(
+    "terraform_state_show",
+    "Show detailed attributes of a specific resource in the Terraform state.",
+    {
+      directory: z.string().describe("Working directory containing Terraform files"),
+      resource_id: z.string().describe("Resource ID in state (e.g., aws_instance.web)"),
+    },
+    async ({ directory, resource_id }) => {
+      const result = await runTerraform(["state", "show", "-no-color", resource_id], { cwd: directory });
+      return {
+        content: [{ type: "text", text: formatResult(result) }],
+        isError: result.exitCode !== 0,
+      };
+    }
+  );
+}

package/src/tools/validate.ts

@@ -0,0 +1,20 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { runTerraform, formatResult } from "../terraform.js";
+
+export function registerValidateTool(server: McpServer) {
+  server.tool(
+    "terraform_validate",
+    "Validate Terraform configuration files for syntax and internal consistency without contacting any remote services.",
+    {
+      directory: z.string().describe("Working directory containing Terraform files"),
+    },
+    async ({ directory }) => {
+      const result = await runTerraform(["validate", "-no-color"], { cwd: directory });
+      return {
+        content: [{ type: "text", text: formatResult(result) }],
+        isError: result.exitCode !== 0,
+      };
+    }
+  );
+}

package/tests/terraform.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { runTerraform, formatResult } from "../src/terraform.js";
+
+// Mock child_process
+vi.mock("node:child_process", () => ({
+  execFile: vi.fn(),
+}));
+
+import { execFile } from "node:child_process";
+
+describe("runTerraform", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("calls terraform with correct args", async () => {
+    vi.mocked(execFile).mockImplementation((_cmd: any, _args: any, _opts: any, cb: any) => {
+      if (typeof cb === "function") {
+        cb(null, { stdout: "ok", stderr: "" });
+      }
+      return {} as any;
+    });
+
+    const result = await runTerraform(["plan", "-no-color"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe("ok");
+  });
+
+  it("returns exit code on error", async () => {
+    vi.mocked(execFile).mockImplementation((_cmd: any, _args: any, _opts: any, cb: any) => {
+      if (typeof cb === "function") {
+        const err = new Error("terraform failed") as any;
+        err.stdout = "Error: Invalid";
+        err.stderr = "exit code 1";
+        err.code = 1;
+        cb(err);
+      }
+      return {} as any;
+    });
+
+    const result = await runTerraform(["plan"]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("exit code 1");
+  });
+});
+
+describe("formatResult", () => {
+  it("returns stdout when available", () => {
+    const result = formatResult({ stdout: "Apply complete!", stderr: "", exitCode: 0 });
+    expect(result).toBe("Apply complete!");
+  });
+
+  it("includes stderr when present", () => {
+    const result = formatResult({ stdout: "", stderr: "Warning: deprecated", exitCode: 0 });
+    expect(result).toContain("STDERR:");
+    expect(result).toContain("Warning: deprecated");
+  });
+
+  it("includes exit code when non-zero", () => {
+    const result = formatResult({ stdout: "", stderr: "", exitCode: 1 });
+    expect(result).toContain("Exit code: 1");
+  });
+
+  it("returns 'No output.' for empty result", () => {
+    const result = formatResult({ stdout: "", stderr: "", exitCode: 0 });
+    expect(result).toBe("No output.");
+  });
+});

package/tests/tools.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerPlanTool } from "../src/tools/plan.js";
+import { registerApplyTool } from "../src/tools/apply.js";
+import { registerDestroyTool } from "../src/tools/destroy.js";
+import { registerInitTool } from "../src/tools/init.js";
+import { registerValidateTool } from "../src/tools/validate.js";
+import { registerStateListTool } from "../src/tools/state-list.js";
+import { registerStateShowTool } from "../src/tools/state-show.js";
+import { registerFmtTool } from "../src/tools/fmt.js";
+import { registerOutputTool } from "../src/tools/output.js";
+import { registerImportTool } from "../src/tools/import.js";
+
+// Mock terraform module
+vi.mock("../src/terraform.js", () => {
+  const mockResult = {
+    stdout: "Terraform has been successfully initialized.",
+    stderr: "",
+    exitCode: 0,
+  };
+  return {
+    runTerraform: vi.fn().mockResolvedValue(mockResult),
+    formatResult: vi.fn().mockImplementation((r) => r.stdout || r.stderr || "No output."),
+  };
+});
+
+function createMockServer(): McpServer {
+  return new McpServer({ name: "test-terraform", version: "0.0.1" });
+}
+
+describe("Tool Registration", () => {
+  it("registers all 10 tools", () => {
+    const server = createMockServer();
+    const toolNames: string[] = [];
+    
+    // Intercept tool registration
+    const originalTool = server.tool.bind(server);
+    server.tool = vi.fn().mockImplementation((name: string, ...args: any[]) => {
+      toolNames.push(name);
+      return originalTool(name, ...args);
+    });
+
+    registerPlanTool(server);
+    registerApplyTool(server);
+    registerDestroyTool(server);
+    registerInitTool(server);
+    registerValidateTool(server);
+    registerStateListTool(server);
+    registerStateShowTool(server);
+    registerFmtTool(server);
+    registerOutputTool(server);
+    registerImportTool(server);
+
+    expect(toolNames).toContain("terraform_plan");
+    expect(toolNames).toContain("terraform_apply");
+    expect(toolNames).toContain("terraform_destroy");
+    expect(toolNames).toContain("terraform_init");
+    expect(toolNames).toContain("terraform_validate");
+    expect(toolNames).toContain("terraform_state_list");
+    expect(toolNames).toContain("terraform_state_show");
+    expect(toolNames).toContain("terraform_fmt");
+    expect(toolNames).toContain("terraform_output");
+    expect(toolNames).toContain("terraform_import");
+    expect(toolNames).toHaveLength(10);
+  });
+});
+
+describe("Plan Tool", () => {
+  it("calls terraform plan with no-color flag", async () => {
+    const { runTerraform } = await import("../src/terraform.js");
+    const mockRun = vi.mocked(runTerraform);
+    mockRun.mockResolvedValueOnce({ stdout: "No changes.", stderr: "", exitCode: 0 });
+
+    const server = createMockServer();
+    registerPlanTool(server);
+    
+    // Access the registered tool handler
+    const tools = (server as any)._tools || {};
+    // Tool was registered - verify mock was called when invoked
+    expect(mockRun).toBeDefined();
+  });
+
+  it("includes -destroy flag when destroy option is true", async () => {
+    const { runTerraform } = await import("../src/terraform.js");
+    const mockRun = vi.mocked(runTerraform);
+    mockRun.mockClear();
+  });
+});
+
+describe("Apply Tool", () => {
+  it("registers with correct name", () => {
+    const server = createMockServer();
+    registerApplyTool(server);
+    expect(server).toBeDefined();
+  });
+});
+
+describe("Destroy Tool", () => {
+  it("registers with correct name", () => {
+    const server = createMockServer();
+    registerDestroyTool(server);
+    expect(server).toBeDefined();
+  });
+});
+
+describe("Init Tool", () => {
+  it("registers with correct name", () => {
+    const server = createMockServer();
+    registerInitTool(server);
+    expect(server).toBeDefined();
+  });
+});
+
+describe("Validate Tool", () => {
+  it("registers with correct name", () => {
+    const server = createMockServer();
+    registerValidateTool(server);
+    expect(server).toBeDefined();
+  });
+});
+
+describe("State List Tool", () => {
+  it("registers with correct name", () => {
+    const server = createMockServer();
+    registerStateListTool(server);
+    expect(server).toBeDefined();
+  });
+});
+
+describe("State Show Tool", () => {
+  it("registers with correct name", () => {
+    const server = createMockServer();
+    registerStateShowTool(server);
+    expect(server).toBeDefined();
+  });
+});
+
+describe("Fmt Tool", () => {
+  it("registers with correct name", () => {
+    const server = createMockServer();
+    registerFmtTool(server);
+    expect(server).toBeDefined();
+  });
+});
+
+describe("Output Tool", () => {
+  it("registers with correct name", () => {
+    const server = createMockServer();
+    registerOutputTool(server);
+    expect(server).toBeDefined();
+  });
+});
+
+describe("Import Tool", () => {
+  it("registers with correct name", () => {
+    const server = createMockServer();
+    registerImportTool(server);
+    expect(server).toBeDefined();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}