fiftyone-mcp-server 0.1.0__py3-none-any.whl

fiftyone_mcp/__init__.py

@@ -0,0 +1,11 @@
+"""
+FiftyOne MCP Server.
+
+Expose FiftyOne dataset tools via Model Context Protocol.
+
+| Copyright 2017-2025, Voxel51, Inc.
+| `voxel51.com <https://voxel51.com/>`_
+|
+"""
+
+__version__ = "0.1.0"

fiftyone_mcp/config/settings.json

@@ -0,0 +1,15 @@
+{
+  "server": {
+    "name": "fiftyone-mcp",
+    "version": "0.1.0",
+    "default_port": 5149
+  },
+  "fiftyone": {
+    "database_dir": null,
+    "default_dataset": null
+  },
+  "logging": {
+    "level": "INFO",
+    "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+  }
+}

fiftyone_mcp/server.py

@@ -0,0 +1,127 @@
+"""
+FiftyOne MCP Server.
+
+Main entrypoint for the FiftyOne Model Context Protocol server.
+
+| Copyright 2017-2025, Voxel51, Inc.
+| `voxel51.com <https://voxel51.com/>`_
+|
+"""
+
+import asyncio
+import json
+import logging
+from pathlib import Path
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent
+
+from .tools.datasets import get_dataset_tools
+from .tools.operators import get_operator_tools
+from .tools.plugins import get_plugin_tools
+from .tools.session import get_session_tools
+from .tools import datasets, operators, plugins, session
+from .tools.utils import format_response
+
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+def load_config():
+    """Loads configuration from settings.json.
+
+    Returns:
+        a config dict
+    """
+    config_path = Path(__file__).parent / "config" / "settings.json"
+    try:
+        with open(config_path, "r") as f:
+            return json.load(f)
+    except Exception as e:
+        logger.warning(f"Could not load config from {config_path}: {e}")
+        return {}
+
+
+async def main():
+    """Main server function."""
+    config = load_config()
+    server_config = config.get("server", {})
+    server_name = server_config.get("name", "fiftyone-mcp")
+
+    logger.info(f"Starting {server_name} server...")
+
+    server = Server(server_name)
+
+    all_tools = (
+        get_dataset_tools()
+        + get_operator_tools()
+        + get_plugin_tools()
+        + get_session_tools()
+    )
+
+    @server.list_tools()
+    async def list_tools_handler():
+        return all_tools
+
+    @server.call_tool()
+    async def call_tool_handler(name, arguments):
+        if name in ["list_datasets", "load_dataset", "dataset_summary"]:
+            return await datasets.handle_tool_call(name, arguments)
+        elif name in [
+            "set_context",
+            "get_context",
+            "list_operators",
+            "get_operator_schema",
+            "execute_operator",
+        ]:
+            return await operators.handle_tool_call(name, arguments)
+        elif name in [
+            "list_plugins",
+            "get_plugin_info",
+            "download_plugin",
+            "enable_plugin",
+            "disable_plugin",
+        ]:
+            return await plugins.handle_plugin_tool(name, arguments)
+        elif name in [
+            "launch_app",
+            "close_app",
+            "get_session_info",
+            "set_view",
+            "clear_view",
+        ]:
+            return await session.handle_session_tool(name, arguments)
+        else:
+            result = format_response(
+                None, success=False, error=f"Unknown tool: {name}"
+            )
+            return [
+                TextContent(type="text", text=json.dumps(result, indent=2))
+            ]
+
+    logger.info(f"{server_name} server initialized successfully")
+
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream, write_stream, server.create_initialization_options()
+        )
+
+
+def run():
+    """Entry point for the server."""
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        logger.info("Server stopped by user")
+    except Exception as e:
+        logger.error(f"Server error: {e}", exc_info=True)
+        raise
+
+
+if __name__ == "__main__":
+    run()

fiftyone_mcp/tools/__init__.py

@@ -0,0 +1,7 @@
+"""
+FiftyOne MCP Tools.
+
+| Copyright 2017-2025, Voxel51, Inc.
+| `voxel51.com <https://voxel51.com/>`_
+|
+"""

fiftyone_mcp/tools/datasets.py

