docker_exec

Instructions

Implementation Reference

• src/tools/docker.ts:228-242 (handler)

  Main handler function that constructs and executes the docker exec command using the helper executeDockerCommand

  export async function dockerExec(args: z.infer<typeof dockerExecSchema>): Promise<ToolResponse> {
    const workdirFlag = args.workdir ? `-w ${args.workdir}` : '';
    const userFlag = args.user ? `-u ${args.user}` : '';
    const envFlags = args.env
      ? Object.entries(args.env).map(([key, value]) => `-e ${key}="${value}"`).join(' ')
      : '';
  
    // Escape the command for shell execution
    const escapedCommand = args.command.replace(/"/g, '\\"');
  
    return executeDockerCommand(
      `docker exec ${workdirFlag} ${userFlag} ${envFlags} ${args.container} sh -c "${escapedCommand}"`.trim(),
      args.cwd
    );
  }

• src/tools/docker.ts:105-112 (schema)

  Zod schema for validating docker_exec tool inputs

  export const dockerExecSchema = z.object({
    container: z.string().describe('Container name or ID'),
    command: z.string().describe('Command to execute'),
    workdir: z.string().optional().describe('Working directory inside container'),
    user: z.string().optional().describe('User to run command as'),
    env: z.record(z.string()).optional().describe('Environment variables'),
    cwd: z.string().optional().describe('Working directory')
  });

• src/index.ts:451-453 (registration)

  Dispatch handler in main server that validates args with schema and calls the dockerExec function

  if (name === 'docker_exec') {
    const validated = dockerExecSchema.parse(args);
    return await dockerExec(validated);

• src/tools/docker.ts:394-409 (registration)

  Tool metadata definition in dockerTools array used for listing available tools

  {
    name: 'docker_exec',
    description: 'Execute a command inside a running container',
    inputSchema: {
      type: 'object',
      properties: {
        container: { type: 'string', description: 'Container name or ID' },
        command: { type: 'string', description: 'Command to execute' },
        workdir: { type: 'string', description: 'Working directory inside container' },
        user: { type: 'string', description: 'User to run command as' },
        env: { type: 'object', additionalProperties: { type: 'string' }, description: 'Environment variables' },
        cwd: { type: 'string', description: 'Working directory' }
      },
      required: ['container', 'command']
    }
  },

• src/tools/docker.ts:21-62 (helper)

  Helper function that executes docker commands and formats the ToolResponse

  async function executeDockerCommand(command: string, cwd?: string): Promise<ToolResponse> {
    try {
      const { stdout, stderr } = await execAsync(command, {
        cwd: cwd || process.cwd(),
        shell: '/bin/bash',
        maxBuffer: 10 * 1024 * 1024, // 10MB buffer for logs
        timeout: 60000 // 60 second timeout for builds
      });
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({
              success: true,
              command: command,
              stdout: stdout.trim(),
              stderr: stderr.trim(),
              cwd: cwd || process.cwd()
            }, null, 2)
          }
        ]
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({
              success: false,
              command: command,
              stdout: error.stdout?.trim() || '',
              stderr: error.stderr?.trim() || error.message,
              exitCode: error.code || 1,
              cwd: cwd || process.cwd()
            }, null, 2)
          }
        ],
        isError: true
      };
    }
  }