fiftyone-mcp-server 0.1.0__tar.gz

fiftyone_mcp_server-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,142 @@
+# 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/pyproject.toml

@@ -0,0 +1,57 @@
+[tool.poetry]
+name = "fiftyone-mcp-server"
+version = "0.1.0"
+description = "MCP server exposing FiftyOne dataset analysis tools"
+authors = ["Adonai Vera <adonai.vera@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+homepage = "https://github.com/AdonaiVera/fiftyone-mcp-server"
+repository = "https://github.com/AdonaiVera/fiftyone-mcp-server"
+documentation = "https://github.com/AdonaiVera/fiftyone-mcp-server#readme"
+keywords = ["mcp", "fiftyone", "computer-vision", "ai", "datasets", "model-context-protocol"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+packages = [{include = "fiftyone_mcp", from = "src"}]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<3.14"
+fiftyone = "^1.0"
+mcp = "^0.9.0"
+torch = "^2.9.1"
+torchvision = "^0.24.1"
+ultralytics = "^8.3.240"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0.0"
+pytest-asyncio = "^0.23.0"
+black = "^24.0.0"
+pylint = "^3.0.0"
+pre-commit = "^3.5.0"
+
+[tool.poetry.scripts]
+fiftyone-mcp = "fiftyone_mcp.server:run"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+
+[tool.black]
+line-length = 79
+target-version = ['py310']

fiftyone_mcp_server-0.1.0/src/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_server-0.1.0/src/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-0.1.0/src/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_server-0.1.0/src/fiftyone_mcp/tools/__init__.py

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