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

fiftyone_mcp/tools/utils.py

@@ -0,0 +1,112 @@
+"""
+Utility functions for FiftyOne MCP tools.
+
+| Copyright 2017-2025, Voxel51, Inc.
+| `voxel51.com <https://voxel51.com/>`_
+|
+"""
+
+import logging
+
+import fiftyone as fo
+
+
+logger = logging.getLogger(__name__)
+
+
+def format_response(data, success=True, error=None, **kwargs):
+    """Formats a standardized response for MCP tools.
+
+    Args:
+        data: the response data
+        success (True): whether the operation succeeded
+        error (None): an optional error message if operation failed
+        **kwargs: additional fields to include in the response
+
+    Returns:
+        a formatted response dict
+    """
+    response = {"success": success, "data": data}
+
+    if error:
+        response["error"] = error
+
+    for key, value in kwargs.items():
+        if value is not None:
+            response[key] = value
+
+    return response
+
+
+def safe_serialize(obj):
+    """Safely serializes FiftyOne objects to JSON-compatible formats.
+
+    Args:
+        obj: an object to serialize
+
+    Returns:
+        a JSON-serializable object
+    """
+    if isinstance(obj, (str, int, float, bool, type(None))):
+        return obj
+
+    if isinstance(obj, dict):
+        return {k: safe_serialize(v) for k, v in obj.items()}
+
+    if isinstance(obj, (list, tuple)):
+        return [safe_serialize(item) for item in obj]
+
+    if hasattr(obj, "to_dict"):
+        return safe_serialize(obj.to_dict())
+
+    if hasattr(obj, "__dict__"):
+        return safe_serialize(obj.__dict__)
+
+    return str(obj)
+
+
+def get_dataset_safe(name):
+    """Safely loads a FiftyOne dataset by name.
+
+    Args:
+        name: the name of the dataset
+
+    Returns:
+        a :class:`fiftyone.core.dataset.Dataset`, or None
+    """
+    try:
+        return fo.load_dataset(name)
+    except Exception as e:
+        logger.warning(f"Failed to load dataset '{name}': {e}")
+        return None
+
+
+def dataset_to_summary(dataset):
+    """Converts a FiftyOne dataset to a summary dictionary.
+
+    Args:
+        dataset: a :class:`fiftyone.core.dataset.Dataset`
+
+    Returns:
+        a summary dict
+    """
+    summary = {
+        "name": dataset.name,
+        "media_type": dataset.media_type,
+        "num_samples": len(dataset),
+        "persistent": dataset.persistent,
+        "tags": dataset.tags,
+        "sample_fields": {},
+    }
+
+    for field_name, field in dataset.get_field_schema().items():
+        summary["sample_fields"][field_name] = {
+            "type": str(type(field).__name__),
+            "description": getattr(field, "description", None),
+        }
+
+    if len(dataset) > 0:
+        first_sample = dataset.first()
+        summary["first_sample_id"] = first_sample.id
+
+    return summary

