ultralytics-mcp 0.1.2 → 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 (20)
+## 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` / `dataset_ingest` / `dataset_upload_file` | Browse / create / soft-delete datasets, start remote ingest jobs, and upload archive files |
+| `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/tools/datasets.js

@@ -117,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);
@@ -182,3 +248,38 @@ export async function datasetUploadFile(client, options) {
         },
     };
 }
+/** 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, datasetsIngest, datasetsList, datasetUploadFile, } 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, datasetsIngest, datasetsList, datasetUploadFile, } 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,6 +32,9 @@ 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",
@@ -87,6 +90,42 @@ 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() },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultralytics-mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "MCP for Ultralytics Platform workflows, datasets, training, prediction, and model operations.",
   "type": "module",
   "bin": {