ultralytics-mcp 0.1.6 → 0.1.7

package/README.md

@@ -19,8 +19,6 @@ dataset uploads.
 - [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)
@@ -61,7 +59,7 @@ Works in many MCP clients that accept JSON stdio server definitions.
   "mcpServers": {
     "ultralytics": {
       "command": "npx",
-      "args": ["-y", "ultralytics-mcp"],
+      "args": ["-y", "ultralytics-mcp@latest"],
       "env": {
         "ULTRALYTICS_API_KEY": "ul_your_api_key_here"
       }
@@ -70,12 +68,34 @@ Works in many MCP clients that accept JSON stdio server definitions.
 }
 ```
 
-### Claude Code
+<details>
+<summary>Antigravity</summary>
+
+Add via the Antigravity settings or by updating your configuration file:
+
+```json
+{
+  "mcpServers": {
+    "ultralytics": {
+      "command": "npx",
+      "args": ["-y", "ultralytics-mcp@latest"],
+      "env": {
+        "ULTRALYTICS_API_KEY": "ul_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>Claude Code</summary>
 
 Add server with Claude Code CLI:
 
 ```bash
-claude mcp add ultralytics --env ULTRALYTICS_API_KEY=ul_your_api_key_here -- npx -y ultralytics-mcp
+claude mcp add ultralytics --env ULTRALYTICS_API_KEY=ul_your_api_key_here -- npx -y ultralytics-mcp@latest
 ```
 
 Or add a project-scoped server in repo-root `.mcp.json`:
@@ -85,7 +105,7 @@ Or add a project-scoped server in repo-root `.mcp.json`:
   "mcpServers": {
     "ultralytics": {
       "command": "npx",
-      "args": ["-y", "ultralytics-mcp"],
+      "args": ["-y", "ultralytics-mcp@latest"],
       "env": {
         "ULTRALYTICS_API_KEY": "ul_your_api_key_here"
       }
@@ -94,12 +114,22 @@ Or add a project-scoped server in repo-root `.mcp.json`:
 }
 ```
 
-### Codex
+</details>
+
+<details>
+<summary>Claude Desktop</summary>
+
+Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), use the standard config above.
+
+</details>
+
+<details>
+<summary>Codex</summary>
 
 Add server with Codex CLI:
 
 ```bash
-codex mcp add ultralytics --env ULTRALYTICS_API_KEY=ul_your_api_key_here -- npx -y ultralytics-mcp
+codex mcp add ultralytics --env ULTRALYTICS_API_KEY=ul_your_api_key_here -- npx -y ultralytics-mcp@latest
 ```
 
 Or add it directly to `~/.codex/config.toml`:
@@ -107,12 +137,62 @@ Or add it directly to `~/.codex/config.toml`:
 ```toml
 [mcp_servers.ultralytics]
 command = "npx"
-args = ["-y", "ultralytics-mcp"]
+args = ["-y", "ultralytics-mcp@latest"]
 
 [mcp_servers.ultralytics.env]
 ULTRALYTICS_API_KEY = "ul_your_api_key_here"
 ```
 
+</details>
+
+<details>
+<summary>Cursor</summary>
+
+#### Click the button to install:
+
+[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=ultralytics&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInVsdHJhbHl0aWNzLW1jcEBsYXRlc3QiXSwiZW52Ijp7IlVMVFJBTFlUSUNTX0FQSV9LRVkiOiJ1bF95b3VyX2FwaV9rZXlfaGVyZSJ9fQ%3D%3D)
+
+> **Important**
+> The install button writes a placeholder key. After installing, open your Cursor MCP config and replace `ul_your_api_key_here` with your Ultralytics API key, then restart Cursor.
+
+#### Or install manually:
+
+Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server` (or edit `~/.cursor/mcp.json` directly) and use the standard config above: `command` set to `npx`, `args` set to `["-y", "ultralytics-mcp@latest"]`, and `ULTRALYTICS_API_KEY` in `env`.
+
+</details>
+
+<details>
+<summary>Gemini CLI</summary>
+
+Follow the MCP install [guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#configure-the-mcp-server-in-settingsjson), use the standard config above.
+
+</details>
+
+<details>
+<summary>VS Code / Copilot</summary>
+
+#### Click the button to install:
+
+[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522ultralytics%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522ultralytics-mcp%2540latest%2522%255D%252C%2522env%2522%253A%257B%2522ULTRALYTICS_API_KEY%2522%253A%2522ul_your_api_key_here%2522%257D%257D)
+
+> **Important**
+> The install button writes a placeholder key. After installing, open your VS Code MCP config and replace `ul_your_api_key_here` with your Ultralytics API key, then restart VS Code.
+
+#### Or install manually:
+
+Follow the MCP install [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), use the standard config above. You can also install the server using the VS Code CLI:
+
+```bash
+# For VS Code
+code --add-mcp '{"name":"ultralytics","command":"npx","args":["-y","ultralytics-mcp@latest"],"env":{"ULTRALYTICS_API_KEY":"ul_your_api_key_here"}}'
+```
+
+After installation, the Ultralytics MCP server will be available for use with your GitHub Copilot agent in VS Code.
+
+</details>
+
+These examples track latest published npm release. Restart MCP client or session after upgrading so new server process picks up latest package.
+
 ## Verify Setup
 
 ### Claude Code
@@ -161,6 +241,8 @@ See [TOOLS.md](./TOOLS.md) for full parameter reference, safety notes, local-pat
 - `training_start` requires `confirm_cost: true`
 - Ambiguous project or dataset refs fail instead of guessing
 - Signed upload and download URLs do not forward `Authorization`
+- Local upload tools read files from the MCP client host; approve calls only for paths you expect to share with Ultralytics
+- `model_download` writes to the requested local path; review `output_path` and `overwrite` before approving
 
 ## Troubleshooting
 
@@ -185,7 +267,7 @@ characters after prefix.
 ### Manual server smoke test
 
 ```bash
-ULTRALYTICS_API_KEY=ul_your_api_key_here npx -y ultralytics-mcp
+ULTRALYTICS_API_KEY=ul_your_api_key_here npx -y ultralytics-mcp@latest
 ```
 
 If command exits immediately with config error, fix environment first.

package/TOOLS.md

@@ -16,6 +16,8 @@ Auto-generated reference for Ultralytics Platform MCP tools.
 - `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.
+- Review local upload paths before approving tool calls; upload tools read from the MCP client host.
+- Review `model_download.output_path` and `overwrite` before approving downloads.
 
 ## Cost and Safety
 

package/dist/tools/downloads.js

@@ -1,9 +1,9 @@
 /** 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 { lstat, rename, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { resolveModel } from "../resolve.js";
 import { asRecord } from "./shared.js";
 function fileName(info) {
@@ -59,6 +59,31 @@ async function statSafe(target) {
         return { exists: false, isDir: false };
     }
 }
+async function lstatSafe(target) {
+    try {
+        const info = await lstat(target);
+        return {
+            exists: true,
+            isDir: info.isDirectory(),
+            isSymlink: info.isSymbolicLink(),
+        };
+    }
+    catch {
+        return { exists: false, isDir: false, isSymlink: false };
+    }
+}
+async function writeFileAtomic(target, content) {
+    const parent = dirname(target);
+    const temporary = join(parent, `.${basename(target)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+        await writeFile(temporary, content, { flag: "wx" });
+        await rename(temporary, target);
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
 async function downloadTarget(outputPath, overwrite) {
     if (!outputPath?.trim()) {
         throw new Error("`output_path` is required.");
@@ -72,10 +97,13 @@ async function downloadTarget(outputPath, overwrite) {
     if (!parentInfo.isDir) {
         throw new Error(`Output parent is not a directory: ${parent}`);
     }
-    const targetInfo = await statSafe(target);
+    const targetInfo = await lstatSafe(target);
     if (targetInfo.exists && targetInfo.isDir) {
         throw new Error(`Output path is a directory: ${target}`);
     }
+    if (targetInfo.exists && targetInfo.isSymlink) {
+        throw new Error(`Output path is a symbolic link: ${target}`);
+    }
     if (targetInfo.exists && !overwrite) {
         throw new Error(`Output path exists: ${target}. Pass overwrite=true to replace it.`);
     }
@@ -94,7 +122,7 @@ export async function modelDownload(client, model, options) {
         throw new Error(`Model file '${selectedName}' did not include a download URL.`);
     }
     const content = await client.downloadBytes(signedUrl);
-    await writeFile(target, content);
+    await writeFileAtomic(target, content);
     return {
         summary: `Downloaded ${selectedName} to ${target} (${content.length} bytes).`,
         data: {

package/dist/tools/index.js

@@ -1,9 +1,9 @@
 /** 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.
+ * the parity fixture runner. Registration helpers wire tools 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";
@@ -72,7 +72,7 @@ export const TOOL_DEFINITIONS = [
     }),
     tool({
         name: "projects_create",
-        registrationGroup: "read",
+        registrationGroup: "write",
         stateChanging: true,
         description: "Create a project in your Ultralytics workspace.",
         inputSchema: {
@@ -93,7 +93,7 @@ export const TOOL_DEFINITIONS = [
     }),
     tool({
         name: "projects_delete",
-        registrationGroup: "read",
+        registrationGroup: "write",
         stateChanging: true,
         description: "Soft-delete a project by id, slug, username/slug, or project ul:// URI.",
         inputSchema: {
@@ -155,7 +155,7 @@ export const TOOL_DEFINITIONS = [
     }),
     tool({
         name: "datasets_create",
-        registrationGroup: "read",
+        registrationGroup: "write",
         stateChanging: true,
         description: "Create a dataset in your Ultralytics workspace.",
         inputSchema: {
@@ -230,7 +230,7 @@ export const TOOL_DEFINITIONS = [
     }),
     tool({
         name: "dataset_version_create",
-        registrationGroup: "read",
+        registrationGroup: "write",
         stateChanging: true,
         description: "Create a frozen dataset version snapshot.",
         inputSchema: {
@@ -251,7 +251,7 @@ export const TOOL_DEFINITIONS = [
     }),
     tool({
         name: "datasets_delete",
-        registrationGroup: "read",
+        registrationGroup: "write",
         stateChanging: true,
         description: "Soft-delete a dataset by id, slug, username/slug, or dataset ul:// URI.",
         inputSchema: {
@@ -268,7 +268,7 @@ export const TOOL_DEFINITIONS = [
     }),
     tool({
         name: "dataset_ingest",
-        registrationGroup: "read",
+        registrationGroup: "write",
         stateChanging: true,
         description: "Start a remote URL ingest job for an existing dataset.",
         inputSchema: {
@@ -292,7 +292,7 @@ export const TOOL_DEFINITIONS = [
     }),
     tool({
         name: "dataset_upload_file",
-        registrationGroup: "read",
+        registrationGroup: "write",
         stateChanging: true,
         description: "Upload a local dataset archive file and start ingest for an existing dataset.",
         inputSchema: {
@@ -326,7 +326,7 @@ export const TOOL_DEFINITIONS = [
     }),
     tool({
         name: "dataset_upload_folder",
-        registrationGroup: "read",
+        registrationGroup: "write",
         stateChanging: true,
         description: "Upload a local image folder as a zip and start ingest for an existing dataset.",
         inputSchema: {
@@ -360,7 +360,7 @@ export const TOOL_DEFINITIONS = [
     }),
     tool({
         name: "dataset_upload_video",
-        registrationGroup: "read",
+        registrationGroup: "write",
         stateChanging: true,
         description: "Upload a local video by extracting JPEG frames with ffmpeg, then start dataset ingest for an existing dataset.",
         inputSchema: {
@@ -443,7 +443,7 @@ export const TOOL_DEFINITIONS = [
     }),
     tool({
         name: "training_monitor",
-        registrationGroup: "action",
+        registrationGroup: "read",
         stateChanging: false,
         description: "Report a model's training status and progress (works for private and public projects).",
         inputSchema: {
@@ -468,7 +468,7 @@ export const TOOL_DEFINITIONS = [
     }),
     tool({
         name: "model_predict",
-        registrationGroup: "action",
+        registrationGroup: "read",
         stateChanging: false,
         description: "Run inference with a trained model on an image URL or base64 source (no local file paths).",
         inputSchema: {
@@ -554,7 +554,7 @@ export const TOOL_DEFINITIONS = [
     }),
     tool({
         name: "exports_list",
-        registrationGroup: "write",
+        registrationGroup: "read",
         stateChanging: false,
         description: "List export jobs for a model.",
         inputSchema: {
@@ -568,7 +568,7 @@ export const TOOL_DEFINITIONS = [
     }),
     tool({
         name: "export_status",
-        registrationGroup: "write",
+        registrationGroup: "read",
         stateChanging: false,
         description: "Get status for one export job by 24-character export id.",
         inputSchema: {
@@ -720,11 +720,11 @@ function registerToolDefinitions(server, getClient, registrationGroup) {
 export function registerReadTools(server, getClient) {
     registerToolDefinitions(server, getClient, "read");
 }
-/** Register training monitor, predict, and download tools. */
+/** Register local action tools. */
 export function registerActionTools(server, getClient) {
     registerToolDefinitions(server, getClient, "action");
 }
-/** Register export and training-start tools. The cost-incurring ones are guarded. */
+/** Register remote mutation tools. The cost-incurring ones are guarded. */
 export function registerWriteTools(server, getClient) {
     registerToolDefinitions(server, getClient, "write");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultralytics-mcp",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "MCP for Ultralytics Platform workflows, datasets, training, prediction, and model operations.",
   "type": "module",
   "bin": {
@@ -37,10 +37,16 @@
     "test": "vitest run"
   },
   "keywords": [
-    "mcp",
     "ultralytics",
     "yolo",
-    "model-context-protocol"
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "codex",
+    "computer-vision",
+    "object-detection",
+    "model-training",
+    "inference"
   ],
   "author": "Aman Harsh",
   "license": "MIT",