AssetControl-Gateway

Introduction

This service implements a Model Context Protocol (MCP) server for the Eagle asset management system. Effective document processing involves making data digitally intelligible, moving beyond mere image capture to structure and content extraction. This gateway provides structured access to Eagle's assets, similar to how complex document interpretation systems extract meaning from complex layouts.

[!NOTE] Official MCP support is anticipated for Eagle version 5, which is scheduled for public beta release in the first quarter of 2026.

• Eagle Official Site: https://eagle.cool/
• Eagle Application Programming Interface Documentation: https://api.eagle.cool/

Supported Media Types

This gateway interface accommodates a wide array of digital formats for management:

• JPG / JPEG
• PNG
• PDF
• SVG
• MP4
• MP3
• FBX
• OBJ
• EPS
• TIF / TIFF
• WebP
• BMP
• ICO
• RAW
• and many others.

System Requirements

To operate this tool successfully, the following dependencies must be present on the host system:

• Python version 3.13 or newer
• The uv package manager utility, obtainable from https://docs.astral.sh/uv/

Prerequisites Setup

Install all necessary software dependencies by executing the following command in your terminal environment:

uv sync

Initiating the Server

Execution of this MCP gateway requires the Eagle application to be running beforehand. Once Eagle is active, start the server process using this command:

uv run main.py

Connecting via Streamable HTTP

Client applications can connect to this MCP interface using HTTP streams, typically configured within their settings files. For instance, the Cursor editor might use a configuration structure resembling this for defining a server endpoint:

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

Operational Toolset Summary

This table details the functions exposed by the server, mapped against the native Eagle API structure. Most item and folder manipulations are enabled by default, indicated by a filled circle ($ullet$).

Supported	Eagle API Endpoint	Operation Identifier	Enabled (Default)	Domain
✅	-	connect		MCP
✅	/api/application/info	get_application_info	$ullet$	Application
✅	/api/folder/create	create_folder	$ullet$	Folder
✅	/api/folder/rename	rename_folder		Folder
✅	/api/folder/update	update_folder	$ullet$	Folder
✅	/api/folder/list	get_folder_list	$ullet$	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	$ullet$	Item
✅	/api/item/addFromPaths	add_items_from_paths		Item
✅	/api/item/addBookmark	add_bookmark		Item
✅	/api/item/info	get_item_info	$ullet$	Item
✅	-	get_item_source	$ullet$	Item
✅	/api/item/thumbnail	get_item_thumbnail		Item
✅	/api/item/list	get_item_list	$ullet$	Item
✅	/api/item/moveToTrash	move_item_to_trash	$ullet$	Item
✅	/api/item/refreshPalette	refresh_item_palette		Item
✅	/api/item/refreshThumbnail	refresh_item_thumbnail		Item
✅	/api/item/update	update_item	$ullet$	Item
✅	/api/library/info	get_library_info	$ullet$	Library
✅	/api/library/history	get_library_history		Library
✅	/api/library/switch	switch_library		Library
✅	/api/library/icon	get_library_icon		Library

API Documentation Links for this MCP Server: - https://tuki0918.github.io/eagle-mcp-server/ - Access the local documentation interface at http://localhost:8000/redoc

Activating Restricted Functions

Certain functions are deactivated upon default initialization, noted by blank entries in the enablement column. To make these operations available for use:

1. Navigate to the function's definition within the source code files.
2. Locate and eliminate the configuration line specifically marked with tags="Disabled".
3. Perform a restart of the Model Context Protocol server process.

Following these steps will immediately expose the previously restricted tools for utilization.

Use Cases and Deployment Scenarios

Deployment context significantly impacts data access permissions, particularly regarding file system interaction.

1) Co-located Operation (Recommended)

When the client, server, and the Eagle application reside on the same host machine, file system access is generally permissible directly by the Eagle application, as illustrated below:

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] In this configuration, the client environment possesses direct pathways to the underlying file system resources.

2) Remote Client with Local Server/Application

If the MCP client resides on a different network segment than the server and application, file system interactions are mediated externally:

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] Direct access to the local host's file system is not available to the remote client in this setup.

3) Fully Remote Deployment

When both the client and the server/application are situated on distinct network segments:

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] The MCP Client cannot interact directly with the file system associated with the Eagle application host.

Related Topics

• Optical Character Recognition (OCR) for text extraction from scanned documents.
• Natural Language Processing (NLP) for semantic interpretation of extracted content.
• Semantic segmentation techniques used in computer vision for layout analysis.
• Digital archiving and the long-term preservation of analog records.
• Asset management systems and metadata standards.

Extra Details

This interface standardizes communication, essential when dealing with heterogeneous data sources, much like how comprehensive document processing pipelines manage different input formats (text, image, layout). The ability to use APIs for item management (adding, updating, retrieving) bypasses the need for manual interaction with the asset repository. Furthermore, the supported media list confirms capability across raster, vector, video, audio, and 3D model data.

Conclusion

This gateway provides essential remote control over the Eagle application's digital library. It transforms static asset management into an automated workflow, complementing broader document processing goals by providing structured access to the digitized information assets. This integration capability optimizes administrative tasks and enhances programmatic interaction with stored media collections.