# Reported issues for media-mcp

Pod holds 6 of 6 GitHub reports that passed its relevance review. This can include external user reports, maintainer-confirmed bugs, and concrete feature gaps. Treat them as evidence to inspect, not a count of distinct defects.

Back to [media-mcp](/mcp/media-mcp).

## Most discussed

### 深化 Media host 配置 module，修复命令行密钥覆盖不一致

## What to build

当用户通过命令行提供或覆盖认证密钥时，enhancement 与 SAM3 两个 Media host 都使用最终生效的值。将配置优先级、校验和派生集中在一个 deep module，再用完整配置装配现有 adapter，消除调用者必须知道的初始化顺序。

推荐强度：Strong。可以先完成正确性修复，再在同一任务内集中配置规则；不依赖 Media task 等待重构。

## 当前摩擦与证据

SAM3 密钥在命令行解析前由通用密钥复制，之后命令行只更新通用密钥：

- 仅提供命令行密钥时，enhancement 使用该值，而 SAM3 保留空值。
- 环境变量提供旧值、命令行提供新值时，SAM3 仍保留环境变量旧值。

已使用合成密钥执行实际配置解析片段复现；未发网络请求、未使用真实密钥。

## Acceptance criteria

- [ ] 仅提供命令行密钥时，两类 Media host 的任务查询和签名请求均获得正确的最终配置。
- [ ] 命令行覆盖环境变量密钥时，两类 Media host 均使用覆盖后的值。
- [ ]…

[Read the thread](https://github.com/avclabs/media-mcp/issues/6) · 2026-10-02 · open · 0 comments

### 深化 Media task 等待 module，统一预算、取消与 SAM3 次数限制

## What to build

让视频、图片增强/上色/降噪、SAM3 的 Sync tool 使用同一个 deep Media task 等待 module，集中等待预算、终态判断、查询次数和本地取消。保留各工具现有名称、参数与结果格式，Media host 差异由 adapter 处理。

推荐强度：Strong；架构改进首选。一个 interface 覆盖完整等待行为，提升 locality、leverage 和测试 depth；不以抽取 sleep 或序列化 helper 代替深化。

## 已确认的行为决策

1. Media task wait budget 从取得 task_id 后开始，计入状态查询和轮询间隔；Media source 准备、上传和任务提交不计入。
2. 保留各工具现有对外结果格式。尤其不能将 enhancement 的“查询成功”与“Media task 成功”混为一谈。
3. 预算耗尽时取消本地在途查询，返回携带 task_id 的 Truncated wait；远端 Media task 继续运行。
4. SAM3 保留最多 N…

[Read the thread](https://github.com/avclabs/media-mcp/issues/5) · 2026-10-02 · open · 0 comments

### [P2] 任务创建成功后轮询失败会丢失 task_id

## 问题

同步工具创建远端任务成功后，如果状态查询失败，只返回错误文本，丢失已经取得的 `task_id`。远端任务可能仍在执行，调用方无法继续查询，重试同步工具又会重复提交任务。

优先级：P2。

## 原因与位置

- `src/image-enhancement.ts:269`
- `src/video-enhancement.ts:217`
- `src/sam3.ts:206`

状态请求抛错时，异常传播到只返回 `{success:false,error}` 的顶层处理器。图片、视频状态接口返回业务错误时，也会直接返回不含任务 ID 的错误对象。SAM3 在第 213 行下载最终结果失败时同样会丢失任务上下文。

## 已验证的复现

分别通过图片增强、视频增强、SAM3 注册后的工具回调：

1. 模拟任务创建成功并返回已知任务 ID。
2. 让第一次状态请求抛出 `ECONNRESET`。
3. 检查工具返回值。

三者均返回以下内容，没有保留已经创建的任务 ID：

```json
{"success":false,"error":"ECONNRESET"}…

[Read the thread](https://github.com/avclabs/media-mcp/issues/4) · 2026-10-02 · open · 0 comments

### [P2] 同步工具未按剩余等待时间限制轮询和 HTTP 请求

## 问题

同步工具的等待期限没有限制休眠和 HTTP 请求。调用可能明显超过配置的 `timeout`，导致 MCP 客户端先超时，未能收到用于继续查询的 `task_id`。

优先级：P2。

## 原因与位置

- `src/image-enhancement.ts:267`、`src/video-enhancement.ts:215` 在上传、创建任务之后才开始计时。
- 每轮先发出状态请求，再检查是否超时；休眠始终使用完整的 `poll_interval`。
- 即使休眠期间已超过期限，下一轮仍会请求状态；单个请求本身允许等待 60 秒。
- `src/sam3.ts:170` 按尝试次数轮询，实际总耗时也会额外累加所有 HTTP 请求时间。

因此默认的 50 秒同步等待不能保证在文档所述的约 60 秒 MCP 调用期限内交还任务 ID。

## 已验证的复现

通过图片、视频工具注册后的回调调用，模拟立即创建任务、每次状态立即返回 `processing`，参数为：

```json…

[Read the thread](https://github.com/avclabs/media-mcp/issues/3) · 2026-10-02 · open · 0 comments

### [P2] 上传等待签名期间文件流错误可能导致进程退出且缺少清理

## 问题

上传模块等待签名时尚未接管文件流的错误事件。文件打开失败可能使整个 MCP 服务退出；签名请求失败后，已打开的文件流也未释放。

优先级：P2。

## 原因与位置

- `src/image-enhancement.ts:195`、`src/video-enhancement.ts:149` 先创建 `ReadStream`，再调用上传模块。
- `src/upload.ts:161` 先等待 `prepareUpload`，第 167 行才把文件流接入 FormData。
- 该等待期间没有流错误处理，也没有签名失败后的流清理。

`existsSync` 和 `statSync` 不能保证文件可读，也不能避免检查之后文件被删除。流的异步 `error` 事件不能由包围 `await uploadObject(...)` 的普通 `try/catch` 捕获。

## 已验证的复现

### 签名失败后文件描述符仍打开

用实际 `package.json` 创建读取流，令签名适配器等待 30 ms 后抛出 `signature…

[Read the thread](https://github.com/avclabs/media-mcp/issues/2) · 2026-10-02 · open · 0 comments

### [P1] SAM3 未使用 --api-key 传入的最终密钥

## 问题

仅通过 `--api-key` 配置密钥时，SAM3 工具仍认为密钥未配置；同时设置环境变量和命令行参数时，SAM3 使用旧的环境变量值。

优先级：P1。

## 原因与位置

`src/server.ts:53` 在解析命令行参数之前执行 `let sam3ApiKey = apiKey`。第 63 行只更新 `apiKey`，第 110、122 行却继续把原来的 `sam3ApiKey` 传给 SAM3 上传签名和工具注册。

## 复现与实际结果

1. 清除启动子进程环境中的 `API_KEY`。
2. 通过 `node dist/server.js --api-key review-placeholder` 启动服务。
3. 使用 MCP SDK 的 stdio 客户端调用 `get_sam3_task_status`，传入任意测试任务 ID。

服务成功启动，但工具在发出远端请求前立即返回：

```json
{"success":false,"error":"SAM3 API Key not configured. Please set API_KEY…

[Read the thread](https://github.com/avclabs/media-mcp/issues/1) · 2026-10-02 · open · 0 comments

## Most recent

The remaining reports are on [the project's issue tracker](https://github.com/avclabs/media-mcp/issues).