SAM3 MCP Server

基于 JavaScript + stdio 的 MCP 服务，封装了 SAM3 图片推理接口。

功能

对外暴露一个 MCP Tool：sam3_predict，支持三种图片输入方式，内部自动完成：

1. 请求 get_postsignature_url 获取 TOS 临时上传凭证
2. 上传图片到 TOS
3. 调用 predict 接口创建异步任务，获取 task_id
4. 轮询 GET /predict/result/{task_id} 查询任务状态
5. 任务完成后，下载 JSON 推理结果并直接返回内容

支持的图片输入方式

| 方式 | 参数 | 适用场景 | |------|------|---------| | 本地文件路径 | imagePath | 用户提供了本地图片的绝对路径，如 C:\Users\xxx\photo.png | | 网络图片链接 | imageUrl | 用户提供了公开可访问的图片 URL，如 https://example.com/photo.jpg | | Base64 编码 | imageBase64 | 用户拖拽或上传了图片附件，没有本地路径可用时 |

三种方式只需提供一种即可。推荐使用 imagePath（最稳定）；当用户拖拽附件时，Agent 会尝试使用 imageBase64 自动传递图片内容。

前置要求

• Node.js >= 18（检查：node --version）
• API Key（用于身份认证，请联系服务提供方获取）

懒人安装（推荐）

如果你使用的 AI Agent 有确定的 MCP 配置路径，直接复制下面这句发给 AI：

帮我安装 npm 包 sam3-mcp-server 作为 MCP server。我的 API Key 是：your_api_key_here。

AI 会自动完成：

1. 检测你使用的 MCP 客户端
2. 找到配置文件路径
3. 写入正确的配置
4. 提示你重启客户端

手动安装

无需安装，直接在 MCP 客户端配置中使用 npx 运行。

1. Claude Code（CLI）

在 Claude Code 中运行：

/mcp

查看输出中 "User MCPs" 对应的配置文件路径，然后编辑该文件。

常见路径（如果 /mcp 不可用）：

• Windows: %USERPROFILE%\.claude.json
• macOS: ~/.claude.json
• Linux: ~/.claude.json
• 旧版/备用: ~/.claude/mcp.json

粘贴以下内容（将 your_api_key_here 替换为实际 API Key）：

{
  "mcpServers": {
    "sam3": {
      "command": "npx",
      "args": ["-y", "sam3-mcp-server"],
      "env": {
        "API_BASE_URL": "https://sam.luluhero.com",
        "API_KEY": "your_api_key_here"
      }
    }
  }
}

保存后运行 /mcp 验证是否加载成功。

2. Cursor

进入 设置 > Tools & MCPs > Add New MCP Server：

• Name：sam3
• Type：command
• Command：

  env API_KEY=your_api_key_here npx -y sam3-mcp-server

或编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "sam3": {
      "command": "npx",
      "args": ["-y", "sam3-mcp-server"],
      "env": {
        "API_BASE_URL": "https://sam.luluhero.com",
        "API_KEY": "your_api_key_here"
      }
    }
  }
}

3. 在智能体/Agent 代码中使用

如果你正在开发自己的 Agent，可以使用 MCP SDK 连接本服务：

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["-y", "sam3-mcp-server"],
  env: {
    API_BASE_URL: "https://sam.luluhero.com",
    API_KEY: process.env.API_KEY,
  },
});

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

// 方式一：使用本地文件路径
const result1 = await client.callTool({
  name: "sam3_predict",
  arguments: {
    imagePath: "/path/to/image.png",
    prompt: "a cat",
  },
});

// 方式二：使用网络图片链接
const result2 = await client.callTool({
  name: "sam3_predict",
  arguments: {
    imageUrl: "https://example.com/photo.jpg",
    prompt: "person",
  },
});

// 方式三：使用 base64 编码的图片数据
const fs = require("fs");
const imageBuffer = fs.readFileSync("/path/to/image.png");
const base64Image = imageBuffer.toString("base64");

const result3 = await client.callTool({
  name: "sam3_predict",
  arguments: {
    imageBase64: base64Image,
    prompt: "a dog",
  },
});

console.log(result1.content[0].text);
// 输出: JSON 字符串，包含 masks、boxes、scores

4. 直接运行（调试）

# 设置环境变量后启动
export API_KEY=your_api_key_here
npx -y sam3-mcp-server

验证安装

重启客户端后，确认工具是否加载成功：

1. 或直接问 AI："你有哪些可用的工具？"
2. 应看到：sam3_predict

全局安装（可选）

如果你不想每次都用 npx：

npm install -g sam3-mcp-server

然后在配置中使用 "command": "sam3-mcp-server" 配合 "args": ["--api-key", "your_api_key_here"] 。

配置

本项目需要以下环境变量：

| 变量名 | 必填 | 默认值 | 说明 | |---|---|---|---| | API_BASE_URL | 否 | https://sam.luluhero.com | SAM3 后端服务地址 | | API_KEY | 是 | - | API 密钥 | | SAM3_POLL_INTERVAL | 否 | 2000 | 轮询间隔（毫秒） | | SAM3_POLL_MAX_ATTEMPTS | 否 | 60 | 最大轮询次数 |

使用方式

1. Cursor

在 Cursor 的 Settings > MCP Servers 中添加：

{
  "mcpServers": {
    "sam3": {
      "command": "npx",
      "args": ["-y", "sam3-mcp-server"],
      "env": {
        "API_BASE_URL": "https://sam.luluhero.com",
        "API_KEY": "your_api_key_here"
      }
    }
  }
}

