ultralytics-mcp 0.1.4 → 0.1.6

package/README.md

@@ -1,32 +1,194 @@
 # 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, explore, monitor, predict, export, and extended
-project and dataset lifecycle tools are available. Additional
-resource-management tools land incrementally from here.
-
-## Tools (27)
-
-| Tool | Description |
-| --- | --- |
-| `projects_list` / `projects_get` | Browse projects |
-| `projects_create` / `projects_delete` | Create / soft-delete projects |
-| `explore_projects` / `explore_datasets` | Search public projects and datasets on Ultralytics Explore |
-| `datasets_list` / `datasets_get` / `datasets_create` / `datasets_delete` / `dataset_images_list` / `dataset_ingest` / `dataset_upload_file` / `dataset_upload_folder` / `dataset_upload_video` | Browse / create / soft-delete datasets, inspect images, start remote ingest jobs, and upload archive files, folders, or videos |
-| `models_list` / `models_get` | Browse trained models and metrics |
-| `training_monitor` | Status, progress, latest metrics, and optional recent metric history |
-| `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`** |
+---
+
+## 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)
+- [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
+
+- 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
+- Pass advanced YOLO training settings through `training_start.train_args`
+- Start training from existing project models or official YOLO base checkpoints
+
+## Tools
+
+See [TOOLS.md](./TOOLS.md) for full parameter reference, safety notes, local-path behavior, and examples for tricky tools.
+
+- Projects: 5 tools
+- Datasets: 12 tools
+- Models: 4 tools
+- Training: 2 tools
+- Exports: 3 tools
+- Infrastructure: 1 tool
+
+## 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
 
@@ -35,4 +197,5 @@ npm install
 npm run check
 npm test
 npm run build
+npm run generate:tools
 ```

package/TOOLS.md

@@ -0,0 +1,486 @@
+# Tools Reference
+
+Auto-generated reference for Ultralytics Platform MCP tools.
+
+> Auto-generated. Do not edit by hand. Run `npm run generate:tools`. Edit tool definitions in `src/tools/index.ts`.
+
+## Conventions
+
+- Many project, dataset, and model lookup tools accept ids, slugs, `username/slug`, or `ul://` refs.
+- Local-path tools operate on files or folders available to the MCP client host.
+- Exact accepted ref variants are documented in tool descriptions and notes when behavior differs.
+
+## Local Path Tools
+
+- `dataset_upload_file` uploads a local archive file.
+- `dataset_upload_folder` uploads a local image folder.
+- `dataset_upload_video` extracts frames from a local video file with `ffmpeg`.
+- `model_download` writes model weights to a local destination path.
+
+## Cost and Safety
+
+- `training_start` requires `confirm_cost=true` and may create a model when checkpoint mode is used.
+- `export_create` requires `confirm_cost=true` and starts a credit-costing export job.
+- `projects_delete` and `datasets_delete` are soft-delete operations.
+
+## Projects
+
+5 tools.
+
+### projects_list
+
+List computer-vision projects in your Ultralytics workspace.
+
+Metadata: read-only
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `username` | string | No |  |
+
+### projects_get
+
+Get details for one project by id, slug, username/slug, or project ul:// URI.
+
+Metadata: read-only
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `project` | string | Yes | Project ref by id, slug, username/slug, or ul:// URI. |
+
+### explore_projects
+
+Search public projects on Ultralytics Explore.
+
+Metadata: read-only, external/live
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `q` | string | Yes |  |
+| `sort` | string | No |  |
+| `offset` | number | No |  |
+
+### projects_create
+
+Create a project in your Ultralytics workspace.
+
+Metadata: state-changing, non-idempotent
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string | Yes |  |
+| `slug` | string | No |  |
+| `description` | string | No |  |
+
+### projects_delete
+
+Soft-delete a project by id, slug, username/slug, or project ul:// URI.
+
+Metadata: state-changing, destructive, non-idempotent
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `project` | string | Yes | Project ref by id, slug, username/slug, or ul:// URI. |
+
+## Datasets
+
+12 tools.
+
+### datasets_list
+
+List datasets in your Ultralytics workspace.
+
+Metadata: read-only
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `username` | string | No |  |
+
+### datasets_get
+
+Get details for one dataset by id, slug, username/slug, or dataset ul:// URI.
+
+Metadata: read-only
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `dataset` | string | Yes | Dataset ref by id, slug, username/slug, or ul:// URI. |
+
+### explore_datasets
+
+Search public datasets on Ultralytics Explore.
+
+Metadata: read-only, external/live
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `q` | string | Yes |  |
+| `sort` | string | No |  |
+| `offset` | number | No |  |
+| `task` | array<string> | No |  |
+
+### datasets_create
+
+Create a dataset in your Ultralytics workspace.
+
+Metadata: state-changing, non-idempotent
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string | Yes |  |
+| `task` | string | Yes | Dataset task such as detect, segment, semantic, pose, obb, or classify. |
+| `slug` | string | Yes |  |
+| `description` | string | No |  |
+| `visibility` | string | No |  |
+| `classNames` | array<string> | No |  |
+
+### dataset_images_list
+
+List images in a dataset with optional filtering.
+
+Metadata: read-only
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `dataset` | string | Yes | Dataset ref by id, slug, username/slug, or ul:// URI. |
+| `split` | string | No |  |
+| `search` | string | No |  |
+| `hasLabel` | boolean | No |  |
+| `classIds` | array<string> | No |  |
+| `limit` | number | No |  |
+| `offset` | number | No |  |
+| `includeImageUrls` | boolean | No |  |
+
+### dataset_export
+
+Get export link for latest or one frozen dataset version.
+
+Metadata: read-only
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `dataset` | string | Yes | Dataset ref by id, slug, username/slug, or ul:// URI. |
+| `version` | number | No |  |
+
+### dataset_version_create
+
+Create a frozen dataset version snapshot.
+
+Metadata: state-changing, non-idempotent
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `dataset` | string | Yes | Dataset ref by id, slug, username/slug, or ul:// URI. |
+| `description` | string | No |  |
+
+### datasets_delete
+
+Soft-delete a dataset by id, slug, username/slug, or dataset ul:// URI.
+
+Metadata: state-changing, destructive, non-idempotent
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `dataset` | string | Yes | Dataset ref by id, slug, username/slug, or ul:// URI. |
+
+### dataset_ingest
+
+Start a remote URL ingest job for an existing dataset.
+
+Metadata: state-changing, non-idempotent, external/live
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `dataset` | string | Yes | Dataset ref by id, slug, username/slug, or ul:// URI. |
+| `sourceUrl` | string | Yes |  |
+| `targetSplit` | string | No |  |
+
+### dataset_upload_file
+
+Upload a local dataset archive file and start ingest for an existing dataset.
+
+Metadata: state-changing, non-idempotent
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `dataset` | string | Yes | Dataset ref by id, slug, username/slug, or ul:// URI. |
+| `file_path` | string | Yes | Local path to dataset archive file. |
+| `targetSplit` | string | No |  |
+
+Notes: Uses a local archive file path and starts ingest into an existing dataset.
+
+#### Upload dataset archive
+
+```json
+{
+  "dataset": "team/datasets/warehouse-items",
+  "file_path": "/data/warehouse-items.zip",
+  "targetSplit": "train"
+}
+```
+
+### dataset_upload_folder
+
+Upload a local image folder as a zip and start ingest for an existing dataset.
+
+Metadata: state-changing, non-idempotent
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `dataset` | string | Yes | Dataset ref by id, slug, username/slug, or ul:// URI. |
+| `folder_path` | string | Yes | Local path to image folder. |
+| `targetSplit` | string | No |  |
+
+Notes: Uses a local image folder path, zips it client-side, and starts ingest into an existing dataset.
+
+#### Upload image folder
+
+```json
+{
+  "dataset": "team/datasets/warehouse-items",
+  "folder_path": "/data/warehouse-items",
+  "targetSplit": "train"
+}
+```
+
+### dataset_upload_video
+
+Upload a local video by extracting JPEG frames with ffmpeg, then start dataset ingest for an existing dataset.
+
+Metadata: state-changing, non-idempotent
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `dataset` | string | Yes | Dataset ref by id, slug, username/slug, or ul:// URI. |
+| `video_path` | string | Yes | Local path to source video file. |
+| `fps` | number | No |  |
+| `max_frames` | number | No |  |
+| `targetSplit` | string | No |  |
+
+Notes: Uses a local video path, extracts JPEG frames with ffmpeg, and starts ingest into an existing dataset.
+
+#### Upload video for frame extraction
+
+```json
+{
+  "dataset": "team/datasets/factory-lines",
+  "video_path": "/videos/factory-shift.mp4",
+  "fps": 2,
+  "max_frames": 500,
+  "targetSplit": "train"
+}
+```
+
+## Models
+
+4 tools.
+
+### models_list
+
+List models in a project by project id, slug, username/slug, or project ul:// URI.
+
+Metadata: read-only
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `project` | string | Yes | Project ref by id, slug, username/slug, or ul:// URI. |
+
+### models_get
+
+Get one model by id, or by slug plus project.
+
+Metadata: read-only
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `model` | string | Yes | Model id, or slug when project is also provided. |
+| `project` | string | No | Project ref required when model is given by slug. |
+
+### model_predict
+
+Run inference with a trained model on an image URL or base64 source (no local file paths).
+
+Metadata: read-only, external/live
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `model` | string | Yes | Model id, or slug when project is also provided. |
+| `source` | string | Yes | Image URL or base64 input string. Local file paths are not supported. |
+| `project` | string | No |  |
+| `conf` | number | No |  |
+| `iou` | number | No |  |
+| `imgsz` | number | No |  |
+
+#### Predict from image URL
+
+```json
+{
+  "model": "team/project/my-model",
+  "source": "https://images.example.com/example.jpg",
+  "conf": 0.25
+}
+```
+
+#### Predict from base64 input
+
+```json
+{
+  "model": "team/project/my-model",
+  "source": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
+}
+```
+
+### model_download
+
+Download one trained model weight file to an explicit local path.
+
+Metadata: state-changing, non-idempotent
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `model` | string | Yes | Model id, or slug when project is also provided. |
+| `output_path` | string | Yes | Local destination path for downloaded model weights. |
+| `project` | string | No |  |
+| `filename` | string | No |  |
+| `overwrite` | boolean | No |  |
+
+Notes: Writes model weights to a local filesystem path.
+
+#### Download model weights
+
+```json
+{
+  "model": "team/project/my-model",
+  "output_path": "/tmp/model.pt",
+  "overwrite": true
+}
+```
+
+## Training
+
+2 tools.
+
+### training_monitor
+
+Report a model's training status and progress (works for private and public projects).
+
+Metadata: read-only, external/live
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `model` | string | Yes | Model id, or slug when project is also provided. |
+| `project` | string | No |  |
+| `include_metrics` | boolean | No |  |
+| `include_history` | boolean | No |  |
+| `history_last_n` | number | No |  |
+
+### training_start
+
+Start a cloud training job from an existing model or official YOLO base checkpoint (state-changing, may cost credits). Requires confirm_cost=true.
+
+Metadata: state-changing, non-idempotent, external/live
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `model` | string | Yes | Existing model ref, or official YOLO base checkpoint such as yolo11n.pt or yolo11n-seg.pt. Checkpoint mode auto-creates a project model. |
+| `project` | string | Yes | Project ref that owns the training job and resolved model. |
+| `dataset` | string | Yes | Dataset ref used as training data for the job. |
+| `gpu_type` | string | Yes | Cloud GPU type to allocate for training. |
+| `train_args` | record<string, unknown> | No |  |
+| `epochs` | number | No |  |
+| `imgsz` | number | No |  |
+| `batch` | number | No |  |
+| `name` | string | No |  |
+| `confirm_cost` | boolean | No | Must be true to allow a credit-costing training run. |
+
+Notes: Checkpoint-pattern model values such as `yolo11n.pt` and `yolo11n-seg.pt` trigger checkpoint mode, auto-create a project model, and require dataset-task compatibility.
+
+#### Train from existing model
+
+```json
+{
+  "model": "team/project/my-model",
+  "project": "team/project",
+  "dataset": "team/datasets/warehouse-items",
+  "gpu_type": "rtx-4090",
+  "confirm_cost": true
+}
+```
+
+#### Train from official YOLO checkpoint
+
+```json
+{
+  "model": "yolo11n-seg.pt",
+  "project": "team/project",
+  "dataset": "team/datasets/road-segments",
+  "gpu_type": "rtx-4090",
+  "confirm_cost": true
+}
+```
+
+## Exports
+
+3 tools.
+
+### exports_list
+
+List export jobs for a model.
+
+Metadata: read-only
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `model` | string | Yes | Model id, or slug when project is also provided. |
+| `project` | string | No |  |
+
+### export_status
+
+Get status for one export job by 24-character export id.
+
+Metadata: read-only
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `export_id` | string | Yes | 24-character export job id. |
+
+### export_create
+
+Create a model export job (state-changing, may cost credits). Requires confirm_cost=true.
+
+Metadata: state-changing, non-idempotent, external/live
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `model` | string | Yes | Model id, or slug when project is also provided. |
+| `format` | string | Yes | Requested export format. |
+| `project` | string | No |  |
+| `gpu_type` | string | No |  |
+| `imgsz` | number | No |  |
+| `half` | boolean | No |  |
+| `dynamic` | boolean | No |  |
+| `confirm_cost` | boolean | No | Must be true to allow a credit-costing export job. |
+
+Notes: State-changing export job that may cost credits. Set `confirm_cost` to `true` explicitly.
+
+#### Create export job
+
+```json
+{
+  "model": "team/project/my-model",
+  "format": "onnx",
+  "confirm_cost": true
+}
+```
+
+## Infrastructure
+
+1 tools.
+
+### gpu_availability
+
+Get current cloud-GPU stock status by GPU type.
+
+Metadata: read-only, external/live
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |