ultralytics-mcp 0.1.3 → 0.1.5

package/README.md

@@ -1,30 +1,240 @@
 # Ultralytics Platform MCP
 
-MCP server for the [Ultralytics Platform](https://platform.ultralytics.com).
+[![npm version](https://img.shields.io/npm/v/ultralytics-mcp.svg)](https://www.npmjs.com/package/ultralytics-mcp)
+[![CI](https://github.com/amanharshx/ultralytics-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/amanharshx/ultralytics-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
+MCP server for [Ultralytics Platform](https://platform.ultralytics.com)
+workflows: projects, datasets, models, training, prediction, exports, and
+dataset uploads.
+
+> [!IMPORTANT]
 > Independent community project. Not affiliated with or endorsed by Ultralytics.
 
-Current milestone: read, monitor, predict, export, and initial project and
-dataset lifecycle tools are available. Additional resource-management tools
-land incrementally from here.
+---
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Get API Key](#get-api-key)
+- [Environment Variables](#environment-variables)
+- [Installation](#installation)
+  - [Claude Code](#claude-code)
+  - [Codex](#codex)
+- [Verify Setup](#verify-setup)
+- [What You Can Do](#what-you-can-do)
+- [Tools](#tools-27)
+- [Safety](#safety)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+
+---
+
+## Requirements
+
+- Node.js `>=20`
+- Ultralytics Platform API key
+- `ffmpeg` and `ffprobe` on `PATH` to upload a dataset from a local video file
+- Claude Code, Codex, or another MCP client that can launch stdio servers
+
+## Get API Key
+
+1. Sign in at [Ultralytics Platform](https://platform.ultralytics.com).
+2. Open `Settings -> API Keys`.
+3. Create or copy an API key.
+
+## Environment Variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `ULTRALYTICS_API_KEY` | ✅ | Ultralytics API key. Expected format: `ul_` followed by 40 hex characters |
+| `ULTRALYTICS_API_BASE` | ❌ | Advanced: override API base URL. Default: `https://platform.ultralytics.com/api` |
+
+## Installation
+
+### Standard Config
+
+Works in many MCP clients that accept JSON stdio server definitions.
+
+```json
+{
+  "mcpServers": {
+    "ultralytics": {
+      "command": "npx",
+      "args": ["-y", "ultralytics-mcp"],
+      "env": {
+        "ULTRALYTICS_API_KEY": "ul_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add server with Claude Code CLI:
+
+```bash
+claude mcp add ultralytics --env ULTRALYTICS_API_KEY=ul_your_api_key_here -- npx -y ultralytics-mcp
+```
+
+Or add a project-scoped server in repo-root `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ultralytics": {
+      "command": "npx",
+      "args": ["-y", "ultralytics-mcp"],
+      "env": {
+        "ULTRALYTICS_API_KEY": "ul_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Codex
+
+Add server with Codex CLI:
+
+```bash
+codex mcp add ultralytics --env ULTRALYTICS_API_KEY=ul_your_api_key_here -- npx -y ultralytics-mcp
+```
+
+Or add it directly to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.ultralytics]
+command = "npx"
+args = ["-y", "ultralytics-mcp"]
+
+[mcp_servers.ultralytics.env]
+ULTRALYTICS_API_KEY = "ul_your_api_key_here"
+```
+
+## Verify Setup
+
+### Claude Code
+
+```bash
+claude mcp list
+```
+
+You should see `ultralytics` in configured MCP servers.
+
+### Codex
+
+```bash
+codex mcp list
+```
+
+You should see `ultralytics` in configured MCP servers.
+
+## What You Can Do
 
-## Tools (23)
+- Browse projects, datasets, models, exports, GPU availability
+- Resolve project and dataset refs by id, slug, `username/slug`, or `ul://`
+- Search public projects and datasets on Ultralytics Explore
+- Start dataset ingest jobs and upload archive files, folders, or videos
+- Monitor training progress and inspect latest metrics or recent metric history
+- Run model prediction from image URL or base64 input
+- Download model weights to local path
+- Create exports and training jobs with explicit cost confirmation
+
+## Tools (27)
+
+### Projects (5 tools)
 
 | Tool | Description |
 | --- | --- |
-| `projects_list` / `projects_get` | Browse projects |
-| `projects_create` / `projects_delete` | Create / soft-delete projects |
-| `datasets_list` / `datasets_get` / `datasets_create` / `datasets_delete` / `dataset_images_list` / `dataset_ingest` / `dataset_upload_file` | Browse / create / soft-delete datasets, inspect images, start remote ingest jobs, and upload archive files |
-| `models_list` / `models_get` | Browse trained models and metrics |
-| `training_monitor` | Status, progress, and latest metrics |
-| `model_predict` | Run inference on an image URL or base64 source |
-| `model_download` | Download a model weight file to a local path |
-| `gpu_availability` | Cloud GPU stock status |
-| `dataset_export` | Get export link for latest or frozen dataset version |
+| `projects_list` | List projects in your Ultralytics workspace |
+| `projects_get` | Get one project by id, slug, `username/slug`, or `ul://` |
+| `projects_create` | Create a new project |
+| `projects_delete` | Soft-delete a project |
+| `explore_projects` | Search public projects on Ultralytics Explore |
+
+### Datasets (12 tools)
+
+| Tool | Description |
+| --- | --- |
+| `datasets_list` | List datasets in your Ultralytics workspace |
+| `datasets_get` | Get one dataset by id, slug, `username/slug`, or `ul://` |
+| `datasets_create` | Create a new dataset |
+| `datasets_delete` | Soft-delete a dataset |
+| `dataset_images_list` | List images in a dataset with optional filters |
+| `dataset_ingest` | Start a remote ingest job from a source URL |
+| `dataset_upload_file` | Upload a local archive file for dataset ingest |
+| `dataset_upload_folder` | Upload a local image folder for dataset ingest |
+| `dataset_upload_video` | Upload a local video by extracting frames for dataset ingest |
+| `dataset_export` | Get an export link for latest or frozen dataset version |
 | `dataset_version_create` | Create a frozen dataset version snapshot |
-| `exports_list` / `export_status` | List / check export jobs |
-| `export_create` | Create an export job — **requires `confirm_cost: true`** |
-| `training_start` | Start cloud training — **requires `confirm_cost: true`** |
+| `explore_datasets` | Search public datasets on Ultralytics Explore |
+
+### Models (4 tools)
+
+| Tool | Description |
+| --- | --- |
+| `models_list` | List trained models and summary metrics |
+| `models_get` | Get one model and its details |
+| `model_predict` | Run inference from an image URL or base64 input |
+| `model_download` | Download a model weight file to a local path |
+
+### Training (2 tools)
+
+| Tool | Description |
+| --- | --- |
+| `training_monitor` | Inspect status, progress, latest metrics, and optional history |
+| `training_start` | Start a cloud training job with explicit cost confirmation |
+
+### Exports (3 tools)
+
+| Tool | Description |
+| --- | --- |
+| `exports_list` | List export jobs |
+| `export_status` | Check export job status |
+| `export_create` | Create an export job with explicit cost confirmation |
+
+### Infrastructure (1 tool)
+
+| Tool | Description |
+| --- | --- |
+| `gpu_availability` | Check cloud GPU availability |
+
+## Safety
+
+- `export_create` requires `confirm_cost: true`
+- `training_start` requires `confirm_cost: true`
+- Ambiguous project or dataset refs fail instead of guessing
+- Signed upload and download URLs do not forward `Authorization`
+
+## Troubleshooting
+
+### Invalid API key
+
+`ULTRALYTICS_API_KEY` must start with `ul_` and contain exactly 40 hex
+characters after prefix.
+
+### Server not loading in Claude Code
+
+- run `claude mcp list`
+- verify `npx` and Node.js are installed
+- verify `ULTRALYTICS_API_KEY` was passed with `--env` when adding server
+- if needed, inspect server config with `claude mcp get ultralytics`
+
+### Server not loading in Codex
+
+- run `codex mcp list`
+- verify `npx` and Node.js are installed
+- verify `ULTRALYTICS_API_KEY` value in `~/.codex/config.toml` or `codex mcp add` command
+
+### Manual server smoke test
+
+```bash
+ULTRALYTICS_API_KEY=ul_your_api_key_here npx -y ultralytics-mcp
+```
+
+If command exits immediately with config error, fix environment first.
 
 ## Development
 

package/dist/server.js

@@ -1,6 +1,12 @@
+import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { UltralyticsClient } from "./client.js";
 import { registerTools } from "./tools/index.js";
+function readPackageVersion() {
+    const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    return packageJson.version;
+}
+export const SERVER_VERSION = readPackageVersion();
 /** Create the MCP server with all tools registered.
  *
  * The client is created lazily on first tool invocation (so it reads the API key
@@ -8,7 +14,10 @@ import { registerTools } from "./tools/index.js";
  * `clientFactory` can be injected for tests.
  */
 export function createServer(clientFactory = () => new UltralyticsClient()) {
-    const server = new McpServer({ name: "ultralytics", version: "0.2.0" });
+    const server = new McpServer({
+        name: "ultralytics",
+        version: SERVER_VERSION,
+    });
     let client;
     const getClient = () => {
         if (!client) {

package/dist/tools/datasets.js

@@ -1,7 +1,12 @@
 /** Read-only dataset tools. */
-import { readFile, stat } from "node:fs/promises";
-import { basename } from "node:path";
+import { execFile as execFileCb } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdtemp, readdir, readFile, rm, stat } from "node:fs/promises";
+import { basename, join, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+import { zipSync } from "fflate";
 import { resolveDataset } from "../resolve.js";
+import { exploreSearch, validateExploreTasks } from "./explore.js";
 import { asRecord, listField, pyCount, pyField } from "./shared.js";
 const DATASET_TASKS = new Set([
     "detect",
@@ -13,6 +18,23 @@ const DATASET_TASKS = new Set([
 ]);
 const TARGET_SPLITS = new Set(["train", "val", "test"]);
 const MAX_UPLOAD_BYTES = 10 * 1024 * 1024 * 1024;
+const IMAGE_SUFFIXES = new Set([
+    ".jpg",
+    ".jpeg",
+    ".png",
+    ".webp",
+    ".bmp",
+    ".tif",
+    ".tiff",
+]);
+const VIDEO_SUFFIXES = new Set([
+    ".mp4",
+    ".webm",
+    ".mov",
+    ".mkv",
+    ".m4v",
+    ".avi",
+]);
 const UPLOAD_TYPES = [
     [".tar.gz", "application/gzip"],
     [".zip", "application/zip"],
@@ -20,6 +42,7 @@ const UPLOAD_TYPES = [
     [".tgz", "application/gzip"],
     [".ndjson", "application/x-ndjson"],
 ];
+const execFile = promisify(execFileCb);
 function resourceId(item, fallback) {
     const value = item._id ?? item.id ?? item.projectId ?? item.datasetId;
     return String(value ?? fallback ?? "None");
@@ -30,6 +53,41 @@ function validateTargetSplit(targetSplit) {
         throw new Error(`Unsupported targetSplit '${targetSplit}'. Expected one of: ${allowed}.`);
     }
 }
+function findToolOnPath(name) {
+    const paths = process.env.PATH?.split(":") ?? [];
+    for (const base of paths) {
+        const candidate = resolve(base, name);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+async function probeVideoDuration(videoPath, ffprobePath) {
+    const { stdout } = await execFile(ffprobePath, [
+        "-v",
+        "error",
+        "-show_entries",
+        "format=duration",
+        "-of",
+        "default=nokey=1:noprint_wrappers=1",
+        videoPath,
+    ]);
+    return Number.parseFloat(stdout.trim());
+}
+async function extractVideoFrames(options) {
+    await execFile(options.ffmpegPath, [
+        "-i",
+        options.videoPath,
+        "-vf",
+        `fps=${options.rate}`,
+        "-frames:v",
+        String(options.maxFrames),
+        "-q:v",
+        "2",
+        join(options.outputDir, "frame_%06d.jpg"),
+    ]);
+}
 async function datasetUploadFileMeta(filePath) {
     if (!filePath.trim()) {
         throw new Error("`filePath` is required.");
@@ -56,6 +114,106 @@ async function datasetUploadFileMeta(filePath) {
         totalBytes: info.size,
     };
 }
+function skipDatasetFolderPart(part) {
+    return part.startsWith(".") || part === "__MACOSX";
+}
+function hasSplitLikePath(path) {
+    return path.split("/").some((part) => TARGET_SPLITS.has(part.toLowerCase()));
+}
+async function datasetFolderImages(folderPath) {
+    if (!folderPath.trim()) {
+        throw new Error("`folderPath` is required.");
+    }
+    const resolvedFolder = resolve(folderPath);
+    const info = await stat(resolvedFolder).catch(() => null);
+    if (info === null) {
+        throw new Error(`Upload folder does not exist: ${resolvedFolder}`);
+    }
+    if (!info.isDirectory()) {
+        throw new Error(`Upload path is not a directory: ${resolvedFolder}`);
+    }
+    const files = [];
+    let totalBytes = 0;
+    let hasSplitDirs = false;
+    async function walk(currentPath) {
+        const entries = await readdir(currentPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (skipDatasetFolderPart(entry.name) || entry.name === ".DS_Store") {
+                continue;
+            }
+            const absolutePath = resolve(currentPath, entry.name);
+            const relativePath = relative(resolvedFolder, absolutePath).replaceAll("\\", "/");
+            if (relativePath
+                .split("/")
+                .some((part) => skipDatasetFolderPart(part) || part === ".DS_Store")) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                await walk(absolutePath);
+                continue;
+            }
+            if (!entry.isFile()) {
+                continue;
+            }
+            const lower = entry.name.toLowerCase();
+            const archiveSuffix = UPLOAD_TYPES.find(([candidate]) => lower.endsWith(candidate));
+            if (archiveSuffix) {
+                continue;
+            }
+            const imageSuffix = Array.from(IMAGE_SUFFIXES).find((candidate) => lower.endsWith(candidate));
+            if (!imageSuffix) {
+                continue;
+            }
+            const fileInfo = await stat(absolutePath);
+            totalBytes += fileInfo.size;
+            if (totalBytes >= MAX_UPLOAD_BYTES) {
+                throw new Error("Upload folder images must be smaller than 10 GB total.");
+            }
+            if (hasSplitLikePath(relativePath)) {
+                hasSplitDirs = true;
+            }
+            files.push({ absolutePath, relativePath, size: fileInfo.size });
+        }
+    }
+    await walk(resolvedFolder);
+    if (files.length === 0) {
+        throw new Error("No images found in folder.");
+    }
+    return { folderPath: resolvedFolder, files, hasSplitDirs };
+}
+async function buildDatasetFolderZip(files) {
+    const entries = {};
+    for (const file of files) {
+        entries[file.relativePath] = await readFile(file.absolutePath);
+    }
+    const zipBytes = zipSync(entries, { level: 6 });
+    if (zipBytes.byteLength >= MAX_UPLOAD_BYTES) {
+        throw new Error("Upload zip must be smaller than 10 GB.");
+    }
+    return zipBytes;
+}
+async function uploadDatasetContent(client, options) {
+    const signed = asRecord(await client.postJson("/upload/signed-url", {
+        assetType: "datasets",
+        assetId: options.datasetId,
+        filename: options.filename,
+        contentType: options.contentType,
+        totalBytes: options.totalBytes,
+    }));
+    const sessionId = String(signed.sessionId);
+    const uploadUrl = String(signed.uploadUrl ?? signed.url);
+    await client.uploadBytes(uploadUrl, options.content, options.contentType);
+    await client.postJson("/upload/complete", { sessionId });
+    const ingestPayload = {
+        datasetId: options.datasetId,
+        sessionId,
+    };
+    if (options.targetSplit !== undefined) {
+        ingestPayload.targetSplit = options.targetSplit;
+    }
+    const ingest = asRecord(await client.postJson("/datasets/ingest", ingestPayload));
+    return { sessionId, ingest };
+}
 /** List datasets in the workspace, optionally filtered by username. */
 export async function datasetsList(client, username) {
     const data = await client.get("/datasets", username ? { username } : undefined);
@@ -70,6 +228,32 @@ export async function datasetsList(client, username) {
     }));
     return { summary: `${items.length} dataset(s).`, data: items };
 }
+/** Search public datasets on Explore. */
+export async function exploreDatasets(client, options) {
+    const data = await exploreSearch(client, "datasets", options.q, {
+        sort: options.sort,
+        offset: options.offset,
+        task: validateExploreTasks(options.task),
+    });
+    const items = listField(data, "datasets").map((dataset) => ({
+        id: dataset._id ?? null,
+        name: dataset.name ?? null,
+        slug: dataset.slug ?? null,
+        username: dataset.username ?? null,
+        task: dataset.task ?? null,
+        imageCount: dataset.imageCount ?? null,
+        classCount: dataset.classCount ?? null,
+        starCount: dataset.starCount ?? null,
+    }));
+    const hasMore = Boolean(data.hasMore);
+    return {
+        summary: `Search '${options.q.trim()}': ${items.length} dataset(s)${hasMore ? " (more available)" : ""}`,
+        data: {
+            datasets: items,
+            hasMore,
+        },
+    };
+}
 /** Get one dataset by id, slug, username/slug, or dataset ul:// URI. */
 export async function datasetsGet(client, dataset) {
     const datasetId = await resolveDataset(client, dataset);
@@ -220,22 +404,15 @@ export async function datasetUploadFile(client, options) {
     const meta = await datasetUploadFileMeta(options.filePath);
     const datasetId = await resolveDataset(client, options.dataset);
     const content = await readFile(options.filePath);
-    const signed = asRecord(await client.postJson("/upload/signed-url", {
-        assetType: "datasets",
-        assetId: datasetId,
+    const upload = await uploadDatasetContent(client, {
+        datasetId,
         filename: meta.filename,
         contentType: meta.contentType,
         totalBytes: meta.totalBytes,
-    }));
-    const uploadUrl = String(signed.url ?? "");
-    const sessionId = String(signed.sessionId ?? "");
-    await client.uploadBytes(uploadUrl, content, meta.contentType);
-    await client.postJson("/upload/complete", { sessionId });
-    const ingestPayload = { datasetId, sessionId };
-    if (options.targetSplit !== undefined) {
-        ingestPayload.targetSplit = options.targetSplit;
-    }
-    const ingest = asRecord(await client.postJson("/datasets/ingest", ingestPayload));
+        content,
+        targetSplit: options.targetSplit,
+    });
+    const ingest = upload.ingest;
     const jobId = ingest.jobId ?? ingest.id ?? "None";
     return {
         summary: `Uploaded ${meta.filename} (${meta.totalBytes} bytes) and started dataset ingest job ${String(jobId)}.`,
@@ -243,11 +420,128 @@ export async function datasetUploadFile(client, options) {
             datasetId,
             filename: meta.filename,
             bytes: meta.totalBytes,
-            sessionId,
+            sessionId: upload.sessionId,
             ingest,
         },
     };
 }
+/** Upload a local image folder as zip, then start dataset ingest for the session. */
+export async function datasetUploadFolder(client, options) {
+    validateTargetSplit(options.targetSplit);
+    const folder = await datasetFolderImages(options.folderPath);
+    if (options.targetSplit !== undefined && folder.hasSplitDirs) {
+        throw new Error("Folder has split directories (train/val/test); don't also pass targetSplit - it's ambiguous. Use one or the other.");
+    }
+    const datasetId = await resolveDataset(client, options.dataset);
+    const content = await buildDatasetFolderZip(folder.files);
+    const filename = `${basename(folder.folderPath)}.zip`;
+    const upload = await uploadDatasetContent(client, {
+        datasetId,
+        filename,
+        contentType: "application/zip",
+        totalBytes: content.byteLength,
+        content,
+        targetSplit: options.targetSplit,
+    });
+    const jobId = upload.ingest.jobId ?? upload.ingest.id ?? "None";
+    return {
+        summary: `Zipped ${folder.files.length} image(s) from ${folder.folderPath} and started ingest job ${String(jobId)} for dataset ${datasetId}.`,
+        data: {
+            datasetId,
+            imageCount: folder.files.length,
+            filename,
+            bytes: content.byteLength,
+            sessionId: upload.sessionId,
+            ingest: upload.ingest,
+        },
+    };
+}
+/** Upload local video by extracting JPEG frames, then start dataset ingest. */
+export async function datasetUploadVideo(client, options) {
+    validateTargetSplit(options.targetSplit);
+    if (!options.videoPath.trim()) {
+        throw new Error("`videoPath` is required.");
+    }
+    const fps = options.fps ?? 1;
+    const maxFrames = options.maxFrames ?? 100;
+    if (fps <= 0) {
+        throw new Error("`fps` must be greater than 0.");
+    }
+    if (maxFrames <= 0) {
+        throw new Error("`maxFrames` must be greater than 0.");
+    }
+    const resolvedVideo = resolve(options.videoPath);
+    const info = await stat(resolvedVideo).catch(() => null);
+    if (info === null) {
+        throw new Error(`Upload video does not exist: ${resolvedVideo}`);
+    }
+    if (!info.isFile()) {
+        throw new Error(`Upload path is not a file: ${resolvedVideo}`);
+    }
+    const lower = basename(resolvedVideo).toLowerCase();
+    if (!Array.from(VIDEO_SUFFIXES).some((suffix) => lower.endsWith(suffix))) {
+        throw new Error(`Unsupported video file type. Expected one of: ${Array.from(VIDEO_SUFFIXES).sort().join(", ")}.`);
+    }
+    const findTool = options._findTool ?? findToolOnPath;
+    const ffmpegPath = findTool("ffmpeg");
+    const ffprobePath = findTool("ffprobe");
+    if (!ffmpegPath || !ffprobePath) {
+        throw new Error("ffmpeg/ffprobe not found on PATH. Install ffmpeg, or extract frames yourself (ffmpeg -i video.mp4 -vf fps=1 frames/%06d.jpg) and use dataset_upload_folder.");
+    }
+    let rate = fps;
+    let usedProbeFallback = false;
+    const probe = options._probeDuration ?? probeVideoDuration;
+    try {
+        const duration = await probe(resolvedVideo, ffprobePath);
+        if (duration > 0) {
+            rate = Math.min(fps, maxFrames / duration);
+        }
+    }
+    catch {
+        usedProbeFallback = true;
+        rate = fps;
+    }
+    const extract = options._extractFrames ?? extractVideoFrames;
+    const outputDir = await mkdtemp(join(process.cwd(), ".ultralytics-video-"));
+    try {
+        await extract({
+            videoPath: resolvedVideo,
+            outputDir,
+            ffmpegPath,
+            rate,
+            maxFrames,
+        });
+        const folder = await datasetFolderImages(outputDir);
+        const content = await buildDatasetFolderZip(folder.files);
+        const datasetId = await resolveDataset(client, options.dataset);
+        const filename = `${basename(resolvedVideo).replace(/\.[^.]+$/, "")}.zip`;
+        const upload = await uploadDatasetContent(client, {
+            datasetId,
+            filename,
+            contentType: "application/zip",
+            totalBytes: content.byteLength,
+            content,
+            targetSplit: options.targetSplit,
+        });
+        const jobId = upload.ingest.jobId ?? upload.ingest.id ?? "None";
+        return {
+            summary: `Extracted ${folder.files.length} frame(s) at ~${Number(rate.toFixed(4))} fps from ${resolvedVideo}; started ingest job ${String(jobId)} for dataset ${datasetId}.${usedProbeFallback ? " probe fallback" : ""}`,
+            data: {
+                datasetId,
+                frameCount: folder.files.length,
+                fps,
+                maxFrames,
+                filename,
+                bytes: content.byteLength,
+                sessionId: upload.sessionId,
+                ingest: upload.ingest,
+            },
+        };
+    }
+    finally {
+        await rm(outputDir, { recursive: true, force: true });
+    }
+}
 /** Get dataset export link for latest or one frozen version. */
 export async function datasetExport(client, options) {
     if (options.version !== undefined && options.version <= 0) {

package/dist/tools/explore.js

@@ -0,0 +1,57 @@
+import { asRecord } from "./shared.js";
+const EXPLORE_SORTS = new Set([
+    "newest",
+    "stars",
+    "oldest",
+    "name-asc",
+    "name-desc",
+    "count-desc",
+    "count-asc",
+]);
+const DATASET_TASKS = new Set([
+    "detect",
+    "segment",
+    "semantic",
+    "classify",
+    "pose",
+    "obb",
+]);
+export function validateExploreQuery(q, sort = "newest", offset = 0) {
+    if (!q.trim()) {
+        throw new Error("q is required: a search query");
+    }
+    if (!EXPLORE_SORTS.has(sort)) {
+        const allowed = Array.from(EXPLORE_SORTS).sort().join(", ");
+        throw new Error(`Unsupported sort '${sort}'. Expected one of: ${allowed}.`);
+    }
+    if (offset < 0) {
+        throw new Error("`offset` must be greater than or equal to 0.");
+    }
+}
+export function validateExploreTasks(task) {
+    if (!task || task.length === 0) {
+        return undefined;
+    }
+    for (const item of task) {
+        if (!DATASET_TASKS.has(item)) {
+            const allowed = Array.from(DATASET_TASKS).sort().join(", ");
+            throw new Error(`Unsupported dataset task '${item}'. Expected one of: ${allowed}.`);
+        }
+    }
+    return task.join(",");
+}
+export async function exploreSearch(client, type, q, options = {}) {
+    const sort = options.sort ?? "newest";
+    const offset = options.offset ?? 0;
+    validateExploreQuery(q, sort, offset);
+    const params = {
+        type,
+        q: q.trim(),
+        sort,
+        offset,
+    };
+    if (options.task !== undefined) {
+        params.task = options.task;
+    }
+    return asRecord(await client.get("/explore/search", params));
+}

package/dist/tools/index.js

@@ -7,37 +7,41 @@
  */
 import { z } from "zod";
 import { toMcpTextResult } from "../tool-result.js";
-import { datasetExport, datasetImagesList, datasetsCreate, datasetsDelete, datasetsGet, datasetsIngest, datasetsList, datasetUploadFile, datasetVersionCreate, } from "./datasets.js";
+import { datasetExport, datasetImagesList, datasetsCreate, datasetsDelete, datasetsGet, datasetsIngest, datasetsList, datasetUploadFile, datasetUploadFolder, datasetUploadVideo, datasetVersionCreate, exploreDatasets, } from "./datasets.js";
 import { modelDownload } from "./downloads.js";
 import { exportCreate, exportStatus, exportsList } from "./exports.js";
 import { gpuAvailability } from "./gpu.js";
 import { modelsGet, modelsList } from "./models.js";
 import { modelPredict } from "./predict.js";
-import { projectsCreate, projectsDelete, projectsGet, projectsList, } from "./projects.js";
+import { exploreProjects, projectsCreate, projectsDelete, projectsGet, projectsList, } from "./projects.js";
 import { trainingMonitor, trainingStart } from "./training.js";
-export { datasetExport, datasetImagesList, datasetsCreate, datasetsDelete, datasetsGet, datasetsIngest, datasetsList, datasetUploadFile, datasetVersionCreate, } from "./datasets.js";
+export { datasetExport, datasetImagesList, datasetsCreate, datasetsDelete, datasetsGet, datasetsIngest, datasetsList, datasetUploadFile, datasetUploadFolder, datasetUploadVideo, datasetVersionCreate, exploreDatasets, } from "./datasets.js";
 export { modelDownload } from "./downloads.js";
 export { exportCreate, exportStatus, exportsList } from "./exports.js";
 export { gpuAvailability } from "./gpu.js";
 export { modelsGet, modelsList } from "./models.js";
 export { modelPredict } from "./predict.js";
-export { projectsCreate, projectsDelete, projectsGet, projectsList, } from "./projects.js";
+export { exploreProjects, projectsCreate, projectsDelete, projectsGet, projectsList, } from "./projects.js";
 export { trainingMonitor, trainingStart } from "./training.js";
 /** Names of the read-only tools registered by `registerReadTools`. */
 export const READ_TOOL_NAMES = [
     "projects_list",
     "projects_get",
+    "explore_projects",
     "projects_create",
     "projects_delete",
     "datasets_list",
     "datasets_get",
-    "datasets_create",
+    "explore_datasets",
     "dataset_images_list",
     "dataset_export",
     "dataset_version_create",
+    "datasets_create",
     "datasets_delete",
     "dataset_ingest",
     "dataset_upload_file",
+    "dataset_upload_folder",
+    "dataset_upload_video",
     "models_list",
     "models_get",
     "gpu_availability",
@@ -52,6 +56,14 @@ export function registerReadTools(server, getClient) {
         description: "Get details for one project by id, slug, username/slug, or project ul:// URI.",
         inputSchema: { project: z.string() },
     }, async ({ project }) => toMcpTextResult(await projectsGet(getClient(), project)));
+    server.registerTool("explore_projects", {
+        description: "Search public projects on Ultralytics Explore.",
+        inputSchema: {
+            q: z.string(),
+            sort: z.string().optional(),
+            offset: z.number().int().optional(),
+        },
+    }, async ({ q, sort, offset }) => toMcpTextResult(await exploreProjects(getClient(), { q, sort, offset })));
     server.registerTool("projects_create", {
         description: "Create a project in your Ultralytics workspace.",
         inputSchema: {
@@ -72,6 +84,15 @@ export function registerReadTools(server, getClient) {
         description: "Get details for one dataset by id, slug, username/slug, or dataset ul:// URI.",
         inputSchema: { dataset: z.string() },
     }, async ({ dataset }) => toMcpTextResult(await datasetsGet(getClient(), dataset)));
+    server.registerTool("explore_datasets", {
+        description: "Search public datasets on Ultralytics Explore.",
+        inputSchema: {
+            q: z.string(),
+            sort: z.string().optional(),
+            offset: z.number().int().optional(),
+            task: z.array(z.string()).optional(),
+        },
+    }, async ({ q, sort, offset, task }) => toMcpTextResult(await exploreDatasets(getClient(), { q, sort, offset, task })));
     server.registerTool("datasets_create", {
         description: "Create a dataset in your Ultralytics workspace.",
         inputSchema: {
@@ -150,6 +171,34 @@ export function registerReadTools(server, getClient) {
         filePath: file_path,
         targetSplit,
     })));
+    server.registerTool("dataset_upload_folder", {
+        description: "Upload a local image folder as a zip and start ingest for an existing dataset.",
+        inputSchema: {
+            dataset: z.string(),
+            folder_path: z.string(),
+            targetSplit: z.string().optional(),
+        },
+    }, async ({ dataset, folder_path, targetSplit }) => toMcpTextResult(await datasetUploadFolder(getClient(), {
+        dataset,
+        folderPath: folder_path,
+        targetSplit,
+    })));
+    server.registerTool("dataset_upload_video", {
+        description: "Upload a local video by extracting JPEG frames with ffmpeg, then start dataset ingest for an existing dataset.",
+        inputSchema: {
+            dataset: z.string(),
+            video_path: z.string(),
+            fps: z.number().optional(),
+            max_frames: z.number().int().optional(),
+            targetSplit: z.string().optional(),
+        },
+    }, async ({ dataset, video_path, fps, max_frames, targetSplit }) => toMcpTextResult(await datasetUploadVideo(getClient(), {
+        dataset,
+        videoPath: video_path,
+        fps,
+        maxFrames: max_frames,
+        targetSplit,
+    })));
     server.registerTool("models_list", {
         description: "List models in a project by project id, slug, username/slug, or project ul:// URI.",
         inputSchema: { project: z.string() },
@@ -173,8 +222,18 @@ export const ACTION_TOOL_NAMES = [
 export function registerActionTools(server, getClient) {
     server.registerTool("training_monitor", {
         description: "Report a model's training status and progress (works for private and public projects).",
-        inputSchema: { model: z.string(), project: z.string().optional() },
-    }, async ({ model, project }) => toMcpTextResult(await trainingMonitor(getClient(), model, project)));
+        inputSchema: {
+            model: z.string(),
+            project: z.string().optional(),
+            include_metrics: z.boolean().optional(),
+            include_history: z.boolean().optional(),
+            history_last_n: z.number().int().positive().optional(),
+        },
+    }, async ({ model, project, include_metrics, include_history, history_last_n, }) => toMcpTextResult(await trainingMonitor(getClient(), model, project, {
+        includeMetrics: include_metrics,
+        includeHistory: include_history,
+        historyLastN: history_last_n,
+    })));
     server.registerTool("model_predict", {
         description: "Run inference with a trained model on an image URL or base64 source (no local file paths).",
         inputSchema: {

package/dist/tools/projects.js

@@ -1,5 +1,6 @@
 /** Read-only project tools. */
 import { resolveProject } from "../resolve.js";
+import { exploreSearch } from "./explore.js";
 import { asRecord, listField, pyCount, pyField } from "./shared.js";
 function resourceId(item, fallback) {
     const value = item._id ?? item.id ?? item.projectId ?? item.datasetId;
@@ -18,6 +19,30 @@ export async function projectsList(client, username) {
     }));
     return { summary: `${items.length} project(s).`, data: items };
 }
+/** Search public projects on Explore. */
+export async function exploreProjects(client, options) {
+    const data = await exploreSearch(client, "projects", options.q, {
+        sort: options.sort,
+        offset: options.offset,
+    });
+    const items = listField(data, "projects").map((project) => ({
+        id: project._id ?? null,
+        name: project.name ?? null,
+        slug: project.slug ?? null,
+        username: project.username ?? null,
+        visibility: project.visibility ?? null,
+        modelCount: project.modelCount ?? null,
+        starCount: project.starCount ?? null,
+    }));
+    const hasMore = Boolean(data.hasMore);
+    return {
+        summary: `Search '${options.q.trim()}': ${items.length} project(s)${hasMore ? " (more available)" : ""}`,
+        data: {
+            projects: items,
+            hasMore,
+        },
+    };
+}
 /** Get one project by id, slug, username/slug, or project ul:// URI. */
 export async function projectsGet(client, project) {
     const projectId = await resolveProject(client, project);

package/dist/tools/training.js

@@ -12,8 +12,15 @@ const KEY_METRICS = [
 function formatPercent(value) {
     return Number.isInteger(value) ? value.toFixed(1) : String(value);
 }
+function validateHistoryLastN(historyLastN) {
+    if (!Number.isInteger(historyLastN) || historyLastN <= 0) {
+        throw new Error("`history_last_n` must be a positive integer.");
+    }
+}
 /** Report model training status using private-safe model trainResults. */
-export async function trainingMonitor(client, model, project) {
+export async function trainingMonitor(client, model, project, options = {}) {
+    const { includeMetrics = false, includeHistory = false, historyLastN = 20, } = options;
+    validateHistoryLastN(historyLastN);
     const modelId = await resolveModel(client, model, project);
     const data = await client.get(`/models/${modelId}`);
     const record = asRecord(data);
@@ -34,19 +41,38 @@ export async function trainingMonitor(client, model, project) {
             keyMetrics[key] = latestMetrics[key];
         }
     }
+    const metricsHistory = trainResults.slice(-historyLastN).map((entry) => {
+        const record = asRecord(entry);
+        return {
+            epoch: record.epoch ?? null,
+            metrics: asRecord(record.metrics),
+        };
+    });
     let progressPct = null;
     let progressText = null;
     let etaMs = null;
     let source = "model.trainResults";
+    let timing = null;
+    let instanceStatus = null;
     try {
         const trainingData = await client.get(`/models/${modelId}/training`);
-        const job = asRecord(asRecord(trainingData).job);
+        const trainingRecord = asRecord(trainingData);
+        const job = asRecord(trainingRecord.job);
         const progress = asRecord(job.progress);
-        const timing = asRecord(job.timing);
+        const timingRecord = asRecord(job.timing);
         progressPct = progress.percentage ?? null;
         progressText = progressPct === null ? null : String(progressPct);
-        etaMs = timing.etaMs ?? null;
+        etaMs = timingRecord.etaMs ?? null;
         source = "models/{id}/training";
+        timing = {
+            etaMs: timingRecord.etaMs ?? null,
+            timePerEpochMs: timingRecord.timePerEpochMs ?? null,
+            elapsedMs: timingRecord.elapsedMs ?? null,
+        };
+        instanceStatus =
+            "instanceStatus" in trainingRecord
+                ? asRecord(trainingRecord.instanceStatus)
+                : null;
     }
     catch (error) {
         if (!(error instanceof UltralyticsApiError) ||
@@ -74,8 +100,15 @@ export async function trainingMonitor(client, model, project) {
             etaMs,
             bestEpoch: item.bestEpoch ?? null,
             bestFitness: item.bestFitness ?? null,
-            latestMetrics: keyMetrics,
+            latestMetrics: includeMetrics ? latestMetrics : keyMetrics,
             progressSource: source,
+            ...(includeMetrics
+                ? {
+                    timing,
+                    instanceStatus,
+                }
+                : {}),
+            ...(includeHistory ? { metricsHistory } : {}),
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultralytics-mcp",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "MCP for Ultralytics Platform workflows, datasets, training, prediction, and model operations.",
   "type": "module",
   "bin": {
@@ -44,6 +44,7 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "fflate": "^0.8.3",
     "zod": "^4.4.3"
   },
   "devDependencies": {