ultralytics-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aman Harsh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# Ultralytics Platform MCP
+
+MCP server for the Ultralytics Platform REST API.
+
+Current milestone: protocol scaffold with CLI entrypoint and protocol-level
+tests. Tooling and API features land incrementally from here.
+
+## Development
+
+```bash
+npm install
+npm run check
+npm test
+npm run build
+```

package/dist/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+const server = createServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/client.js

@@ -0,0 +1,179 @@
+/** HTTP client wrapper for the Ultralytics Platform REST API.
+ *
+ * Mirrors the Python `UltralyticsClient` safety behaviors exactly:
+ * - Bearer auth + Accept: application/json on API calls.
+ * - GET retries 429 (idempotent); POST defaults to NO retry (no duplicate
+ *   state-changing/cost calls).
+ * - `Retry-After` numeric header wins over exponential backoff.
+ * - Non-2xx responses normalize into `UltralyticsApiError`.
+ * - `downloadBytes` fetches signed URLs WITHOUT forwarding `Authorization`.
+ *
+ * `fetchImpl` / `downloadFetchImpl` are injectable for tests.
+ */
+import { getApiBase, getApiKey } from "./config.js";
+import { UltralyticsApiError } from "./errors.js";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class UltralyticsClient {
+    baseUrl;
+    apiKey;
+    timeoutMs;
+    maxRetries;
+    fetchImpl;
+    downloadFetchImpl;
+    constructor(options = {}) {
+        this.baseUrl = (options.baseUrl ?? getApiBase()).replace(/\/+$/, "");
+        this.apiKey = options.apiKey ?? getApiKey();
+        this.timeoutMs = options.timeoutMs ?? 60_000;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.downloadFetchImpl = options.downloadFetchImpl ?? fetch;
+    }
+    // -- public verbs --------------------------------------------------------
+    /** GET requests are idempotent and retry 429 responses. */
+    async get(path, params) {
+        return this.request("GET", path, { params, retryOn429: true });
+    }
+    /** POST JSON. Defaults to no retry to avoid duplicate state-changing calls. */
+    async postJson(path, payload, options = {}) {
+        return this.request("POST", path, {
+            jsonBody: payload,
+            retryOn429: options.retryOn429 ?? false,
+        });
+    }
+    /** POST multipart/form-data. Defaults to no retry. */
+    async postMultipart(path, content, options = {}) {
+        const form = new FormData();
+        if (content.data) {
+            for (const [key, value] of Object.entries(content.data)) {
+                form.append(key, String(value));
+            }
+        }
+        if (content.files) {
+            for (const [key, file] of Object.entries(content.files)) {
+                if (file.filename) {
+                    form.append(key, file.blob, file.filename);
+                }
+                else {
+                    form.append(key, file.blob);
+                }
+            }
+        }
+        return this.request("POST", path, {
+            formBody: form,
+            retryOn429: options.retryOn429 ?? false,
+        });
+    }
+    /** Download bytes from a signed URL WITHOUT forwarding API credentials. */
+    async downloadBytes(url) {
+        let attempt = 0;
+        while (true) {
+            const response = await this.fetchWithTimeout(this.downloadFetchImpl, url, {
+                method: "GET",
+                headers: { Accept: "*/*" }, // deliberately no Authorization
+            });
+            if (response.status === 429 && attempt < this.maxRetries) {
+                attempt += 1;
+                await sleep(this.retryAfterMs(response, attempt));
+                continue;
+            }
+            if (response.ok) {
+                return new Uint8Array(await response.arrayBuffer());
+            }
+            await this.handle(response, url); // throws UltralyticsApiError
+            throw new Error("unreachable");
+        }
+    }
+    // -- internals -----------------------------------------------------------
+    buildUrl(path, params) {
+        const suffix = path.startsWith("/") ? path : `/${path}`;
+        const url = new URL(this.baseUrl + suffix);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                if (value !== undefined && value !== null) {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        return url.toString();
+    }
+    async request(method, path, spec) {
+        const url = this.buildUrl(path, spec.params);
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+        };
+        let body;
+        if (spec.jsonBody !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(spec.jsonBody);
+        }
+        else if (spec.formBody !== undefined) {
+            // Let fetch set multipart Content-Type with boundary.
+            body = spec.formBody;
+        }
+        let attempt = 0;
+        while (true) {
+            const response = await this.fetchWithTimeout(this.fetchImpl, url, {
+                method,
+                headers,
+                body,
+            });
+            if (response.status === 429 &&
+                spec.retryOn429 &&
+                attempt < this.maxRetries) {
+                attempt += 1;
+                await sleep(this.retryAfterMs(response, attempt));
+                continue;
+            }
+            return this.handle(response, url);
+        }
+    }
+    async fetchWithTimeout(impl, url, init) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            return await impl(url, { ...init, signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    retryAfterMs(response, attempt) {
+        const raw = response.headers.get("Retry-After");
+        if (raw) {
+            const seconds = Number(raw);
+            if (!Number.isNaN(seconds)) {
+                return seconds * 1000;
+            }
+        }
+        return 2 ** attempt * 1000;
+    }
+    async handle(response, url) {
+        const text = await response.text();
+        if (response.ok) {
+            if (!text) {
+                return {};
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return { raw: text };
+            }
+        }
+        let message = response.statusText || "request failed";
+        if (text) {
+            try {
+                const parsed = JSON.parse(text);
+                if (parsed && typeof parsed === "object") {
+                    const obj = parsed;
+                    message = obj.error || obj.message || message;
+                }
+            }
+            catch {
+                message = text.slice(0, 300);
+            }
+        }
+        throw new UltralyticsApiError(response.status, message, url);
+    }
+}

package/dist/config.js

@@ -0,0 +1,29 @@
+/** Configuration and environment handling for the Ultralytics MCP server. */
+const DEFAULT_API_BASE = "https://platform.ultralytics.com/api";
+const API_KEY_ENV = "ULTRALYTICS_API_KEY";
+const API_BASE_ENV = "ULTRALYTICS_API_BASE";
+/** Documented key format: 'ul_' followed by exactly 40 hex characters. */
+const API_KEY_RE = /^ul_[0-9a-fA-F]{40}$/;
+/** Raised when required configuration is missing or invalid. */
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+/** Return the API base URL, without a trailing slash. */
+export function getApiBase(env = process.env) {
+    return (env[API_BASE_ENV] ?? DEFAULT_API_BASE).replace(/\/+$/, "");
+}
+/** Return a validated Ultralytics API key from the environment. */
+export function getApiKey(env = process.env) {
+    const key = (env[API_KEY_ENV] ?? "").trim();
+    if (!key) {
+        throw new ConfigError(`Missing ${API_KEY_ENV}. Generate a key at ` +
+            "https://platform.ultralytics.com (Settings > API Keys) and set it.");
+    }
+    if (!API_KEY_RE.test(key)) {
+        throw new ConfigError(`${API_KEY_ENV} looks malformed: expected 'ul_' followed by 40 hex characters.`);
+    }
+    return key;
+}

package/dist/errors.js

@@ -0,0 +1,25 @@
+/** Normalized error type for non-success Ultralytics API responses. */
+const STATUS_HINTS = {
+    400: "invalid request",
+    401: "authentication failed - check your ULTRALYTICS_API_KEY",
+    403: "insufficient permissions for this resource",
+    404: "resource not found",
+    409: "conflict",
+    429: "rate limit exceeded",
+    500: "server error",
+};
+/** A non-success response from the Ultralytics API. */
+export class UltralyticsApiError extends Error {
+    statusCode;
+    apiMessage;
+    url;
+    constructor(statusCode, message, url) {
+        const hint = STATUS_HINTS[statusCode];
+        const suffix = hint ? ` (${hint})` : "";
+        super(`HTTP ${statusCode}${suffix}: ${message} [${url}]`);
+        this.name = "UltralyticsApiError";
+        this.statusCode = statusCode;
+        this.apiMessage = message;
+        this.url = url;
+    }
+}

package/dist/resolve.js

@@ -0,0 +1,141 @@
+/** Resolve friendly Platform references to opaque resource IDs.
+ *
+ * Mirrors the Python `resolve` module exactly, including the resource-aware
+ * `ul://` URI shapes and the hard rule that ambiguous/missing references fail
+ * loudly (never silently pick the first match).
+ */
+const ID_RE = /^[0-9a-fA-F]{24}$/;
+const UL_PREFIX = "ul://";
+/** Raised when a reference cannot resolve to exactly one resource. */
+export class ResolutionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ResolutionError";
+    }
+}
+/** Return true when `ref` is a 24-hex Platform object id. */
+export function looksLikeId(ref) {
+    return ID_RE.test(ref.trim());
+}
+/** Split a reference into `{ isUlUri, parts }`. */
+export function parseRef(ref) {
+    const cleaned = ref.trim();
+    const isUlUri = cleaned.startsWith(UL_PREFIX);
+    const body = isUlUri ? cleaned.slice(UL_PREFIX.length) : cleaned;
+    return { isUlUri, parts: body.split("/").filter((part) => part.length > 0) };
+}
+function simpleUsernameSlug(parts, kind, ref) {
+    if (parts.length === 1) {
+        return [null, parts[0]];
+    }
+    if (parts.length === 2) {
+        return [parts[0], parts[1]];
+    }
+    throw new ResolutionError(`Cannot parse ${kind} reference '${ref}'. Use 'slug', 'username/slug', ` +
+        "a ul:// URI, or a 24-character id.");
+}
+function listField(data, field) {
+    if (data && typeof data === "object") {
+        const value = data[field];
+        if (Array.isArray(value)) {
+            return value;
+        }
+    }
+    return [];
+}
+function select(matches, kind, ref) {
+    if (matches.length === 0) {
+        throw new ResolutionError(`No ${kind} found matching '${ref}'. Check the slug/username, or pass the ` +
+            `24-character ${kind} id directly.`);
+    }
+    if (matches.length > 1) {
+        const options = matches
+            .slice(0, 8)
+            .map((item) => `${item.username ?? "?"}/${item.slug ?? "?"} (id=${item._id})`)
+            .join(", ");
+        throw new ResolutionError(`Ambiguous ${kind} reference '${ref}' matched ${matches.length} resources: ` +
+            `${options}. Pass the explicit id or a fully qualified reference.`);
+    }
+    return matches[0];
+}
+/** Resolve a project id, slug, username/slug, or project ul:// URI. */
+export async function resolveProject(client, ref) {
+    if (looksLikeId(ref)) {
+        return ref;
+    }
+    const { isUlUri, parts } = parseRef(ref);
+    let username;
+    let slug;
+    if (isUlUri) {
+        if (parts.length === 3 && parts[1] === "datasets") {
+            throw new ResolutionError(`'${ref}' is a dataset URI, not a project.`);
+        }
+        if (parts.length === 3) {
+            throw new ResolutionError(`'${ref}' is a model URI; use 'ul://${parts[0]}/${parts[1]}' for the project.`);
+        }
+        if (parts.length !== 2) {
+            throw new ResolutionError(`Unsupported project ul:// URI '${ref}'. Expected ul://username/project.`);
+        }
+        [username, slug] = [parts[0], parts[1]];
+    }
+    else {
+        [username, slug] = simpleUsernameSlug(parts, "project", ref);
+    }
+    const data = await client.get("/projects", username ? { username } : undefined);
+    const matches = listField(data, "projects").filter((project) => project.slug === slug &&
+        (username === null || project.username === username));
+    return select(matches, "project", ref)._id;
+}
+/** Resolve a dataset id, slug, username/slug, or dataset ul:// URI. */
+export async function resolveDataset(client, ref) {
+    if (looksLikeId(ref)) {
+        return ref;
+    }
+    const { isUlUri, parts } = parseRef(ref);
+    let username;
+    let slug;
+    if (isUlUri) {
+        if (!(parts.length === 3 && parts[1] === "datasets")) {
+            throw new ResolutionError(`Unsupported dataset ul:// URI '${ref}'. Expected ul://username/datasets/slug.`);
+        }
+        [username, slug] = [parts[0], parts[2]];
+    }
+    else {
+        [username, slug] = simpleUsernameSlug(parts, "dataset", ref);
+    }
+    const params = { slug };
+    if (username) {
+        params.username = username;
+    }
+    const data = await client.get("/datasets", params);
+    const matches = listField(data, "datasets").filter((dataset) => dataset.slug === slug &&
+        (username === null || dataset.username === username));
+    return select(matches, "dataset", ref)._id;
+}
+/** Resolve a model id, slug plus project, or model ul:// URI. */
+export async function resolveModel(client, ref, projectRef) {
+    if (looksLikeId(ref)) {
+        return ref;
+    }
+    const { isUlUri, parts } = parseRef(ref);
+    let slug;
+    let resolvedProjectRef = projectRef;
+    if (isUlUri) {
+        if (!(parts.length === 3 && parts[1] !== "datasets")) {
+            throw new ResolutionError(`Unsupported model ul:// URI '${ref}'. Expected ul://username/project/model.`);
+        }
+        const [username, projectSlug, modelSlug] = parts;
+        slug = modelSlug;
+        resolvedProjectRef = `${username}/${projectSlug}`;
+    }
+    else {
+        if (resolvedProjectRef === undefined) {
+            throw new ResolutionError(`Model reference '${ref}' is a slug; a project id/slug is required to resolve it.`);
+        }
+        [, slug] = simpleUsernameSlug(parts, "model", ref);
+    }
+    const projectId = await resolveProject(client, resolvedProjectRef);
+    const data = await client.get("/models", { projectId });
+    const matches = listField(data, "models").filter((model) => model.slug === slug);
+    return select(matches, "model", ref)._id;
+}

