docker_build

Instructions

Implementation Reference

• src/index.js:386-448 (handler)

  The core handler function for the 'docker_build' tool. It validates the image name, checks for a Dockerfile in the specified path, executes the 'docker build' command, and provides user-friendly success or error messages with next steps.

    async ({ image_name, tag, path }) => {
      // Validate image name
      if (!/^[a-z0-9][a-z0-9._-]*$/.test(image_name)) {
        return {
          content: [{
            type: "text",
            text: `Invalid image name: "${image_name}"
  
  Rules:
  - Must be lowercase
  - Must start with letter or number
  - Can contain: a-z, 0-9, ., -, _
  
  Examples: myapp, my-api, company.service`
          }]
        };
      }
  
      // Check Dockerfile exists
      try {
        await access(`${path}/Dockerfile`, constants.F_OK);
      } catch {
        return {
          content: [{
            type: "text",
            text: `No Dockerfile found in ${path}
  
  Use 'docker_analyze_project' tool to generate one.`
          }]
        };
      }
  
      const fullTag = `${image_name}:${tag}`;
      const result = await runCommand(`docker build -t ${fullTag} ${path}`, { timeout: 300000 });
  
      if (!result.success) {
        return {
          content: [{
            type: "text",
            text: `Build failed!\n\nError:\n${result.stderr || result.error}\n\nCommon fixes:\n- Check Dockerfile syntax\n- Ensure base image exists\n- Check file permissions`
          }]
        };
      }
  
      return {
        content: [{
          type: "text",
          text: `Successfully built: ${fullTag}
  
  NEXT STEPS:
  1. Test locally:
     docker run -p 8080:8080 ${fullTag}
  
  2. View running containers:
     docker ps
  
  3. Push to registry:
     - Docker Hub:  docker push ${fullTag}
     - GHCR:        docker tag ${fullTag} ghcr.io/OWNER/${fullTag}
                    docker push ghcr.io/OWNER/${fullTag}`
        }]
      };
    }

• src/index.js:381-385 (schema)

  JSON schema defining the input parameters for the 'docker_build' tool: image_name (required string), tag (string, default 'latest'), path (string, default '.').

  {
    image_name: { type: "string", description: "Name for the image (lowercase)" },
    tag: { type: "string", description: "Image tag", default: "latest" },
    path: { type: "string", description: "Build context path", default: "." }
  },

• src/index.js:378-449 (registration)

  MCP server registration of the 'docker_build' tool, including name, description, input schema, and handler function reference.

  server.tool(
    "docker_build",
    "Build a Docker image with guidance",
    {
      image_name: { type: "string", description: "Name for the image (lowercase)" },
      tag: { type: "string", description: "Image tag", default: "latest" },
      path: { type: "string", description: "Build context path", default: "." }
    },
    async ({ image_name, tag, path }) => {
      // Validate image name
      if (!/^[a-z0-9][a-z0-9._-]*$/.test(image_name)) {
        return {
          content: [{
            type: "text",
            text: `Invalid image name: "${image_name}"
  
  Rules:
  - Must be lowercase
  - Must start with letter or number
  - Can contain: a-z, 0-9, ., -, _
  
  Examples: myapp, my-api, company.service`
          }]
        };
      }
  
      // Check Dockerfile exists
      try {
        await access(`${path}/Dockerfile`, constants.F_OK);
      } catch {
        return {
          content: [{
            type: "text",
            text: `No Dockerfile found in ${path}
  
  Use 'docker_analyze_project' tool to generate one.`
          }]
        };
      }
  
      const fullTag = `${image_name}:${tag}`;
      const result = await runCommand(`docker build -t ${fullTag} ${path}`, { timeout: 300000 });
  
      if (!result.success) {
        return {
          content: [{
            type: "text",
            text: `Build failed!\n\nError:\n${result.stderr || result.error}\n\nCommon fixes:\n- Check Dockerfile syntax\n- Ensure base image exists\n- Check file permissions`
          }]
        };
      }
  
      return {
        content: [{
          type: "text",
          text: `Successfully built: ${fullTag}
  
  NEXT STEPS:
  1. Test locally:
     docker run -p 8080:8080 ${fullTag}
  
  2. View running containers:
     docker ps
  
  3. Push to registry:
     - Docker Hub:  docker push ${fullTag}
     - GHCR:        docker tag ${fullTag} ghcr.io/OWNER/${fullTag}
                    docker push ghcr.io/OWNER/${fullTag}`
        }]
      };
    }
  );

• src/index.js:18-25 (helper)

  Helper function 'runCommand' used by the docker_build handler to safely execute shell commands like 'docker build', with timeout and error handling.

  async function runCommand(cmd, options = {}) {
    try {
      const { stdout, stderr } = await execAsync(cmd, { timeout: 30000, ...options });
      return { success: true, stdout: stdout.trim(), stderr: stderr.trim() };
    } catch (error) {
      return { success: false, error: error.message, stdout: error.stdout?.trim(), stderr: error.stderr?.trim() };
    }
  }