Image Viewer MCP

Instructions

Implementation Reference

• src/mcp.ts:53-80 (handler)

  Handler function that executes the 'list-images' tool logic by calling the helper findImages and returning a JSON-formatted text response.

  async ({ searchPath, recursive }) => {
      try {
          const imagePaths = await imageViewer.findImages(searchPath, recursive);
          
          return {
              content: [
                  {
                      type: "text",
                      text: JSON.stringify({
                          searchPath,
                          recursive,
                          count: imagePaths.length,
                          images: imagePaths
                      }, null, 2),
                  },
              ],
          };
      } catch (error) {
          return {
              content: [
                  {
                      type: "text",
                      text: `Error listing images: ${error instanceof Error ? error.message : 'Unknown error'}`,
                  },
              ],
          };
      }
  }

• src/mcp.ts:49-52 (schema)

  Zod input schema defining parameters for the list-images tool: searchPath and optional recursive.

  {
      searchPath: z.string().describe("Directory path to search for images (supports ~ for home directory)"),
      recursive: z.boolean().optional().default(false).describe("Whether to search subdirectories recursively"),
  },

• src/mcp.ts:46-52 (registration)

  Registration of the 'list-images' tool on the MCP server, including name, description, and schema.

  server.tool(
      "list-images",
      "Find and list image files in a directory",
      {
          searchPath: z.string().describe("Directory path to search for images (supports ~ for home directory)"),
          recursive: z.boolean().optional().default(false).describe("Whether to search subdirectories recursively"),
      },

• src/imageViewer.ts:65-99 (helper)

  Helper function that implements the core logic for finding image files in a directory, recursively if specified, using isImageFile check.

  export async function findImages(searchPath: string, recursive: boolean = false): Promise<string[]> {
      const resolvedPath = path.resolve(searchPath.replace(/^~/, process.env.HOME || ''));
      
      if (!fs.existsSync(resolvedPath)) {
          throw new Error(`Directory not found: ${resolvedPath}`);
      }
  
      const results: string[] = [];
      
      function scanDirectory(dirPath: string) {
          const items = fs.readdirSync(dirPath);
          
          for (const item of items) {
              const itemPath = path.join(dirPath, item);
              const stats = fs.statSync(itemPath);
              
              if (stats.isFile() && isImageFile(itemPath)) {
                  results.push(itemPath);
              } else if (stats.isDirectory() && recursive) {
                  scanDirectory(itemPath);
              }
          }
      }
      
      const stats = fs.statSync(resolvedPath);
      if (stats.isFile()) {
          if (isImageFile(resolvedPath)) {
              results.push(resolvedPath);
          }
      } else if (stats.isDirectory()) {
          scanDirectory(resolvedPath);
      }
      
      return results.sort();
  }

• src/imageViewer.ts:35-38 (helper)

  Utility function to check if a file is a supported image type based on extension.

  export function isImageFile(filePath: string): boolean {
      const ext = path.extname(filePath).toLowerCase();
      return SUPPORTED_EXTENSIONS.includes(ext);
  }