cover_image

Instructions

Implementation Reference

• src/tools/image-tools.ts:41-96 (handler)

  Main handler for the 'cover_image' tool. Searches Unsplash for cover images matching a query. Validates query, checks for Unsplash API key config, calls the Unsplash search API, maps results with attribution, and returns success data.

  export async function handleCoverImage(input: z.infer<typeof coverImageSchema>) {
    const queryErr = validateRequired(input.query, "query");
    if (queryErr) return makeError("VALIDATION_ERROR", queryErr);
  
    const config = readConfig();
    const accessKey = config.images?.unsplash_access_key;
  
    if (!accessKey) {
      return makeError(
        "VALIDATION_ERROR",
        'Unsplash API key not configured. Run: setup unsplash with credentials { "access_key": "your_unsplash_access_key" }. Get a free key at https://unsplash.com/developers'
      );
    }
  
    const orientation = input.orientation ?? "landscape";
    const count = input.count ?? 3;
  
    const url = `https://api.unsplash.com/search/photos?query=${encodeURIComponent(input.query)}&orientation=${orientation}&per_page=${count}`;
  
    const result = await httpRequest(url, {
      method: "GET",
      headers: { Authorization: `Client-ID ${accessKey}` },
    });
  
    if (!result.success) return result;
  
    const data = result.data as UnsplashSearchResponse;
    const photos = (data.results ?? []).map((photo) => {
      // Fire and forget download tracking for Unsplash API compliance
      httpRequest(`https://api.unsplash.com/photos/${photo.id}/download`, {
        method: "GET",
        headers: { Authorization: `Client-ID ${accessKey}` },
      }).catch(() => {});
  
      return {
        id: photo.id,
        description: photo.description ?? photo.alt_description ?? "",
        urls: {
          regular: photo.urls.regular,
          small: photo.urls.small,
        },
        attribution: {
          photographer: photo.user.name,
          profile_url: photo.user.links.html,
          text: `Photo by ${photo.user.name} on Unsplash`,
        },
      };
    });
  
    return makeSuccess({
      query: input.query,
      orientation,
      total_available: data.total,
      results: photos,
    });
  }

• src/tools/image-tools.ts:8-20 (schema)

  Zod schema defining the cover_image tool input: query (string), orientation (landscape|portrait|squarish, optional), count (1-5, optional, default 3).

  export const coverImageSchema = z.object({
    query: z.string().describe("Search terms for the image"),
    orientation: z
      .enum(["landscape", "portrait", "squarish"])
      .optional()
      .describe("Image orientation (default: landscape)"),
    count: z
      .number()
      .min(1)
      .max(5)
      .optional()
      .describe("Number of results 1-5 (default: 3)"),
  });

• src/index.ts:131-135 (registration)

  Registration of the 'cover_image' tool on the MCP server with description, schema, and handler that parses input, calls handleCoverImage, and formats the response.

  server.tool("cover_image", "Search Unsplash for cover images. FREE. Requires Unsplash access_key via setup. Subject to Unsplash's 50 req/h demo or 5000 req/h production rate limit. Returns: { results: [{ url_full, url_regular, url_small, photographer, photographer_url, attribution_html, alt }] }. Common errors: missing Unsplash key (VALIDATION_ERROR), rate-limit exceeded (PLATFORM_ERROR).", coverImageSchema.shape, async (input) => {
    const parsed = coverImageSchema.parse(input);
    const result = await handleCoverImage(parsed);
    return { content: [{ type: "text", text: formatToolResponse("cover_image", result, formatCoverImage) }] };
  });

• src/format-response.ts:288-321 (helper)

  Formatter that converts the cover_image tool's result into a Markdown response for the MCP client, showing query info, image results with thumbnails, and Unsplash attribution.

  export function formatCoverImage(data: unknown): string {
    const d = data as {
      query: string;
      orientation: string;
      total_available: number;
      results: Array<{
        id: string;
        description: string;
        urls: { regular: string; small: string };
        attribution: { photographer: string; profile_url: string; text: string };
      }>;
    };
  
    const lines = [
      successHeader("Cover Images Found"),
      "",
      field("Query", `"${d.query}"`),
      field("Results", `${d.results.length} of ${d.total_available.toLocaleString()}+`),
    ];
  
    for (let i = 0; i < d.results.length; i++) {
      const photo = d.results[i];
      lines.push(
        "",
        `### ${i + 1}. ${photo.description || "Untitled"}`,
        `![](${photo.urls.small})`,
        `\ud83d\udcf7 Photo by ${photo.attribution.photographer} on [Unsplash](${photo.attribution.profile_url})`,
        `\`${photo.urls.regular}\``
      );
    }
  
    lines.push("", note("Use the full-size URL in your frontmatter's `featured_image` field."));
    return lines.join("\n");
  }

• src/index.ts:11-13 (helper)

  Import of coverImageSchema and handleCoverImage from image-tools.ts into the main server file.

  import {
    coverImageSchema, handleCoverImage,
  } from "./tools/image-tools.js";