ultralytics-mcp 0.1.1 → 0.1.3

package/README.md

@@ -8,18 +8,20 @@ Current milestone: read, monitor, predict, export, and initial project and
 dataset lifecycle tools are available. Additional resource-management tools
 land incrementally from here.
 
-## Tools (18)
+## Tools (23)
 
 | Tool | Description |
 | --- | --- |
 | `projects_list` / `projects_get` | Browse projects |
 | `projects_create` / `projects_delete` | Create / soft-delete projects |
-| `datasets_list` / `datasets_get` / `datasets_create` / `datasets_delete` | Browse / create / soft-delete datasets |
+| `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 |
+| `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`** |

package/dist/client.js

@@ -20,6 +20,7 @@ export class UltralyticsClient {
     maxRetries;
     fetchImpl;
     downloadFetchImpl;
+    uploadFetchImpl;
     constructor(options = {}) {
         this.baseUrl = (options.baseUrl ?? getApiBase()).replace(/\/+$/, "");
         this.apiKey = options.apiKey ?? getApiKey();
@@ -27,6 +28,7 @@ export class UltralyticsClient {
         this.maxRetries = options.maxRetries ?? 3;
         this.fetchImpl = options.fetchImpl ?? fetch;
         this.downloadFetchImpl = options.downloadFetchImpl ?? fetch;
+        this.uploadFetchImpl = options.uploadFetchImpl ?? fetch;
     }
     // -- public verbs --------------------------------------------------------
     /** GET requests are idempotent and retry 429 responses. */
@@ -87,6 +89,23 @@ export class UltralyticsClient {
             throw new Error("unreachable");
         }
     }
+    /** Upload bytes to a signed URL WITHOUT forwarding API credentials. */
+    async uploadBytes(url, content, contentType) {
+        const bytes = new Uint8Array(content.byteLength);
+        bytes.set(content);
+        const response = await this.fetchWithTimeout(this.uploadFetchImpl, url, {
+            method: "PUT",
+            headers: {
+                Accept: "*/*",
+                "Content-Type": contentType,
+            },
+            body: bytes,
+        });
+        if (response.ok) {
+            return;
+        }
+        await this.handle(response, url);
+    }
     // -- internals -----------------------------------------------------------
     buildUrl(path, params) {
         const suffix = path.startsWith("/") ? path : `/${path}`;

package/dist/tools/datasets.js

@@ -1,4 +1,6 @@
 /** Read-only dataset tools. */
+import { readFile, stat } from "node:fs/promises";
+import { basename } from "node:path";
 import { resolveDataset } from "../resolve.js";
 import { asRecord, listField, pyCount, pyField } from "./shared.js";
 const DATASET_TASKS = new Set([
@@ -9,10 +11,51 @@ const DATASET_TASKS = new Set([
     "pose",
     "obb",
 ]);
+const TARGET_SPLITS = new Set(["train", "val", "test"]);
+const MAX_UPLOAD_BYTES = 10 * 1024 * 1024 * 1024;
+const UPLOAD_TYPES = [
+    [".tar.gz", "application/gzip"],
+    [".zip", "application/zip"],
+    [".tar", "application/x-tar"],
+    [".tgz", "application/gzip"],
+    [".ndjson", "application/x-ndjson"],
+];
 function resourceId(item, fallback) {
     const value = item._id ?? item.id ?? item.projectId ?? item.datasetId;
     return String(value ?? fallback ?? "None");
 }
+function validateTargetSplit(targetSplit) {
+    if (targetSplit !== undefined && !TARGET_SPLITS.has(targetSplit)) {
+        const allowed = Array.from(TARGET_SPLITS).sort().join(", ");
+        throw new Error(`Unsupported targetSplit '${targetSplit}'. Expected one of: ${allowed}.`);
+    }
+}
+async function datasetUploadFileMeta(filePath) {
+    if (!filePath.trim()) {
+        throw new Error("`filePath` is required.");
+    }
+    const info = await stat(filePath).catch(() => null);
+    if (info === null) {
+        throw new Error(`Upload file does not exist: ${filePath}`);
+    }
+    if (!info.isFile()) {
+        throw new Error(`Upload path is not a file: ${filePath}`);
+    }
+    if (info.size >= MAX_UPLOAD_BYTES) {
+        throw new Error("Upload file must be smaller than 10 GB.");
+    }
+    const filename = basename(filePath);
+    const lower = filename.toLowerCase();
+    const matched = UPLOAD_TYPES.find(([suffix]) => lower.endsWith(suffix));
+    if (!matched) {
+        throw new Error("Unsupported dataset upload file type. Expected one of: .zip, .tar, .tar.gz, .tgz, .ndjson.");
+    }
+    return {
+        filename,
+        contentType: matched[1],
+        totalBytes: info.size,
+    };
+}
 /** List datasets in the workspace, optionally filtered by username. */
 export async function datasetsList(client, username) {
     const data = await client.get("/datasets", username ? { username } : undefined);
@@ -74,6 +117,72 @@ export async function datasetsCreate(client, options) {
         data: item,
     };
 }
+/** List images in a dataset with optional filtering. */
+export async function datasetImagesList(client, options) {
+    if (options.split !== undefined && !TARGET_SPLITS.has(options.split)) {
+        const allowed = Array.from(TARGET_SPLITS).sort().join(", ");
+        throw new Error(`Unsupported split '${options.split}'. Expected one of: ${allowed}.`);
+    }
+    if (options.limit !== undefined) {
+        if (options.limit <= 0) {
+            throw new Error("`limit` must be greater than 0.");
+        }
+        if (options.limit > 5000) {
+            throw new Error("`limit` must be at most 5000.");
+        }
+    }
+    if (options.offset !== undefined && options.offset < 0) {
+        throw new Error("`offset` must be greater than or equal to 0.");
+    }
+    const datasetId = await resolveDataset(client, options.dataset);
+    const params = {};
+    if (options.split !== undefined) {
+        params.split = options.split;
+    }
+    if (options.search !== undefined) {
+        params.search = options.search;
+    }
+    if (options.hasLabel !== undefined) {
+        params.hasLabel = options.hasLabel;
+    }
+    if (options.classIds && options.classIds.length > 0) {
+        params.classIds = options.classIds.join(",");
+    }
+    if (options.limit !== undefined) {
+        params.limit = options.limit;
+    }
+    if (options.offset !== undefined) {
+        params.offset = options.offset;
+    }
+    if (options.includeImageUrls !== undefined) {
+        params.includeImageUrls = options.includeImageUrls;
+    }
+    const data = await client.get(`/datasets/${datasetId}/images`, Object.keys(params).length > 0 ? params : undefined);
+    const record = asRecord(data);
+    const images = listField(data, "images").map((image) => ({
+        id: image._id ?? image.id ?? null,
+        name: image.name ?? null,
+        ext: image.ext ?? null,
+        split: image.split ?? null,
+        width: image.width ?? null,
+        height: image.height ?? null,
+        labelCount: image.labelCount ?? null,
+        bytes: image.bytes ?? null,
+        ...(image.imageUrl !== undefined ? { imageUrl: image.imageUrl } : {}),
+        ...(image.thumbnailUrl !== undefined
+            ? { thumbnailUrl: image.thumbnailUrl }
+            : {}),
+    }));
+    return {
+        summary: `${images.length} image(s) (total ${String(record.total ?? null)})`,
+        data: {
+            total: record.total ?? null,
+            hasMore: record.hasMore ?? null,
+            nextCursor: record.nextCursor ?? null,
+            images,
+        },
+    };
+}
 /** Soft-delete a dataset by id, slug, username/slug, or dataset ul:// URI. */
 export async function datasetsDelete(client, dataset) {
     const datasetId = await resolveDataset(client, dataset);
@@ -83,3 +192,94 @@ export async function datasetsDelete(client, dataset) {
         data: { id: datasetId, response: data },
     };
 }
+/** Start a remote URL ingest job for an existing dataset. */
+export async function datasetsIngest(client, options) {
+    if (!options.sourceUrl.trim()) {
+        throw new Error("`sourceUrl` is required.");
+    }
+    validateTargetSplit(options.targetSplit);
+    const datasetId = await resolveDataset(client, options.dataset);
+    const payload = {
+        datasetId,
+        sourceUrl: options.sourceUrl,
+    };
+    if (options.targetSplit !== undefined) {
+        payload.targetSplit = options.targetSplit;
+    }
+    const data = await client.postJson("/datasets/ingest", payload);
+    const item = asRecord(data);
+    const jobId = item.jobId ?? item.id ?? "None";
+    return {
+        summary: `Started dataset ingest job ${String(jobId)} for dataset ${datasetId}.`,
+        data: item,
+    };
+}
+/** Upload a local dataset archive file, then start ingest for that upload. */
+export async function datasetUploadFile(client, options) {
+    validateTargetSplit(options.targetSplit);
+    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,
+        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));
+    const jobId = ingest.jobId ?? ingest.id ?? "None";
+    return {
+        summary: `Uploaded ${meta.filename} (${meta.totalBytes} bytes) and started dataset ingest job ${String(jobId)}.`,
+        data: {
+            datasetId,
+            filename: meta.filename,
+            bytes: meta.totalBytes,
+            sessionId,
+            ingest,
+        },
+    };
+}
+/** Get dataset export link for latest or one frozen version. */
+export async function datasetExport(client, options) {
+    if (options.version !== undefined && options.version <= 0) {
+        throw new Error("`version` must be greater than 0.");
+    }
+    const datasetId = await resolveDataset(client, options.dataset);
+    const data = asRecord(await client.get(`/datasets/${datasetId}/export`, options.version !== undefined ? { v: options.version } : undefined));
+    const cached = typeof data.cached === "boolean"
+        ? String(data.cached)
+        : String(data.cached ?? null);
+    return {
+        summary: `Export link for ${options.dataset} ` +
+            `(version ${String(options.version ?? "latest")}, cached=${cached})`,
+        data: {
+            downloadUrl: data.downloadUrl ?? null,
+            cached: data.cached ?? null,
+        },
+    };
+}
+/** Create frozen dataset export version. */
+export async function datasetVersionCreate(client, options) {
+    const datasetId = await resolveDataset(client, options.dataset);
+    const payload = {};
+    if (options.description !== undefined) {
+        payload.description = options.description;
+    }
+    const data = asRecord(await client.postJson(`/datasets/${datasetId}/export`, payload));
+    return {
+        summary: `Created dataset version ${String(data.version ?? null)}`,
+        data: {
+            version: data.version ?? null,
+            downloadUrl: data.downloadUrl ?? null,
+        },
+    };
+}

package/dist/tools/index.js

@@ -7,7 +7,7 @@
  */
 import { z } from "zod";
 import { toMcpTextResult } from "../tool-result.js";
-import { datasetsCreate, datasetsDelete, datasetsGet, datasetsList, } from "./datasets.js";
+import { datasetExport, datasetImagesList, datasetsCreate, datasetsDelete, datasetsGet, datasetsIngest, datasetsList, datasetUploadFile, datasetVersionCreate, } from "./datasets.js";
 import { modelDownload } from "./downloads.js";
 import { exportCreate, exportStatus, exportsList } from "./exports.js";
 import { gpuAvailability } from "./gpu.js";
@@ -15,7 +15,7 @@ import { modelsGet, modelsList } from "./models.js";
 import { modelPredict } from "./predict.js";
 import { projectsCreate, projectsDelete, projectsGet, projectsList, } from "./projects.js";
 import { trainingMonitor, trainingStart } from "./training.js";
-export { datasetsCreate, datasetsDelete, datasetsGet, datasetsList, } from "./datasets.js";
+export { datasetExport, datasetImagesList, datasetsCreate, datasetsDelete, datasetsGet, datasetsIngest, datasetsList, datasetUploadFile, datasetVersionCreate, } from "./datasets.js";
 export { modelDownload } from "./downloads.js";
 export { exportCreate, exportStatus, exportsList } from "./exports.js";
 export { gpuAvailability } from "./gpu.js";
@@ -32,7 +32,12 @@ export const READ_TOOL_NAMES = [
     "datasets_list",
     "datasets_get",
     "datasets_create",
+    "dataset_images_list",
+    "dataset_export",
+    "dataset_version_create",
     "datasets_delete",
+    "dataset_ingest",
+    "dataset_upload_file",
     "models_list",
     "models_get",
     "gpu_availability",
@@ -85,10 +90,66 @@ export function registerReadTools(server, getClient) {
         visibility,
         classNames,
     })));
+    server.registerTool("dataset_images_list", {
+        description: "List images in a dataset with optional filtering.",
+        inputSchema: {
+            dataset: z.string(),
+            split: z.string().optional(),
+            search: z.string().optional(),
+            hasLabel: z.boolean().optional(),
+            classIds: z.array(z.string()).optional(),
+            limit: z.number().optional(),
+            offset: z.number().optional(),
+            includeImageUrls: z.boolean().optional(),
+        },
+    }, async ({ dataset, split, search, hasLabel, classIds, limit, offset, includeImageUrls, }) => toMcpTextResult(await datasetImagesList(getClient(), {
+        dataset,
+        split,
+        search,
+        hasLabel,
+        classIds,
+        limit,
+        offset,
+        includeImageUrls,
+    })));
+    server.registerTool("dataset_export", {
+        description: "Get export link for latest or one frozen dataset version.",
+        inputSchema: {
+            dataset: z.string(),
+            version: z.number().optional(),
+        },
+    }, async ({ dataset, version }) => toMcpTextResult(await datasetExport(getClient(), { dataset, version })));
+    server.registerTool("dataset_version_create", {
+        description: "Create a frozen dataset version snapshot.",
+        inputSchema: {
+            dataset: z.string(),
+            description: z.string().optional(),
+        },
+    }, async ({ dataset, description }) => toMcpTextResult(await datasetVersionCreate(getClient(), { dataset, description })));
     server.registerTool("datasets_delete", {
         description: "Soft-delete a dataset by id, slug, username/slug, or dataset ul:// URI.",
         inputSchema: { dataset: z.string() },
     }, async ({ dataset }) => toMcpTextResult(await datasetsDelete(getClient(), dataset)));
+    server.registerTool("dataset_ingest", {
+        description: "Start a remote URL ingest job for an existing dataset.",
+        inputSchema: {
+            dataset: z.string(),
+            sourceUrl: z.string(),
+            targetSplit: z.string().optional(),
+        },
+    }, async ({ dataset, sourceUrl, targetSplit }) => toMcpTextResult(await datasetsIngest(getClient(), { dataset, sourceUrl, targetSplit })));
+    server.registerTool("dataset_upload_file", {
+        description: "Upload a local dataset archive file and start ingest for an existing dataset.",
+        inputSchema: {
+            dataset: z.string(),
+            file_path: z.string(),
+            targetSplit: z.string().optional(),
+        },
+    }, async ({ dataset, file_path, targetSplit }) => toMcpTextResult(await datasetUploadFile(getClient(), {
+        dataset,
+        filePath: file_path,
+        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() },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ultralytics-mcp",
-  "version": "0.1.1",
-  "description": "TypeScript MCP server for the Ultralytics Platform REST API.",
+  "version": "0.1.3",
+  "description": "MCP for Ultralytics Platform workflows, datasets, training, prediction, and model operations.",
   "type": "module",
   "bin": {
     "ultralytics-mcp": "./dist/cli.js"