Banana Image MCP

Instructions

Implementation Reference

• banana_image_mcp/tools/output_stats.py:24-71 (handler)

  The core handler function for the 'show_output_stats' tool. It fetches statistics from the file image service, handles errors, formats a markdown summary, and returns a ToolResult with text content and structured data.

  def show_output_stats(
      ctx: Context = None,
  ) -> ToolResult:
      """
      Show statistics about the output directory and recently generated images.
      """
      logger = logging.getLogger(__name__)
  
      try:
          logger.info("Getting output directory stats")
  
          file_service = get_file_image_service()
          stats = file_service.get_output_stats()
  
          if "error" in stats:
              return ToolResult(
                  content=[
                      TextContent(
                          type="text", text=f"❌ Error getting output stats: {stats['error']}"
                      )
                  ],
                  structured_content=stats,
              )
  
          if stats["total_images"] == 0:
              summary = (
                  f"📁 **Output Directory:** `{stats['output_directory']}`\n\n"
                  f"📊 **Stats:** No images found in output directory."
              )
          else:
              summary = (
                  f"📁 **Output Directory:** `{stats['output_directory']}`\n\n"
                  f"📊 **Stats:**\n"
                  f"- Total images: {stats['total_images']}\n"
                  f"- Total size: {stats['total_size_mb']} MB\n\n"
                  f"🕒 **Recent Images:**\n"
              )
  
              for filename in stats.get("recent_images", []):
                  summary += f"- `{filename}`\n"
  
          return ToolResult(
              content=[TextContent(type="text", text=summary)], structured_content=stats
          )
  
      except Exception as e:
          logger.error(f"Failed to get output stats: {e}")
          raise

• banana_image_mcp/tools/output_stats.py:14-23 (registration)

  The registration function that defines and registers the 'show_output_stats' tool on the FastMCP server using a decorator with metadata annotations.

  def register_output_stats_tool(server: FastMCP):
      """Register output statistics tool with the FastMCP server."""
  
      @server.tool(
          annotations={
              "title": "Show output directory stats",
              "description": "Show statistics about the IMAGE_OUTPUT_DIR and recently generated images",
              "readOnlyHint": True,
          }
      )

• banana_image_mcp/core/server.py:40-45 (registration)

  The call site in the main server class where the output_stats tool registration function is imported and invoked during server initialization.

  from ..tools.output_stats import register_output_stats_tool
  from ..tools.upload_file import register_upload_file_tool
  
  register_generate_image_tool(self.server)
  register_upload_file_tool(self.server)
  register_output_stats_tool(self.server)

• banana_image_mcp/services/file_image_service.py:317-340 (helper)

  Supporting helper method in FileImageService that scans the output directory for image files, computes totals and lists recent ones; called by the tool handler.

  def get_output_stats(self) -> dict[str, Any]:
      """Get statistics about the output directory."""
      try:
          image_files = (
              list(self.output_dir.glob("*.png"))
              + list(self.output_dir.glob("*.jpg"))
              + list(self.output_dir.glob("*.jpeg"))
          )
  
          total_size = sum(f.stat().st_size for f in image_files)
  
          return {
              "output_directory": str(self.output_dir),
              "total_images": len(image_files),
              "total_size_bytes": total_size,
              "total_size_mb": round(total_size / (1024 * 1024), 2),
              "recent_images": [
                  str(f.name)
                  for f in sorted(image_files, key=lambda x: x.stat().st_mtime, reverse=True)[:5]
              ],
          }
      except Exception as e:
          self.logger.error(f"Failed to get output stats: {e}")
          return {"output_directory": str(self.output_dir), "error": str(e)}