2. 在智能体/Agent 代码中使用

如果你正在开发自己的 Agent，可以使用 MCP SDK 连接本服务：

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["-y", "sam3-mcp-server"],
  env: {
    API_BASE_URL: "https://sam.luluhero.com",
    API_KEY: process.env.API_KEY,
  },
});

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

// 方式一：使用本地文件路径
const result1 = await client.callTool({
  name: "sam3_predict",
  arguments: {
    imagePath: "/path/to/image.png",
    prompt: "a cat",
  },
});

// 方式二：使用网络图片链接
const result2 = await client.callTool({
  name: "sam3_predict",
  arguments: {
    imageUrl: "https://example.com/photo.jpg",
    prompt: "person",
  },
});

// 方式三：使用 base64 编码的图片数据
const fs = require("fs");
const imageBuffer = fs.readFileSync("/path/to/image.png");
const base64Image = imageBuffer.toString("base64");

const result3 = await client.callTool({
  name: "sam3_predict",
  arguments: {
    imageBase64: base64Image,
    prompt: "a dog",
  },
});

console.log(result1.content[0].text);
// 输出: JSON 字符串，包含 masks、boxes、scores

3. 直接运行（调试）

# 设置环境变量后启动
export API_KEY=your_api_key_here
npx -y sam3-mcp-server

Tool 说明

sam3_predict

参数：

图片输入（三选一，必须提供其中一种）：

• imagePath (string): 本地图片的绝对路径。支持常见图片格式（如 PNG、JPG、JPEG）。

  • 示例："C:\\Users\\xxx\\photo.png"、"/home/user/images/cat.jpg"
  • 适用场景：用户明确提供了本地文件路径

• imageUrl (string): 公开可访问的图片 URL。

  • 示例："https://example.com/photo.jpg"
  • 适用场景：图片已在网上，用户提供了链接
  • 注意：URL 必须公开可访问，不支持需要登录或签名的链接

• imageBase64 (string): Base64 编码的图片数据。

  • 示例："iVBORw0KGgoAAAANSUhEUgAA..."
  • 适用场景：用户拖拽或上传了图片附件，Agent 将图片编码为 base64 后传入
  • 注意：大图片的 base64 数据会比较大，传输时间可能稍长

其他参数：

• prompt (string, required): 英文文本提示，用于指定要在图片中分割的目标物体。例如 "person"、"car"、"a cat sitting on a sofa"。由于 SAM3 模型仅接受英文 prompt，建议传入英文描述。如果用户提供中文或其他非英文文本，Agent 会自动翻译为英文后调用。

返回：

推理完成后，直接返回 JSON 字符串。该 JSON 包含以下三个字段：

• masks：二维数组。每个元素是一个与输入图片尺寸相同的二值掩码（取值为 0 或 1），用于标记检测到的物体在图片中的像素级位置。数组中的第 i 个掩码对应第 i 个检测到的物体实例。

• boxes：二维数组。每个元素是 [x1, y1, x2, y2] 格式的边界框坐标，表示检测到的物体在图片中的矩形区域。x1、y1 为左上角坐标，x2、y2 为右下角坐标。

  坐标系说明：以图片左上角为原点 (0, 0)，x 轴向右增长，y 轴向下增长，单位为像素。例如 [120, 80, 300, 450] 表示该物体区域从图片左边缘向右 120px、上边缘向下 80px 处开始，延伸至左边缘向右 300px、上边缘向下 450px 处结束，区域宽度为 x2 - x1 = 180px，高度为 y2 - y1 = 370px。

• scores：一维数组。每个元素是对应检测结果的置信度分数，取值范围为 0 到 1。分数越高，表示模型对该检测结果的把握越大。

结果 JSON 内容示例：

{
  "masks": [
    [[0, 0, 1, ...], [0, 1, 1, ...], ...],
    [[0, 0, 0, ...], [0, 0, 1, ...], ...]
  ],
  "boxes": [
    [120, 80, 300, 450],
    [400, 200, 600, 500]
  ],
  "scores": [0.95, 0.87]
}

常见问题

拖拽附件后提示找不到文件？

这是 stdio MCP 的已知限制。当通过 Agent 界面拖拽或上传附件时，文件路径通常不会自动传给 MCP Server。

解决方法：

1. 同时提供路径（推荐）：拖拽图片后，在文字中补充说明图片的本地绝对路径：

   "请处理这张图片 D:\\photos\\cat.jpg，找出里面的猫"

2. 等待自动编码：Claude 可能会自动将图片编码为 base64 传入。如果成功，无需额外操作。

3. 回答路径询问：如果 Claude 询问图片路径，直接回复本地绝对路径即可。

三种输入方式有优先级吗？

没有严格优先级。Claude 会根据对话上下文自动选择最合适的方式：

• 你提供了本地路径 → 使用 imagePath
• 你提供了网络链接 → 使用 imageUrl
• 你拖拽了附件且没有路径 → 尝试 imageBase64

支持哪些图片格式？

支持常见格式：PNG、JPG、JPEG、BMP、WebP 等。建议优先使用 PNG 或 JPG。

URL 图片下载失败怎么办？

确保 URL 是公开可访问的，不需要登录、Cookie 或签名。如果图片在需要身份验证的服务上（如私有 S3 Bucket、需要登录的图床），请先下载到本地再使用 imagePath。

Base64 图片太大怎么办？

如果图片很大（如 4K 分辨率），base64 编码后的数据会非常大，可能导致传输变慢。建议：

1. 使用 imagePath 代替
2. 或先将图片压缩后再编码