@@ -0,0 +1,210 @@
+"""
+Dataset management tools for FiftyOne MCP server.
+
+| Copyright 2017-2025, Voxel51, Inc.
+| `voxel51.com <https://voxel51.com/>`_
+|
+"""
+
+import json
+import logging
+
+import fiftyone as fo
+from mcp.types import Tool, TextContent
+
+from .utils import format_response, safe_serialize, dataset_to_summary
+
+
+logger = logging.getLogger(__name__)
+
+
+def list_datasets():
+    """Lists all available FiftyOne datasets.
+
+    Returns:
+        a dict containing list of dataset names and metadata
+    """
+    try:
+        datasets = fo.list_datasets()
+        dataset_info = []
+
+        for name in datasets:
+            try:
+                dataset = fo.load_dataset(name)
+                dataset_info.append(
+                    {
+                        "name": name,
+                        "media_type": dataset.media_type,
+                        "num_samples": len(dataset),
+                        "persistent": dataset.persistent,
+                        "tags": dataset.tags,
+                    }
+                )
+            except Exception as e:
+                logger.warning(f"Could not load dataset '{name}': {e}")
+                dataset_info.append({"name": name, "error": str(e)})
+
+        return format_response(
+            {"count": len(datasets), "datasets": dataset_info}
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to list datasets: {e}")
+        return format_response(None, success=False, error=str(e))
+
+
+def load_dataset(name):
+    """Loads a FiftyOne dataset by name and returns basic info.
+
+    Args:
+        name: the name of the dataset to load
+
+    Returns:
+        a dict containing dataset information
+    """
+    try:
+        dataset = fo.load_dataset(name)
+
+        info = {
+            "name": dataset.name,
+            "media_type": dataset.media_type,
+            "num_samples": len(dataset),
+            "persistent": dataset.persistent,
+            "tags": dataset.tags,
+            "info": safe_serialize(dataset.info),
+            "fields": list(dataset.get_field_schema().keys()),
+        }
+
+        return format_response(info)
+
+    except Exception as e:
+        logger.error(f"Failed to load dataset '{name}': {e}")
+        return format_response(None, success=False, error=str(e))
+
+
+def dataset_summary(name):
+    """Gets detailed summary statistics for a dataset.
+
+    Args:
+        name: the name of the dataset
+
+    Returns:
+        a dict containing detailed dataset statistics
+    """
+    try:
+        dataset = fo.load_dataset(name)
+        summary = dataset_to_summary(dataset)
+
+        summary["stats"] = {"total_samples": len(dataset), "tags": {}}
+
+        for tag in dataset.tags:
+            tagged_view = dataset.match_tags(tag)
+            summary["stats"]["tags"][tag] = len(tagged_view)
+
+        schema = dataset.get_field_schema()
+        summary["value_counts"] = {}
+
+        for field_name in schema.keys():
+            if field_name in ["id", "filepath", "metadata"]:
+                continue
+
+            try:
+                if hasattr(dataset, "count_values"):
+                    counts = dataset.count_values(field_name)
+                    if counts and len(counts) < 100:
+                        summary["value_counts"][field_name] = dict(counts)
+            except Exception:
+                pass
+
+        return format_response(summary)
+
+    except Exception as e:
+        logger.error(f"Failed to get summary for dataset '{name}': {e}")
+        return format_response(None, success=False, error=str(e))
+
+
+def get_dataset_tools():
+    """Gets dataset tool definitions.
+
+    Returns:
+        a list of :class:`mcp.types.Tool` instances
+    """
+    return [
+        Tool(
+            name="list_datasets",
+            description="List all available FiftyOne datasets with metadata",
+            inputSchema={"type": "object", "properties": {}, "required": []},
+        ),
+        Tool(
+            name="load_dataset",
+            description="Load a FiftyOne dataset by name and return basic information",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "description": "Name of the dataset to load",
+                    }
+                },
+                "required": ["name"],
+            },
+        ),
+        Tool(
+            name="dataset_summary",
+            description="Get detailed summary statistics and metadata for a dataset",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "description": "Name of the dataset",
+                    }
+                },
+                "required": ["name"],
+            },
+        ),
+    ]
+
+
+async def handle_tool_call(name, arguments):
+    """Handles tool calls for dataset operations.
+
+    Args:
+        name: the name of the tool
+        arguments: a dict of arguments for the tool
+
+    Returns:
+        a list of :class:`mcp.types.TextContent` instances
+    """
+    try:
+        if name == "list_datasets":
+            result = list_datasets()
+        elif name == "load_dataset":
+            dataset_name = arguments.get("name")
+            if not dataset_name:
+                result = format_response(
+                    None, success=False, error="Dataset name is required"
+                )
+            else:
+                result = load_dataset(dataset_name)
+        elif name == "dataset_summary":
+            dataset_name = arguments.get("name")
+            if not dataset_name:
+                result = format_response(
+                    None, success=False, error="Dataset name is required"
+                )
+            else:
+                result = dataset_summary(dataset_name)
+        else:
+            result = format_response(
+                None, success=False, error=f"Unknown tool: {name}"
+            )
+
+        return [TextContent(type="text", text=json.dumps(result, indent=2))]
+
+    except Exception as e:
+        logger.error(f"Error handling tool call '{name}': {e}")
+        error_result = format_response(None, success=False, error=str(e))
+        return [
+            TextContent(type="text", text=json.dumps(error_result, indent=2))
+        ]