@avclabs.ai/media-mcp 0.1.1 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +229 -147
- package/README_CN.md +419 -0
- package/dist/sam3.js +39 -26
- package/dist/sam3.js.map +1 -1
- package/dist/server.d.ts +1 -1
- package/dist/server.js +7 -7
- package/dist/server.js.map +1 -1
- package/dist/video-enhancement.d.ts.map +1 -1
- package/dist/video-enhancement.js +44 -33
- package/dist/video-enhancement.js.map +1 -1
- package/package.json +2 -2
- package/README_EN.md +0 -336
|
@@ -5,19 +5,19 @@ import { z } from 'zod';
|
|
|
5
5
|
import FormData from 'form-data';
|
|
6
6
|
// Schemas
|
|
7
7
|
const CreateTaskSchema = z.object({
|
|
8
|
-
video_source: z.string().describe('
|
|
9
|
-
type: z.enum(['url', 'local']).default('url').describe('
|
|
10
|
-
resolution: z.enum(['480p', '540p', '720p', '1080p', '2k']).default('720p').describe('
|
|
8
|
+
video_source: z.string().describe('Video URL or local file path (URL must be publicly accessible, login or signed links are not supported)'),
|
|
9
|
+
type: z.enum(['url', 'local']).default('url').describe('Upload type: url=remote video, local=local file'),
|
|
10
|
+
resolution: z.enum(['480p', '540p', '720p', '1080p', '2k']).default('720p').describe('Target resolution, default 720p'),
|
|
11
11
|
});
|
|
12
12
|
const GetTaskStatusSchema = z.object({
|
|
13
|
-
task_id: z.string().describe('
|
|
13
|
+
task_id: z.string().describe('Task ID'),
|
|
14
14
|
});
|
|
15
15
|
const EnhanceVideoSyncSchema = z.object({
|
|
16
|
-
video_source: z.string().describe('
|
|
17
|
-
type: z.enum(['url', 'local']).default('url').describe('
|
|
18
|
-
resolution: z.enum(['480p', '540p', '720p', '1080p', '2k']).default('720p').describe('
|
|
19
|
-
poll_interval: z.number().default(5).describe('
|
|
20
|
-
timeout: z.number().default(
|
|
16
|
+
video_source: z.string().describe('Video URL or local file path (URL must be publicly accessible, login or signed links are not supported)'),
|
|
17
|
+
type: z.enum(['url', 'local']).default('url').describe('Upload type: url=remote video, local=local file'),
|
|
18
|
+
resolution: z.enum(['480p', '540p', '720p', '1080p', '2k']).default('720p').describe('Target resolution, default 720p'),
|
|
19
|
+
poll_interval: z.number().default(5).describe('Polling interval in seconds, default 5'),
|
|
20
|
+
timeout: z.number().default(50).describe('Synchronous wait timeout in seconds, default 50. Returns task_id early when exceeded, use get_task_status to continue polling'),
|
|
21
21
|
});
|
|
22
22
|
export function setupVideoEnhancementTools(server, baseUrl, apiKey) {
|
|
23
23
|
const client = axios.create({
|
|
@@ -29,16 +29,18 @@ export function setupVideoEnhancementTools(server, baseUrl, apiKey) {
|
|
|
29
29
|
timeout: 60000,
|
|
30
30
|
});
|
|
31
31
|
// create_task tool
|
|
32
|
-
server.tool('create_task',
|
|
32
|
+
server.tool('create_task', `Create a video enhancement task (asynchronous).
|
|
33
33
|
|
|
34
|
-
|
|
35
|
-
1. URL
|
|
36
|
-
2.
|
|
34
|
+
Two upload methods are supported:
|
|
35
|
+
1. URL upload: provide a video URL
|
|
36
|
+
2. Local upload: provide a local file path, the MCP Server will auto-upload to TOS object storage
|
|
37
37
|
|
|
38
|
-
|
|
39
|
-
- video_source:
|
|
40
|
-
- type: "url"
|
|
41
|
-
- resolution:
|
|
38
|
+
Parameters:
|
|
39
|
+
- video_source: video URL or local file path
|
|
40
|
+
- type: "url" or "local"
|
|
41
|
+
- resolution: target resolution
|
|
42
|
+
|
|
43
|
+
After creating a task, a task_id is returned immediately. Use get_task_status to poll for results until status becomes "completed" or "failed".`, CreateTaskSchema.shape, async (args) => {
|
|
42
44
|
try {
|
|
43
45
|
const result = await createTask(client, args.video_source, args.type, args.resolution);
|
|
44
46
|
return {
|
|
@@ -53,7 +55,7 @@ export function setupVideoEnhancementTools(server, baseUrl, apiKey) {
|
|
|
53
55
|
}
|
|
54
56
|
});
|
|
55
57
|
// get_task_status tool
|
|
56
|
-
server.tool('get_task_status', '
|
|
58
|
+
server.tool('get_task_status', 'Query video enhancement task status. The status field can be: processing, completed, or failed. If status is processing, wait a few seconds and call this tool again to poll.', GetTaskStatusSchema.shape, async (args) => {
|
|
57
59
|
try {
|
|
58
60
|
const result = await getTaskStatus(client, args.task_id);
|
|
59
61
|
return {
|
|
@@ -68,18 +70,20 @@ export function setupVideoEnhancementTools(server, baseUrl, apiKey) {
|
|
|
68
70
|
}
|
|
69
71
|
});
|
|
70
72
|
// enhance_video_sync tool
|
|
71
|
-
server.tool('enhance_video_sync',
|
|
73
|
+
server.tool('enhance_video_sync', `Synchronously enhance video (blocks until completion).
|
|
74
|
+
|
|
75
|
+
Two upload methods are supported:
|
|
76
|
+
1. URL upload: provide a video URL
|
|
77
|
+
2. Local upload: provide a local file path, the MCP Server will auto-upload to TOS object storage
|
|
72
78
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
79
|
+
Parameters:
|
|
80
|
+
- video_source: video URL or local file path
|
|
81
|
+
- type: "url" or "local"
|
|
82
|
+
- resolution: target resolution
|
|
83
|
+
- poll_interval: polling interval in seconds
|
|
84
|
+
- timeout: synchronous wait timeout in seconds, default 50
|
|
76
85
|
|
|
77
|
-
|
|
78
|
-
- video_source: 视频 URL 或本地文件路径
|
|
79
|
-
- type: "url" 或 "local"
|
|
80
|
-
- resolution: 目标分辨率
|
|
81
|
-
- poll_interval: 轮询间隔（秒）
|
|
82
|
-
- timeout: 超时时间（秒）`, EnhanceVideoSyncSchema.shape, async (args) => {
|
|
86
|
+
Best for short videos (estimated processing time < 1 minute). If the task is not completed within 50 seconds, the tool returns early with a task_id. Use get_task_status to continue polling.`, EnhanceVideoSyncSchema.shape, async (args) => {
|
|
83
87
|
try {
|
|
84
88
|
const result = await enhanceVideoSync(client, args.video_source, args.type, args.resolution, args.poll_interval, args.timeout);
|
|
85
89
|
return {
|
|
@@ -96,12 +100,12 @@ export function setupVideoEnhancementTools(server, baseUrl, apiKey) {
|
|
|
96
100
|
}
|
|
97
101
|
function checkLocalFile(filePath) {
|
|
98
102
|
if (!fs.existsSync(filePath)) {
|
|
99
|
-
throw new Error(
|
|
103
|
+
throw new Error(`File does not exist: ${filePath}`);
|
|
100
104
|
}
|
|
101
105
|
const stats = fs.statSync(filePath);
|
|
102
106
|
const maxSize = 100 * 1024 * 1024;
|
|
103
107
|
if (stats.size > maxSize) {
|
|
104
|
-
throw new Error('
|
|
108
|
+
throw new Error('File size exceeds 100MB limit');
|
|
105
109
|
}
|
|
106
110
|
return { filePath, fileName: path.basename(filePath) };
|
|
107
111
|
}
|
|
@@ -112,7 +116,7 @@ async function getTosSignature(client, fileName) {
|
|
|
112
116
|
});
|
|
113
117
|
const data = response.data;
|
|
114
118
|
if (data.code !== 0 && data.code !== 200) {
|
|
115
|
-
throw new Error(data.message || '
|
|
119
|
+
throw new Error(data.message || 'Failed to get TOS signature');
|
|
116
120
|
}
|
|
117
121
|
return data.data;
|
|
118
122
|
}
|
|
@@ -149,7 +153,7 @@ async function uploadToTos(filePath, signatureData) {
|
|
|
149
153
|
fileName,
|
|
150
154
|
fileSize: fs.statSync(filePath).size,
|
|
151
155
|
}, null, 2);
|
|
152
|
-
throw new Error(`TOS
|
|
156
|
+
throw new Error(`TOS upload failed: ${response.status} ${response.statusText}\nDebug info: ${debugInfo}`);
|
|
153
157
|
}
|
|
154
158
|
}
|
|
155
159
|
function parseFileIdFromUrl(url) {
|
|
@@ -195,6 +199,7 @@ async function getTaskStatus(client, taskId) {
|
|
|
195
199
|
error_message: result.error_message,
|
|
196
200
|
created_at: result.created_at,
|
|
197
201
|
updated_at: result.updated_at,
|
|
202
|
+
message: result.status === 'processing' ? 'Task is still processing, please check again later' : undefined,
|
|
198
203
|
};
|
|
199
204
|
}
|
|
200
205
|
async function enhanceVideoSync(client, videoSource, sourceType, resolution, pollInterval, timeout) {
|
|
@@ -214,7 +219,13 @@ async function enhanceVideoSync(client, videoSource, sourceType, resolution, pol
|
|
|
214
219
|
}
|
|
215
220
|
const elapsed = (Date.now() - startTime) / 1000;
|
|
216
221
|
if (elapsed >= timeout) {
|
|
217
|
-
return {
|
|
222
|
+
return {
|
|
223
|
+
success: true,
|
|
224
|
+
status: 'processing',
|
|
225
|
+
task_id: taskId,
|
|
226
|
+
message: `Task is still processing (waited ${timeout} seconds). Please use get_task_status to continue polling.`,
|
|
227
|
+
note: 'The synchronous wait for this long-running task has been truncated. Switch to get_task_status polling.',
|
|
228
|
+
};
|
|
218
229
|
}
|
|
219
230
|
await sleep(pollInterval * 1000);
|
|
220
231
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"video-enhancement.js","sourceRoot":"","sources":["../src/video-enhancement.ts"],"names":[],"mappings":"AACA,OAAO,KAAwB,MAAM,OAAO,CAAC;AAC7C,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,QAAQ,MAAM,WAAW,CAAC;AAEjC,UAAU;AACV,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,
|
|
1
|
+
{"version":3,"file":"video-enhancement.js","sourceRoot":"","sources":["../src/video-enhancement.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"type": "module",
|
|
3
3
|
"name": "@avclabs.ai/media-mcp",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.2.1",
|
|
5
5
|
"description": "MCP Server for video enhancement and image segmentation (SAM3)",
|
|
6
6
|
"mcpName": "io.github.avclabs/media-mcp",
|
|
7
7
|
"main": "dist/server.js",
|
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
"config.json",
|
|
15
15
|
"LICENSE",
|
|
16
16
|
"README.md",
|
|
17
|
-
"
|
|
17
|
+
"README_CN.md"
|
|
18
18
|
],
|
|
19
19
|
"scripts": {
|
|
20
20
|
"build": "tsc",
|
package/README_EN.md
DELETED
|
@@ -1,336 +0,0 @@
|
|
|
1
|
-
# media-mcp (Node.js)
|
|
2
|
-
|
|
3
|
-
[中文](https://github.com/avclabs/media-mcp/blob/main/README.md) | English
|
|
4
|
-
|
|
5
|
-
[](https://www.npmjs.com/package/@avclabs.ai/media-mcp)
|
|
6
|
-
[](https://nodejs.org/)
|
|
7
|
-
[](https://opensource.org/licenses/MIT)
|
|
8
|
-
|
|
9
|
-
A video enhancement and image segmentation service based on the MCP protocol, acting as an MCP Client-Server to interact with backend HTTP Servers.
|
|
10
|
-
|
|
11
|
-
## Features
|
|
12
|
-
|
|
13
|
-
Provides the following MCP Tools:
|
|
14
|
-
- `create_task` - Create a video enhancement task (supports URL or local file upload)
|
|
15
|
-
- `get_task_status` - Query task status
|
|
16
|
-
- `enhance_video_sync` - Synchronously enhance video (blocking wait)
|
|
17
|
-
- `sam3_predict` - SAM3 image segmentation (supports local path, URL, or Base64 image)
|
|
18
|
-
|
|
19
|
-
## Prerequisites
|
|
20
|
-
|
|
21
|
-
- **Node.js >= 18** (check: `node --version`)
|
|
22
|
-
- **API Key** (required for authentication)
|
|
23
|
-
|
|
24
|
-
## Lazy Install (Recommended)
|
|
25
|
-
|
|
26
|
-
If your AI Agent has a known MCP config path, just copy the line below and send it to your AI:
|
|
27
|
-
|
|
28
|
-
```
|
|
29
|
-
Install the npm package @avclabs.ai/media-mcp as an MCP server. My API Key is: sk-xxxxxxxx.
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
The AI will automatically:
|
|
33
|
-
1. Detect your MCP client
|
|
34
|
-
2. Find the config file path
|
|
35
|
-
3. Write the correct configuration
|
|
36
|
-
4. Prompt you to restart the client
|
|
37
|
-
|
|
38
|
-
## Manual Install
|
|
39
|
-
|
|
40
|
-
No installation needed. Use `npx` directly in your MCP client config.
|
|
41
|
-
|
|
42
|
-
### 1. Claude Code (CLI)
|
|
43
|
-
|
|
44
|
-
Run in Claude Code:
|
|
45
|
-
|
|
46
|
-
```
|
|
47
|
-
/mcp
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
Check the output for the **"User MCPs"** section to find the config file path, then edit that file.
|
|
51
|
-
|
|
52
|
-
Common paths (if `/mcp` is unavailable):
|
|
53
|
-
- **Windows**: `%USERPROFILE%\.claude.json`
|
|
54
|
-
- **macOS**: `~/.claude.json`
|
|
55
|
-
- **Linux**: `~/.claude.json`
|
|
56
|
-
- **Legacy/Alternative**: `~/.claude/mcp.json`
|
|
57
|
-
|
|
58
|
-
Paste this (replace `your-api-key`):
|
|
59
|
-
|
|
60
|
-
```json
|
|
61
|
-
{
|
|
62
|
-
"mcpServers": {
|
|
63
|
-
"video-enhancement": {
|
|
64
|
-
"command": "npx",
|
|
65
|
-
"args": ["-y", "@avclabs.ai/media-mcp@latest"],
|
|
66
|
-
"env": {
|
|
67
|
-
"API_KEY": "your-api-key"
|
|
68
|
-
}
|
|
69
|
-
}
|
|
70
|
-
}
|
|
71
|
-
}
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
Save and run `/mcp` to verify it's loaded.
|
|
75
|
-
|
|
76
|
-
### 2. Cursor
|
|
77
|
-
|
|
78
|
-
Go to **Settings > Tools & MCPs > Add New MCP Server**:
|
|
79
|
-
|
|
80
|
-
- **Name**: `video-enhancement`
|
|
81
|
-
- **Type**: `command`
|
|
82
|
-
- **Command**:
|
|
83
|
-
```bash
|
|
84
|
-
env HTTP_API_KEY=your-api-key npx -y @avclabs.ai/media-mcp@latest
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
Or edit `~/.cursor/mcp.json`:
|
|
88
|
-
|
|
89
|
-
```json
|
|
90
|
-
{
|
|
91
|
-
"mcpServers": {
|
|
92
|
-
"video-enhancement": {
|
|
93
|
-
"command": "npx",
|
|
94
|
-
"args": ["-y", "@avclabs.ai/media-mcp@latest"],
|
|
95
|
-
"env": {
|
|
96
|
-
"API_KEY": "your-api-key"
|
|
97
|
-
}
|
|
98
|
-
}
|
|
99
|
-
}
|
|
100
|
-
}
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
## Verify Installation
|
|
104
|
-
|
|
105
|
-
After restarting your client, check if the tools are available:
|
|
106
|
-
|
|
107
|
-
1. Or ask: "What tools do you have available?"
|
|
108
|
-
2. You should see: `create_task`, `get_task_status`, `enhance_video_sync`, `sam3_predict`
|
|
109
|
-
|
|
110
|
-
## Configuration Options
|
|
111
|
-
|
|
112
|
-
| Variable | Required | Default | Description |
|
|
113
|
-
|---|---|---|---|
|
|
114
|
-
| `API_KEY` | **Yes** | - | API authentication key (shared by video enhancement and SAM3) |
|
|
115
|
-
| `HTTP_API_BASE_URL` | No | `https://mcp.avc.ai/enhance` | Video enhancement service endpoint |
|
|
116
|
-
| `SAM3_API_BASE_URL` | No | `https://mcp.avc.ai/sam` | SAM3 service endpoint |
|
|
117
|
-
| `SAM3_POLL_INTERVAL` | No | `2000` | Polling interval (milliseconds) |
|
|
118
|
-
| `SAM3_POLL_MAX_ATTEMPTS` | No | `60` | Maximum polling attempts |
|
|
119
|
-
|
|
120
|
-
### Custom Endpoint
|
|
121
|
-
|
|
122
|
-
```json
|
|
123
|
-
{
|
|
124
|
-
"env": {
|
|
125
|
-
"HTTP_API_BASE_URL": "https://your-endpoint.com",
|
|
126
|
-
"HTTP_API_KEY": "your-api-key"
|
|
127
|
-
}
|
|
128
|
-
}
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
Or via CLI args:
|
|
132
|
-
```bash
|
|
133
|
-
npx -y @avclabs.ai/media-mcp@latest --base-url https://your-endpoint.com --api-key your-api-key --sam3-base-url http://localhost:8001 --sam3-api-key your-sam3-key
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
## Usage Examples
|
|
137
|
-
|
|
138
|
-
Once configured, ask your AI agent naturally:
|
|
139
|
-
|
|
140
|
-
> "Enhance this video to 1080p: https://example.com/video.mp4"
|
|
141
|
-
|
|
142
|
-
> "Improve the quality of /Users/me/Desktop/video.mp4 to 2k"
|
|
143
|
-
|
|
144
|
-
The agent will automatically call the appropriate tools.
|
|
145
|
-
|
|
146
|
-
> "Analyze this image and find all objects: C:\Users\xxx\photo.png"
|
|
147
|
-
>
|
|
148
|
-
> "Use SAM3 to segment this image, prompt: 'find all cars'"
|
|
149
|
-
|
|
150
|
-
## Provided Tools
|
|
151
|
-
|
|
152
|
-
### create_task
|
|
153
|
-
|
|
154
|
-
Create an asynchronous video enhancement task.
|
|
155
|
-
|
|
156
|
-
> **Recommended for most use cases.** Ideal for longer videos (over 10 seconds) to avoid blocking the connection for an extended period.
|
|
157
|
-
|
|
158
|
-
| Parameter | Type | Required | Default | Description |
|
|
159
|
-
|---|---|---|---|---|
|
|
160
|
-
| `video_source` | string | Yes | - | Video URL or local file path (URL must be publicly accessible, links requiring login or signatures are not supported) |
|
|
161
|
-
| `type` | string | No | `url` | `url` or `local` |
|
|
162
|
-
| `resolution` | string | No | `720p` | `480p`, `540p`, `720p`, `1080p`, `2k` |
|
|
163
|
-
|
|
164
|
-
**Returns:**
|
|
165
|
-
```json
|
|
166
|
-
{
|
|
167
|
-
"success": true,
|
|
168
|
-
"task_id": "xxx",
|
|
169
|
-
"status": "wait"
|
|
170
|
-
}
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
### get_task_status
|
|
174
|
-
|
|
175
|
-
Query task status.
|
|
176
|
-
|
|
177
|
-
| Parameter | Type | Required |
|
|
178
|
-
|---|---|---|
|
|
179
|
-
| `task_id` | string | Yes |
|
|
180
|
-
|
|
181
|
-
**Returns:**
|
|
182
|
-
```json
|
|
183
|
-
{
|
|
184
|
-
"success": true,
|
|
185
|
-
"task_id": "xxx",
|
|
186
|
-
"status": "completed",
|
|
187
|
-
"progress": 100,
|
|
188
|
-
"video_url": "https://..."
|
|
189
|
-
}
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
### enhance_video_sync
|
|
193
|
-
|
|
194
|
-
Synchronously enhance video (blocks until completion).
|
|
195
|
-
|
|
196
|
-
> **Best for short videos (under 10 seconds).** Long videos may cause timeouts or keep the client connection occupied.
|
|
197
|
-
|
|
198
|
-
| Parameter | Type | Required | Default | Description |
|
|
199
|
-
|---|---|---|---|---|
|
|
200
|
-
| `video_source` | string | Yes | - | Video URL or local file path (URL must be publicly accessible, links requiring login or signatures are not supported) |
|
|
201
|
-
| `type` | string | No | `url` | `url` or `local` |
|
|
202
|
-
| `resolution` | string | No | `720p` | Target resolution |
|
|
203
|
-
| `poll_interval` | number | No | `5` | Poll interval (seconds) |
|
|
204
|
-
| `timeout` | number | No | `600` | Timeout (seconds) |
|
|
205
|
-
|
|
206
|
-
### sam3_predict
|
|
207
|
-
|
|
208
|
-
Analyze an image using the SAM3 segmentation API to generate inference results (masks, boxes, scores).
|
|
209
|
-
|
|
210
|
-
**Parameters:**
|
|
211
|
-
|
|
212
|
-
Image input (choose one, must provide exactly one):
|
|
213
|
-
|
|
214
|
-
- `imagePath` (string): Absolute path of a local image file. Supports common formats (PNG, JPG, JPEG, BMP, WebP).
|
|
215
|
-
- Example: `"C:\\Users\\xxx\\photo.png"`, `"/home/user/images/cat.jpg"`
|
|
216
|
-
- Use when: The user explicitly provides a local file path
|
|
217
|
-
|
|
218
|
-
- `imageUrl` (string): Publicly accessible URL of the image.
|
|
219
|
-
- Example: `"https://example.com/photo.jpg"`
|
|
220
|
-
- Use when: The image is already online and the user provides a link
|
|
221
|
-
- Note: The URL must be publicly accessible. Links requiring login or signatures are not supported
|
|
222
|
-
|
|
223
|
-
- `imageBase64` (string): Base64-encoded image data.
|
|
224
|
-
- Example: `"iVBORw0KGgoAAAANSUhEUgAA..."`
|
|
225
|
-
- Use when: The user drags or uploads an image attachment, and the Agent encodes it as base64
|
|
226
|
-
- Note: Large images will produce very large base64 strings, which may slow transmission
|
|
227
|
-
|
|
228
|
-
Other parameters:
|
|
229
|
-
|
|
230
|
-
- `prompt` (string, required): English text prompt specifying the target object to segment. Examples: `"person"`, `"car"`, `"a cat sitting on a sofa"`. Since the SAM3 model only accepts English prompts, provide an English description. If the user provides Chinese or other non-English text, the Agent will automatically translate it before calling the tool.
|
|
231
|
-
|
|
232
|
-
**Returns:**
|
|
233
|
-
|
|
234
|
-
After inference completes, returns a JSON string containing three fields:
|
|
235
|
-
|
|
236
|
-
- **`masks`**: 2D array. Each element is a binary mask (values 0 or 1) with the same dimensions as the input image, marking the pixel-level location of detected objects. The i-th mask corresponds to the i-th detected object instance.
|
|
237
|
-
- **`boxes`**: 2D array. Each element is a bounding box in `[x1, y1, x2, y2]` format, representing the rectangular region of the detected object. `x1`, `y1` are the top-left coordinates; `x2`, `y2` are the bottom-right coordinates.
|
|
238
|
-
|
|
239
|
-
Coordinate system: The top-left corner of the image is the origin `(0, 0)`. The x-axis increases to the right, and the y-axis increases downward, in pixels. For example, `[120, 80, 300, 450]` means the region starts 120px from the left edge and 80px from the top edge, extending to 300px from the left and 450px from the top. Width = `x2 - x1 = 180px`, Height = `y2 - y1 = 370px`.
|
|
240
|
-
- **`scores`**: 1D array. Each element is a confidence score for the corresponding detection result, ranging from 0 to 1. Higher scores indicate greater model confidence.
|
|
241
|
-
|
|
242
|
-
Example result JSON:
|
|
243
|
-
|
|
244
|
-
```json
|
|
245
|
-
{
|
|
246
|
-
"masks": [
|
|
247
|
-
[[0, 0, 1, ...], [0, 1, 1, ...], ...],
|
|
248
|
-
[[0, 0, 0, ...], [0, 0, 1, ...], ...]
|
|
249
|
-
],
|
|
250
|
-
"boxes": [
|
|
251
|
-
[120, 80, 300, 450],
|
|
252
|
-
[400, 200, 600, 500]
|
|
253
|
-
],
|
|
254
|
-
"scores": [0.95, 0.87]
|
|
255
|
-
}
|
|
256
|
-
```
|
|
257
|
-
|
|
258
|
-
## FAQ
|
|
259
|
-
|
|
260
|
-
### Drag-and-drop attachment says file not found?
|
|
261
|
-
|
|
262
|
-
This is a known limitation of stdio MCP. When dragging or uploading an attachment through the Agent interface, the file path is usually not automatically passed to the MCP Server.
|
|
263
|
-
|
|
264
|
-
**Solutions:**
|
|
265
|
-
|
|
266
|
-
1. **Provide the path simultaneously** (recommended): After dragging the image,补充 the local absolute path in your message:
|
|
267
|
-
> "Please analyze this image `D:\\photos\\cat.jpg` and find the cat"
|
|
268
|
-
|
|
269
|
-
2. **Wait for auto-encoding**: Claude may automatically encode the image as base64. If successful, no extra action is needed.
|
|
270
|
-
|
|
271
|
-
3. **Reply to path inquiry**: If Claude asks for the image path, simply reply with the local absolute path.
|
|
272
|
-
|
|
273
|
-
### Is there a priority among the three input methods?
|
|
274
|
-
|
|
275
|
-
There is no strict priority. Claude will automatically choose the most appropriate method based on conversation context:
|
|
276
|
-
|
|
277
|
-
- You provided a local path → uses `imagePath`
|
|
278
|
-
- You provided a web link → uses `imageUrl`
|
|
279
|
-
- You dragged an attachment without a path → tries `imageBase64`
|
|
280
|
-
|
|
281
|
-
### What image formats are supported?
|
|
282
|
-
|
|
283
|
-
Common formats: PNG, JPG, JPEG, BMP, WebP, etc. PNG or JPG is recommended.
|
|
284
|
-
|
|
285
|
-
### What if URL image download fails?
|
|
286
|
-
|
|
287
|
-
Ensure the URL is **publicly accessible**, requiring no login, cookies, or signatures. If the image is on a service requiring authentication (e.g., private S3 Bucket, login-required image host), download it locally first and use `imagePath`.
|
|
288
|
-
|
|
289
|
-
### What if the base64 image is too large?
|
|
290
|
-
|
|
291
|
-
If the image is very large (e.g., 4K resolution), the base64-encoded data will be very large and may slow transmission. Suggestions:
|
|
292
|
-
|
|
293
|
-
1. Use `imagePath` instead
|
|
294
|
-
2. Or compress the image before encoding
|
|
295
|
-
|
|
296
|
-
## File Upload Notes
|
|
297
|
-
|
|
298
|
-
When `type` is `"local"`:
|
|
299
|
-
1. File is read locally by the MCP Server
|
|
300
|
-
2. Uploaded directly to TOS object storage via pre-signed URL
|
|
301
|
-
3. **Max file size: 100MB**
|
|
302
|
-
|
|
303
|
-
## Troubleshooting
|
|
304
|
-
|
|
305
|
-
### "command not found: npx"
|
|
306
|
-
|
|
307
|
-
Install Node.js >= 18: https://nodejs.org/
|
|
308
|
-
|
|
309
|
-
### "Error:需要提供 --api-key 或设置 HTTP_API_KEY"
|
|
310
|
-
|
|
311
|
-
Your API Key is missing. Double-check the `env.HTTP_API_KEY` in your config.
|
|
312
|
-
|
|
313
|
-
### MCP Server shows red/error in client
|
|
314
|
-
|
|
315
|
-
Check logs:
|
|
316
|
-
- **Claude Desktop macOS**: `~/Library/Logs/Claude/mcp*.log`
|
|
317
|
-
- **Claude Desktop Windows**: `%APPDATA%\Claude\logs\mcp*.log`
|
|
318
|
-
- **Cursor**: Output panel > MCP
|
|
319
|
-
|
|
320
|
-
### "TOS 上传失败"
|
|
321
|
-
|
|
322
|
-
Usually a signature mismatch. Ensure your `HTTP_API_BASE_URL` and `HTTP_API_KEY` are correct and active.
|
|
323
|
-
|
|
324
|
-
## Global Install (Alternative)
|
|
325
|
-
|
|
326
|
-
If you prefer not using `npx` every time:
|
|
327
|
-
|
|
328
|
-
```bash
|
|
329
|
-
npm install -g @avclabs.ai/media-mcp
|
|
330
|
-
```
|
|
331
|
-
|
|
332
|
-
Then use `"command": "media-mcp"` with `"args": ["--api-key", "your-api-key"]` in your config.
|
|
333
|
-
|
|
334
|
-
## License
|
|
335
|
-
|
|
336
|
-
MIT License - See [LICENSE](LICENSE) file for details
|