docker_ps

Instructions

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "docker_ps"
  }
}

Implementation Reference

• src/tools/docker.ts:206-214 (handler)

  Main handler function for 'docker_ps' tool. Constructs the docker ps command with flags for all, filter, format, and executes it via executeDockerCommand helper.

  export async function dockerPs(args: z.infer<typeof dockerPsSchema>): Promise<ToolResponse> {
    const allFlag = args.all ? '-a' : '';
    const filterFlag = args.filter ? `--filter "${args.filter}"` : '';
    const formatFlag = args.format === 'json'
      ? '--format "{{json .}}"'
      : '--format "table {{.ID}}\\t{{.Image}}\\t{{.Status}}\\t{{.Names}}\\t{{.Ports}}"';
  
    return executeDockerCommand(`docker ps ${allFlag} ${filterFlag} ${formatFlag}`.trim(), args.cwd);
  }

• src/tools/docker.ts:89-94 (schema)

  Zod schema defining input validation for docker_ps tool parameters: all, filter, format, cwd.

  export const dockerPsSchema = z.object({
    all: z.boolean().optional().default(false).describe('Show all containers (default shows just running)'),
    filter: z.string().optional().describe('Filter output based on conditions (e.g., "status=running")'),
    format: z.enum(['table', 'json']).optional().default('table').describe('Output format'),
    cwd: z.string().optional().describe('Working directory')
  });

• src/tools/docker.ts:365-377 (registration)

  Tool registration entry in dockerTools array, providing MCP-compatible tool metadata including name, description, and inputSchema for listing tools.

  {
    name: 'docker_ps',
    description: 'List Docker containers with their status',
    inputSchema: {
      type: 'object',
      properties: {
        all: { type: 'boolean', default: false, description: 'Show all containers (default shows just running)' },
        filter: { type: 'string', description: 'Filter output based on conditions (e.g., "status=running")' },
        format: { type: 'string', enum: ['table', 'json'], default: 'table', description: 'Output format' },
        cwd: { type: 'string', description: 'Working directory' }
      }
    }
  },

• src/index.ts:443-446 (registration)

  Dispatcher in main MCP server handler that matches 'docker_ps' tool calls, validates args with schema, and invokes the handler function.

  if (name === 'docker_ps') {
    const validated = dockerPsSchema.parse(args);
    return await dockerPs(validated);
  }

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

  Helper function used by dockerPs (and other docker tools) to execute docker commands asynchronously, handling output and errors in MCP ToolResponse format.

  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
      };
    }
  }