screenshot

Instructions

Implementation Reference

• server.js:111-157 (handler)

  The main screenshot handler function. Captures a screenshot using maim, scrot, or gnome-screenshot (in preference order) with fallback. Supports full-screen and active_window capture. Saves PNG to /tmp/claude-linux-mcp/shots/ and returns the path.

  async function screenshot(args) {
    if (!haveScreenshotTool()) {
      return errorResult('No screenshot tool found. Install one: sudo apt install maim (preferred), or scrot, or gnome-screenshot.');
    }
    fs.mkdirSync(SHOTS_ROOT, { recursive: true });
    const out = args.path || path.join(SHOTS_ROOT, `shot-${Date.now()}.png`);
    const active = args.active_window === true;
    const env = cleanEnv();
  
    // Try each installed tool in order; fall through on runtime failure.
    const attempts = [];
  
    async function tryMaim() {
      if (!BIN.maim) return null;
      const args2 = active && BIN.xdotool
        ? ['-i', (await run(BIN.xdotool, ['getactivewindow'], { env })).stdout.trim(), out]
        : [out];
      return { tool: 'maim', ...(await run(BIN.maim, args2, { env })) };
    }
    async function tryScrot() {
      if (!BIN.scrot) return null;
      return { tool: 'scrot', ...(await run(BIN.scrot, active ? ['-u', out] : [out], { env })) };
    }
    async function tryGnome() {
      if (!BIN.gnomeShot) return null;
      return { tool: 'gnome-screenshot', ...(await run(BIN.gnomeShot, active ? ['-w', '-f', out] : ['-f', out], { env })) };
    }
  
    for (const attempt of [tryMaim, tryScrot, tryGnome]) {
      // Clear any stale file before each attempt so size=0 check is meaningful.
      try { if (fs.existsSync(out)) fs.unlinkSync(out); } catch (_) {}
      const r = await attempt();
      if (!r) continue;
      const size = fs.existsSync(out) ? fs.statSync(out).size : 0;
      attempts.push({ tool: r.tool, code: r.code, size, stderr: (r.stderr || '').slice(0, 200) });
      if (r.code === 0 && size > 0) {
        return textResult({ path: out, size_bytes: size, active_window: active, tool: r.tool });
      }
    }
  
    return errorResult(
      `screenshot failed. Tried: ${attempts.map(a => `${a.tool}(code=${a.code}, size=${a.size})`).join('; ') || '<none installed>'}. ` +
      `DISPLAY=${process.env.DISPLAY || 'unset'}, XDG_SESSION_TYPE=${process.env.XDG_SESSION_TYPE || 'unset'}. ` +
      `If XDG_SESSION_TYPE is "wayland", log out and pick an X11 session; this extension does not support Wayland in v0.1. ` +
      `If you only have gnome-screenshot installed and it's failing, try: sudo apt install maim`
    );
  }

• server.js:384-396 (schema)

  Tool registration entry for 'screenshot' including its description, annotations (readOnlyHint: true), and inputSchema (path string, active_window boolean).

  const TOOLS = [
    {
      name: 'screenshot',
      description: 'Capture a screenshot of the full screen (or the active window if active_window=true). Saves a PNG under /tmp/claude-linux-mcp/shots/ and returns the path.',
      annotations: { title: 'Take screenshot', readOnlyHint: true },
      inputSchema: {
        type: 'object',
        properties: {
          path: { type: 'string', description: 'Optional target path. Defaults to /tmp/claude-linux-mcp/shots/shot-<ts>.png.' },
          active_window: { type: 'boolean', description: 'If true, capture only the currently-focused window instead of the full screen.' },
        },
      },
    },

• server.js:553-554 (registration)

  HANDLERS object mapping 'screenshot' to the 'screenshot' function, used by the tools/call dispatch at line 587-598.

  const HANDLERS = {
    screenshot,

• server.js:30-32 (helper)

  haveScreenshotTool() checks whether at least one of maim, scrot, or gnome-screenshot is available on the system.

  function haveScreenshotTool() {
    return BIN.gnomeShot || BIN.scrot || BIN.maim;
  }

• server.js:89-96 (helper)

  cleanEnv() strips Snap-confinement environment variables to prevent GNOME/maim/scrot tools from breaking due to Snap env pollution. Used by the screenshot handler.

  function cleanEnv() {
    const e = {};
    for (const [k, v] of Object.entries(process.env)) {
      if (k.startsWith('SNAP_') || k === 'SNAP' || k === 'GTK_PATH' || k === 'GIO_MODULE_DIR' || k === 'LD_LIBRARY_PATH' || k === 'LD_PRELOAD') continue;
      e[k] = v;
    }
    return e;
  }