MCP 设置

让 MCP 客户端使用本机语音、说话人与模型生成。

支持 12 个本机 MCP 工具，包括使用已安装的语言模型生成文本与图片。

接入

支持 stdio 的 MCP 客户端都能接入。先安装并激活 edgespeak-cli，再注册 EdgeSpeak。以 Claude Code 为例：

claude mcp add edgespeak -- edgespeak-cli mcp

CLI 安装指南

通道

推荐 stdio：桌面 App 运行时经本地网关复用已加载的模型；未运行时，stdio 会自行拉起随附的本地引擎，并按需下载缺失模型。HTTP /mcp 是备选通道，桌面 App 和 Headless 服务都会提供，沿用网关的鉴权设置。上方开关也会切换 HTTP 示例；stdio 不需要 API Key。

edgespeak-cli mcp                   # stdio
POST http://127.0.0.1:1117/mcp      # HTTP（桌面 App 运行时）
POST http://127.0.0.1:1118/mcp      # HTTP（edgespeak-cli serve）

通过 HTTP 调用 MCP

POST /mcp 是服务根路径下的 JSON-RPC 传输，不是 /v1/mcp。沿用快速开始的环境变量。此服务使用无状态 HTTP 并直接返回 JSON，无需保存会话 ID。MCP 客户端会自动处理初始化与工具发现。若要手动检查，先发送初始化请求（需要 jq）：

请求示例：

MCP_URL="${EDGESPEAK_BASE_URL%/v1}/mcp"
curl --fail-with-body "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"docs-example","version":"1.0"}}}' \
  -o mcp-init.json
jq '{id, server: .result.serverInfo.name, protocolVersion: .result.protocolVersion}' mcp-init.json
MCP_PROTOCOL=$(jq -er '.result.protocolVersion' mcp-init.json)

输出示例（jq 提取结果；协商的协议版本可能不同）：

{"id":1,"server":"edgespeak","protocolVersion":"2025-03-26"}

发送初始化完成通知，再调用工具。通知返回 202 且响应体为空；工具请求返回 JSON-RPC 结果。后续请求沿用协商得到的版本：

curl --fail-with-body "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: $MCP_PROTOCOL" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

curl --fail-with-body "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: $MCP_PROTOCOL" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"edgespeak_segment_sentences","arguments":{"text":"Hello world. Let us begin."}}}' \
  -o mcp-result.json
jq '.result.structuredContent' mcp-result.json

输出示例（structuredContent 提取结果；模型切分边界可能不同）：

{
  "metadata": {"sentence_count": 2},
  "result": [{"text":"Hello world.","start":0.0,"end":0.0},{"text":"Let us begin.","start":0.0,"end":0.0}],
  "truncated": false
}

MCP 纯文本切分结果中的零值 start 与 end 是占位值，不是测得的音频时间；HTTP 文本切分接口则省略这些字段。

若要获取工具的完整 schema，使用相同请求头发送 {"jsonrpc":"2.0","id":3,"method":"tools/list","params":{}}；响应中的 result.tools[] 包含 name、description 与 inputSchema。工具调用失败时也可能返回 HTTP 200，读取结果前请检查 JSON-RPC 的 error 与 result.isError。

MCP 接受的文件路径均位于服务主机，不会自动上传远端客户端的文件。远端转录可传入内联音频，或改用 multipart HTTP API。接口返回的 artifact 路径同样属于服务主机，并非可下载链接。

工具

共 12 个工具，其中 9 个只读。声音创建、删除与播报只修改受管理的本机文件。产品能力统称「播报」，工具标识沿用开发者契约中的 speech。

edgespeak_transcribe_file    必填: path（绝对路径）
                             可选: model, language, diarize, timestamps (none|word|segment),
                                   min_chars, max_chars, start_margin, end_margin

edgespeak_transcribe         必填: audio_base64（解码后 ≤ 50MB）
                             可选: 同 transcribe_file

edgespeak_diarize_file       必填: path（绝对路径）
                             可选: num_speakers (1..32)

edgespeak_align              必填: text + path | audio_base64 二选一
                             可选: language, protected_terms
                             结果: words，以及与 POST /v1/audio/alignments 同形的
                                   task、text、segments、usage

edgespeak_segment_sentences  必填: text 或 segments[]
                             可选: threshold (默认 0.35), min_chars, max_chars,
                                   start_margin, end_margin

edgespeak_speech_examples    可选: model、mode、language、id、recipe
                             返回模型专属播报示例与适用性

edgespeak_list_models        无参数 → {models: [{id, owned_by, locality}]}

edgespeak_create_response    必填: model，以及 input 或 images
                             可选: max_output_tokens、temperature、reasoning、translation
                                   （与 /v1/responses 顶层 translation 同形：target_language、
                                   language_pair、source_language、style）
                             图片: 最多 4 张，解码后总计 ≤ 20MB

edgespeak_list_voices        无参数 → {voices: [...]}

edgespeak_add_voice          必填: audio_path（绝对路径）、ref_text、name、
                                   consent=true
                             可选: language、speaker_description

edgespeak_delete_voice       必填: voice_id（user:<uuid>）
                             不允许删除内置声音

edgespeak_create_speech      必填: model、input、voice
                             模型: 从 edgespeak_list_models 的当前目录中选择
                             可选: instructions、disable_style、clone_mode、speed、language、seed、
                                   guidance_scale、inference_steps、retry_badcase、clone_recipe、
                                   temperature、top_p、top_k、repetition_penalty、
                                   user_marks、phonetic_spans、control_policy
                             instructions: 不传 / "" / null 沿用音色保存的风格，
                             非空文本表示本次改用这段风格
                             disable_style: true 表示本次不用任何风格，
                             不能与非空 instructions 同给
                             clone_mode: quick | ultimate，省略用模型缺省档
                             voice=builtin:design 按 instructions 描述设计声音（描述必填）
                             qwen3-tts-voice-design 必须传 instructions，
                             并使用 voice=builtin:auto 或 builtin:design
                             输出: 受管理的本机 WAV artifact

