AssetForge Protocol Gateway

Introduction

This utility establishes an intermediary service layer, functioning as a Model Context Protocol (MCP) endpoint for the Eagle application. Such protocols enable structured communication for managing digital collections. In the context of visual media generation, these systems often rely on robust data handling, mirroring how T2I models process inputs to produce synthesized images.

Supported file formats:

- `JPG` / `JPEG` - `PNG` - `PDF` - `SVG` - `MP4` - `MP3` - `FBX` - `OBJ` - `EPS` - `TIF` / `TIFF` - `WebP` - `BMP` - `ICO` - `RAW` - etc

• Eagle Asset Manager: https://eagle.cool/
  
• Official Eagle API Documentation: https://api.eagle.cool/
  

Requirements

Execution necessitates Python version 3.13 or newer. Furthermore, the uv package manager is mandatory for dependency resolution.

Prerequisites

Use the package manager to install all necessary project dependencies properly:

uv sync

Usage

Initiate the Eagle application software first. Subsequently, start this specialized MCP intermediary service by invoking the following command from your terminal:

uv run main.py

Connecting to the MCP Server using Streamable HTTP

When configuring a client, such as a code editor, use this structural configuration format. The endpoint typically defaults to port 8000 on the local interface:

{
  "mcpServers": {
    "eagle-mcp-server": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Tools

This table details the functions exposed by the gateway and their mapping to the underlying Eagle API structure. Many Item and Folder operations are active by default, facilitating immediate asset interaction:

Supported	Eagle API endpoint	Operation ID	Enabled (default)	Category
✅	-	connect		MCP
✅	/api/application/info	get_application_info	⚫︎	Application
✅	/api/folder/create	create_folder	⚫︎	Folder
✅	/api/folder/rename	rename_folder		Folder
✅	/api/folder/update	update_folder	⚫︎	Folder
✅	/api/folder/list	get_folder_list	⚫︎	Folder
✅	/api/folder/listRecent	get_folder_list_recent		Folder
✅	/api/item/addFromURL	add_item_from_url		Item
✅	/api/item/addFromURLs	add_items_from_urls		Item
✅	/api/item/addFromPath	add_item_from_path	⚫︎	Item
✅	/api/item/addFromPaths	add_items_from_paths		Item
✅	/api/item/addBookmark	add_bookmark		Item
✅	/api/item/info	get_item_info	⚫︎	Item
✅	-	get_item_source	⚫︎	Item
✅	/api/item/thumbnail	get_item_thumbnail		Item
✅	/api/item/list	get_item_list	⚫︎	Item
✅	/api/item/moveToTrash	move_item_to_trash	⚫︎	Item
✅	/api/item/refreshPalette	refresh_item_palette		Item
✅	/api/item/refreshThumbnail	refresh_item_thumbnail		Item
✅	/api/item/update	update_item	⚫︎	Item
✅	/api/library/info	get_library_info	⚫︎	Library
✅	/api/library/history	get_library_history		Library
✅	/api/library/switch	switch_library		Library
✅	/api/library/icon	get_library_icon		Library

Refer to the service-specific documentation for detailed endpoint specifications: - Gateway API Reference: https://tuki0918.github.io/eagle-mcp-server/ - Interactive API Viewer (Redoc): http://localhost:8000/redoc

Enabling Disabled Tools

Some functionalities are intentionally inactive upon initial deployment, indicated by blank entries in the default status column. To permit access to these suppressed operations, one must modify the source code directly. Locate the specific tool's definition, eliminate the tags=["Disabled"] assignment line, and then cycle the MCP server's execution. This procedure unlocks previously restricted capabilities.

Use Cases

1) Same Host (Recommended)

This flow demonstrates local communication where the client, server, and application reside on the same machine, ensuring minimal latency for asset operations:

flowchart LR

    subgraph 192.168.1.100
        direction LR

        subgraph FileSystem [File System]
        end
        subgraph EagleApp [Eagle App<br/>localhost:41595]
        end
        subgraph MCPServer [MCP Server<br/>localhost:8000]
        end
        subgraph MCPClient [MCP Client]
        end
    end

    EagleApp ==> MCPServer e1@==> MCPClient
    MCPClient e2@==> MCPServer ==> EagleApp
    EagleApp ==> FileSystem
    FileSystem ==> EagleApp

    e1@{ animate: true }
    e2@{ animate: true }

[!TIP] Direct access to the local storage structure is available in this configuration setup.

2) Other Host (MCP Client) + Same Host (MCP Server, Eagle App)

If the client operates remotely, file system interaction is mediated entirely through the local server process:

flowchart LR

    subgraph 192.168.1.100
        subgraph FileSystem [File System]
        end
        subgraph EagleApp [Eagle App<br/>localhost:41595]
        end
        subgraph MCPServer [MCP Server<br/>localhost:8000]
        end
    end

    subgraph 192.168.1.xxx
        subgraph MCPClient [MCP Client]
        end
    end

    EagleApp ==> MCPServer e1@==> MCPClient
    MCPClient e2@==> MCPServer ==> EagleApp
    EagleApp ==> FileSystem
    FileSystem ==> EagleApp

    e1@{ animate: true }
    e2@{ animate: true }

[!WARNING] Access to the external file system is explicitly denied when the client is running on a separate machine.

3) Other Host

In this fully distributed scenario, all components are separated, relying exclusively on network communication pathways:

flowchart LR

    subgraph 192.168.1.100
        subgraph FileSystem [File System]
        end
        subgraph EagleApp [Eagle App<br/>localhost:41595]
        end
    end

    subgraph 192.168.1.101
        subgraph MCPServer [MCP Server<br/>localhost:8000]
        end
    end

    subgraph 192.168.1.xxx
        subgraph MCPClient [MCP Client]
        end
    end

    EagleApp ==> MCPServer e1@==> MCPClient
    MCPClient e2@==> MCPServer ==> EagleApp
    EagleApp ==> FileSystem
    FileSystem ==> EagleApp

    e1@{ animate: true }
    e2@{ animate: true }

[!WARNING] Direct file system interaction is unavailable when the client, server, and application are all hosted across different network locations.

Related Topics

• Latent Diffusion Models for image synthesis.
• Text-to-Image (T2I) generation principles.
• Importance of structured data representation in generative AI pipelines.
• Metadata standards for digital asset management systems.
• HTTP stream protocols for remote data exchange.

Extra Details

While this specific tool manages existing assets in Eagle, sophisticated generation tools like DALL-E 2 or Stable Diffusion utilize latent spaces. The concept of organizing and retrieving data via a standardized protocol, like MCP, is essential for training or utilizing those large generative models effectively. Effective model performance relies on clean, well-indexed datasets, which this server helps maintain for visual media.

Conclusion

This MCP gateway provides essential programmatic access to the Eagle asset repository, enabling automated cataloging and manipulation of various media types. This capability supports workflows that require integrating structured digital media management with other systems, including those involved in advanced visual media creation.