package/dist/server.js

@@ -0,0 +1,21 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { UltralyticsClient } from "./client.js";
+import { registerTools } from "./tools/index.js";
+/** Create the MCP server with all tools registered.
+ *
+ * The client is created lazily on first tool invocation (so it reads the API key
+ * only when a tool actually runs, not at registration/listing time). A custom
+ * `clientFactory` can be injected for tests.
+ */
+export function createServer(clientFactory = () => new UltralyticsClient()) {
+    const server = new McpServer({ name: "ultralytics", version: "0.2.0" });
+    let client;
+    const getClient = () => {
+        if (!client) {
+            client = clientFactory();
+        }
+        return client;
+    };
+    registerTools(server, getClient);
+    return server;
+}

package/dist/tool-result.js

@@ -0,0 +1,10 @@
+export function toMcpTextResult(result) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result),
+            },
+        ],
+    };
+}

package/dist/tools/datasets.js

@@ -0,0 +1,30 @@
+/** Read-only dataset tools. */
+import { resolveDataset } from "../resolve.js";
+import { asRecord, listField, pyCount, pyField } from "./shared.js";
+/** List datasets in the workspace, optionally filtered by username. */
+export async function datasetsList(client, username) {
+    const data = await client.get("/datasets", username ? { username } : undefined);
+    const items = listField(data, "datasets").map((dataset) => ({
+        id: dataset._id ?? null,
+        name: dataset.name ?? null,
+        slug: dataset.slug ?? null,
+        task: dataset.task ?? null,
+        imageCount: dataset.imageCount ?? null,
+        classCount: dataset.classCount ?? null,
+        visibility: dataset.visibility ?? null,
+    }));
+    return { summary: `${items.length} dataset(s).`, data: items };
+}
+/** Get one dataset by id, slug, username/slug, or dataset ul:// URI. */
+export async function datasetsGet(client, dataset) {
+    const datasetId = await resolveDataset(client, dataset);
+    const data = await client.get(`/datasets/${datasetId}`);
+    const record = asRecord(data);
+    const item = "dataset" in record ? record.dataset : data;
+    const fields = asRecord(item);
+    return {
+        summary: `Dataset '${pyField(fields.name)}' [${pyField(fields.task)}], ` +
+            `${pyCount(fields, "imageCount")} images, ${pyCount(fields, "classCount")} classes.`,
+        data: item,
+    };
+}

