display-image

Instructions

Implementation Reference

• src/mcp.ts:16-43 (handler)

  Handler function for the display-image tool. It calls the loadImage helper, constructs a response with base64-encoded image data and accompanying text metadata, or an error message if loading fails.

  async ({ imagePath }) => {
      try {
          const imageInfo = await imageViewer.loadImage(imagePath);
          
          return {
              content: [
                  {
                      type: "image",
                      data: imageInfo.base64Data,
                      mimeType: imageInfo.mimeType,
                  },
                  {
                      type: "text",
                      text: `Image: ${imageInfo.name}\nPath: ${imageInfo.path}\nSize: ${Math.round(imageInfo.size / 1024)} KB\nType: ${imageInfo.mimeType}`,
                  },
              ],
          };
      } catch (error) {
          return {
              content: [
                  {
                      type: "text",
                      text: `Error loading image: ${error instanceof Error ? error.message : 'Unknown error'}`,
                  },
              ],
          };
      }
  }

• src/mcp.ts:13-15 (schema)

  Zod input schema for the display-image tool, defining the imagePath parameter as a string.

  {
      imagePath: z.string().describe("Path to the image file (supports ~ for home directory)"),
  },

• src/mcp.ts:10-44 (registration)

  Full registration of the display-image tool using server.tool(), including name, description, schema, and inline handler.

  server.tool(
      "display-image",
      "Display an image from the filesystem. Returns the image as base64 data that Claude can render.",
      {
          imagePath: z.string().describe("Path to the image file (supports ~ for home directory)"),
      },
      async ({ imagePath }) => {
          try {
              const imageInfo = await imageViewer.loadImage(imagePath);
              
              return {
                  content: [
                      {
                          type: "image",
                          data: imageInfo.base64Data,
                          mimeType: imageInfo.mimeType,
                      },
                      {
                          type: "text",
                          text: `Image: ${imageInfo.name}\nPath: ${imageInfo.path}\nSize: ${Math.round(imageInfo.size / 1024)} KB\nType: ${imageInfo.mimeType}`,
                      },
                  ],
              };
          } catch (error) {
              return {
                  content: [
                      {
                          type: "text",
                          text: `Error loading image: ${error instanceof Error ? error.message : 'Unknown error'}`,
                      },
                  ],
              };
          }
      }
  );

• src/imageViewer.ts:40-63 (helper)

  Core helper function loadImage that resolves the file path (handling ~), validates it's an image, reads the file, encodes to base64, determines MIME type, and returns ImageInfo object used by the tool handler.

  export async function loadImage(imagePath: string): Promise<ImageInfo> {
      // Resolve the path to handle ~ and relative paths
      const resolvedPath = path.resolve(imagePath.replace(/^~/, process.env.HOME || ''));
      
      if (!fs.existsSync(resolvedPath)) {
          throw new Error(`Image file not found: ${resolvedPath}`);
      }
  
      if (!isImageFile(resolvedPath)) {
          throw new Error(`File is not a supported image type: ${resolvedPath}`);
      }
  
      const stats = fs.statSync(resolvedPath);
      const imageData = fs.readFileSync(resolvedPath);
      const base64Data = imageData.toString('base64');
      
      return {
          path: resolvedPath,
          name: path.basename(resolvedPath),
          size: stats.size,
          mimeType: getMimeType(resolvedPath),
          base64Data: base64Data
      };
  }

• src/imageViewer.ts:4-10 (schema)

  TypeScript interface defining the structure of image information returned by loadImage, used in the tool's response.

  export interface ImageInfo {
      path: string;
      name: string;
      size: number;
      mimeType: string;
      base64Data: string;
  }