volcengine-api-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marvin Pan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# volcengine-api-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把火山引擎 OpenAPI 封装为 [MCP](https://modelcontextprotocol.io) 服务，供 Claude / Cursor / Cline 等 Agent 直接调用。
+
+## 项目结构
+
+单包仓库：`src/lib/` 是火山各产品的 API 客户端，`src/tools/` 是 MCP 工具，`src/index.ts` 为 server 入口。
+
+```
+src/
+  lib/     # API 客户端：ark（方舟生图）/ tts（语音合成）/ tos（对象存储）/ auc（语音识别）/ search（联网搜索）/ client + signer（V4 签名底座）
+  tools/   # MCP 工具封装（每个文件对应一类 API）
+  index.ts # MCP Server 入口（stdio 传输）
+```
+
+## 快速开始
+
+```bash
+pnpm install
+pnpm build          # 构建到 dist/
+pnpm dev            # 以 tsx 直接启动 MCP server（开发）
+```
+
+### 配置凭据
+
+各工具独立取自己的环境变量（参考 `.env.example`），**不用哪个工具就不用配**；配置缺失只在调用对应工具时报错。
+
+| 工具 | 必需 | 可选 |
+| --- | --- | --- |
+| `plan_images_generations` | `ARK_API_KEY`（`ark-` 开头，必须显式配置，不做其他回退） | — |
+| `plan_tts_unidirectional` | 同上（复用 `ARK_API_KEY`，走方舟 Agent Plan 网关） | — |
+| `tos_object_put` | `VOLC_TOS_ACCESS_KEY` / `VOLC_TOS_SECRET_KEY` / `VOLC_TOS_BUCKET` / `VOLC_TOS_REGION` | `VOLC_TOS_ENDPOINT`、`VOLC_TOS_PREFIX`（key 前缀，默认 `volcengine-api-mcp`） |
+| `auc_bigmodel_transcribe` | `VOLC_ASR_API_KEY`（火山语音控制台 API Key）；传本地音频时还需 TOS 四件套（同上） | — |
+| `askecho_web_search` | `ASK_ECHO_SEARCH_INFINITY_API_KEY`（搜索 API Key）或 `VOLCENGINE_ACCESS_KEY` + `VOLCENGINE_SECRET_KEY`（V4 签名）二者其一 | — |
+
+> `VOLCENGINE_ACCESS_KEY` / `VOLCENGINE_SECRET_KEY` 除 `askecho_web_search` 的 AK/SK 鉴权模式外，也供 core 的 V4 签名客户端后续封装其他 OpenAPI 工具使用。
+
+### 接入 Claude Code / Cursor
+
+```json
+{
+  "mcpServers": {
+    "volcengine-api": {
+      "command": "npx",
+      "args": ["-y", "volcengine-api-mcp"],
+      "env": {
+        "VOLCENGINE_ACCESS_KEY": "your-ak",
+        "VOLCENGINE_SECRET_KEY": "your-sk",
+        "VOLCENGINE_REGION": "cn-north-1",
+        "ARK_API_KEY": "ark-xxx",
+        "VOLC_TOS_ACCESS_KEY": "your-ak",
+        "VOLC_TOS_SECRET_KEY": "your-sk",
+        "VOLC_TOS_BUCKET": "your-bucket",
+        "VOLC_TOS_REGION": "cn-beijing",
+        "VOLC_ASR_API_KEY": "xxx"
+      }
+    }
+  }
+}
+```
+
+> `npx volcengine-api-mcp` 要求本包已发布到 npm；发布前可临时用本地路径：
+> `"command": "node", "args": ["/absolute/path/to/volcengine-api-mcp/dist/index.js"]`
+
+## 提供的工具
+
+| 工具 | 说明 |
+| --- | --- |
+| `plan_images_generations` | 火山方舟文生图（`/api/plan/v3/images/generations`）：生成图片落盘并直接返回给 Agent（抽自 nova-voyage 的 ark-image.mjs 逻辑） |
+| `plan_tts_unidirectional` | 豆包语音合成大模型-单向流式（`/api/v3/plan/tts/unidirectional`）：文本合成音频落盘并返回给 Agent |
+| `tos_object_put` | 火山引擎 TOS 上传（Action: `PutObject`）：文件落 bucket 并返回预签名下载 URL，bucket 保持私有 |
+| `auc_bigmodel_transcribe` | 大模型录音文件识别（`/api/v3/auc/bigmodel/submit` + `query`）：提交音频轮询至完成，返回全文 + 分句时间戳 + 说话人（抽自 content-forge clip 的 doubao.ts） |
+| `askecho_web_search` | 联网搜索（豆包搜索，服务 `volc_torchlight_api` / Action `WebSearch`）：网页/图片搜索，支持时间/站点/行业过滤与正文返回（移植自 mcp-server 的 askecho_search_infinity） |
+
+## 新增具体工具
+
+在 `src/tools/` 下新建文件，参照 [tos.ts](src/tools/tos.ts)（单 API 专用工具）或 [image.ts](src/tools/image.ts)（含图片回传的处理类工具），API 客户端放 `src/lib/`：
+
+1. 定义 `name` / `description` / zod `inputSchema` / `handler`
+2. 在 [index.ts](packages/mcp-server/src/index.ts) 中 `registerTool` 注册
+
+### 工具命名约定
+
+统一 `服务_资源_动作`（全小写下划线），从火山 API 推导，让用户一眼对上背后调的是哪个 API：
+
+- REST 路径类：取端点路径段，如 `/api/plan/v3/images/generations` → `plan_images_generations`
+- OpenAPI Action 类：拆 Action 名，如 TOS `PutObject` → `tos_object_put`、ECS `DescribeInstances` → `ecs_describe_instances`
+- 语音识别放在 `auc*` 前缀下（openspeech 的 `/api/v3/auc/...` 端点）
+
+工具 `description` 里务必写明实际端点路径或 Action 名，方便对照文档。
+
+> `src/lib/` 自带火山 Signature V4 签名客户端（[client.ts](src/lib/client.ts) + [signer.ts](src/lib/signer.ts)），
+> 可直接调任何火山 OpenAPI（`askecho_web_search` 的 AK/SK 模式已在用）；后续封装其他 OpenAPI 工具时
+> 配合 `SERVICE_HOSTS`（已映射 ecs / vpc / iam / vod / live / tls / ces）即可。

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { generateImageTool } from './tools/image.js';
+import { tosPutObjectTool } from './tools/tos.js';
+import { asrTranscribeTool } from './tools/auc.js';
+import { ttsUnidirectionalTool } from './tools/tts.js';
+import { webSearchTool } from './tools/search.js';
+async function main() {
+    const server = new McpServer({ name: 'volcengine-api-mcp', version: '0.1.0' }, { instructions: '通过此服务调用火山引擎 API（方舟生图 / TOS / 语音识别等）。' });
+    server.registerTool(generateImageTool.name, {
+        title: '火山方舟图片生成 plan/images/generations',
+        description: generateImageTool.description,
+        inputSchema: generateImageTool.inputSchema,
+    }, generateImageTool.handler);
+    server.registerTool(tosPutObjectTool.name, {
+        title: 'TOS 上传文件 tos/object/put',
+        description: tosPutObjectTool.description,
+        inputSchema: tosPutObjectTool.inputSchema,
+    }, tosPutObjectTool.handler);
+    server.registerTool(asrTranscribeTool.name, {
+        title: '大模型录音文件识别 auc/bigmodel',
+        description: asrTranscribeTool.description,
+        inputSchema: asrTranscribeTool.inputSchema,
+    }, asrTranscribeTool.handler);
+    server.registerTool(ttsUnidirectionalTool.name, {
+        title: '语音合成（单向流式）plan/tts/unidirectional',
+        description: ttsUnidirectionalTool.description,
+        inputSchema: ttsUnidirectionalTool.inputSchema,
+    }, ttsUnidirectionalTool.handler);
+    server.registerTool(webSearchTool.name, {
+        title: '联网搜索 askecho/WebSearch',
+        description: webSearchTool.description,
+        inputSchema: webSearchTool.inputSchema,
+    }, webSearchTool.handler);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('[volcengine-api-mcp] server started on stdio');
+}
+main().catch((err) => {
+    console.error('[volcengine-api-mcp] fatal:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,OAAO,EAAE,EAChD,EAAE,YAAY,EAAE,sCAAsC,EAAE,CACzD,CAAC;IAEF,MAAM,CAAC,YAAY,CAAC,iBAAiB,CAAC,IAAI,EAAE;QAC1C,KAAK,EAAE,kCAAkC;QACzC,WAAW,EAAE,iBAAiB,CAAC,WAAW;QAC1C,WAAW,EAAE,iBAAiB,CAAC,WAAW;KAC3C,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAE9B,MAAM,CAAC,YAAY,CAAC,gBAAgB,CAAC,IAAI,EAAE;QACzC,KAAK,EAAE,yBAAyB;QAChC,WAAW,EAAE,gBAAgB,CAAC,WAAW;QACzC,WAAW,EAAE,gBAAgB,CAAC,WAAW;KAC1C,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAE7B,MAAM,CAAC,YAAY,CAAC,iBAAiB,CAAC,IAAI,EAAE;QAC1C,KAAK,EAAE,wBAAwB;QAC/B,WAAW,EAAE,iBAAiB,CAAC,WAAW;QAC1C,WAAW,EAAE,iBAAiB,CAAC,WAAW;KAC3C,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAE9B,MAAM,CAAC,YAAY,CAAC,qBAAqB,CAAC,IAAI,EAAE;QAC9C,KAAK,EAAE,mCAAmC;QAC1C,WAAW,EAAE,qBAAqB,CAAC,WAAW;QAC9C,WAAW,EAAE,qBAAqB,CAAC,WAAW;KAC/C,EAAE,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAElC,MAAM,CAAC,YAAY,CAAC,aAAa,CAAC,IAAI,EAAE;QACtC,KAAK,EAAE,wBAAwB;QAC/B,WAAW,EAAE,aAAa,CAAC,WAAW;QACtC,WAAW,EAAE,aAAa,CAAC,WAAW;KACvC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAE1B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;AAChE,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,GAAG,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/lib/ark.d.ts

@@ -0,0 +1,28 @@
+export declare const ARK_DEFAULT_IMAGE_MODEL = "doubao-seedream-5-0-pro-260628";
+export declare const ARK_DEFAULT_SIZE = "1728x2304";
+export interface ArkImageOptions {
+    apiKey: string;
+    prompt: string;
+    model?: string;
+    /** 宽x高（如 1728x2304）或 1K/2K/4K */
+    size?: string;
+    /** 默认不加水印 */
+    watermark?: boolean;
+    seed?: number;
+    /** png / jpeg */
+    outputFormat?: string;
+}
+export interface ArkImageResult {
+    url: string;
+    model: string;
+    size: string;
+    outputFormat: string;
+}
+export declare function validateArkSize(size: string): string;
+/** 调火山方舟（Agent Plan）生图接口，返回图片 URL。 */
+export declare function arkGenerateImage(opts: ArkImageOptions): Promise<ArkImageResult>;
+/** 下载图片并落盘。仅接受 https，重定向逐次校验，最多 5 跳。 */
+export declare function arkDownloadImage(url: string, output: string): Promise<{
+    path: string;
+    bytes: number;
+}>;

package/dist/lib/ark.js

@@ -0,0 +1,105 @@
+import { mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+const API_URL = 'https://ark.cn-beijing.volces.com/api/plan/v3/images/generations';
+const DOWNLOAD_TIMEOUT_MS = 120_000;
+const GENERATE_TIMEOUT_MS = 180_000;
+const MAX_REDIRECT_HOPS = 5;
+export const ARK_DEFAULT_IMAGE_MODEL = 'doubao-seedream-5-0-pro-260628'; // 5.0 pro，文字渲染与细节明显优于 flash
+export const ARK_DEFAULT_SIZE = '1728x2304'; // 2K @ 3:4，与豆包 App 参考图原生分辨率一致
+export function validateArkSize(size) {
+    if (/^(1K|2K|4K)$/i.test(size))
+        return size.toUpperCase();
+    if (!/^\d{3,4}x\d{3,4}$/.test(size)) {
+        throw new Error(`size 参数无效:${size}(应为 宽x高,如 1728x2304,或 1K/2K/4K)`);
+    }
+    const [w, h] = size.split('x').map(Number);
+    if (w < 512 || h < 512 || w > 4096 || h > 4096) {
+        throw new Error(`size 超出范围(512~4096):${size}`);
+    }
+    // 方舟接口要求图片面积 ≥ 921600 px（如 960x960），实测 512x512 会被 400 拒绝
+    if (w * h < 921_600) {
+        throw new Error(`size 面积过小(${w}x${h}=${w * h}px)，要求至少 921600px（如 960x960 / 1024x1024）`);
+    }
+    return size;
+}
+/** 调火山方舟（Agent Plan）生图接口，返回图片 URL。 */
+export async function arkGenerateImage(opts) {
+    if (!opts.apiKey?.trim()) {
+        throw new Error('未找到有效的方舟 API Key(ark- 开头)。请配置环境变量 ARK_API_KEY 或 ANTHROPIC_AUTH_TOKEN');
+    }
+    if (!opts.prompt?.trim()) {
+        throw new Error('缺少 prompt');
+    }
+    const model = opts.model || ARK_DEFAULT_IMAGE_MODEL;
+    const size = validateArkSize(opts.size || ARK_DEFAULT_SIZE);
+    const body = {
+        model,
+        prompt: opts.prompt,
+        size,
+        watermark: opts.watermark === true, // 默认不加水印
+        response_format: 'url',
+        output_format: opts.outputFormat || 'png', // pro 支持 png/jpeg
+    };
+    if (opts.seed !== undefined)
+        body.seed = opts.seed;
+    const res = await fetch(API_URL, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${opts.apiKey.trim()}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(GENERATE_TIMEOUT_MS),
+    });
+    const payload = (await res.json().catch(() => null));
+    if (!res.ok || !payload) {
+        throw new Error(`生图接口返回 ${res.status}:${JSON.stringify(payload ?? '响应不是 JSON')}`);
+    }
+    if (payload.error) {
+        throw new Error(`生图接口报错:${JSON.stringify(payload.error)}`);
+    }
+    const item = payload.data?.[0];
+    if (!item?.url) {
+        throw new Error(`响应中没有图片 URL:${JSON.stringify(payload).slice(0, 500)}`);
+    }
+    return {
+        url: item.url,
+        model: payload.model ?? model,
+        size: item.size ?? size,
+        outputFormat: item.output_format ?? body.output_format,
+    };
+}
+/** 下载图片并落盘。仅接受 https，重定向逐次校验，最多 5 跳。 */
+export async function arkDownloadImage(url, output) {
+    let current = url;
+    let buf;
+    for (let hop = 0; hop < MAX_REDIRECT_HOPS; hop++) {
+        const u = new URL(current);
+        if (u.protocol !== 'https:') {
+            throw new Error(`拒绝非 https 下载地址:${current.slice(0, 80)}`);
+        }
+        const dl = await fetch(current, {
+            signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+            redirect: 'manual',
+        });
+        if (dl.status >= 300 && dl.status < 400) {
+            const location = dl.headers.get('location');
+            if (!location)
+                throw new Error(`重定向缺少 location(${dl.status})`);
+            current = location;
+            continue;
+        }
+        if (!dl.ok)
+            throw new Error(`下载返回 ${dl.status}`);
+        buf = Buffer.from(await dl.arrayBuffer());
+        break;
+    }
+    if (!buf || buf.length === 0)
+        throw new Error('下载内容为空');
+    const path = resolve(output);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, buf);
+    const bytes = statSync(path).size;
+    if (bytes < 1024) {
+        throw new Error(`落盘文件过小(${bytes}B),疑似异常响应`);
+    }
+    return { path, bytes };
+}
+//# sourceMappingURL=ark.js.map

package/dist/lib/ark.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ark.js","sourceRoot":"","sources":["../../src/lib/ark.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE7C,MAAM,OAAO,GAAG,kEAAkE,CAAC;AACnF,MAAM,mBAAmB,GAAG,OAAO,CAAC;AACpC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AACpC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAE5B,MAAM,CAAC,MAAM,uBAAuB,GAAG,gCAAgC,CAAC,CAAC,4BAA4B;AACrG,MAAM,CAAC,MAAM,gBAAgB,GAAG,WAAW,CAAC,CAAC,8BAA8B;AAsB3E,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC;IAC1D,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,aAAa,IAAI,iCAAiC,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,uBAAuB,IAAI,EAAE,CAAC,CAAC;IACjD,CAAC;IACD,yDAAyD;IACzD,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;IAC1F,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,sCAAsC;AACtC,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAqB;IAC1D,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;IAC1F,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,WAAW,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,uBAAuB,CAAC;IACpD,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,IAAI,gBAAgB,CAAC,CAAC;IAE5D,MAAM,IAAI,GAA4B;QACpC,KAAK;QACL,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,IAAI;QACJ,SAAS,EAAE,IAAI,CAAC,SAAS,KAAK,IAAI,EAAE,SAAS;QAC7C,eAAe,EAAE,KAAK;QACtB,aAAa,EAAE,IAAI,CAAC,YAAY,IAAI,KAAK,EAAE,kBAAkB;KAC9D,CAAC;IACF,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IAEnD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE;QAC/B,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC9F,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;QAC1B,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,mBAAmB,CAAC;KACjD,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAA+B,CAAC;IACnF,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,UAAU,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,WAAW,CAAC,EAAE,CAAC,CAAC;IACpF,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,UAAU,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/B,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,eAAe,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,OAAO;QACL,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,KAAK;QAC7B,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI;QACvB,YAAY,EAAE,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,aAAa;KACvD,CAAC;AACJ,CAAC;AAED,wCAAwC;AACxC,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,GAAW,EAAE,MAAc;IAChE,IAAI,OAAO,GAAG,GAAG,CAAC;IAClB,IAAI,GAAuB,CAAC;IAC5B,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,iBAAiB,EAAE,GAAG,EAAE,EAAE,CAAC;QACjD,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3B,IAAI,CAAC,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,kBAAkB,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;QAC5D,CAAC;QACD,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE;YAC9B,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,mBAAmB,CAAC;YAChD,QAAQ,EAAE,QAAQ;SACnB,CAAC,CAAC;QACH,IAAI,EAAE,CAAC,MAAM,IAAI,GAAG,IAAI,EAAE,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;YACxC,MAAM,QAAQ,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAC5C,IAAI,CAAC,QAAQ;gBAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;YAC/D,OAAO,GAAG,QAAQ,CAAC;YACnB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,EAAE,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC;QACjD,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;QAC1C,MAAM;IACR,CAAC;IACD,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC;IAExD,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7B,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACzB,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;IAClC,IAAI,KAAK,GAAG,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,UAAU,KAAK,WAAW,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACzB,CAAC"}

package/dist/lib/auc.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Doubao file-transcription ASR client (Volcano Engine speech). Submit an audio URL, poll until
+ * done, and normalize the utterances (per-sentence text + start/end + optional speaker).
+ * 抽自 content-forge clip 的 asr/doubao.ts，供 MCP 工具 auc_bigmodel_transcribe 使用。
+ * 凭据来自环境变量 VOLC_ASR_API_KEY。
+ *
+ * API（docs.volcengine.com/docs/6561/1354831 与配套结果查询）：
+ * - 提交  POST https://openspeech.bytedance.com/api/v3/auc/bigmodel/submit
+ * - 查询  POST https://openspeech.bytedance.com/api/v3/auc/bigmodel/query
+ * 状态码在响应头 X-Api-Status-Code：20000000 完成；20000001/20000002 处理中/排队中；
+ * 20000003 无有效语音；其他为失败。查询需回传提交响应的 X-Tt-Logid。
+ */
+/** Resource id per model version: 2.0 is current, 1.0 is legacy */
+declare const RESOURCE_IDS: {
+    readonly '2.0': "volc.seedasr.auc";
+    readonly '1.0': "volc.bigasr.auc";
+};
+export type AsrModelVersion = keyof typeof RESOURCE_IDS;
+/** One normalized sentence with timing (and speaker when enabled) */
+export interface Utterance {
+    text: string;
+    /** start time in ms from audio beginning */
+    start: number;
+    end: number;
+    speaker?: number;
+}
+export interface TranscribeOptions {
+    /** X-Api-Key from the Volcano speech console */
+    apiKey: string;
+    /** Publicly fetchable audio URL (pre-signed TOS URL for local files) */
+    url: string;
+    format: string;
+    language?: string;
+    model?: AsrModelVersion;
+    enableSpeakerInfo?: boolean;
+    /** Speaker-diarization model: 200 non-meeting (≤5 speakers) / 300 voiceprint long meetings */
+    ssdVersion?: '200' | '300';
+    ssdMode?: 0 | 1;
+    enableItn?: boolean;
+    enablePunc?: boolean;
+    enableDdc?: boolean;
+    vadSegment?: boolean;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    /** Cancellation for long polls (workflow stages abort through this) */
+    signal?: AbortSignal;
+    /** Progress hook (e.g. workflow run-log lines) */
+    onLog?: (message: string) => void;
+}
+export interface TranscribeResult {
+    taskId: string;
+    /** Full plain text (joined utterances when the service omits it) */
+    text: string;
+    utterances: Utterance[];
+    raw: Record<string, unknown>;
+}
+/** Infer audio format from a path/URL extension; null when unknown */
+export declare function detectFormat(source: string): string | null;
+/** ms → mm:ss (or h:mm:ss beyond an hour) */
+export declare function formatClock(ms: number): string;
+/** Human-readable transcript: one line per utterance with [clock] and optional speaker */
+export declare function renderTranscriptMd(utterances: Utterance[]): string;
+/** Normalize the raw utterances[] of the API result */
+export declare function normalizeUtterances(raw: unknown): Utterance[];
+/** Full submit → poll → normalize round-trip */
+export declare function transcribeAudio(opts: TranscribeOptions): Promise<TranscribeResult>;
+export {};

package/dist/lib/auc.js

@@ -0,0 +1,160 @@
+/**
+ * Doubao file-transcription ASR client (Volcano Engine speech). Submit an audio URL, poll until
+ * done, and normalize the utterances (per-sentence text + start/end + optional speaker).
+ * 抽自 content-forge clip 的 asr/doubao.ts，供 MCP 工具 auc_bigmodel_transcribe 使用。
+ * 凭据来自环境变量 VOLC_ASR_API_KEY。
+ *
+ * API（docs.volcengine.com/docs/6561/1354831 与配套结果查询）：
+ * - 提交  POST https://openspeech.bytedance.com/api/v3/auc/bigmodel/submit
+ * - 查询  POST https://openspeech.bytedance.com/api/v3/auc/bigmodel/query
+ * 状态码在响应头 X-Api-Status-Code：20000000 完成；20000001/20000002 处理中/排队中；
+ * 20000003 无有效语音；其他为失败。查询需回传提交响应的 X-Tt-Logid。
+ */
+const SUBMIT_URL = 'https://openspeech.bytedance.com/api/v3/auc/bigmodel/submit';
+const QUERY_URL = 'https://openspeech.bytedance.com/api/v3/auc/bigmodel/query';
+const STATUS_OK = '20000000';
+const STATUS_RUNNING = new Set(['20000001', '20000002']);
+const STATUS_SILENCE = '20000003';
+/** Resource id per model version: 2.0 is current, 1.0 is legacy */
+const RESOURCE_IDS = { '2.0': 'volc.seedasr.auc', '1.0': 'volc.bigasr.auc' };
+/** Infer audio format from a path/URL extension; null when unknown */
+export function detectFormat(source) {
+    const ext = source.split('?')[0].split('#')[0].split('.').pop()?.toLowerCase() ?? '';
+    return ['wav', 'mp3', 'ogg', 'spx', 'amr', 'aac', 'm4a'].includes(ext) ? ext : null;
+}
+/** ms → mm:ss (or h:mm:ss beyond an hour) */
+export function formatClock(ms) {
+    const total = Math.round(ms / 1000);
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = total % 60;
+    const mm = h > 0 ? String(m).padStart(2, '0') : String(m);
+    return `${h > 0 ? `${h}:` : ''}${mm}:${String(s).padStart(2, '0')}`;
+}
+/** Human-readable transcript: one line per utterance with [clock] and optional speaker */
+export function renderTranscriptMd(utterances) {
+    return utterances
+        .map((u) => {
+        const speaker = u.speaker !== undefined ? `（说话人 ${u.speaker}）` : '';
+        return `**[${formatClock(u.start)} → ${formatClock(u.end)}]**${speaker} ${u.text}`;
+    })
+        .join('\n\n');
+}
+/** Normalize the raw utterances[] of the API result */
+export function normalizeUtterances(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .map((u) => {
+        const r = u;
+        const out = {
+            text: String(r.text ?? '').trim(),
+            start: Number(r.start_time ?? 0),
+            end: Number(r.end_time ?? 0),
+        };
+        // 说话人字段随模型版本不同：1.0 顶层 speaker_id；2.0 在 additions.speaker（字符串）
+        const additions = r.additions;
+        const speaker = r.speaker_id ?? additions?.speaker;
+        if (speaker !== undefined && speaker !== null && speaker !== '') {
+            out.speaker = Number(speaker);
+        }
+        return out;
+    })
+        .filter((u) => u.text.length > 0);
+}
+/** POST with the common headers; retries network errors, throws on HTTP failure */
+async function apiPost(url, body, headers, signal, retries = 3) {
+    for (let i = 0;; i++) {
+        try {
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', ...headers },
+                body: JSON.stringify(body),
+                signal,
+            });
+            if (!res.ok) {
+                throw new Error(`HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
+            }
+            return res;
+        }
+        catch (err) {
+            if (signal?.aborted)
+                throw err;
+            if (i >= retries - 1)
+                throw err;
+            await new Promise((r) => setTimeout(r, 1000 * (i + 1)));
+        }
+    }
+}
+function apiError(res, what) {
+    const status = res.headers.get('X-Api-Status-Code') ?? '';
+    const message = res.headers.get('X-Api-Message') ?? '';
+    return `${what}失败：X-Api-Status-Code=${status || '缺失'}，X-Api-Message=${message || '无'}`;
+}
+/** Submit the task and return its id plus the X-Tt-Logid needed by the query calls */
+async function submitTask(opts, headers) {
+    const requestId = crypto.randomUUID();
+    const res = await apiPost(SUBMIT_URL, {
+        user: { uid: 'volcengine-api-mcp' },
+        audio: { url: opts.url, format: opts.format },
+        request: {
+            model_name: 'bigmodel',
+            language: opts.language,
+            show_utterances: true,
+            enable_itn: opts.enableItn,
+            enable_punc: opts.enablePunc,
+            enable_ddc: opts.enableDdc,
+            enable_speaker_info: opts.enableSpeakerInfo,
+            ssd_version: opts.ssdVersion,
+            ssd_mode: opts.ssdMode,
+            vad_segment: opts.vadSegment,
+        },
+    }, { ...headers, 'X-Api-Request-Id': requestId }, opts.signal).catch((err) => {
+        throw new Error(`提交转写任务失败：${err instanceof Error ? err.message : String(err)}`);
+    });
+    if (res.headers.get('X-Api-Status-Code') !== STATUS_OK) {
+        throw new Error(apiError(res, '提交转写任务'));
+    }
+    return { taskId: requestId, logId: res.headers.get('X-Tt-Logid') ?? '' };
+}
+/** Poll the task until done; 20000003 (silence) resolves to an empty result */
+async function pollTask(opts, headers, taskId, logId) {
+    const interval = opts.pollIntervalMs ?? 3000;
+    const deadline = Date.now() + (opts.timeoutMs ?? 600_000);
+    const log = opts.onLog ?? (() => { });
+    for (;;) {
+        if (opts.signal?.aborted)
+            throw new Error('已取消');
+        if (Date.now() > deadline) {
+            throw new Error(`转写超时（${Math.round((opts.timeoutMs ?? 600_000) / 1000)}s）：任务 ${taskId} 仍未完成`);
+        }
+        await new Promise((r) => setTimeout(r, interval));
+        const res = await apiPost(QUERY_URL, {}, { ...headers, 'X-Api-Request-Id': taskId, ...(logId ? { 'X-Tt-Logid': logId } : {}) }, opts.signal).catch((err) => {
+            throw new Error(`查询转写结果失败：${err instanceof Error ? err.message : String(err)}`);
+        });
+        const status = res.headers.get('X-Api-Status-Code') ?? '';
+        if (status === STATUS_OK)
+            return (await res.json());
+        if (status === STATUS_SILENCE)
+            return { result: {} }; // 无有效语音：空结果
+        if (!STATUS_RUNNING.has(status))
+            throw new Error(apiError(res, '查询转写结果'));
+        log(`[asr] 处理中（${status}）…`);
+    }
+}
+/** Full submit → poll → normalize round-trip */
+export async function transcribeAudio(opts) {
+    const baseHeaders = {
+        'X-Api-Key': opts.apiKey,
+        'X-Api-Resource-Id': RESOURCE_IDS[opts.model ?? '2.0'],
+        'X-Api-Sequence': '-1',
+    };
+    const { taskId, logId } = await submitTask(opts, baseHeaders);
+    opts.onLog?.(`[asr] 任务已提交 ${taskId}`);
+    const raw = await pollTask(opts, baseHeaders, taskId, logId);
+    const inner = (raw.result ?? {});
+    const utterances = normalizeUtterances(inner.utterances);
+    const text = String(inner.text ?? utterances.map((u) => u.text).join(''));
+    return { taskId, text, utterances, raw };
+}
+//# sourceMappingURL=auc.js.map

package/dist/lib/auc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auc.js","sourceRoot":"","sources":["../../src/lib/auc.ts"],"names":[],"mappings":"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"}

package/dist/lib/client.d.ts

@@ -0,0 +1,18 @@
+import { type VolcengineApiRequest, type VolcengineApiResponse, type VolcengineCredentials } from './types.js';
+export interface VolcengineClientOptions {
+    credentials: VolcengineCredentials;
+    region?: string;
+    timeoutMs?: number;
+}
+/** 常见服务的默认 Host（不在此表中的服务回退为 <service>.<region>.volcengineapi.com） */
+export declare const SERVICE_HOSTS: Record<string, string>;
+export declare class VolcengineClient {
+    private readonly opts;
+    constructor(opts: VolcengineClientOptions);
+    private resolveHost;
+    request<T = unknown>(req: VolcengineApiRequest): Promise<VolcengineApiResponse<T>>;
+}
+/**
+ * 把嵌套参数展开成火山 API 需要的扁平 query（如 List.1.Name=a&List.1.Id=b）。
+ */
+export declare function flattenParams(params: Record<string, unknown>, prefix?: string): Record<string, string>;