package/dist/tools/downloads.js

@@ -0,0 +1,107 @@
+/** Model weight download tool. Writes to an explicit local path; the signed-URL
+ * fetch never forwards API credentials (handled by client.downloadBytes).
+ */
+import { stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { resolveModel } from "../resolve.js";
+import { asRecord } from "./shared.js";
+function fileName(info) {
+    const value = info.name ?? info.filename ?? info.fileName;
+    return value ? String(value) : null;
+}
+function fileUrl(info) {
+    const value = info.url ?? info.downloadUrl ?? info.download_url ?? info.signedUrl;
+    return value ? String(value) : null;
+}
+function modelFiles(data) {
+    const record = asRecord(data);
+    const files = record.files ?? record.modelFiles ?? record.models;
+    if (!Array.isArray(files)) {
+        return [];
+    }
+    return files.filter((item) => item && typeof item === "object");
+}
+function selectModelFile(files, filename) {
+    if (files.length === 0) {
+        throw new Error("No downloadable model files returned by the API.");
+    }
+    if (filename) {
+        for (const file of files) {
+            if (fileName(file) === filename) {
+                return file;
+            }
+        }
+        throw new Error(`No model file named '${filename}' was returned by the API.`);
+    }
+    for (const file of files) {
+        if (fileName(file) === "best.pt") {
+            return file;
+        }
+    }
+    return files[0];
+}
+function expandHome(input) {
+    if (input === "~") {
+        return homedir();
+    }
+    if (input.startsWith("~/")) {
+        return join(homedir(), input.slice(2));
+    }
+    return input;
+}
+async function statSafe(target) {
+    try {
+        const info = await stat(target);
+        return { exists: true, isDir: info.isDirectory() };
+    }
+    catch {
+        return { exists: false, isDir: false };
+    }
+}
+async function downloadTarget(outputPath, overwrite) {
+    if (!outputPath?.trim()) {
+        throw new Error("`output_path` is required.");
+    }
+    const target = resolve(expandHome(outputPath));
+    const parent = dirname(target);
+    const parentInfo = await statSafe(parent);
+    if (!parentInfo.exists) {
+        throw new Error(`Output directory does not exist: ${parent}`);
+    }
+    if (!parentInfo.isDir) {
+        throw new Error(`Output parent is not a directory: ${parent}`);
+    }
+    const targetInfo = await statSafe(target);
+    if (targetInfo.exists && targetInfo.isDir) {
+        throw new Error(`Output path is a directory: ${target}`);
+    }
+    if (targetInfo.exists && !overwrite) {
+        throw new Error(`Output path exists: ${target}. Pass overwrite=true to replace it.`);
+    }
+    return target;
+}
+/** Download one model weight file to an explicit local path. */
+export async function modelDownload(client, model, options) {
+    const { outputPath, project, filename, overwrite = false } = options;
+    const target = await downloadTarget(outputPath, overwrite);
+    const modelId = await resolveModel(client, model, project);
+    const data = await client.get(`/models/${modelId}/files`);
+    const fileInfo = selectModelFile(modelFiles(data), filename);
+    const selectedName = fileName(fileInfo) ?? filename ?? "model file";
+    const signedUrl = fileUrl(fileInfo);
+    if (signedUrl === null) {
+        throw new Error(`Model file '${selectedName}' did not include a download URL.`);
+    }
+    const content = await client.downloadBytes(signedUrl);
+    await writeFile(target, content);
+    return {
+        summary: `Downloaded ${selectedName} to ${target} (${content.length} bytes).`,
+        data: {
+            modelId,
+            filename: selectedName,
+            path: target,
+            bytes: content.length,
+        },
+    };
+}

package/dist/tools/exports.js

@@ -0,0 +1,93 @@
+/** Export tools. `export_create` is state-changing and guarded by confirm_cost. */
+import { looksLikeId, resolveModel } from "../resolve.js";
+import { asRecord, listField, pyField } from "./shared.js";
+const EXPORT_FORMATS = new Set([
+    "onnx",
+    "torchscript",
+    "openvino",
+    "engine",
+    "coreml",
+    "tflite",
+    "saved_model",
+    "pb",
+    "paddle",
+    "ncnn",
+    "edgetpu",
+    "tfjs",
+    "mnn",
+    "rknn",
+    "qnn",
+    "imx",
+    "axelera",
+    "executorch",
+    "deepx",
+]);
+/** List exports for a model. */
+export async function exportsList(client, model, project) {
+    const modelId = await resolveModel(client, model, project);
+    const data = await client.get("/exports", { modelId });
+    const items = listField(data, "exports").map((entry) => ({
+        id: entry._id ?? null,
+        format: entry.format ?? null,
+        status: entry.status ?? null,
+    }));
+    return { summary: `${items.length} export(s) for model.`, data: items };
+}
+/** Get status for one export job. */
+export async function exportStatus(client, exportId) {
+    if (!looksLikeId(exportId)) {
+        throw new Error("`export_id` must be a 24-character export id.");
+    }
+    const data = await client.get(`/exports/${exportId}`);
+    const record = asRecord(data);
+    const item = "export" in record ? record.export : data;
+    const fields = asRecord(item);
+    const idText = "_id" in fields ? pyField(fields._id) : exportId;
+    return {
+        summary: `Export ${idText} status=${pyField(fields.status)} format=${pyField(fields.format)}.`,
+        data: item,
+    };
+}
+/** Create a model export job. This is state-changing and may cost credits. */
+export async function exportCreate(client, model, format, options = {}) {
+    const { project, gpuType, imgsz, half, dynamic, confirmCost = false, } = options;
+    if (!confirmCost) {
+        throw new Error("Set confirm_cost=true to create an export job.");
+    }
+    const exportFormat = format.trim().toLowerCase();
+    if (!EXPORT_FORMATS.has(exportFormat)) {
+        throw new Error(`Unsupported export format '${format}'.`);
+    }
+    if (exportFormat === "engine" && !gpuType) {
+        throw new Error("`gpu_type` is required for TensorRT engine exports.");
+    }
+    const modelId = await resolveModel(client, model, project);
+    const payload = { modelId, format: exportFormat };
+    if (gpuType) {
+        payload.gpuType = gpuType;
+    }
+    const args = {};
+    if (imgsz !== undefined) {
+        if (imgsz <= 0) {
+            throw new Error("`imgsz` must be greater than 0.");
+        }
+        args.imgsz = imgsz;
+    }
+    if (half !== undefined) {
+        args.half = half;
+    }
+    if (dynamic !== undefined) {
+        args.dynamic = dynamic;
+    }
+    if (Object.keys(args).length > 0) {
+        payload.args = args;
+    }
+    const data = await client.postJson("/exports", payload);
+    const record = asRecord(data);
+    const item = "export" in record ? record.export : data;
+    const fields = asRecord(item);
+    return {
+        summary: `Created export ${pyField(fields._id)} status=${pyField(fields.status)} format=${pyField(fields.format)}.`,
+        data: item,
+    };
+}

package/dist/tools/gpu.js

@@ -0,0 +1,13 @@
+/** Cloud GPU availability tool. */
+import { asRecord } from "./shared.js";
+/** Get current cloud GPU stock status by GPU type. */
+export async function gpuAvailability(client) {
+    const data = await client.get("/training/gpu-availability");
+    const available = Object.entries(asRecord(data))
+        .filter(([, stock]) => stock === "High" || stock === "Medium")
+        .map(([name]) => name);
+    return {
+        summary: `${available.length} GPU type(s) with High/Medium stock.`,
+        data,
+    };
+}

package/dist/tools/index.js

@@ -0,0 +1,185 @@
+/** Tool registration for the MCP server.
+ *
+ * Logic functions live in the sibling modules and are re-exported for tests and
+ * the parity fixture runner. `registerReadTools` wires them onto an `McpServer`
+ * with Zod input schemas. User-facing tool names stay snake_case for parity with
+ * the Python package.
+ */
+import { z } from "zod";
+import { toMcpTextResult } from "../tool-result.js";
+import { datasetsGet, datasetsList } 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 { projectsGet, projectsList } from "./projects.js";
+import { trainingMonitor, trainingStart } from "./training.js";
+export { datasetsGet, datasetsList } 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 { 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",
+    "datasets_list",
+    "datasets_get",
+    "models_list",
+    "models_get",
+    "gpu_availability",
+];
+/** Register the read-only tools onto a server, using a lazy client provider. */
+export function registerReadTools(server, getClient) {
+    server.registerTool("projects_list", {
+        description: "List computer-vision projects in your Ultralytics workspace.",
+        inputSchema: { username: z.string().optional() },
+    }, async ({ username }) => toMcpTextResult(await projectsList(getClient(), username)));
+    server.registerTool("projects_get", {
+        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("datasets_list", {
+        description: "List datasets in your Ultralytics workspace.",
+        inputSchema: { username: z.string().optional() },
+    }, async ({ username }) => toMcpTextResult(await datasetsList(getClient(), username)));
+    server.registerTool("datasets_get", {
+        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("models_list", {
+        description: "List models in a project by project id, slug, username/slug, or project ul:// URI.",
+        inputSchema: { project: z.string() },
+    }, async ({ project }) => toMcpTextResult(await modelsList(getClient(), project)));
+    server.registerTool("models_get", {
+        description: "Get one model by id, or by slug plus project.",
+        inputSchema: { model: z.string(), project: z.string().optional() },
+    }, async ({ model, project }) => toMcpTextResult(await modelsGet(getClient(), model, project)));
+    server.registerTool("gpu_availability", {
+        description: "Get current cloud-GPU stock status by GPU type.",
+        inputSchema: {},
+    }, async () => toMcpTextResult(await gpuAvailability(getClient())));
+}
+/** Names of the monitor/predict/download tools. */
+export const ACTION_TOOL_NAMES = [
+    "training_monitor",
+    "model_predict",
+    "model_download",
+];
+/** Register training monitor, predict, and download tools. */
+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)));
+    server.registerTool("model_predict", {
+        description: "Run inference with a trained model on an image URL or base64 source (no local file paths).",
+        inputSchema: {
+            model: z.string(),
+            source: z.string(),
+            project: z.string().optional(),
+            conf: z.number().optional(),
+            iou: z.number().optional(),
+            imgsz: z.number().optional(),
+        },
+    }, async ({ model, source, project, conf, iou, imgsz }) => toMcpTextResult(await modelPredict(getClient(), model, {
+        source,
+        project,
+        conf,
+        iou,
+        imgsz,
+    })));
+    server.registerTool("model_download", {
+        description: "Download one trained model weight file to an explicit local path.",
+        inputSchema: {
+            model: z.string(),
+            output_path: z.string(),
+            project: z.string().optional(),
+            filename: z.string().optional(),
+            overwrite: z.boolean().optional(),
+        },
+    }, async ({ model, output_path, project, filename, overwrite }) => toMcpTextResult(await modelDownload(getClient(), model, {
+        outputPath: output_path,
+        project,
+        filename,
+        overwrite,
+    })));
+}
+/** Names of the guarded write tools (exports + training start). */
+export const WRITE_TOOL_NAMES = [
+    "exports_list",
+    "export_status",
+    "export_create",
+    "training_start",
+];
+/** Register export and training-start tools. The cost-incurring ones are guarded. */
+export function registerWriteTools(server, getClient) {
+    server.registerTool("exports_list", {
+        description: "List export jobs for a model.",
+        inputSchema: { model: z.string(), project: z.string().optional() },
+    }, async ({ model, project }) => toMcpTextResult(await exportsList(getClient(), model, project)));
+    server.registerTool("export_status", {
+        description: "Get status for one export job by 24-character export id.",
+        inputSchema: { export_id: z.string() },
+    }, async ({ export_id }) => toMcpTextResult(await exportStatus(getClient(), export_id)));
+    server.registerTool("export_create", {
+        description: "Create a model export job (state-changing, may cost credits). Requires confirm_cost=true.",
+        inputSchema: {
+            model: z.string(),
+            format: z.string(),
+            project: z.string().optional(),
+            gpu_type: z.string().optional(),
+            imgsz: z.number().optional(),
+            half: z.boolean().optional(),
+            dynamic: z.boolean().optional(),
+            confirm_cost: z.boolean().optional(),
+        },
+    }, async ({ model, format, project, gpu_type, imgsz, half, dynamic, confirm_cost, }) => toMcpTextResult(await exportCreate(getClient(), model, format, {
+        project,
+        gpuType: gpu_type,
+        imgsz,
+        half,
+        dynamic,
+        confirmCost: confirm_cost,
+    })));
+    server.registerTool("training_start", {
+        description: "Start a cloud training job (state-changing, may cost credits). Requires confirm_cost=true.",
+        inputSchema: {
+            model: z.string(),
+            project: z.string(),
+            dataset: z.string(),
+            gpu_type: z.string(),
+            epochs: z.number().optional(),
+            imgsz: z.number().optional(),
+            batch: z.number().optional(),
+            name: z.string().optional(),
+            confirm_cost: z.boolean().optional(),
+        },
+    }, async ({ model, project, dataset, gpu_type, epochs, imgsz, batch, name, confirm_cost, }) => toMcpTextResult(await trainingStart(getClient(), {
+        model,
+        project,
+        dataset,
+        gpuType: gpu_type,
+        epochs,
+        imgsz,
+        batch,
+        name,
+        confirmCost: confirm_cost,
+    })));
+}
+/** All tool names registered so far. */
+export const TOOL_NAMES = [
+    ...READ_TOOL_NAMES,
+    ...ACTION_TOOL_NAMES,
+    ...WRITE_TOOL_NAMES,
+];
+/** Register all available tools onto a server. */
+export function registerTools(server, getClient) {
+    registerReadTools(server, getClient);
+    registerActionTools(server, getClient);
+    registerWriteTools(server, getClient);
+}

package/dist/tools/models.js

@@ -0,0 +1,32 @@
+/** Read-only model tools. */
+import { resolveModel, resolveProject } from "../resolve.js";
+import { asRecord, listField, pyField } from "./shared.js";
+/** List models in a project. */
+export async function modelsList(client, project) {
+    const projectId = await resolveProject(client, project);
+    const data = await client.get("/models", { projectId });
+    const items = listField(data, "models").map((model) => ({
+        id: model._id ?? null,
+        name: model.name ?? null,
+        slug: model.slug ?? null,
+        status: model.status ?? null,
+        task: model.task ?? null,
+        epochs: model.epochs ?? null,
+        bestFitness: model.bestFitness ?? null,
+    }));
+    return { summary: `${items.length} model(s) in project.`, data: items };
+}
+/** Get one model by id, or by slug within a project. */
+export async function modelsGet(client, model, project) {
+    const modelId = await resolveModel(client, model, project);
+    const data = await client.get(`/models/${modelId}`);
+    const record = asRecord(data);
+    const item = "model" in record ? record.model : data;
+    const fields = asRecord(item);
+    const info = asRecord(fields.modelInfo);
+    return {
+        summary: `Model '${pyField(fields.name)}' [${pyField(fields.task)}] status=${pyField(fields.status)}, ` +
+            `epochs=${pyField(fields.epochs)}, params=${pyField(info.parameters)}.`,
+        data: item,
+    };
+}

package/dist/tools/predict.js

@@ -0,0 +1,28 @@
+/** Inference tool. Accepts only an image URL or base64 source (no local paths). */
+import { resolveModel } from "../resolve.js";
+import { asRecord, listField } from "./shared.js";
+/** Run inference from an image URL or base64 source. Local paths are not accepted. */
+export async function modelPredict(client, model, options) {
+    const { source, project, conf = 0.25, iou = 0.7, imgsz = 640 } = options;
+    if (!source?.trim()) {
+        throw new Error("`source` is required: an image URL or base64-encoded image.");
+    }
+    const modelId = await resolveModel(client, model, project);
+    const result = await client.postMultipart(`/models/${modelId}/predict`, {
+        data: {
+            source,
+            conf: String(conf),
+            iou: String(iou),
+            imgsz: String(imgsz),
+        },
+    });
+    const images = listField(result, "images");
+    const detectionCount = images.reduce((total, image) => total +
+        (Array.isArray(asRecord(image).results)
+            ? asRecord(image).results.length
+            : 0), 0);
+    return {
+        summary: `${images.length} image(s), ${detectionCount} detection(s).`,
+        data: result,
+    };
+}

package/dist/tools/projects.js

@@ -0,0 +1,29 @@
+/** Read-only project tools. */
+import { resolveProject } from "../resolve.js";
+import { asRecord, listField, pyCount, pyField } from "./shared.js";
+/** List projects in the workspace, optionally filtered by username. */
+export async function projectsList(client, username) {
+    const data = await client.get("/projects", username ? { username } : undefined);
+    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,
+    }));
+    return { summary: `${items.length} project(s).`, data: items };
+}
+/** Get one project by id, slug, username/slug, or project ul:// URI. */
+export async function projectsGet(client, project) {
+    const projectId = await resolveProject(client, project);
+    const data = await client.get(`/projects/${projectId}`);
+    const record = asRecord(data);
+    const item = "project" in record ? record.project : data;
+    const fields = asRecord(item);
+    return {
+        summary: `Project '${pyField(fields.name)}' (${pyField(fields.visibility)}), ` +
+            `${pyCount(fields, "modelCount")} model(s).`,
+        data: item,
+    };
+}