所有 language 参数与 HTTP API 使用同一套代码，见语言代码。MCP 的 edgespeak_segment_sentences 当前提供分句参数；段落切分请通过 HTTP API 或 CLI segment --paragraph-threshold 使用。播报控制能力因模型而异，调用前请查阅模型目录与 edgespeak_speech_examples；instructions、clone_mode 与 builtin:design 的规则见风格指令、克隆档位与声音设计，translation 见指定翻译语向。

各工具的请求与结果示例

将每行的工具名与参数放进上方 tools/call 请求的 params:{name,arguments}。输出列都是 result.structuredContent 的节选，省略了无关字段与额外数组项，不是完整 JSON-RPC 信封。调用时请替换示例中的文件路径、Base64 数据、模型 ID 与声音 ID；所有路径均对应服务主机。添加／删除音色以及生成语音会写入本机管理的文件，仅在需要时执行。

工具名	参数示例	结构化结果示例（节选）
`edgespeak_list_models`	`{}`	`{"models":[{"id":"Qwen/Qwen3.5-4B","owned_by":"EdgeSpeak","locality":"local"}]}`
`edgespeak_transcribe_file`	`{"path":"/absolute/path/hello.wav"}`	`{"result":{"text":"Hello world."},"truncated":false}`
`edgespeak_transcribe`	`{"audio_base64":"<base64 audio file bytes>"}`	`{"result":{"text":"Hello world."},"truncated":false}`
`edgespeak_diarize_file`	`{"path":"/absolute/path/meeting.wav","num_speakers":2}`	`{"result":{"speakers":["SPEAKER_00","SPEAKER_01"],"segments":[{"start":0.4,"end":3.2,"speaker":"SPEAKER_00"}]},"truncated":false}`
`edgespeak_align`	`{"path":"/absolute/path/hello.wav","text":"Hello world."}`	`{"result":{"words":[{"word":"Hello","start":0.2,"end":0.6,"score":0.98}],"task":"align","text":"Hello world.","segments":[{"id":0,"start":0.2,"end":1.1,"text":"Hello world.","words":[{"word":"Hello","start":0.2,"end":0.6,"score":0.98}]}],"usage":{"type":"duration","seconds":1.2}},"truncated":false}`
`edgespeak_segment_sentences`	`{"text":"Hello world. Let us begin."}`	`{"metadata":{"sentence_count":2},"result":[{"text":"Hello world.","start":0.0,"end":0.0}],"truncated":false}`
`edgespeak_speech_examples`	`{}`	`{"examples":[{"model":"openbmb/VoxCPM2","mode":"voice-design","applicable":true,"reason":null}]}`
`edgespeak_create_response`	`{"model":"Qwen/Qwen3.5-4B","input":"我们下周一开会。","translation":{"target_language":"en"}}`	`{"output":[{"type":"message","role":"assistant","content":[{"type":"output_text","text":"We have a meeting next Monday."}]}]}`
`edgespeak_list_voices`	`{}`	`{"voices":[{"id":"builtin:bright-girl","available":true}]}`
`edgespeak_add_voice`	`{"audio_path":"/absolute/path/reference.wav","ref_text":"Hello world.","name":"My voice","language":"en-US","consent":true}`	`{"voice":{"id":"user:00000000-0000-4000-8000-000000000001"}}`
`edgespeak_create_speech`	`{"model":"Qwen/Qwen3-TTS-0.6B-Base","voice":"builtin:bright-girl","input":"Hello world.","clone_mode":"quick"}`	`{"artifact_path":"/service/artifacts/speech-example.wav","format":"wav","sample_rate":24000,"duration":1.2}`
`edgespeak_delete_voice`	`{"voice_id":"user:00000000-0000-4000-8000-000000000001"}`	`{"deleted":{"id":"user:00000000-0000-4000-8000-000000000001","name":"My voice"}}`

完整音色与模型说明参见音色字段及模型发现。MCP 模型目录使用 models[] 与 locality，HTTP 接口则使用 data[] 与 execution_location，请勿混用两种响应格式。超长结果请参阅结果。

结果

文本结果在 2000 字符内直接内联返回；超过 2000 字符落盘为本机 artifact 并保留内联预览。播报始终返回受管理的本机 WAV artifact 路径与生成诊断。

≤ 2000 字符  →  { "metadata": …, "result": …, "truncated": false }
> 2000 字符  →  { "metadata": …, "preview": { "head": …, "tail": … },
                  "artifact_path": …, "artifact_json_path": …, "truncated": true }
播报           →  { "artifact_path": …, "format": "wav", "sample_rate": …,
                  "duration": …, "seed_used": …, "warnings": […] }

隐私

语音工作流与已安装的本机模型让源音频、声音、生成音频、转录稿、提示词与图片留在当前设备。只有在你明确选择 execution_location=remote 的模型时，才会把发给该模型的请求传给对应供应商。

使用本机模型生成

启动桌面 App，下载并加载本机模型后，可通过 Responses、Chat Completions、CLI 或 MCP 调用。

调用 edgespeak_create_response 工具并传入以下参数，将图片占位值替换为 PNG 文件字节的 Base64 编码：

{
  "model": "Qwen/Qwen3.5-4B",
  "input": "Describe the attached image",
  "images": [{ "mime_type": "image/png", "data_base64": "<base64>" }]
}