fiftyone_mcp_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: fiftyone-mcp-server
+Version: 0.1.0
+Summary: MCP server exposing FiftyOne dataset analysis tools
+License: MIT
+Keywords: mcp,fiftyone,computer-vision,ai,datasets,model-context-protocol
+Author: Adonai Vera
+Author-email: adonai.vera@gmail.com
+Requires-Python: >=3.10,<3.14
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Dist: fiftyone (>=1.0,<2.0)
+Requires-Dist: mcp (>=0.9.0,<0.10.0)
+Requires-Dist: torch (>=2.9.1,<3.0.0)
+Requires-Dist: torchvision (>=0.24.1,<0.25.0)
+Requires-Dist: ultralytics (>=8.3.240,<9.0.0)
+Project-URL: Documentation, https://github.com/AdonaiVera/fiftyone-mcp-server#readme
+Project-URL: Homepage, https://github.com/AdonaiVera/fiftyone-mcp-server
+Project-URL: Repository, https://github.com/AdonaiVera/fiftyone-mcp-server
+Description-Content-Type: text/markdown
+
+# FiftyOne MCP Server
+
+<div align="center">
+<p align="center">
+
+<!-- prettier-ignore -->
+<img src="https://user-images.githubusercontent.com/25985824/106288517-2422e000-6216-11eb-871d-26ad2e7b1e59.png" height="55px"> &nbsp;
+<img src="https://user-images.githubusercontent.com/25985824/106288518-24bb7680-6216-11eb-8f10-60052c519586.png" height="50px">
+
+![fo_agent](https://github.com/user-attachments/assets/ffba1886-125c-4c73-ae51-a300b652cffe)
+
+> Control FiftyOne datasets through AI assistants using the Model Context Protocol
+
+</p>
+</div>
+
+## Overview
+
+Enable ChatGPT and Claude to explore datasets, execute operators, and build computer vision workflows through natural language. This server exposes FiftyOne's operator framework (80+ built-in operators) through 16 MCP tools.
+
+## Features
+
+- **Dataset Management (3 tools)** - List, load, and summarize datasets
+- **Operator System (5 tools)** - Execute any FiftyOne operator dynamically
+  - Context management (dataset/view/selection)
+  - Operator discovery and schema resolution
+  - Dynamic execution interface
+- **Plugin Management (5 tools)** - Discover and install FiftyOne plugins
+  - List available plugins and their operators
+  - Install plugins from GitHub on demand
+  - Enable/disable plugins dynamically
+- **Session Management (3 tools)** - Control FiftyOne App for delegated execution
+  - Launch/close FiftyOne App server
+  - Required for background operators (brain, evaluation, etc.)
+  - Session info and status monitoring
+- **Natural Language Workflows** - Multi-step operations through conversation
+- **ChatGPT & Claude Compatible** - Works with desktop apps
+
+## Installation
+
+```bash
+git clone https://github.com/AdonaiVera/fiftyone-mcp-server.git
+cd fiftyone-mcp-server
+poetry install
+```
+
+**Requirements:** Python 3.10-3.13, Poetry, FiftyOne
+
+## Configuration
+
+Add to MCP config:
+
+- ChatGPT: `~/Library/Application Support/ChatGPT/config.json`
+- Claude: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "fiftyone": {
+      "command": "poetry",
+      "args": ["run", "fiftyone-mcp"],
+      "cwd": "/absolute/path/to/fiftyone-mcp-server"
+    }
+  }
+}
+```
+
+Restart your AI assistant.
+
+## Usage
+
+```
+# Run
+poetry run fiftyone-mcp
+```
+
+And then you can query directly the agent:
+
+```
+"List all my datasets"
+"Load quickstart dataset and show summary"
+"What operators are available for managing samples?"
+"Set context to my dataset, then tag high-confidence samples"
+"What plugins are available? Install the brain plugin"
+"Find similar images in my dataset"
+```
+
+Example of functionality:
+
+The server starts with 50 built-in operators. Install plugins to expand functionality - the AI can discover and install plugins automatically when needed (brain, zoo, annotation, evaluation, and more).
+
+## Architecture
+
+**Operator-Based Design:**
+
+- Exposes 80+ FiftyOne operators through unified interface
+- Dynamic schema resolution based on current context
+- Context state management (dataset, view, selection)
+
+**Plugin Architecture:**
+
+- AI discovers plugins on demand through `list_plugins`
+- Installs plugins automatically when needed
+- All plugin operators immediately available after installation
+- Self-expanding capability set
+
+**Session Architecture:**
+
+- AI can launch FiftyOne App when needed for delegated operators
+- Enables background execution for compute-intensive operations
+- Automatic session management through natural conversation
+
+**Design Philosophy:**
+
+- Minimal tool count (16 tools total)
+- Maximum flexibility (access to full operator & plugin ecosystem)
+- Mirrors FiftyOne App's execution model
+
+## Development
+
+```bash
+# Run tests
+poetry run pytest
+
+# Code quality
+poetry run black -l 79 src/
+poetry run pylint --errors-only src/
+
+# Test with MCP Inspector
+npx @modelcontextprotocol/inspector poetry run fiftyone-mcp
+```
+
+## Resources
+
+- [FiftyOne Docs](https://docs.voxel51.com/)
+- [FiftyOne Operators](https://docs.voxel51.com/plugins/developing_plugins.html)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+- [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
+
+---
+
+Built with [FiftyOne](https://voxel51.com/fiftyone) and [Model Context Protocol](https://modelcontextprotocol.io)
+

fiftyone_mcp_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+fiftyone_mcp/__init__.py,sha256=YfZLPWQjpAhU3cuTk1O5Yaas22luCnIGxM8JtZbb1EM,191
+fiftyone_mcp/config/settings.json,sha256=gmaex1G-kj8crQGiuSIiIROX8aqv04Xv8ef5Y2K9SYs,284
+fiftyone_mcp/server.py,sha256=pF5pmzJUAVwyMvNGDXLQTnwr1MDn056QJpDTxZdROBE,3417
+fiftyone_mcp/tools/__init__.py,sha256=3U-GgTeVSkxdYB0Fpx4NCHjxuRy1i9GtUfDVAQYWM80,108
+fiftyone_mcp/tools/datasets.py,sha256=3rMZoGWeuKzTB_JhXlPfFzojtiteSDwu090-6dkMPsk,6300
+fiftyone_mcp/tools/operators.py,sha256=bek1o1GjOsy8o4WAtv1DcMm35wvLbi2fcsOKsnIY9qA,19548
+fiftyone_mcp/tools/plugins.py,sha256=nwITl1k2cbhsP4hjuZvbwVOFe5-GQARrqghltpWOwUY,10509
+fiftyone_mcp/tools/session.py,sha256=AYBaj6pugyC1w-hHf4EZJ149Edvy0amweZeoZ4h71Fw,10721
+fiftyone_mcp/tools/utils.py,sha256=kAswqiJugRBuC4ZFaeA8mKPchDVQzic7mrSMR1zGTug,2660
+fiftyone_mcp_server-0.1.0.dist-info/METADATA,sha256=fN33anNo53vLQGV15clsqddob10M-BzYXBY4V_sF-xg,5649
+fiftyone_mcp_server-0.1.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+fiftyone_mcp_server-0.1.0.dist-info/entry_points.txt,sha256=SaZqYMrreTAYdbR5Dtle_pMKL5hFpi95dVPWMmlDXHs,56
+fiftyone_mcp_server-0.1.0.dist-info/RECORD,,

fiftyone_mcp_server-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.1
+Root-Is-Purelib: true
+Tag: py3-none-any

fiftyone_mcp_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+fiftyone-mcp=fiftyone_mcp.server:run
+