package/dist/tools/shared.js

@@ -0,0 +1,24 @@
+/** Shared helpers for tool logic. */
+/** Coerce unknown JSON into a record for safe field access. */
+export function asRecord(data) {
+    return data && typeof data === "object"
+        ? data
+        : {};
+}
+/** Return `data[field]` as an array of records, or []. */
+export function listField(data, field) {
+    const value = asRecord(data)[field];
+    return Array.isArray(value) ? value : [];
+}
+/** Render a summary field like Python's `dict.get(key)`: missing -> "None". */
+export function pyField(value) {
+    return value === undefined || value === null ? "None" : String(value);
+}
+/** Render a count like Python's `dict.get(key, "?")`: absent -> "?", present-null -> "None". */
+export function pyCount(fields, key) {
+    if (!(key in fields)) {
+        return "?";
+    }
+    const value = fields[key];
+    return value === undefined || value === null ? "None" : String(value);
+}

package/dist/tools/training.js

@@ -0,0 +1,129 @@
+/** Training monitor tool (private-safe: derives progress from model trainResults). */
+import { UltralyticsApiError } from "../errors.js";
+import { resolveDataset, resolveModel, resolveProject } from "../resolve.js";
+import { asRecord, pyField } from "./shared.js";
+const KEY_METRICS = [
+    "metrics/mAP50(B)",
+    "metrics/mAP50-95(B)",
+    "metrics/mAP50(M)",
+    "metrics/mAP50-95(M)",
+];
+/** Format a percentage like Python's `str(round(x, 1))` (whole numbers keep `.0`). */
+function formatPercent(value) {
+    return Number.isInteger(value) ? value.toFixed(1) : String(value);
+}
+/** Report model training status using private-safe model trainResults. */
+export async function trainingMonitor(client, model, project) {
+    const modelId = await resolveModel(client, model, project);
+    const data = await client.get(`/models/${modelId}`);
+    const record = asRecord(data);
+    const item = asRecord("model" in record ? record.model : data);
+    const status = item.status ?? null;
+    const totalEpochs = item.epochs;
+    const hasTotal = typeof totalEpochs === "number" && totalEpochs > 0;
+    const trainResults = Array.isArray(item.trainResults)
+        ? item.trainResults
+        : [];
+    const epochsDone = trainResults.length;
+    const latestMetrics = epochsDone > 0
+        ? asRecord(asRecord(trainResults[epochsDone - 1]).metrics)
+        : {};
+    const keyMetrics = {};
+    for (const key of KEY_METRICS) {
+        if (key in latestMetrics) {
+            keyMetrics[key] = latestMetrics[key];
+        }
+    }
+    let progressPct = null;
+    let progressText = null;
+    let etaMs = null;
+    let source = "model.trainResults";
+    try {
+        const trainingData = await client.get(`/models/${modelId}/training`);
+        const job = asRecord(asRecord(trainingData).job);
+        const progress = asRecord(job.progress);
+        const timing = asRecord(job.timing);
+        progressPct = progress.percentage ?? null;
+        progressText = progressPct === null ? null : String(progressPct);
+        etaMs = timing.etaMs ?? null;
+        source = "models/{id}/training";
+    }
+    catch (error) {
+        if (!(error instanceof UltralyticsApiError) ||
+            ![401, 403, 404].includes(error.statusCode)) {
+            throw error;
+        }
+        if (hasTotal) {
+            progressPct =
+                Math.round(((100 * epochsDone) / totalEpochs) * 10) / 10;
+            progressText = formatPercent(progressPct);
+        }
+    }
+    const totalDisplay = hasTotal ? totalEpochs : "?";
+    const summary = `Training status=${status}; epoch ${epochsDone}/${totalDisplay}` +
+        (progressPct !== null ? `; ~${progressText}%` : "") +
+        (etaMs ? `; ETA ${Math.round(etaMs / 60000)}min` : "");
+    return {
+        summary,
+        data: {
+            modelId,
+            status,
+            epochsDone,
+            totalEpochs: hasTotal ? totalEpochs : null,
+            progressPercentage: progressPct,
+            etaMs,
+            bestEpoch: item.bestEpoch ?? null,
+            bestFitness: item.bestFitness ?? null,
+            latestMetrics: keyMetrics,
+            progressSource: source,
+        },
+    };
+}
+/** Start cloud training. This is state-changing and may cost credits. */
+export async function trainingStart(client, options) {
+    const { model, project, dataset, gpuType, epochs, imgsz, batch, name, confirmCost = false, } = options;
+    if (!confirmCost) {
+        throw new Error("Set confirm_cost=true to start a cloud training job.");
+    }
+    if (!gpuType?.trim()) {
+        throw new Error("`gpu_type` is required.");
+    }
+    const modelId = await resolveModel(client, model, project);
+    const projectId = await resolveProject(client, project);
+    const datasetId = await resolveDataset(client, dataset);
+    const trainArgs = { data: datasetId };
+    if (epochs !== undefined) {
+        if (epochs <= 0) {
+            throw new Error("`epochs` must be greater than 0.");
+        }
+        trainArgs.epochs = epochs;
+    }
+    if (imgsz !== undefined) {
+        if (imgsz <= 0) {
+            throw new Error("`imgsz` must be greater than 0.");
+        }
+        trainArgs.imgsz = imgsz;
+    }
+    if (batch !== undefined) {
+        if (batch <= 0) {
+            throw new Error("`batch` must be greater than 0.");
+        }
+        trainArgs.batch = batch;
+    }
+    if (name) {
+        trainArgs.name = name;
+    }
+    const data = await client.postJson("/training/start", {
+        modelId,
+        projectId,
+        gpuType,
+        trainArgs,
+    });
+    const record = asRecord(data);
+    const item = "job" in record ? record.job : data;
+    const fields = asRecord(item);
+    return {
+        summary: `Started training job ${pyField(fields._id)} status=${pyField(fields.status)}.`,
+        data: item,
+    };
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "ultralytics-mcp",
+  "version": "0.1.0",
+  "description": "TypeScript MCP server for the Ultralytics Platform REST API.",
+  "type": "module",
+  "bin": {
+    "ultralytics-mcp": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "package.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amanharshx/ultralytics-mcp.git"
+  },
+  "homepage": "https://github.com/amanharshx/ultralytics-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/amanharshx/ultralytics-mcp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "biome check .",
+    "format": "biome check --write .",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "mcp",
+    "ultralytics",
+    "yolo",
+    "model-context-protocol"
+  ],
+  "author": "Aman Harsh",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.1",
+    "@types/node": "^24.4.0",
+    "typescript": "^5.9.2",
+    "vitest": "^4.1.9"
+  }
+}