@devramps/mcp-server 0.1.6

package/dist/index.js

@@ -0,0 +1,2658 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/config.ts
+import { readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+function loadConfig() {
+  const apiUrl = process.env.DEVRAMPS_API_URL || "https://devramps.com";
+  const envApiKey = process.env.DEVRAMPS_API_KEY;
+  const envOrgId = process.env.DEVRAMPS_ORG_ID;
+  if (envApiKey && envOrgId) {
+    return { apiKey: envApiKey, orgId: envOrgId, apiUrl };
+  }
+  const fileConfig = loadFromConfigFile();
+  if (fileConfig) {
+    return {
+      apiKey: fileConfig.accessToken,
+      orgId: fileConfig.organizationId,
+      apiUrl: fileConfig.apiBaseUrl || apiUrl
+    };
+  }
+  throw new Error(
+    "No DevRamps credentials found. Run `npx @devramps/cli login` to authenticate, or set DEVRAMPS_API_KEY and DEVRAMPS_ORG_ID environment variables."
+  );
+}
+function loadFromConfigFile() {
+  const configPath = join(homedir(), ".devramps", "configuration.json");
+  let content;
+  try {
+    content = readFileSync(configPath, "utf-8");
+  } catch {
+    return null;
+  }
+  let stored;
+  try {
+    stored = JSON.parse(content);
+  } catch {
+    return null;
+  }
+  if (!stored.accessToken || !stored.organizationId || !stored.expiresAt) {
+    return null;
+  }
+  const expiresAt = new Date(stored.expiresAt);
+  if (expiresAt <= /* @__PURE__ */ new Date()) {
+    return null;
+  }
+  return stored;
+}
+
+// src/api/client.ts
+var ApiError = class extends Error {
+  constructor(statusCode, message, responseBody) {
+    super(message);
+    this.statusCode = statusCode;
+    this.responseBody = responseBody;
+    this.name = "ApiError";
+  }
+};
+var DevRampsApiClient = class {
+  baseUrl;
+  apiKey;
+  orgId;
+  constructor(config) {
+    this.baseUrl = config.apiUrl.replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+    this.orgId = config.orgId;
+  }
+  orgPath(path) {
+    return `/api/v1/organizations/${this.orgId}${path}`;
+  }
+  async request(method, path, body, query) {
+    const url = new URL(path, this.baseUrl);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json"
+    };
+    const response = await fetch(url.toString(), {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!response.ok) {
+      let responseBody;
+      try {
+        responseBody = await response.json();
+      } catch {
+        responseBody = await response.text();
+      }
+      throw new ApiError(
+        response.status,
+        `API request failed: ${response.status} ${response.statusText}`,
+        responseBody
+      );
+    }
+    return await response.json();
+  }
+  // Pipeline operations
+  async listPipelines(limit = 50, offset = 0) {
+    return this.request("GET", this.orgPath("/pipelines"), void 0, { limit, offset });
+  }
+  async getPipelineState(pipelineId) {
+    return this.request("GET", this.orgPath(`/pipelines/${pipelineId}/state`));
+  }
+  async getStageHealth(pipelineId, stageName) {
+    return this.request("GET", this.orgPath(`/pipelines/${pipelineId}/stages/${stageName}/health`));
+  }
+  // Stage management
+  async retryStage(pipelineId, stageName) {
+    return this.request(
+      "POST",
+      this.orgPath(`/pipelines/${pipelineId}/stages/${stageName}/retry`)
+    );
+  }
+  async cancelStage(pipelineId, stageName, reason) {
+    return this.request(
+      "POST",
+      this.orgPath(`/pipelines/${pipelineId}/stages/${stageName}/cancel`),
+      reason ? { reason } : void 0
+    );
+  }
+  async stopPipeline(pipelineId, reason) {
+    return this.request(
+      "POST",
+      this.orgPath(`/pipelines/${pipelineId}/stop`),
+      reason ? { reason } : void 0
+    );
+  }
+  async startPipeline(pipelineId) {
+    return this.request(
+      "POST",
+      this.orgPath(`/pipelines/${pipelineId}/start`)
+    );
+  }
+  async stopStagePromotion(pipelineId, stageName, reason) {
+    return this.request(
+      "POST",
+      this.orgPath(`/pipelines/${pipelineId}/stages/${stageName}/stop`),
+      reason ? { reason } : void 0
+    );
+  }
+  async startStagePromotion(pipelineId, stageName) {
+    return this.request(
+      "POST",
+      this.orgPath(`/pipelines/${pipelineId}/stages/${stageName}/start`)
+    );
+  }
+  async bypassStageBlockers(pipelineId, stageName) {
+    return this.request(
+      "POST",
+      this.orgPath(`/pipelines/${pipelineId}/stages/${stageName}/bypass-blockers`)
+    );
+  }
+  // Debugging
+  async getStepLogs(pipelineId, stageName, revisionId, stepName, options) {
+    return this.request(
+      "GET",
+      this.orgPath(
+        `/pipelines/${pipelineId}/${stageName}/${revisionId}/${stepName}/logs`
+      ),
+      void 0,
+      { limit: options?.limit, search: options?.search }
+    );
+  }
+  async getPipelineEvents(pipelineId, options) {
+    return this.request("GET", this.orgPath(`/pipelines/${pipelineId}/events`), void 0, {
+      limit: options?.limit,
+      offset: options?.offset
+    });
+  }
+  async listRevisions(pipelineId, options) {
+    return this.request("GET", this.orgPath(`/pipelines/${pipelineId}/revisions`), void 0, {
+      limit: options?.limit,
+      offset: options?.offset
+    });
+  }
+  // Ephemeral environments
+  async listEphemeralEnvironments(pipelineId) {
+    return this.request("GET", this.orgPath(`/pipelines/${pipelineId}/ephemeral-environments`));
+  }
+  async claimEphemeralSession(pipelineId, envName, commitId, context) {
+    return this.request(
+      "POST",
+      this.orgPath(`/pipelines/${pipelineId}/ephemeral-environments/${envName}/sessions`),
+      { commitId, context }
+    );
+  }
+  async forceClaimEphemeralSession(pipelineId, envName, commitId, context) {
+    return this.request(
+      "POST",
+      this.orgPath(`/pipelines/${pipelineId}/ephemeral-environments/${envName}/force-claim`),
+      { commitId, context }
+    );
+  }
+  async getEphemeralSessionStatus(pipelineId, envName, sessionId) {
+    return this.request("GET", this.orgPath(`/pipelines/${pipelineId}/ephemeral-environments/${envName}/sessions/${sessionId}`));
+  }
+  async releaseEphemeralSession(pipelineId, envName, sessionId) {
+    return this.request(
+      "DELETE",
+      this.orgPath(`/pipelines/${pipelineId}/ephemeral-environments/${envName}/sessions/${sessionId}`)
+    );
+  }
+  async deployEphemeralCommit(pipelineId, envName, sessionId, commitId) {
+    return this.request(
+      "POST",
+      this.orgPath(`/pipelines/${pipelineId}/ephemeral-environments/${envName}/sessions/${sessionId}/deploy`),
+      { commitId }
+    );
+  }
+  // Step type docs
+  async listStepTypes() {
+    return this.request("GET", this.orgPath("/steps"), void 0, { limit: 100 });
+  }
+  // Public (unauthenticated) endpoints
+  async validatePipelineRemote(args) {
+    return this.publicRequest("POST", "/api/v1/public/validate-pipeline", args);
+  }
+  async publicRequest(method, path, body) {
+    const url = new URL(path, this.baseUrl);
+    const response = await fetch(url.toString(), {
+      method,
+      headers: { "Content-Type": "application/json" },
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!response.ok) {
+      let responseBody;
+      try {
+        responseBody = await response.json();
+      } catch {
+        responseBody = await response.text();
+      }
+      throw new ApiError(
+        response.status,
+        `API request failed: ${response.status} ${response.statusText}`,
+        responseBody
+      );
+    }
+    return await response.json();
+  }
+};
+var DevRampsPublicClient = class {
+  baseUrl;
+  constructor(apiUrl) {
+    this.baseUrl = apiUrl.replace(/\/$/, "");
+  }
+  async validatePipeline(args) {
+    const url = new URL("/api/v1/public/validate-pipeline", this.baseUrl);
+    const response = await fetch(url.toString(), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(args)
+    });
+    if (!response.ok) {
+      let responseBody;
+      try {
+        responseBody = await response.json();
+      } catch {
+        responseBody = await response.text();
+      }
+      throw new ApiError(
+        response.status,
+        `API request failed: ${response.status} ${response.statusText}`,
+        responseBody
+      );
+    }
+    return await response.json();
+  }
+};
+
+// src/tools/validate-pipeline.ts
+import { z } from "zod";
+import { readFile } from "fs/promises";
+import { resolve } from "path";
+import { parse as parseYaml } from "yaml";
+var ValidatePipelineSchema = z.object({
+  file_path: z.string().describe(
+    "Path to the pipeline definition YAML file (absolute or relative to cwd)"
+  )
+});
+async function validatePipeline(args, apiClient, publicClient) {
+  const filePath = resolve(args.file_path);
+  let fileContent;
+  try {
+    fileContent = await readFile(filePath, "utf-8");
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error reading file: ${filePath}
+${err instanceof Error ? err.message : String(err)}`
+        }
+      ],
+      isError: true
+    };
+  }
+  try {
+    parseYaml(fileContent);
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `YAML parsing error in ${filePath}:
+${err instanceof Error ? err.message : String(err)}`
+        }
+      ],
+      isError: true
+    };
+  }
+  let result;
+  const remoteClient = apiClient || publicClient;
+  try {
+    const validateFn = "validatePipelineRemote" in remoteClient ? remoteClient.validatePipelineRemote.bind(
+      remoteClient
+    ) : remoteClient.validatePipeline.bind(
+      remoteClient
+    );
+    result = await validateFn({ yaml: fileContent });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("401") || message.includes("403")) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Authentication error during pipeline validation.
+
+Run \`npx @devramps/cli login\` to authenticate, then try again.`
+          }
+        ],
+        isError: true
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Could not reach the DevRamps API for pipeline validation.
+
+Error: ${message}
+
+Check your internet connection and try again. If the issue persists, run \`npx @devramps/cli login\` to refresh credentials.`
+        }
+      ],
+      isError: true
+    };
+  }
+  const lines = [];
+  if (result.valid && result.warnings.length === 0) {
+    lines.push(`Pipeline definition is valid: ${filePath}`);
+  } else if (result.valid) {
+    lines.push(`Pipeline definition is valid with warnings: ${filePath}`);
+  } else {
+    lines.push(`Pipeline definition has errors: ${filePath}`);
+  }
+  if (result.errors.length > 0) {
+    lines.push("");
+    lines.push("Errors:");
+    for (const error of result.errors) {
+      lines.push(`  - [${error.path || "root"}] ${error.message}`);
+    }
+  }
+  if (result.warnings.length > 0) {
+    lines.push("");
+    lines.push("Warnings:");
+    for (const warning of result.warnings) {
+      lines.push(`  - [${warning.path || "root"}] ${warning.message}`);
+    }
+  }
+  if (result.valid) {
+    lines.push("");
+    lines.push("Next steps:");
+    lines.push(
+      "  - Run `npx @devramps/cli bootstrap` in your project root to bootstrap the pipeline"
+    );
+    lines.push("  - Commit the .devramps/ directory and push to deploy");
+    lines.push("");
+    lines.push(
+      "After deploying, you can use the `list-pipelines` and `get-pipeline-state` tools to monitor your pipeline, or ask the agent to debug any failing steps. View your pipelines in the dashboard: https://app.devramps.com/pipelines"
+    );
+  }
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    isError: !result.valid
+  };
+}
+
+// src/tools/scaffold-pipeline.ts
+import { z as z2 } from "zod";
+import { writeFile, mkdir, stat } from "fs/promises";
+import { join as join2, resolve as resolve2 } from "path";
+import { stringify as stringifyYaml } from "yaml";
+var ScaffoldPipelineSchema = z2.object({
+  project_path: z2.string().describe("Path to the project root directory"),
+  pipeline_name: z2.string().describe(
+    "Human-readable pipeline name. Will be converted to snake_case for the directory name under .devramps/"
+  ),
+  pipeline_definition: z2.record(z2.string(), z2.any()).describe(
+    "The complete pipeline definition object to serialize to YAML. Must follow the DevRamps pipeline schema: { version: '1.0.0', pipeline: { cloud_provider: 'AWS', pipeline_updates_require_approval, stages, steps, artifacts, ... } }. See the pipeline-schema resource and scaffold-project prompt for the full structure."
+  )
+});
+function toSnakeCase(str) {
+  return str.replace(/([a-z])([A-Z])/g, "$1_$2").replace(/[\s\-]+/g, "_").toLowerCase().replace(/[^a-z0-9_]/g, "");
+}
+function formatPipelineYaml(yaml) {
+  const lines = yaml.split("\n");
+  const result = [];
+  const pipelineSectionKeys = /* @__PURE__ */ new Set([
+    "notifications:",
+    "stage_defaults:",
+    "stages:",
+    "ephemeral_environments:",
+    "steps:",
+    "artifacts:"
+  ]);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trimStart();
+    const indent = line.length - trimmed.length;
+    const prev = result.length > 0 ? result[result.length - 1] : "";
+    const prevIsBlank = prev === "";
+    if (i > 0 && !prevIsBlank) {
+      if (indent === 0 && /^\w/.test(trimmed) && trimmed.includes(":")) {
+        result.push("");
+      } else if (indent === 2 && pipelineSectionKeys.has(trimmed)) {
+        result.push("");
+      } else if (indent === 4 && trimmed.startsWith("- name:")) {
+        const prevIndent = prev.length - prev.trimStart().length;
+        if (prevIndent >= 4) {
+          result.push("");
+        }
+      } else if (indent === 4 && !trimmed.startsWith("-") && trimmed.endsWith(":")) {
+        const prevIndent = prev.length - prev.trimStart().length;
+        if (prevIndent >= 4) {
+          result.push("");
+        }
+      }
+    }
+    result.push(line);
+  }
+  return result.join("\n");
+}
+async function scaffoldPipeline(args) {
+  const projectPath = resolve2(args.project_path);
+  const pipelineSlug = toSnakeCase(args.pipeline_name);
+  if (!pipelineSlug) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: pipeline_name "${args.pipeline_name}" could not be converted to a valid snake_case directory name.`
+        }
+      ],
+      isError: true
+    };
+  }
+  const devrampsDirPath = join2(projectPath, ".devramps", pipelineSlug);
+  try {
+    const projectStat = await stat(projectPath);
+    if (!projectStat.isDirectory()) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${projectPath} is not a directory.`
+          }
+        ],
+        isError: true
+      };
+    }
+  } catch {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: project directory ${projectPath} does not exist.`
+        }
+      ],
+      isError: true
+    };
+  }
+  const rawYaml = stringifyYaml(args.pipeline_definition, {
+    lineWidth: 120
+  });
+  const yamlContent = formatPipelineYaml(rawYaml);
+  await mkdir(devrampsDirPath, { recursive: true });
+  const pipelineFilePath = join2(devrampsDirPath, "pipeline.yaml");
+  await writeFile(pipelineFilePath, yamlContent, "utf-8");
+  const lines = [
+    `Pipeline scaffolded successfully for "${args.pipeline_name}"`,
+    "",
+    "Files created:",
+    `  - ${pipelineFilePath}`,
+    "",
+    "Next steps:",
+    "  1. Review the generated pipeline.yaml and verify the configuration",
+    "  2. Run the validate-pipeline tool to check for any issues",
+    "  3. If you have Terraform files, run generate-iam-policies to create IAM permissions",
+    "  4. Run `npx @devramps/cli bootstrap` in your project root to bootstrap the pipeline",
+    "  5. Commit the .devramps/ directory to your repository",
+    "  6. Push to trigger your first deployment",
+    "",
+    "After deploying, you can ask the agent to check on your pipeline status,",
+    "debug failing steps, or retry failed stages. View your pipelines at:",
+    "https://app.devramps.com/pipelines"
+  ];
+  return {
+    content: [{ type: "text", text: lines.join("\n") }]
+  };
+}
+
+// src/tools/generate-iam-policies.ts
+import { z as z3 } from "zod";
+import { readdir, writeFile as writeFile2, mkdir as mkdir2 } from "fs/promises";
+import { join as join3, resolve as resolve3, extname } from "path";
+var GenerateIamPoliciesSchema = z3.object({
+  terraform_dir: z3.string().describe("Path to the directory containing Terraform files"),
+  pipeline_name: z3.string().describe(
+    "Pipeline name (must match the pipeline_name used in scaffold-pipeline). Used to determine the output directory under .devramps/<pipeline_name_snake_case>/"
+  ),
+  project_path: z3.string().optional().describe(
+    "Path to the project root directory. Defaults to the parent of terraform_dir if not provided."
+  ),
+  iam_policy: z3.array(
+    z3.object({
+      Version: z3.string().optional(),
+      Statement: z3.array(z3.any())
+    })
+  ).describe(
+    "The IAM policy document array to write. The agent should analyze the Terraform files and construct a comprehensive IAM policy covering all AWS resources and actions needed. Format: [{ Version: '2012-10-17', Statement: [{ Sid, Effect, Action, Resource }] }]. Be broad rather than narrow \u2014 use service-level wildcards (e.g., 'ecs:*', 's3:*') to avoid first-deploy failures from missing permissions. Always include 'iam:CreateServiceLinkedRole' if using ECS or ELB. The user can tighten permissions later."
+  )
+});
+function toSnakeCase2(str) {
+  return str.replace(/([a-z])([A-Z])/g, "$1_$2").replace(/[\s\-]+/g, "_").toLowerCase().replace(/[^a-z0-9_]/g, "");
+}
+async function generateIamPolicies(args) {
+  const terraformDir = resolve3(args.terraform_dir);
+  const pipelineSlug = toSnakeCase2(args.pipeline_name);
+  if (!pipelineSlug) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: pipeline_name "${args.pipeline_name}" could not be converted to a valid snake_case directory name.`
+        }
+      ],
+      isError: true
+    };
+  }
+  let files;
+  try {
+    const entries = await readdir(terraformDir, { recursive: true });
+    files = entries.filter((f) => typeof f === "string" && extname(f) === ".tf").map((f) => join3(terraformDir, f));
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error reading Terraform directory: ${terraformDir}
+${err instanceof Error ? err.message : String(err)}`
+        }
+      ],
+      isError: true
+    };
+  }
+  if (files.length === 0) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `No .tf files found in ${terraformDir}`
+        }
+      ],
+      isError: true
+    };
+  }
+  let outputPath;
+  if (args.project_path) {
+    outputPath = join3(
+      resolve3(args.project_path),
+      ".devramps",
+      pipelineSlug,
+      "aws_additional_iam_policies.json"
+    );
+  } else {
+    outputPath = join3(
+      resolve3(terraformDir, ".."),
+      ".devramps",
+      pipelineSlug,
+      "aws_additional_iam_policies.json"
+    );
+  }
+  const outputDir = join3(outputPath, "..");
+  await mkdir2(outputDir, { recursive: true });
+  try {
+    await writeFile2(
+      outputPath,
+      JSON.stringify(args.iam_policy, null, 2),
+      "utf-8"
+    );
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error writing output file: ${outputPath}
+${err instanceof Error ? err.message : String(err)}`
+        }
+      ],
+      isError: true
+    };
+  }
+  const statementCount = args.iam_policy.reduce(
+    (sum, p) => sum + (p.Statement?.length || 0),
+    0
+  );
+  const lines = [
+    `IAM policies written from analysis of ${files.length} Terraform file(s)`,
+    `Output: ${outputPath}`,
+    "",
+    `Generated ${statementCount} IAM policy statement(s).`,
+    "",
+    "Important: Review the generated policy and adjust if needed.",
+    "Consider narrowing wildcard resources to specific ARNs for production use.",
+    "",
+    "Next steps:",
+    "  1. Review the generated IAM policy file",
+    "  2. Run `npx @devramps/cli bootstrap` in your project root to apply the permissions",
+    "",
+    "After deploying, you can ask the agent to check on your pipeline status,",
+    "debug failing steps, or retry failed stages. View your pipelines at:",
+    "https://app.devramps.com/pipelines"
+  ];
+  return {
+    content: [{ type: "text", text: lines.join("\n") }]
+  };
+}
+
+// src/tools/ephemeral-tools.ts
+import { z as z4 } from "zod";
+function formatApiError(err) {
+  if (err instanceof ApiError) {
+    const body = err.responseBody && typeof err.responseBody === "object" ? JSON.stringify(err.responseBody, null, 2) : String(err.responseBody ?? "");
+    return `API Error (${err.statusCode}): ${err.message}${body ? `
+${body}` : ""}`;
+  }
+  return err instanceof Error ? err.message : String(err);
+}
+function textResult(text, isError = false) {
+  return {
+    content: [{ type: "text", text }],
+    ...isError ? { isError: true } : {}
+  };
+}
+var ListEphemeralEnvironmentsSchema = z4.object({
+  pipeline_id: z4.string().uuid().describe("The pipeline ID to list ephemeral environments for")
+});
+async function listEphemeralEnvironments(client, args) {
+  try {
+    const result = await client.listEphemeralEnvironments(args.pipeline_id);
+    const envs = result.environments;
+    if (envs.length === 0) {
+      return textResult(
+        "No ephemeral environments configured for this pipeline."
+      );
+    }
+    const lines = [`Ephemeral Environments (${envs.length}):`, ""];
+    for (const env of envs) {
+      const status = env.activeLock ? "LOCKED" : "AVAILABLE";
+      const triggers = env.triggerConfig.map((t) => t.on).join(", ");
+      lines.push(`- ${env.name} [${status}]`);
+      lines.push(`  Region: ${env.region} | Account: ${env.accountId}`);
+      lines.push(`  Triggers: ${triggers}`);
+      if (env.activeLock) {
+        lines.push(`  Locked by: ${env.activeLock.lockedBy} (${env.activeLock.lockType})`);
+        lines.push(`  Session: ${env.activeLock.sessionId}`);
+        lines.push(`  Claimed: ${env.activeLock.claimedAt}`);
+      }
+      lines.push("");
+    }
+    return textResult(lines.join("\n"));
+  } catch (err) {
+    return textResult(formatApiError(err), true);
+  }
+}
+var ClaimEphemeralSessionSchema = z4.object({
+  pipeline_id: z4.string().uuid().describe("The pipeline ID"),
+  environment_name: z4.string().describe("The ephemeral environment name (e.g. 'agent-env')"),
+  commit_id: z4.string().describe("The commit SHA to deploy"),
+  context: z4.string().optional().describe(
+    "Optional context describing why the session is being claimed (e.g. 'testing feature X')"
+  )
+});
+async function claimEphemeralSession(client, args) {
+  try {
+    const result = await client.claimEphemeralSession(
+      args.pipeline_id,
+      args.environment_name,
+      args.commit_id,
+      args.context
+    );
+    return textResult(
+      [
+        "Session claimed successfully!",
+        "",
+        `Session ID: ${result.sessionId}`,
+        `Status: ${result.lock.status}`,
+        `Claimed at: ${result.lock.claimedAt}`,
+        "",
+        "An initial deployment has been triggered for the provided commit.",
+        `Use get-ephemeral-session-status with session_id "${result.sessionId}" to monitor deployment progress.`
+      ].join("\n")
+    );
+  } catch (err) {
+    if (err instanceof ApiError && err.statusCode === 409) {
+      const body = err.responseBody;
+      const existing = body?.existingLock;
+      const lines = [
+        "Environment is currently locked by another session.",
+        ""
+      ];
+      if (existing) {
+        lines.push(`Existing session: ${existing.sessionId}`);
+        lines.push(`Locked by: ${existing.lockedBy} (${existing.lockType})`);
+        lines.push(`Claimed at: ${existing.claimedAt}`);
+        lines.push("");
+        lines.push(
+          "Use force-claim-ephemeral-session to override the existing lock."
+        );
+      }
+      return textResult(lines.join("\n"), true);
+    }
+    return textResult(formatApiError(err), true);
+  }
+}
+var ForceClaimEphemeralSessionSchema = z4.object({
+  pipeline_id: z4.string().uuid().describe("The pipeline ID"),
+  environment_name: z4.string().describe("The ephemeral environment name (e.g. 'agent-env')"),
+  commit_id: z4.string().optional().describe("Optional commit SHA to deploy immediately after claiming"),
+  context: z4.string().optional().describe("Optional context for the session")
+});
+async function forceClaimEphemeralSession(client, args) {
+  try {
+    const result = await client.forceClaimEphemeralSession(
+      args.pipeline_id,
+      args.environment_name,
+      args.commit_id,
+      args.context
+    );
+    const lines = [
+      "Session force-claimed successfully! Any previous session has been released.",
+      "",
+      `Session ID: ${result.sessionId}`,
+      `Status: ${result.lock.status}`,
+      `Claimed at: ${result.lock.claimedAt}`
+    ];
+    if (args.commit_id) {
+      lines.push(
+        "",
+        "A deployment has been triggered for the provided commit.",
+        `Use get-ephemeral-session-status with session_id "${result.sessionId}" to monitor progress.`
+      );
+    }
+    return textResult(lines.join("\n"));
+  } catch (err) {
+    return textResult(formatApiError(err), true);
+  }
+}
+var DeployEphemeralCommitSchema = z4.object({
+  pipeline_id: z4.string().uuid().describe("The pipeline ID"),
+  environment_name: z4.string().describe("The ephemeral environment name"),
+  session_id: z4.string().describe("The session ID from claim-ephemeral-session"),
+  commit_id: z4.string().describe("The commit SHA to deploy")
+});
+async function deployEphemeralCommit(client, args) {
+  try {
+    const result = await client.deployEphemeralCommit(
+      args.pipeline_id,
+      args.environment_name,
+      args.session_id,
+      args.commit_id
+    );
+    return textResult(
+      [
+        "Deployment triggered!",
+        "",
+        `Build deployment ID: ${result.buildDeploymentId}`,
+        `Deploy deployment ID: ${result.deployDeploymentId}`,
+        "",
+        `Use get-ephemeral-session-status with session_id "${args.session_id}" to monitor progress.`
+      ].join("\n")
+    );
+  } catch (err) {
+    return textResult(formatApiError(err), true);
+  }
+}
+var GetEphemeralSessionStatusSchema = z4.object({
+  pipeline_id: z4.string().uuid().describe("The pipeline ID"),
+  environment_name: z4.string().describe("The ephemeral environment name"),
+  session_id: z4.string().describe("The session ID to check")
+});
+async function getEphemeralSessionStatus(client, args) {
+  try {
+    const result = await client.getEphemeralSessionStatus(
+      args.pipeline_id,
+      args.environment_name,
+      args.session_id
+    );
+    const lines = [
+      "Session Status:",
+      `  Status: ${result.lock.status}`,
+      `  Type: ${result.lock.lockType}`,
+      `  Locked by: ${result.lock.lockedBy}`,
+      `  Claimed: ${result.lock.claimedAt}`
+    ];
+    if (result.lock.releasedAt) {
+      lines.push(`  Released: ${result.lock.releasedAt}`);
+      lines.push(`  Release reason: ${result.lock.releaseReason}`);
+    }
+    if (result.overridden) {
+      lines.push("");
+      lines.push("[!] This session was overridden by another claim.");
+    }
+    lines.push("");
+    if (result.deployments.length === 0) {
+      lines.push("Deployments: None");
+    } else {
+      lines.push(`Deployments (${result.deployments.length}):`);
+      for (const deployment of result.deployments) {
+        lines.push("");
+        lines.push(`  Commit: ${deployment.commitId.substring(0, 8)}`);
+        lines.push(`  Status: ${deployment.status}`);
+        if (deployment.startedAt) {
+          lines.push(`  Started: ${deployment.startedAt}`);
+        }
+        if (deployment.finishedAt) {
+          lines.push(`  Finished: ${deployment.finishedAt}`);
+        }
+        if (deployment.cause) {
+          lines.push(`  Cause: ${deployment.cause}`);
+        }
+        if (deployment.stepStatuses.length > 0) {
+          lines.push("  Steps:");
+          for (const step of deployment.stepStatuses) {
+            let stepLine = `    [${step.stage}] ${step.name}: ${step.status}`;
+            if (step.error) {
+              stepLine += ` - ${step.error}`;
+            }
+            lines.push(stepLine);
+          }
+        }
+      }
+    }
+    return textResult(lines.join("\n"));
+  } catch (err) {
+    return textResult(formatApiError(err), true);
+  }
+}
+var ReleaseEphemeralSessionSchema = z4.object({
+  pipeline_id: z4.string().uuid().describe("The pipeline ID"),
+  environment_name: z4.string().describe("The ephemeral environment name"),
+  session_id: z4.string().describe("The session ID to release")
+});
+async function releaseEphemeralSession(client, args) {
+  try {
+    await client.releaseEphemeralSession(
+      args.pipeline_id,
+      args.environment_name,
+      args.session_id
+    );
+    return textResult(
+      "Session released successfully. Any in-progress deployments have been cancelled."
+    );
+  } catch (err) {
+    return textResult(formatApiError(err), true);
+  }
+}
+
+// src/tools/pipeline-tools.ts
+import { z as z5 } from "zod";
+function formatApiError2(err) {
+  if (err instanceof ApiError) {
+    const body = err.responseBody && typeof err.responseBody === "object" ? JSON.stringify(err.responseBody, null, 2) : String(err.responseBody ?? "");
+    return `API Error (${err.statusCode}): ${err.message}${body ? `
+${body}` : ""}`;
+  }
+  return err instanceof Error ? err.message : String(err);
+}
+function textResult2(text, isError = false) {
+  return {
+    content: [{ type: "text", text }],
+    ...isError ? { isError: true } : {}
+  };
+}
+var ListPipelinesSchema = z5.object({
+  limit: z5.number().int().min(1).max(100).default(50).optional().describe("Maximum number of pipelines to return (1-100, default 50)"),
+  offset: z5.number().int().min(0).default(0).optional().describe("Number of pipelines to skip for pagination")
+});
+async function listPipelines(client, args) {
+  try {
+    const result = await client.listPipelines(args.limit, args.offset);
+    const lines = [
+      `Pipelines (${result.pagination.total} total, showing ${result.pipelines.length}):`,
+      ""
+    ];
+    if (result.pipelines.length === 0) {
+      lines.push("No pipelines found.");
+    }
+    for (const pipeline of result.pipelines) {
+      const status = pipeline.stopped ? "STOPPED" : pipeline.blocked ? "BLOCKED" : pipeline.failedStages.length > 0 ? "FAILED" : "ACTIVE";
+      lines.push(`- ${pipeline.name} (${pipeline.slug})`);
+      lines.push(`  ID: ${pipeline.id}`);
+      lines.push(`  Status: ${status}`);
+      lines.push(`  Source: ${pipeline.source}`);
+      if (pipeline.failedStages.length > 0) {
+        lines.push(`  Failed stages: ${pipeline.failedStages.join(", ")}`);
+      }
+      if (pipeline.lastDeploymentAt) {
+        lines.push(`  Last deployment: ${pipeline.lastDeploymentAt}`);
+      }
+      lines.push("");
+    }
+    if (result.pagination.hasMore) {
+      lines.push(
+        `Page ${Math.floor((args.offset ?? 0) / (args.limit ?? 50)) + 1} \u2014 use offset=${(args.offset ?? 0) + (args.limit ?? 50)} for the next page.`
+      );
+    }
+    return textResult2(lines.join("\n"));
+  } catch (err) {
+    return textResult2(formatApiError2(err), true);
+  }
+}
+var GetPipelineStateSchema = z5.object({
+  pipeline_id: z5.string().uuid().describe("Pipeline ID")
+});
+async function getPipelineState(client, args) {
+  try {
+    const state = await client.getPipelineState(args.pipeline_id);
+    const lines = [
+      `Pipeline: ${state.pipeline.name} (${state.pipeline.slug})`,
+      `ID: ${state.pipeline.id}`,
+      `Stopped: ${state.pipeline.stopped}`,
+      `Blocked: ${state.pipeline.blocked}`,
+      "",
+      "Stages:"
+    ];
+    for (const stage of state.stages) {
+      lines.push(`  ${stage.name}: ${stage.status}`);
+      if (stage.activeRevisionId !== void 0) {
+        lines.push(`    Active revision: ${stage.activeRevisionId}`);
+      }
+      if (stage.lastSuccessfulRevisionId !== void 0) {
+        lines.push(`    Last successful revision: ${stage.lastSuccessfulRevisionId}`);
+      }
+      if (stage.blockers.length > 0) {
+        lines.push(
+          `    Blockers: ${stage.blockers.map((b) => `${b.type}${b.message ? ` (${b.message})` : ""}`).join(", ")}`
+        );
+      }
+      if (stage.alarmStatus?.state) {
+        lines.push(`    Alarm: ${stage.alarmStatus.state} (${stage.alarmStatus.alarmName})`);
+      }
+      const failedSteps = stage.steps.filter((s) => s.status === "FAILED");
+      const inProgressSteps = stage.steps.filter((s) => s.status === "IN_PROGRESS");
+      const pendingApproval = stage.steps.filter((s) => s.status === "PENDING_APPROVAL");
+      if (failedSteps.length > 0) {
+        lines.push(
+          `    Failed steps: ${failedSteps.map((s) => `${s.name}${s.cause ? ` (${s.cause})` : ""}`).join(", ")}`
+        );
+      }
+      if (inProgressSteps.length > 0) {
+        lines.push(`    In progress: ${inProgressSteps.map((s) => s.name).join(", ")}`);
+      }
+      if (pendingApproval.length > 0) {
+        lines.push(`    Pending approval: ${pendingApproval.map((s) => s.name).join(", ")}`);
+      }
+      if (stage.startedAt) {
+        lines.push(`    Started: ${stage.startedAt}`);
+      }
+      if (stage.finishedAt) {
+        lines.push(`    Finished: ${stage.finishedAt}`);
+      }
+      lines.push("");
+    }
+    if (state.presentRevisions.length > 0) {
+      lines.push(
+        `Active revisions: ${state.presentRevisions.map((r) => r.revisionId).join(", ")}`
+      );
+    }
+    return textResult2(lines.join("\n"));
+  } catch (err) {
+    return textResult2(formatApiError2(err), true);
+  }
+}
+var GetStageHealthSchema = z5.object({
+  pipeline_id: z5.string().uuid().describe("Pipeline ID"),
+  stage_name: z5.string().describe("Stage name")
+});
+async function getStageHealth(client, args) {
+  try {
+    const health = await client.getStageHealth(args.pipeline_id, args.stage_name);
+    const lines = [
+      `Stage Health: ${args.stage_name}`,
+      "",
+      `Success rate: ${health.successRate}%`,
+      `Total deployments (30d): ${health.totalDeployments30d}`,
+      `Successful (30d): ${health.successfulDeployments30d}`,
+      `Failed (30d): ${health.failedDeployments30d}`,
+      "",
+      `Execution times:`,
+      `  p50: ${health.p50ExecutionTimeSec !== null ? `${health.p50ExecutionTimeSec}s` : "N/A"}`,
+      `  p90: ${health.p90ExecutionTimeSec !== null ? `${health.p90ExecutionTimeSec}s` : "N/A"}`,
+      `  max: ${health.maxExecutionTimeSec !== null ? `${health.maxExecutionTimeSec}s` : "N/A"}`
+    ];
+    return textResult2(lines.join("\n"));
+  } catch (err) {
+    return textResult2(formatApiError2(err), true);
+  }
+}
+var RetryStageSchema = z5.object({
+  pipeline_id: z5.string().uuid().describe("Pipeline ID"),
+  stage_name: z5.string().describe("Stage name to retry")
+});
+async function retryStage(client, args) {
+  try {
+    const result = await client.retryStage(args.pipeline_id, args.stage_name);
+    return textResult2(
+      result.success ? `Stage "${args.stage_name}" retry initiated successfully.` : `Failed to retry stage "${args.stage_name}".`
+    );
+  } catch (err) {
+    return textResult2(formatApiError2(err), true);
+  }
+}
+var CancelStageSchema = z5.object({
+  pipeline_id: z5.string().uuid().describe("Pipeline ID"),
+  stage_name: z5.string().describe("Stage name to cancel"),
+  reason: z5.string().optional().describe("Reason for cancellation")
+});
+async function cancelStage(client, args) {
+  try {
+    const result = await client.cancelStage(
+      args.pipeline_id,
+      args.stage_name,
+      args.reason
+    );
+    return textResult2(
+      result.success ? `Stage "${args.stage_name}" cancellation initiated. ${result.message}` : `Failed to cancel stage: ${result.message}`
+    );
+  } catch (err) {
+    return textResult2(formatApiError2(err), true);
+  }
+}
+var StopPipelineSchema = z5.object({
+  pipeline_id: z5.string().uuid().describe("Pipeline ID"),
+  reason: z5.string().optional().describe("Reason for stopping the pipeline")
+});
+async function stopPipeline(client, args) {
+  try {
+    const result = await client.stopPipeline(args.pipeline_id, args.reason);
+    return textResult2(
+      result.success ? `Pipeline stopped. ${result.message}` : `Failed to stop pipeline: ${result.message}`
+    );
+  } catch (err) {
+    return textResult2(formatApiError2(err), true);
+  }
+}
+var StartPipelineSchema = z5.object({
+  pipeline_id: z5.string().uuid().describe("Pipeline ID")
+});
+async function startPipeline(client, args) {
+  try {
+    const result = await client.startPipeline(args.pipeline_id);
+    return textResult2(
+      result.success ? `Pipeline resumed. ${result.message}` : `Failed to start pipeline: ${result.message}`
+    );
+  } catch (err) {
+    return textResult2(formatApiError2(err), true);
+  }
+}
+var StopStagePromotionSchema = z5.object({
+  pipeline_id: z5.string().uuid().describe("Pipeline ID"),
+  stage_name: z5.string().describe("Stage name"),
+  reason: z5.string().optional().describe("Reason for stopping promotion")
+});
+async function stopStagePromotion(client, args) {
+  try {
+    const result = await client.stopStagePromotion(
+      args.pipeline_id,
+      args.stage_name,
+      args.reason
+    );
+    return textResult2(
+      result.success ? `Promotion stopped for stage "${args.stage_name}". ${result.message}` : `Failed to stop promotion: ${result.message}`
+    );
+  } catch (err) {
+    return textResult2(formatApiError2(err), true);
+  }
+}
+var StartStagePromotionSchema = z5.object({
+  pipeline_id: z5.string().uuid().describe("Pipeline ID"),
+  stage_name: z5.string().describe("Stage name")
+});
+async function startStagePromotion(client, args) {
+  try {
+    const result = await client.startStagePromotion(
+      args.pipeline_id,
+      args.stage_name
+    );
+    return textResult2(
+      result.success ? `Promotion resumed for stage "${args.stage_name}". ${result.message}` : `Failed to start promotion: ${result.message}`
+    );
+  } catch (err) {
+    return textResult2(formatApiError2(err), true);
+  }
+}
+var BypassStageBlockersSchema = z5.object({
+  pipeline_id: z5.string().uuid().describe("Pipeline ID"),
+  stage_name: z5.string().describe("Stage name")
+});
+async function bypassStageBlockers(client, args) {
+  try {
+    const result = await client.bypassStageBlockers(
+      args.pipeline_id,
+      args.stage_name
+    );
+    return textResult2(
+      result.success ? `Blockers bypassed for stage "${args.stage_name}". ${result.message}
+
+Warning: Bypassing blockers skips safety checks (manual approvals, time windows, etc). Ensure this is intentional.` : `Failed to bypass blockers: ${result.message}`
+    );
+  } catch (err) {
+    return textResult2(formatApiError2(err), true);
+  }
+}
+var GetStepLogsSchema = z5.object({
+  pipeline_id: z5.string().uuid().describe("Pipeline ID"),
+  stage_name: z5.string().describe("Stage name"),
+  revision_id: z5.string().describe("Revision ID (numeric)"),
+  step_name: z5.string().describe("Step name"),
+  limit: z5.number().int().min(1).max(1e3).default(100).optional().describe("Maximum number of log lines to return"),
+  search: z5.string().optional().describe("Search string to filter logs")
+});
+async function getStepLogs(client, args) {
+  try {
+    const result = await client.getStepLogs(
+      args.pipeline_id,
+      args.stage_name,
+      args.revision_id,
+      args.step_name,
+      { limit: args.limit, search: args.search }
+    );
+    if (result.logs.length === 0) {
+      return textResult2("No logs found for this step.");
+    }
+    const lines = [
+      `Logs for step "${args.step_name}" (stage: ${args.stage_name}, revision: ${args.revision_id}):`,
+      `Showing ${result.logs.length} of ${result.pagination.total} entries`,
+      "",
+      ...result.logs.map(
+        (log) => `[${log.timestamp}] [${log.stream}] ${log.data}`
+      )
+    ];
+    if (result.pagination.hasMore) {
+      lines.push("", "... more logs available. Increase limit to see more.");
+    }
+    return textResult2(lines.join("\n"));
+  } catch (err) {
+    return textResult2(formatApiError2(err), true);
+  }
+}
+var GetPipelineEventsSchema = z5.object({
+  pipeline_id: z5.string().uuid().describe("Pipeline ID"),
+  limit: z5.number().int().min(1).max(100).default(50).optional().describe("Maximum number of events to return"),
+  offset: z5.number().int().min(0).default(0).optional().describe("Number of events to skip for pagination")
+});
+async function getPipelineEvents(client, args) {
+  try {
+    const result = await client.getPipelineEvents(args.pipeline_id, {
+      limit: args.limit,
+      offset: args.offset
+    });
+    if (result.events.length === 0) {
+      return textResult2("No events found for this pipeline.");
+    }
+    const lines = [
+      `Pipeline Events (${result.pagination.total} total, showing ${result.events.length}):`,
+      ""
+    ];
+    for (const event of result.events) {
+      const parts = [`[${event.createdAt}] ${event.eventType}`];
+      if (event.stageName) parts.push(`stage: ${event.stageName}`);
+      if (event.stepName) parts.push(`step: ${event.stepName}`);
+      parts.push(`rev: ${event.revisionId}`);
+      if (event.commitId) parts.push(`commit: ${event.commitId.slice(0, 8)}`);
+      lines.push(parts.join(" | "));
+    }
+    if (result.pagination.hasMore) {
+      lines.push(
+        "",
+        `Use offset=${(args.offset ?? 0) + (args.limit ?? 50)} for the next page.`
+      );
+    }
+    return textResult2(lines.join("\n"));
+  } catch (err) {
+    return textResult2(formatApiError2(err), true);
+  }
+}
+var ListRevisionsSchema = z5.object({
+  pipeline_id: z5.string().uuid().describe("Pipeline ID"),
+  limit: z5.number().int().min(1).max(100).default(20).optional().describe("Maximum number of revisions to return"),
+  offset: z5.number().int().min(0).default(0).optional().describe("Number of revisions to skip for pagination")
+});
+async function listRevisions(client, args) {
+  try {
+    const result = await client.listRevisions(args.pipeline_id, {
+      limit: args.limit,
+      offset: args.offset
+    });
+    if (result.revisions.length === 0) {
+      return textResult2("No revisions found for this pipeline.");
+    }
+    const lines = [
+      `Revisions (${result.pagination.total} total, showing ${result.revisions.length}):`,
+      ""
+    ];
+    for (const rev of result.revisions) {
+      lines.push(`Revision #${rev.revisionId}`);
+      lines.push(`  Commit: ${rev.commitId.slice(0, 8)}${rev.commitMessage ? ` \u2014 ${rev.commitMessage}` : ""}`);
+      lines.push(
+        `  Stages deployed: ${rev.stagesDeployed.length > 0 ? rev.stagesDeployed.join(", ") : "none"}`
+      );
+      lines.push(`  Created: ${rev.createdAt}`);
+      lines.push("");
+    }
+    if (result.pagination.hasMore) {
+      lines.push(
+        `Use offset=${(args.offset ?? 0) + (args.limit ?? 20)} for the next page.`
+      );
+    }
+    return textResult2(lines.join("\n"));
+  } catch (err) {
+    return textResult2(formatApiError2(err), true);
+  }
+}
+
+// src/schemas/pipeline-definition.ts
+import { z as z6 } from "zod";
+var DeploymentTimeWindowSchema = z6.enum([
+  "NONE",
+  "PACIFIC_WORKING_HOURS",
+  "PACIFIC_WORKING_HOURS_REDUCED"
+]);
+var RequireApprovalTypeSchema = z6.enum([
+  "ALWAYS",
+  "NEVER",
+  "DESTRUCTIVE_CHANGES_ONLY"
+]);
+var KNOWN_STEP_TYPES = [
+  "DEVRAMPS:TERRAFORM:SYNTHESIZE",
+  "DEVRAMPS:ECS:DEPLOY",
+  "DEVRAMPS:EKS:DEPLOY",
+  "DEVRAMPS:EKS:HELM",
+  "DEVRAMPS:LAMBDA:DEPLOY",
+  "DEVRAMPS:LAMBDA:INVOKE",
+  "DEVRAMPS:EC2:DEPLOY",
+  "DEVRAMPS:CODEDEPLOY:DEPLOY",
+  "DEVRAMPS:S3:UPLOAD",
+  "DEVRAMPS:CLOUDFRONT:INVALIDATE",
+  "DEVRAMPS:SCRIPT:EXECUTE",
+  "DEVRAMPS:DATABASE:MIGRATE",
+  "DEVRAMPS:APPROVAL:BAKE",
+  "DEVRAMPS:APPROVAL:TEST",
+  "DEVRAMPS:APPROVAL:MANUAL"
+];
+var KNOWN_ARTIFACT_TYPES = [
+  "DEVRAMPS:DOCKER:BUILD",
+  "DEVRAMPS:DOCKER:IMPORT",
+  "DEVRAMPS:BUNDLE:BUILD",
+  "DEVRAMPS:BUNDLE:IMPORT"
+];
+var NotificationEventKeySchema = z6.enum([
+  "stage_succeeded",
+  "stage_failed",
+  "approval_required",
+  "stage_auto_rolled_back",
+  "stage_rolled_back",
+  "stage_rolled_forward"
+]);
+var SlackNotificationConfigSchema = z6.object({
+  channel: z6.string(),
+  events: z6.array(NotificationEventKeySchema).min(1)
+});
+var NotificationsSchema = z6.object({
+  slack: SlackNotificationConfigSchema.optional()
+});
+var StageDefaultsSchema = z6.object({
+  deployment_time_window: DeploymentTimeWindowSchema.optional()
+});
+var StageSchema = z6.object({
+  name: z6.string(),
+  account_id: z6.string(),
+  region: z6.string(),
+  deployment_time_window: DeploymentTimeWindowSchema.optional(),
+  vars: z6.record(z6.string(), z6.any()).optional(),
+  auto_rollback_alarm_name: z6.string().optional(),
+  skip: z6.array(z6.string()).optional()
+});
+var StepSchema = z6.object({
+  type: z6.string(),
+  name: z6.string(),
+  id: z6.string().optional(),
+  params: z6.any().optional(),
+  goes_after: z6.array(z6.string()).optional(),
+  host_size: z6.enum(["small", "medium", "large"]).optional(),
+  architecture: z6.enum(["linux/amd64", "linux/arm64"]).optional(),
+  dependencies: z6.array(z6.string()).optional()
+}).passthrough();
+var ArtifactDefinitionSchema = z6.object({
+  type: z6.string(),
+  id: z6.string().optional(),
+  params: z6.any().optional(),
+  goes_after: z6.array(z6.string()).optional(),
+  rebuild_when_changed: z6.array(z6.string()).optional(),
+  per_stage: z6.boolean().optional(),
+  host_size: z6.enum(["small", "medium", "large"]).optional(),
+  architecture: z6.enum(["linux/amd64", "linux/arm64"]).optional(),
+  dependencies: z6.array(z6.string()).optional(),
+  envs: z6.record(z6.string(), z6.any()).optional()
+}).passthrough();
+var ArtifactsMapSchema = z6.record(
+  z6.string(),
+  ArtifactDefinitionSchema
+);
+var EphemeralTriggerSchema = z6.object({
+  on: z6.enum(["pull_request", "api"]),
+  target_branches: z6.array(z6.string()).optional()
+}).passthrough();
+var EphemeralReleaseSchema = z6.object({
+  on: z6.enum(["pr_closed", "api", "timeout"]),
+  after_idle_hours: z6.number().optional()
+}).passthrough();
+var EphemeralEnvironmentSchema = z6.object({
+  triggers: z6.array(EphemeralTriggerSchema).min(1),
+  release: z6.array(EphemeralReleaseSchema).min(1),
+  on_release: z6.enum(["deploy_main"]).optional(),
+  account_id: z6.string(),
+  region: z6.string(),
+  skip: z6.array(z6.string()).optional(),
+  vars: z6.record(z6.string(), z6.any()).optional()
+}).passthrough();
+var EphemeralEnvironmentsMapSchema = z6.record(
+  z6.string(),
+  EphemeralEnvironmentSchema
+);
+var PipelineInnerSchema = z6.object({
+  cloud_provider: z6.enum(["AWS"]),
+  pipeline_updates_require_approval: RequireApprovalTypeSchema,
+  tracks: z6.string().optional(),
+  notifications: NotificationsSchema.optional(),
+  stage_defaults: StageDefaultsSchema.optional(),
+  stages: z6.array(StageSchema).min(1),
+  steps: z6.array(StepSchema),
+  artifacts: ArtifactsMapSchema,
+  ephemeral_environments: EphemeralEnvironmentsMapSchema.optional()
+});
+var PipelineDefinitionSchema = z6.object({
+  version: z6.string(),
+  pipeline: PipelineInnerSchema
+});
+
+// src/resources/pipeline-schema.ts
+var PIPELINE_SCHEMA_URI = "devramps://schema/pipeline-definition";
+function getPipelineSchemaResource() {
+  return {
+    uri: PIPELINE_SCHEMA_URI,
+    name: "Pipeline Definition Schema",
+    description: "Reference documentation for the DevRamps pipeline definition YAML format",
+    mimeType: "text/markdown"
+  };
+}
+function getPipelineSchemaContent() {
+  return `# DevRamps Pipeline Definition Schema
+
+## Overview
+
+A DevRamps pipeline definition is a YAML file at \`.devramps/<pipeline_name>/pipeline.yaml\` that describes your CI/CD pipeline configuration.
+
+## Top-Level Structure
+
+\`\`\`yaml
+version: "1.0.0"
+
+pipeline:
+  cloud_provider: AWS
+  pipeline_updates_require_approval: ALWAYS  # ALWAYS | NEVER | DESTRUCTIVE_CHANGES_ONLY
+  tracks: main                               # Optional: branch to track (default: main)
+
+  notifications:                             # Optional
+    slack:
+      channel: "#deployments"
+      events:
+        - stage_failed
+        - approval_required
+        - stage_auto_rolled_back
+        - stage_rolled_back
+        - stage_rolled_forward
+
+  stage_defaults:                            # Optional - inherited by all stages
+    deployment_time_window: PACIFIC_WORKING_HOURS
+
+  stages:
+    - name: staging
+      account_id: "123456789012"
+      region: us-east-1
+      deployment_time_window: NONE           # Optional per-stage override
+      vars:                                  # Optional stage-specific variables
+        env: staging
+      skip:                                  # Optional - step names to skip in this stage
+        - "Bake Period"
+      auto_rollback_alarm_name: my-alarm     # Optional CloudWatch alarm
+
+    - name: production
+      account_id: "123456789012"
+      region: us-east-1
+      vars:
+        env: production
+
+  ephemeral_environments:                    # Optional
+    pr-env:
+      triggers:
+        - on: pull_request
+          target_branches: ["main"]
+        - on: api
+      release:
+        - on: pr_closed
+        - on: api
+        - on: timeout
+          after_idle_hours: 24
+      on_release: deploy_main
+      account_id: "123456789012"
+      region: us-east-1
+      skip: ["Bake Period"]
+      vars:
+        env: ephemeral
+
+  steps:
+    - name: Synthesize Infrastructure
+      id: infra
+      type: DEVRAMPS:TERRAFORM:SYNTHESIZE
+      params:
+        requires_approval: ALWAYS
+        source: /infrastructure
+        variables:
+          region: \${{ stage.region }}
+          aws_account_id: \${{ stage.account_id }}
+          env: \${{ vars.env }}
+
+    - name: Deploy Backend Service
+      type: DEVRAMPS:ECS:DEPLOY
+      goes_after: ["Synthesize Infrastructure"]
+      params:
+        cluster_name: \${{ steps.infra.ecs_cluster_name }}
+        service_name: \${{ steps.infra.ecs_service_name }}
+        reference_task_definition: \${{ steps.infra.task_definition }}
+        images:
+          - container_name: service
+            image: \${{ stage.artifacts.backend.image_url }}
+
+    - name: Deploy Frontend
+      type: DEVRAMPS:S3:UPLOAD
+      goes_after: ["Synthesize Infrastructure"]
+      params:
+        source_s3_url: \${{ stage.artifacts.frontend.s3_url }}
+        bucket: "\${{ steps.infra.frontend_bucket_name }}"
+        prefix: assets/
+        decompress: true
+        clean: true
+
+    - name: Invalidate Cache
+      type: DEVRAMPS:CLOUDFRONT:INVALIDATE
+      goes_after: ["Deploy Frontend"]
+      params:
+        distribution_id: \${{ steps.infra.cloudfront_distribution_id }}
+        paths: ["/*"]
+
+    - name: Bake Period
+      type: DEVRAMPS:APPROVAL:BAKE
+      params:
+        duration_minutes: 5
+
+  artifacts:
+    Backend Image:
+      id: backend
+      type: DEVRAMPS:DOCKER:BUILD
+      architecture: "linux/amd64"
+      host_size: "medium"
+      rebuild_when_changed:
+        - /services/backend
+      params:
+        dockerfile: /services/backend/Dockerfile
+
+    Frontend Bundle:
+      id: frontend
+      type: DEVRAMPS:BUNDLE:BUILD
+      per_stage: true
+      rebuild_when_changed:
+        - /services/frontend
+      dependencies: ["node.24"]
+      envs:
+        environment: \${{ vars.env }}
+      params:
+        build_commands: |
+          cd services/frontend
+          npm install
+          npm run build
+          zip -r ../../bundle.zip ./dist
+        file_path: /bundle.zip
+\`\`\`
+
+## Step Types
+
+${KNOWN_STEP_TYPES.map((t) => `- \`${t}\``).join("\n")}
+- \`CUSTOM:<your-type>\` \u2014 Custom step types from your step registry
+
+## Artifact Types
+
+${KNOWN_ARTIFACT_TYPES.map((t) => `- \`${t}\``).join("\n")}
+
+## Stage Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | string | Yes | Unique stage name |
+| account_id | string | Yes | AWS account ID |
+| region | string | Yes | AWS region |
+| deployment_time_window | enum | No | When deployments are allowed |
+| vars | object | No | Stage-specific variables accessible via \${{ vars.key }} |
+| skip | string[] | No | Step names to skip in this stage |
+| auto_rollback_alarm_name | string | No | CloudWatch alarm for auto-rollback |
+
+## Step Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| type | string | Yes | Step type identifier |
+| name | string | Yes | Unique step name |
+| id | string | No | Short ID for expression references |
+| params | object | Yes | Step-specific parameters |
+| goes_after | string[] | No | Dependencies (step names, IDs, or artifact names) |
+| host_size | enum | No | VM size: small, medium, large |
+| architecture | enum | No | linux/amd64 or linux/arm64 |
+| dependencies | string[] | No | System dependencies to install |
+
+## Artifact Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| type | string | Yes | Artifact type identifier |
+| id | string | No | Short ID for expression references |
+| params | object | Yes | Artifact-specific parameters |
+| rebuild_when_changed | string[] | No | Paths that trigger rebuild |
+| per_stage | boolean | No | Build per stage (default: false) |
+| host_size | enum | No | VM size: small, medium, large |
+| architecture | enum | No | linux/amd64 or linux/arm64 |
+| dependencies | string[] | No | System dependencies to install (e.g., "node.24") |
+| envs | object | No | Environment variables for the build |
+
+## Expression Syntax
+
+Steps and artifacts can reference dynamic values using \`\${{ }}\` expressions:
+
+**Stage context:**
+- \`\${{ stage.name }}\` \u2014 Current stage name
+- \`\${{ stage.account_id }}\` \u2014 Current stage AWS account ID
+- \`\${{ stage.region }}\` \u2014 Current stage AWS region
+
+**Stage variables:**
+- \`\${{ vars.key }}\` \u2014 Stage-specific variable
+- \`\${{ vars.nested.key }}\` \u2014 Nested variable access
+
+**Step outputs (from Terraform or other steps):**
+- \`\${{ steps.<step_id>.<output_name> }}\` \u2014 Reference by step ID
+- \`\${{ steps["Step Name"].<output_name> }}\` \u2014 Reference by step name
+
+**Artifact outputs:**
+- \`\${{ stage.artifacts.<artifact_id>.image_url }}\` \u2014 Docker image URL
+- \`\${{ stage.artifacts.<artifact_id>.s3_url }}\` \u2014 Bundle S3 URL
+- \`\${{ stage.artifacts.<artifact_id>.s3_bucket }}\` \u2014 Bundle S3 bucket
+- \`\${{ stage.artifacts.<artifact_id>.s3_key }}\` \u2014 Bundle S3 key
+
+**Secrets:**
+- \`\${{ organization.secrets["SECRET_NAME"] }}\` \u2014 Organization secret
+- \`\${{ secret("SECRET_NAME") }}\` \u2014 Shorthand for organization secret
+
+**Pipeline/org context:**
+- \`\${{ pipeline.name }}\` / \`\${{ pipeline.slug }}\`
+- \`\${{ organization.name }}\` / \`\${{ organization.slug }}\`
+- \`\${{ trigger.sha }}\` / \`\${{ trigger.branch }}\`
+
+## Notification Events
+
+- \`stage_succeeded\` \u2014 A stage deployment completed successfully
+- \`stage_failed\` \u2014 A stage deployment failed
+- \`approval_required\` \u2014 A manual approval is needed
+- \`stage_auto_rolled_back\` \u2014 A stage was automatically rolled back
+- \`stage_rolled_back\` \u2014 A stage rollback completed
+- \`stage_rolled_forward\` \u2014 A stage roll-forward completed
+
+## Deployment Time Windows
+
+- \`NONE\` \u2014 No restrictions, deploy any time
+- \`PACIFIC_WORKING_HOURS\` \u2014 9am-5pm Pacific, weekdays only
+- \`PACIFIC_WORKING_HOURS_REDUCED\` \u2014 10am-4pm Pacific, weekdays only
+
+## Ephemeral Environments
+
+Ephemeral environments are temporary deployment environments that can be triggered by pull requests or API calls. They use the same stages, steps, and artifacts as the main pipeline but with their own account, region, and variables.
+
+**Trigger types:**
+- \`pull_request\` \u2014 Triggered when a PR is opened against specified branches
+- \`api\` \u2014 Triggered via the DevRamps API (for AI agents, etc.)
+
+**Release types:**
+- \`pr_closed\` \u2014 Released when the PR is closed/merged
+- \`api\` \u2014 Released via the API
+- \`timeout\` \u2014 Released after idle for specified hours
+
+## File Structure
+
+Pipeline definitions live under \`.devramps/<pipeline_name>/\`:
+\`\`\`
+.devramps/
+  my_pipeline/
+    pipeline.yaml                      # Pipeline definition
+    aws_additional_iam_policies.json   # Additional IAM permissions for Terraform
+\`\`\`
+
+## Bootstrap
+
+After creating or modifying pipeline files, run:
+\`\`\`
+npx @devramps/cli bootstrap
+\`\`\`
+
+This provisions the required AWS resources (ECR repos, S3 buckets, IAM roles, Terraform state buckets) in your target accounts.
+
+## Documentation
+
+For more details, visit https://devramps.com/docs
+`;
+}
+
+// src/resources/step-type-docs.ts
+var STEP_TYPE_DOCS_URI = "devramps://docs/step-types";
+function getStepTypeDocsResource() {
+  return {
+    uri: STEP_TYPE_DOCS_URI,
+    name: "Step Type Documentation",
+    description: "Documentation for all available DevRamps step types, including parameters and YAML examples",
+    mimeType: "text/markdown"
+  };
+}
+async function getStepTypeDocsContent(client) {
+  if (client) {
+    try {
+      const result = await client.listStepTypes();
+      const lines = [
+        "# DevRamps Step Types",
+        "",
+        "Available step types for pipeline definitions.",
+        ""
+      ];
+      for (const step of result.steps) {
+        lines.push(`## ${step.name} (\`${step.stepType}\`)`);
+        lines.push("");
+        if (step.shortDescription) {
+          lines.push(step.shortDescription);
+          lines.push("");
+        }
+        if (step.longDescription) {
+          lines.push(step.longDescription);
+          lines.push("");
+        }
+        if (step.category) {
+          lines.push(`**Category:** ${step.category}`);
+        }
+        if (step.status) {
+          lines.push(`**Status:** ${step.status}`);
+        }
+        if (step.version) {
+          lines.push(`**Version:** ${step.version}`);
+        }
+        lines.push("");
+        if (step.yamlExample) {
+          lines.push("### YAML Example");
+          lines.push("");
+          lines.push("```yaml");
+          lines.push(step.yamlExample);
+          lines.push("```");
+          lines.push("");
+        }
+        if (step.paramsJsonSchema && typeof step.paramsJsonSchema === "object") {
+          lines.push("### Parameters Schema");
+          lines.push("");
+          lines.push("```json");
+          lines.push(JSON.stringify(step.paramsJsonSchema, null, 2));
+          lines.push("```");
+          lines.push("");
+        }
+        if (step.documentationUrl) {
+          lines.push(`[Documentation](${step.documentationUrl})`);
+          lines.push("");
+        }
+        lines.push("---");
+        lines.push("");
+      }
+      return lines.join("\n");
+    } catch {
+    }
+  }
+  return getStaticStepTypeDocs();
+}
+function getStaticStepTypeDocs() {
+  return `# DevRamps Step Types
+
+## Deployment Steps
+
+### ECS Deploy (\`DEVRAMPS:ECS:DEPLOY\`)
+Deploy a container image to an Amazon ECS service.
+
+**Parameters:**
+- \`cluster_name\` (string, required) \u2014 ECS cluster name
+- \`service_name\` (string, required) \u2014 ECS service name
+- \`reference_task_definition\` (string, required) \u2014 Task definition ARN
+- \`images\` (array, required) \u2014 Container image mappings
+  - \`container_name\` (string) \u2014 Container name in task definition
+  - \`image\` (string) \u2014 Image URL or artifact reference
+- \`account_id\` (string, optional) \u2014 Override AWS account
+- \`region\` (string, optional) \u2014 Override AWS region
+- \`timeout\` (number, optional) \u2014 Timeout in minutes (default: 360)
+
+### Lambda Deploy (\`DEVRAMPS:LAMBDA:DEPLOY\`)
+Deploy code to an AWS Lambda function.
+
+**Parameters:**
+- \`function_name\` (string, required) \u2014 Lambda function name
+- \`s3_bucket\` (string, optional) \u2014 S3 bucket with deployment package
+- \`s3_key\` (string, optional) \u2014 S3 key for deployment package
+- \`image_url\` (string, optional) \u2014 Container image URL
+- \`account_id\`, \`region\`, \`timeout\` \u2014 Same as ECS Deploy
+
+### Lambda Invoke (\`DEVRAMPS:LAMBDA:INVOKE\`)
+Invoke a Lambda function as a pipeline step.
+
+**Parameters:**
+- \`function_name\` (string, required)
+- \`payload\` (string, optional) \u2014 JSON payload
+- \`invocation_type\` (enum, optional) \u2014 "RequestResponse" or "Event"
+
+### S3 Upload (\`DEVRAMPS:S3:UPLOAD\`)
+Upload files to an S3 bucket.
+
+### CloudFront Invalidate (\`DEVRAMPS:CLOUDFRONT:INVALIDATE\`)
+Invalidate CloudFront distribution cache.
+
+### EKS Deploy (\`DEVRAMPS:EKS:DEPLOY\`)
+Deploy to Amazon EKS (Kubernetes).
+
+### EKS Helm (\`DEVRAMPS:EKS:HELM\`)
+Deploy using Helm charts to EKS.
+
+## Custom Steps
+
+### Script Execute (\`DEVRAMPS:SCRIPT:EXECUTE\`)
+Run a custom script during deployment.
+
+**Parameters:**
+- \`script_path\` (string, required) \u2014 Path to the script
+- \`params\` (string[], optional) \u2014 CLI arguments
+- \`working_directory\` (string, optional)
+- \`environment_variables\` (object, optional)
+- \`timeout\` (number, optional) \u2014 Minutes (default: 30)
+- \`run_in_vpc\` (boolean, optional)
+
+### Database Migrate (\`DEVRAMPS:DATABASE:MIGRATE\`)
+Run database migrations.
+
+## Approval Workflows
+
+### Bake (\`DEVRAMPS:APPROVAL:BAKE\`)
+Wait for a specified duration before allowing promotion.
+
+**Parameters:**
+- \`duration_minutes\` (number, required)
+
+### Test (\`DEVRAMPS:APPROVAL:TEST\`)
+Run tests and wait for results before promotion.
+
+### Manual (\`DEVRAMPS:APPROVAL:MANUAL\`)
+Require manual approval before promotion.
+
+## Artifact Types
+
+### Docker Build (\`DEVRAMPS:DOCKER:BUILD\`)
+Build a Docker container image.
+
+**Parameters:**
+- \`dockerfile\` (string, required) \u2014 Dockerfile path
+- \`build_root\` (string, optional) \u2014 Build context directory
+- \`args\` (string[], optional) \u2014 Build arguments
+- \`env\` (object, optional) \u2014 Environment variables
+
+### Docker Import (\`DEVRAMPS:DOCKER:IMPORT\`)
+Import a pre-built Docker image from an external registry.
+
+### Bundle Build (\`DEVRAMPS:BUNDLE:BUILD\`)
+Build a file bundle (zip archive).
+
+**Parameters:**
+- \`build_commands\` (string, required) \u2014 Build command(s)
+- \`file_path\` (string, required) \u2014 Path to bundle output
+- \`env\` (object, optional) \u2014 Environment variables
+
+### Bundle Import (\`DEVRAMPS:BUNDLE:IMPORT\`)
+Import a pre-built bundle from an external source.
+`;
+}
+
+// src/prompts/scaffold-project.ts
+import { z as z7 } from "zod";
+var SCAFFOLD_PROJECT_PROMPT = {
+  name: "scaffold-project",
+  description: "Guided workflow to scaffold a DevRamps CI/CD pipeline for a project. Deeply analyzes the codebase, determines the right infrastructure and deployment architecture, generates Terraform configs for new projects, and produces a complete pipeline definition.",
+  argsSchema: {
+    project_path: z7.string().describe("Path to the project root directory")
+  }
+};
+function getScaffoldProjectMessages(args) {
+  const projectPath = args.project_path || ".";
+  return {
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: `I want to set up a DevRamps CI/CD pipeline for my project at ${projectPath}.
+
+You are an expert DevOps engineer helping me set up a production-grade CI/CD pipeline using DevRamps. Follow this workflow carefully.
+
+---
+
+## Phase 1: Deep Codebase Analysis
+
+Thoroughly analyze the project at \`${projectPath}\`. Read files, explore directories, and build a complete picture:
+
+1. **Project structure** \u2014 List the top-level directory layout. Understand the monorepo vs single-service structure.
+2. **Backend services** \u2014 Look for Dockerfiles, server code, API frameworks (Express, FastAPI, Django, Spring, Go net/http, etc.). Note the language, framework, and entry point.
+3. **Frontend apps** \u2014 Look for package.json with build scripts, React/Vue/Angular/Next.js/Vite configs. Note the build command and output directory.
+4. **Infrastructure** \u2014 Look for \`terraform/\`, \`infrastructure/\`, or \`*.tf\` files. If found, read them to understand what resources are already defined.
+5. **Existing CI/CD** \u2014 Look for .github/workflows, .gitlab-ci.yml, Jenkinsfile, buildspec.yml, existing \`.devramps/\` directories.
+6. **Dependencies** \u2014 Check package.json, requirements.txt, go.mod, Cargo.toml, etc. for frameworks, tools, and build requirements.
+7. **Database** \u2014 Look for migration files, ORM configs (Prisma, TypeORM, Alembic, Flyway), database connection configuration.
+
+Based on your analysis, classify the project into one of these categories:
+- **Brand new / nearly empty repo** \u2014 Minimal or no existing application code
+- **Has application code but no infrastructure** \u2014 App code exists but no Terraform/IaC
+- **Has infrastructure and code** \u2014 Both application code and Terraform exist
+- **Already has DevRamps config** \u2014 Has a \`.devramps/\` directory (analyze gaps and suggest improvements)
+
+---
+
+## Phase 2: Ask Key Questions Up Front
+
+Before generating anything, ask the user these questions **all at once** in a single message. Suggest reasonable defaults based on what you learned in Phase 1:
+
+- **Project name** \u2014 What should this project/pipeline be called? (Suggest a default based on the directory name, repo name, or any package.json name field. e.g., "my-saas-app")
+- **What are you building?** \u2014 (Only ask for brand new / empty repos.) e.g., "A SaaS API with a React frontend", "A data processing pipeline". For existing repos, state what you determined from the code and ask if that's correct.
+- **Stages** \u2014 Do you want to start with a single stage (e.g., just staging) or multiple stages (e.g., staging + production)? Recommend starting with one stage to get up and running quickly \u2014 they can always add more later. If they choose multiple, ask whether staging and production use the same or different AWS accounts.
+- **AWS account ID(s)** \u2014 What AWS account ID(s) for the stage(s) they chose?
+- **AWS regions** \u2014 What region(s) to deploy to? (Default: us-east-1)
+- **Architecture tier** \u2014 Present the three tiers (see Phase 3) with a recommendation based on context. Let the user pick.
+
+**Do NOT ask about:**
+- Deployment targets, artifact types, build commands, frameworks \u2014 determine these from the code
+- CI/CD tool choice \u2014 DevRamps handles this
+- Individual AWS service choices \u2014 the architecture tier determines this
+- Slack notifications, ephemeral environments, approval policies \u2014 use sensible defaults (no Slack, no ephemeral envs, ALWAYS for approval) and mention the user can add these later
+
+---
+
+## Phase 3: Determine Architecture & Generate Terraform
+
+Based on the user's answers, generate Terraform configuration files under \`/infrastructure\` in the project.
+
+### Architecture Tiers
+
+Present these to the user in Phase 2 and make a recommendation:
+
+**1. Budget-friendly** (~$50-80/mo, cheapest to run):
+- VPC with public + private subnets across 2 AZs
+- FCK-NAT instance for NAT (no NAT Gateway \u2014 saves ~$30/mo)
+- Fargate ECS service in private subnets
+- Private ALB in private subnets (accessed via CloudFront only)
+- CloudFront as CDN + entry point (routes /api/* to ALB, static assets to S3)
+- S3 bucket for frontend static assets with OAC
+- RDS PostgreSQL (db.t4g.micro) in private subnets
+
+**2. Standard** (recommended, ~$100-150/mo):
+- VPC with public + private subnets across 2 AZs
+- FCK-NAT instance for NAT (no NAT Gateway)
+- Fargate ECS service in private subnets
+- Private ALB in public subnets
+- CloudFront as CDN in front of ALB and S3
+- S3 bucket for frontend static assets with OAC
+- RDS PostgreSQL (db.t4g.small) in private subnets with Multi-AZ standby
+
+**3. High Availability** (production-grade, ~$200-300/mo):
+- VPC with public + private subnets across 3 AZs
+- Managed NAT Gateway (highest availability)
+- Fargate ECS service in private subnets (multi-AZ)
+- Private ALB in public subnets
+- CloudFront as CDN in front of ALB and S3
+- S3 bucket for frontend static assets with OAC
+- RDS PostgreSQL (db.t4g.medium) in private subnets with Multi-AZ
+
+### Terraform File Organization
+
+**CRITICAL: You MUST split Terraform into separate files by concern. Putting everything in a single main.tf is NOT acceptable and will be rejected by the user.** Use this exact structure:
+
+\`\`\`
+infrastructure/
+  backend.tf        # Terraform backend configuration (S3 remote state)
+  providers.tf      # AWS provider configuration
+  variables.tf      # All input variables
+  outputs.tf        # All outputs (MUST output everything the pipeline needs)
+  vpc.tf            # VPC, subnets, internet gateway, NAT, route tables
+  security.tf       # Security groups
+  ecs.tf            # ECS cluster, task definition, service, IAM roles
+  alb.tf            # Application load balancer, target groups, listeners
+  frontend.tf       # S3 bucket for static assets, bucket policy
+  cloudfront.tf     # CloudFront distribution, OAC, cache behaviors
+  rds.tf            # RDS instance, subnet group (if database needed)
+\`\`\`
+
+### Terraform Requirements
+
+Every generated Terraform file set MUST include:
+
+**backend.tf \u2014 REQUIRED (without this, DevRamps cannot manage Terraform state):**
+\`\`\`hcl
+terraform {
+  required_version = ">= 1.5"
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.0"
+    }
+  }
+  backend "s3" {}  # MUST be present \u2014 DevRamps configures the state bucket during bootstrap
+}
+\`\`\`
+
+**providers.tf:**
+\`\`\`hcl
+provider "aws" {
+  region = var.region
+}
+\`\`\`
+
+**variables.tf** \u2014 Must accept these variables (plus any project-specific ones):
+\`\`\`hcl
+variable "region" {
+  type        = string
+  description = "AWS region"
+}
+
+variable "aws_account_id" {
+  type        = string
+  description = "AWS account ID"
+}
+
+variable "env" {
+  type        = string
+  description = "Environment name (staging, production, etc.)"
+}
+
+variable "app_name" {
+  type        = string
+  description = "Application name"
+  default     = "<project-name>"
+}
+
+# Artifact variables \u2014 passed by the pipeline so Terraform can reference them
+variable "backend_service_image_uri" {
+  type        = string
+  description = "Docker image URI for the backend service"
+  default     = ""  # Empty on first run before any image is built
+}
+
+variable "frontend_bundle_s3_bucket" {
+  type        = string
+  description = "S3 bucket containing the frontend bundle"
+  default     = ""
+}
+
+variable "frontend_bundle_s3_key" {
+  type        = string
+  description = "S3 key for the frontend bundle"
+  default     = ""
+}
+\`\`\`
+
+**outputs.tf** \u2014 Must output everything the pipeline steps need:
+\`\`\`hcl
+# ECS outputs (used by DEVRAMPS:ECS:DEPLOY step)
+output "backend_cluster_name" {
+  value = aws_ecs_cluster.main.name
+}
+
+output "backend_service_name" {
+  value = aws_ecs_service.api.name
+}
+
+output "backend_task_definition" {
+  value = aws_ecs_task_definition.api.family
+}
+
+# Frontend outputs (used by DEVRAMPS:S3:UPLOAD step)
+output "frontend_bundle_bucket_name" {
+  value = aws_s3_bucket.frontend.id
+}
+
+# CloudFront outputs (used by DEVRAMPS:CLOUDFRONT:INVALIDATE step)
+output "cloudfront_distribution_id" {
+  value = aws_cloudfront_distribution.main.id
+}
+
+# Convenience outputs
+output "cloudfront_domain_name" {
+  value = aws_cloudfront_distribution.main.domain_name
+}
+
+output "alb_dns_name" {
+  value = aws_lb.api.dns_name
+}
+\`\`\`
+
+**vpc.tf** \u2014 MUST include private subnets and NAT for ECS tasks:
+- Public subnets (for ALB, NAT)
+- Private subnets (for ECS tasks, RDS)
+- Internet gateway on public subnets
+- NAT (FCK-NAT instance for Budget/Standard, managed NAT Gateway for High Availability)
+- Route tables: public routes through IGW, private routes through NAT
+- **ECS tasks MUST be in private subnets** \u2014 they need NAT to pull images from ECR and reach AWS APIs
+
+**ecs.tf** \u2014 Must include:
+- ECS cluster
+- Task definition using the \`backend_service_image_uri\` variable for the container image (with a sensible placeholder default like a public nginx image for the initial \`terraform apply\` before any image is built)
+- ECS service in private subnets with \`assign_public_ip = false\`
+- Task execution IAM role with ECS task execution policy
+- CloudWatch log group for container logs
+
+**cloudfront.tf** \u2014 MUST include BOTH origins (S3 and ALB). A CloudFront distribution with only one origin will break either the frontend or the API:
+- **Two origins required:** S3 origin (for static assets) AND ALB/custom origin (for API backend)
+- **Ordered cache behavior:** \`/api/*\` path pattern routes to the ALB origin with caching DISABLED (min/default/max TTL all 0, forward all query strings, headers including Authorization and Origin, forward all cookies)
+- **Default cache behavior:** routes to S3 origin with caching enabled
+- **Origin Access Control** for the S3 origin (OAC, not OAI)
+- **Custom error response** for SPA routing: 403 \u2192 200 with /index.html
+- The ALB origin must use \`custom_origin_config\` with \`origin_protocol_policy = "http-only"\` (ALB listener is HTTP port 80)
+
+**Naming convention:**
+Use \`\${var.app_name}-\${var.env}\` as a prefix for all resource names and tags.
+
+**Tagging:**
+All resources should include at minimum:
+\`\`\`hcl
+tags = {
+  Name        = "\${var.app_name}-\${var.env}-<resource>"
+  Environment = var.env
+  Project     = var.app_name
+  ManagedBy   = "terraform"
+}
+\`\`\`
+
+---
+
+## Phase 3.5: Validate Terraform & Infrastructure Review
+
+After generating the Terraform files, **validate them and present a summary to the user** before moving on. This is a checkpoint \u2014 don't proceed until the user confirms they're happy.
+
+### Terraform Validation
+
+Run \`terraform validate\` to catch syntax errors before going further:
+
+\`\`\`bash
+cd infrastructure && terraform init -backend=false && terraform validate
+\`\`\`
+
+Use \`-backend=false\` because the S3 backend isn't configured yet (DevRamps sets that up during bootstrap). If validation fails, fix the errors in the Terraform files and re-run until it passes. Do not present the summary to the user until validation succeeds.
+
+### Pre-Summary Checklist
+
+Before presenting the summary, verify ALL of the following. If any check fails, fix the issue first:
+
+- [ ] \`backend.tf\` exists and contains \`backend "s3" {}\`
+- [ ] \`providers.tf\` exists and is separate from \`backend.tf\`
+- [ ] \`variables.tf\` exists with all required variables
+- [ ] \`outputs.tf\` exists with outputs for every value the pipeline references
+- [ ] \`vpc.tf\` exists with both public AND private subnets, and NAT (FCK-NAT or NAT Gateway per tier)
+- [ ] \`cloudfront.tf\` has BOTH an S3 origin AND an ALB origin (if the project has both frontend and backend)
+- [ ] \`cloudfront.tf\` has an ordered cache behavior routing \`/api/*\` to the ALB origin
+- [ ] ECS tasks are in private subnets with \`assign_public_ip = false\`
+- [ ] Terraform files are split across multiple files (NOT all in main.tf)
+- [ ] \`terraform validate\` passes
+
+### Summary Format
+
+Present the summary in this structure:
+
+**1. Decisions made:**
+List every significant architectural choice you made, written in plain English. For example:
+- "VPC with 2 availability zones (us-east-1a, us-east-1b) and private subnets for ECS/RDS"
+- "FCK-NAT instance instead of a managed NAT Gateway (saves ~$32/mo)"
+- "Fargate ECS service (serverless containers, no EC2 instances to manage)"
+- "Private ALB in public subnets \u2014 only accessible via CloudFront"
+- "RDS PostgreSQL db.t4g.micro with 20GB storage (no Multi-AZ standby)"
+- "CloudFront distribution routing /api/* to ALB, static assets to S3"
+- "S3 bucket with Origin Access Control for frontend assets"
+
+**2. Estimated monthly cost:**
+Provide a line-item cost estimate in a table. Use the AWS pricing for the selected region. Be specific about instance sizes, storage, and data transfer assumptions. Example:
+
+| Resource | Configuration | Est. Monthly Cost |
+|----------|--------------|-------------------|
+| ECS Fargate | 0.25 vCPU, 0.5 GB, 1 task 24/7 | ~$9 |
+| ALB | Application Load Balancer | ~$16 + data |
+| RDS PostgreSQL | db.t4g.micro, 20GB gp3 | ~$13 |
+| FCK-NAT | t4g.nano instance | ~$3 |
+| S3 | Frontend assets (<1GB) | ~$0.02 |
+| CloudFront | 10GB transfer/mo | ~$1 |
+| CloudWatch Logs | 5GB ingestion/mo | ~$2.50 |
+| **Total** | | **~$45-50/mo** |
+
+Note: actual costs vary with traffic, data transfer, and usage. This estimate assumes low-moderate traffic.
+
+**3. Optional upgrades:**
+List 3-5 concrete changes the user could ask for, each with the benefit, tradeoff, and approximate cost impact. Format as a numbered list so the user can say "do 1 and 3". For example:
+
+1. **Replace FCK-NAT with managed NAT Gateway** \u2014 Higher availability and throughput, no instance to manage. +~$32/mo.
+2. **Enable RDS Multi-AZ** \u2014 Automatic failover to standby in another AZ. Better durability. +~$13/mo (doubles RDS cost).
+3. **Increase ECS task size to 0.5 vCPU / 1GB** \u2014 More headroom for the backend service. +~$9/mo.
+4. **Add a third availability zone** \u2014 Better fault tolerance. Adds one more subnet pair + slightly higher NAT costs.
+5. **Add a custom domain with ACM certificate** \u2014 HTTPS with your own domain instead of the CloudFront \`.cloudfront.net\` URL. No additional cost (ACM certs are free), but requires a Route 53 hosted zone or DNS access.
+
+Then ask: "Want me to make any of these changes, or are you happy with the current setup?"
+
+If the user requests changes, apply them to the Terraform files and re-present the updated summary. Once the user confirms, proceed to Phase 4.
+
+---
+
+## Phase 4: Generate Pipeline Definition
+
+After Terraform files are written and the user has confirmed the infrastructure, construct the complete pipeline definition object and call the \`scaffold-pipeline\` tool. The definition must follow this structure:
+
+\`\`\`yaml
+version: "1.0.0"
+
+pipeline:
+  cloud_provider: AWS
+  pipeline_updates_require_approval: ALWAYS
+
+  stage_defaults:
+    deployment_time_window: PACIFIC_WORKING_HOURS
+
+  stages:
+    - name: staging
+      deployment_time_window: NONE
+      account_id: "<AWS_ACCOUNT_ID>"
+      region: us-east-1
+      skip: ["Bake Period"]
+      vars:
+        env: staging
+
+    - name: production
+      account_id: "<AWS_ACCOUNT_ID>"
+      region: us-east-1
+      vars:
+        env: production
+
+  steps:
+    - name: Synthesize Infrastructure
+      id: infra
+      type: DEVRAMPS:TERRAFORM:SYNTHESIZE
+      params:
+        requires_approval: ALWAYS
+        source: /infrastructure
+        variables:
+          region: \${{ stage.region }}
+          aws_account_id: \${{ stage.account_id }}
+          env: \${{ vars.env }}
+          backend_service_image_uri: \${{ stage.artifacts.backend_service.image_url }}
+          frontend_bundle_s3_bucket: \${{ stage.artifacts.frontend_bundle.s3_bucket }}
+          frontend_bundle_s3_key: \${{ stage.artifacts.frontend_bundle.s3_key }}
+
+    - name: Deploy Backend Service
+      id: backend
+      type: DEVRAMPS:ECS:DEPLOY
+      goes_after: ["Synthesize Infrastructure"]
+      params:
+        cluster_name: \${{ steps.infra.backend_cluster_name }}
+        service_name: \${{ steps.infra.backend_service_name }}
+        reference_task_definition: \${{ steps.infra.backend_task_definition }}
+        images:
+          - container_name: service
+            image: \${{ stage.artifacts.backend_service.image_url }}
+
+    - name: Deploy Frontend Bundle
+      type: DEVRAMPS:S3:UPLOAD
+      goes_after: ["Synthesize Infrastructure"]
+      params:
+        source_s3_url: \${{ stage.artifacts.frontend_bundle.s3_url }}
+        bucket: "\${{ steps.infra.frontend_bundle_bucket_name }}"
+        prefix: assets/
+        decompress: true
+        clean: true
+
+    - name: Invalidate Frontend Cache
+      type: DEVRAMPS:CLOUDFRONT:INVALIDATE
+      goes_after: ["Deploy Frontend Bundle"]
+      params:
+        distribution_id: \${{ steps.infra.cloudfront_distribution_id }}
+        paths: ["/*"]
+
+    - name: Bake Period
+      type: DEVRAMPS:APPROVAL:BAKE
+      params:
+        duration_minutes: 5
+
+  artifacts:
+    Backend Service Image:
+      id: backend_service
+      type: DEVRAMPS:DOCKER:BUILD
+      architecture: "linux/amd64"
+      host_size: "medium"
+      rebuild_when_changed:
+        - /services/backend
+      params:
+        dockerfile: /services/backend/Dockerfile
+        args: []
+
+    Frontend Bundle:
+      id: frontend_bundle
+      type: DEVRAMPS:BUNDLE:BUILD
+      per_stage: true
+      host_size: "medium"
+      rebuild_when_changed:
+        - /services/frontend
+      dependencies: ["node.22"]
+      envs:
+        environment: \${{ vars.env }}
+      params:
+        build_commands: |
+          cd services/frontend
+          npm install
+          npm run build
+          zip -r ./bundle.zip ./dist
+        file_path: /services/frontend/bundle.zip
+\`\`\`
+
+### Key rules for constructing the pipeline definition:
+
+**Step types to use:**
+- \`DEVRAMPS:TERRAFORM:SYNTHESIZE\` \u2014 for ALL infrastructure management
+- \`DEVRAMPS:ECS:DEPLOY\` \u2014 for deploying backend services to ECS
+- \`DEVRAMPS:S3:UPLOAD\` \u2014 for deploying static frontend assets to S3
+- \`DEVRAMPS:CLOUDFRONT:INVALIDATE\` \u2014 for invalidating CDN cache after frontend deploy
+- \`DEVRAMPS:APPROVAL:BAKE\` \u2014 for soak/bake periods between stages
+
+**Artifact types to use:**
+- \`DEVRAMPS:DOCKER:BUILD\` \u2014 for building Docker images (pushed to ECR automatically)
+- \`DEVRAMPS:BUNDLE:BUILD\` \u2014 for building frontend/file bundles (uploaded to S3 automatically)
+
+**Expression syntax for dynamic values:**
+- \`\${{ stage.region }}\` / \`\${{ stage.account_id }}\` \u2014 current stage info
+- \`\${{ vars.key }}\` \u2014 stage-specific variables
+- \`\${{ steps.<step_id>.<output_name> }}\` \u2014 Terraform outputs or step outputs
+- \`\${{ stage.artifacts.<artifact_id>.image_url }}\` \u2014 Docker image URL
+- \`\${{ stage.artifacts.<artifact_id>.s3_url }}\` / \`.s3_bucket\` / \`.s3_key\` \u2014 Bundle locations
+
+**Execution order:**
+- Steps run in parallel by default unless \`goes_after\` creates dependencies
+- Terraform synthesize should always run first (other steps depend on its outputs)
+- Frontend cache invalidation should depend on S3 upload completing
+- Bake period runs last (and can be skipped per-stage via the \`skip\` list)
+
+**Adapt the pipeline to the actual project:**
+- Backend only? Remove frontend artifact and S3/CloudFront steps.
+- Frontend only? Remove backend artifact and ECS deploy step.
+- Multiple backend services? Add more Docker artifacts and ECS deploy steps.
+- No database? Skip rds.tf in the Terraform generation.
+- Lambda instead of ECS? Use \`DEVRAMPS:LAMBDA:DEPLOY\` step type instead.
+- Adjust all paths (\`rebuild_when_changed\`, \`dockerfile\`, \`build_commands\`) to match the actual project structure.
+
+### CRITICAL: Terraform variables and pipeline variables MUST be in sync
+
+The \`DEVRAMPS:TERRAFORM:SYNTHESIZE\` step passes variables to Terraform via \`params.variables\`. These map directly to Terraform \`variable\` blocks. **Both sides must match exactly or synthesis will fail.**
+
+**Rule 1: Every Terraform variable without a \`default\` MUST be passed by the synthesize step.**
+If \`variables.tf\` declares \`variable "region" {}\` with no default, then the synthesize step's \`params.variables\` must include \`region: ...\`. If it's missing, Terraform will error asking for the value.
+
+**Rule 2: Every variable passed by the synthesize step MUST exist in Terraform's \`variables.tf\`.**
+If the pipeline passes \`backend_service_image_uri: \${{ stage.artifacts.backend_service.image_url }}\`, then \`variables.tf\` must declare \`variable "backend_service_image_uri" {}\`. If it's missing, Terraform will error on an unexpected variable.
+
+**After generating both the Terraform files and the pipeline definition, verify the sync:**
+1. List every \`variable\` in \`variables.tf\` that has no \`default\` value
+2. List every key under the synthesize step's \`params.variables\`
+3. Confirm the two lists match exactly. If they don't, fix whichever side is wrong.
+
+Variables with a \`default\` value are optional \u2014 they don't need to be passed by the pipeline, but it's fine if they are.
+
+### Pipeline output names must match Terraform output names
+
+The expressions in the pipeline (e.g., \`\${{ steps.infra.backend_cluster_name }}\`) reference **Terraform output names**. Make sure every \`\${{ steps.infra.X }}\` in the pipeline has a corresponding \`output "X"\` in outputs.tf.
+
+---
+
+## Phase 5: Generate IAM Policies
+
+If the project has Terraform files (existing or newly generated):
+
+1. Read ALL the Terraform files and identify every AWS resource type and data source used
+2. For each AWS service involved, determine the IAM actions Terraform needs to create, read, update, and delete those resources
+3. Construct a comprehensive IAM policy. **Be broad rather than narrow** \u2014 use service-level wildcards (e.g., \`ecs:*\`, \`s3:*\`, \`ec2:*\`, \`logs:*\`) to avoid first-deploy failures. The user can tighten permissions later.
+4. Always include \`iam:CreateServiceLinkedRole\` if the terraform uses ECS or ELB \u2014 these services require service-linked roles on first creation.
+5. Call the \`generate-iam-policies\` tool with:
+   - \`terraform_dir\`: path to the Terraform directory
+   - \`pipeline_name\`: same pipeline name used in scaffold-pipeline
+   - \`project_path\`: the project root
+   - \`iam_policy\`: the policy array you constructed
+
+The tool writes the policy to \`.devramps/<pipeline_name>/aws_additional_iam_policies.json\`.
+
+---
+
+## Phase 6: Validate
+
+Call the \`validate-pipeline\` tool on the generated pipeline.yaml to catch any structural issues. Fix any errors before proceeding.
+
+---
+
+## Phase 7: Final Instructions
+
+After everything is generated and validated, tell the user:
+
+1. Review the generated files:
+   - \`.devramps/<pipeline_name>/pipeline.yaml\` \u2014 pipeline definition
+   - \`.devramps/<pipeline_name>/aws_additional_iam_policies.json\` \u2014 IAM permissions
+   - \`/infrastructure/*.tf\` \u2014 Terraform configs (if generated)
+2. Run \`npx @devramps/cli bootstrap\` in the project root to bootstrap the pipeline
+3. Commit everything and push to the tracked branch (default: \`main\`)
+4. The pipeline will start running automatically on push
+5. View the pipeline in the dashboard: https://app.devramps.com/pipelines
+
+Then ask: "Would you like me to check on your pipeline status after you push? I can monitor the deployment and debug any failing steps."
+
+You have access to tools for monitoring and debugging deployed pipelines: \`list-pipelines\`, \`get-pipeline-state\`, \`get-step-logs\`, \`get-pipeline-events\`, \`get-stage-health\`, \`retry-stage\`, and \`cancel-stage\`. Use these proactively when the user reports deployment issues or asks about pipeline status.
+
+If the user wants to learn more about any DevRamps features, direct them to https://devramps.com/docs.
+
+---
+
+Please start by analyzing the project directory now.`
+        }
+      }
+    ]
+  };
+}
+
+// src/prompts/debug-deployment.ts
+import { z as z8 } from "zod";
+var DEBUG_DEPLOYMENT_PROMPT = {
+  name: "debug-deployment",
+  description: "Guided workflow to diagnose and debug a failed deployment. Walks through checking pipeline state, finding failed steps, retrieving logs, and suggesting fixes.",
+  argsSchema: {
+    pipeline_id: z8.string().describe("Pipeline ID to debug"),
+    stage_name: z8.string().optional().describe(
+      "Specific stage name to investigate (optional \u2014 will auto-detect failed stages if not provided)"
+    )
+  }
+};
+function getDebugDeploymentMessages(args) {
+  const pipelineId = args.pipeline_id || "<pipeline_id>";
+  const stageName = args.stage_name || "";
+  return {
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: `I need help debugging a failed deployment.
+
+Pipeline ID: ${pipelineId}
+${stageName ? `Stage: ${stageName}` : ""}
+
+Please follow this systematic debugging workflow:
+
+1. **Check pipeline state** using \`get-pipeline-state\` with pipeline_id "${pipelineId}":
+   - Identify which stages are failing
+   - Check for any blockers
+   - Note the active revision ID
+
+2. **Get recent events** using \`get-pipeline-events\` to understand the deployment timeline:
+   - Look for the sequence of events leading to failure
+   - Identify when the failure occurred
+
+3. **Investigate failed steps**: For each failed stage${stageName ? ` (focusing on "${stageName}")` : ""}:
+   - Identify the specific step(s) that failed from the pipeline state
+   - Note the step type and any cause/error messages
+
+4. **Retrieve logs** using \`get-step-logs\` for each failed step:
+   - Look for error messages, stack traces, or timeout indicators
+   - Check if the failure is in the step logic or infrastructure
+
+5. **Check stage health** using \`get-stage-health\` to understand patterns:
+   - Is this stage frequently failing? (low success rate)
+   - Are execution times trending up? (might indicate resource issues)
+
+6. **Suggest fixes** based on your analysis:
+   - If the issue is transient, suggest using \`retry-stage\`
+   - If it's a code issue, suggest specific fixes
+   - If it's an infrastructure issue, suggest config changes
+   - If a blocker is preventing progress, explain how to resolve it
+
+7. **Take action** if appropriate:
+   - Offer to retry the failed stage with \`retry-stage\`
+   - If a stage is stuck with blockers, offer to bypass with \`bypass-stage-blockers\` (with appropriate warnings)
+
+Please start the investigation now.`
+        }
+      }
+    ]
+  };
+}
+
+// src/index.ts
+async function main() {
+  let apiClient = null;
+  const apiUrl = process.env.DEVRAMPS_API_URL || "https://devramps.com";
+  try {
+    const config = loadConfig();
+    apiClient = new DevRampsApiClient(config);
+  } catch (err) {
+    console.error(
+      `Warning: ${err instanceof Error ? err.message : String(err)}`
+    );
+    console.error(
+      "API-dependent tools will not be available. Run `npx @devramps/cli login` to authenticate. Scaffold and IAM tools will still work."
+    );
+  }
+  const publicClient = new DevRampsPublicClient(apiUrl);
+  const server = new McpServer({
+    name: "devramps",
+    version: "0.1.0"
+  });
+  server.tool(
+    "validate-pipeline",
+    "Validate a DevRamps pipeline definition YAML file against the platform schema. Always uses the DevRamps API for authoritative validation. If authentication fails, instruct the user to run `npx @devramps/cli login`.",
+    ValidatePipelineSchema.shape,
+    async (args) => validatePipeline(args, apiClient, publicClient)
+  );
+  server.tool(
+    "scaffold-pipeline",
+    "Generate a .devramps/<pipeline_name>/pipeline.yaml file from a complete pipeline definition object. The AI agent should analyze the codebase and construct the pipeline definition, then pass it to this tool to serialize and write the YAML file. Use the scaffold-project prompt for a guided workflow.",
+    ScaffoldPipelineSchema.shape,
+    async (args) => scaffoldPipeline(args)
+  );
+  server.tool(
+    "generate-iam-policies",
+    "Write an IAM policy to .devramps/<pipeline_name>/aws_additional_iam_policies.json. The agent should first read the Terraform files, determine all AWS resources and actions needed, then construct a comprehensive IAM policy and pass it via the iam_policy parameter. Use broad service-level wildcards (e.g., 'ecs:*') to avoid first-deploy failures.",
+    GenerateIamPoliciesSchema.shape,
+    async (args) => generateIamPolicies(args)
+  );
+  if (apiClient) {
+    const client = apiClient;
+    server.tool(
+      "list-pipelines",
+      "List all CI/CD pipelines in the DevRamps organization with status summaries including blocked, stopped, and failed stage information.",
+      ListPipelinesSchema.shape,
+      async (args) => listPipelines(client, args)
+    );
+    server.tool(
+      "get-pipeline-state",
+      "Get the detailed current state of a pipeline including all stages, their statuses, active steps, blockers, alarms, and revision information.",
+      GetPipelineStateSchema.shape,
+      async (args) => getPipelineState(client, args)
+    );
+    server.tool(
+      "get-stage-health",
+      "Get health metrics for a specific stage: success rate, deployment counts, and execution time percentiles (p50/p90/max) over the last 30 days.",
+      GetStageHealthSchema.shape,
+      async (args) => getStageHealth(client, args)
+    );
+    server.tool(
+      "retry-stage",
+      "Retry a failed stage deployment. Use this when a stage has failed and you want to re-run it.",
+      RetryStageSchema.shape,
+      async (args) => retryStage(client, args)
+    );
+    server.tool(
+      "cancel-stage",
+      "Cancel an in-progress stage deployment. Optionally provide a reason for the cancellation.",
+      CancelStageSchema.shape,
+      async (args) => cancelStage(client, args)
+    );
+    server.tool(
+      "stop-pipeline",
+      "Stop a pipeline from promoting revisions to further stages. The pipeline can be resumed later with start-pipeline.",
+      StopPipelineSchema.shape,
+      async (args) => stopPipeline(client, args)
+    );
+    server.tool(
+      "start-pipeline",
+      "Resume a stopped pipeline, allowing it to promote revisions to stages again.",
+      StartPipelineSchema.shape,
+      async (args) => startPipeline(client, args)
+    );
+    server.tool(
+      "stop-stage-promotion",
+      "Stop promotion for a specific stage, preventing new revisions from being deployed to it.",
+      StopStagePromotionSchema.shape,
+      async (args) => stopStagePromotion(client, args)
+    );
+    server.tool(
+      "start-stage-promotion",
+      "Resume promotion for a specific stage, allowing new revisions to be deployed to it again.",
+      StartStagePromotionSchema.shape,
+      async (args) => startStagePromotion(client, args)
+    );
+    server.tool(
+      "bypass-stage-blockers",
+      "Force-bypass blockers on a stage (manual approvals, time windows, etc). WARNING: This skips safety checks \u2014 use with caution.",
+      BypassStageBlockersSchema.shape,
+      async (args) => bypassStageBlockers(client, args)
+    );
+    server.tool(
+      "get-step-logs",
+      "Retrieve execution logs for a specific step in a stage deployment. Useful for debugging failed steps.",
+      GetStepLogsSchema.shape,
+      async (args) => getStepLogs(client, args)
+    );
+    server.tool(
+      "get-pipeline-events",
+      "List events for a pipeline, useful for understanding deployment history and the sequence of actions that occurred.",
+      GetPipelineEventsSchema.shape,
+      async (args) => getPipelineEvents(client, args)
+    );
+    server.tool(
+      "list-revisions",
+      "List pipeline revisions with their commit info, deployed stages, and timestamps.",
+      ListRevisionsSchema.shape,
+      async (args) => listRevisions(client, args)
+    );
+    server.tool(
+      "list-ephemeral-environments",
+      "List all ephemeral environments for a pipeline with their current lock status, triggers, and region. Use this to discover available environments before claiming one.",
+      ListEphemeralEnvironmentsSchema.shape,
+      async (args) => listEphemeralEnvironments(client, args)
+    );
+    server.tool(
+      "claim-ephemeral-session",
+      "Claim a lock on an API-triggered ephemeral environment and trigger an initial deployment. Returns a session ID for subsequent operations. If the environment is already locked, use force-claim-ephemeral-session to override.",
+      ClaimEphemeralSessionSchema.shape,
+      async (args) => claimEphemeralSession(client, args)
+    );
+    server.tool(
+      "force-claim-ephemeral-session",
+      "Force-claim an ephemeral environment, overriding any existing lock. The previous session's deployments will be cancelled. Use this when the environment is locked by a stale or abandoned session.",
+      ForceClaimEphemeralSessionSchema.shape,
+      async (args) => forceClaimEphemeralSession(client, args)
+    );
+    server.tool(
+      "deploy-ephemeral-commit",
+      "Deploy a new commit to an ephemeral environment within an active session. Triggers a full build and deploy cycle. Use get-ephemeral-session-status to monitor progress.",
+      DeployEphemeralCommitSchema.shape,
+      async (args) => deployEphemeralCommit(client, args)
+    );
+    server.tool(
+      "get-ephemeral-session-status",
+      "Get the status of an ephemeral session including lock info and deployment progress with per-step details. Use this to monitor ongoing deployments or check if a session is still active.",
+      GetEphemeralSessionStatusSchema.shape,
+      async (args) => getEphemeralSessionStatus(client, args)
+    );
+    server.tool(
+      "release-ephemeral-session",
+      "Release the lock on an ephemeral session, making the environment available for others. Any in-progress deployments will be cancelled.",
+      ReleaseEphemeralSessionSchema.shape,
+      async (args) => releaseEphemeralSession(client, args)
+    );
+  }
+  server.resource(
+    "pipeline-schema",
+    PIPELINE_SCHEMA_URI,
+    getPipelineSchemaResource(),
+    async () => ({
+      contents: [
+        {
+          uri: PIPELINE_SCHEMA_URI,
+          mimeType: "text/markdown",
+          text: getPipelineSchemaContent()
+        }
+      ]
+    })
+  );
+  server.resource(
+    "step-type-docs",
+    STEP_TYPE_DOCS_URI,
+    getStepTypeDocsResource(),
+    async () => ({
+      contents: [
+        {
+          uri: STEP_TYPE_DOCS_URI,
+          mimeType: "text/markdown",
+          text: await getStepTypeDocsContent(apiClient)
+        }
+      ]
+    })
+  );
+  server.prompt(
+    SCAFFOLD_PROJECT_PROMPT.name,
+    SCAFFOLD_PROJECT_PROMPT.description,
+    SCAFFOLD_PROJECT_PROMPT.argsSchema,
+    async (args) => getScaffoldProjectMessages(args)
+  );
+  server.prompt(
+    DEBUG_DEPLOYMENT_PROMPT.name,
+    DEBUG_DEPLOYMENT_PROMPT.description,
+    DEBUG_DEPLOYMENT_PROMPT.argsSchema,
+    async (args) => getDebugDeploymentMessages(args)
+  );
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("Fatal error starting DevRamps MCP server:", err);
+  process.exit(1);
+});