agent-voice-mcp-minus

agent-voice-mcp 강화판 · 로컬 MCP 음성 알림 서비스로, AI 프로그래밍 어시스턴트(Trae / Claude Desktop / Cursor 등)에 작업 진행 상황 음성 알림 기능을 제공하며, 火山引擎 豆包 음성 합성 대모델(seed-tts)에 깊이 최적화되어 있습니다.

이 프로젝트는 al96169/agent-voice-mcp(저자 Antonio Liang, MIT 라이선스)에서 포크했으며, 그 위에 火山引擎 v3 인터페이스와 실제 사용 시나리오를 대상으로 많은 실측 튜닝을 수행했습니다. 원본이 본체이고, 이 프로젝트는 본체 + 실전 강화입니다. 모든 강화 기능은 구성 스위치로 끌 수 있어 원본에 가까운 동작으로 되돌릴 수 있습니다.

강화 기능(원본 1.2.0 대비)

일、설치

사전 요구 사항

• Node.js ≥ 18(다운로드)

• Windows(클라우드 합성은 크로스 플랫폼 사용 가능; SAPI 폴백과 경고음은 Windows 전용이며, 다른 플랫폼에서는 자동으로 축소됨)

• 火山引擎 계정(음성 합성 대모델 서비스 활성화 필요, 2단계 참조)

1단계: MCP 클라이언트 구성

방식 A · npx 직접 실행(권장, 클론 불필요)

MCP 클라이언트 구성에 추가합니다(Trae는 프로젝트 디렉터리의 .trae/mcp.json, Claude Desktop은 claude_desktop_config.json, Cursor는 .cursor/mcp.json):

{
  "mcpServers": {
    "agent-voice": {
      "command": "npx",
      "args": ["-y", "github:doer1296/agent-voice-mcp-minus"]
    }
  }
}

방식 B · 저장소를 클론하여 로컬에서 실행(코드를 수정해야 하는 사용자에게 권장)

git clone https://github.com/doer1296/agent-voice-mcp-minus.git
cd agent-voice-mcp-minus
npm install

MCP 구성을 node 직접 연결로 변경합니다(시작이 더 빠르고 npm 저장소의 영향을 받지 않습니다):

{
  "mcpServers": {
    "agent-voice": {
      "command": "node",
      "args": ["D:/your/path/agent-voice-mcp-minus/dist/index.js"]
    }
  }
}

구성 완료 후 클라이언트를 재시작하거나 새 세션을 열면, MCP 서비스가 시작될 때 'agent-voice 서비스가 시작되었습니다'라고 음성으로 알려 주며 준비 완료를 나타냅니다.

2단계: 火山引擎 자격 증명 가져오기

1. 火山引擎에 가입/로그인

2. 콘솔에서 '음성 기술' 검색 → '음성 합성 대모델' 서비스 활성화(신규 사용자에게 무료 할당량 제공)

3. 'API Key 관리' 페이지에서 X-Api-Key를 생성하여 가져옵니다

4. 주의: 사용하는 음색과 일치하는 모델 리소스를 활성화해야 합니다(seed-tts-1.0 또는 seed-tts-2.0, 대모델 설정 참조)

무료 대안: 원본에는 Edge TTS 엔진(Microsoft 무료 온라인 합성, API Key 불필요, 수백 가지 음색)이 내장되어 있으며, engine을 "edge-tts"로 설정하면 사용할 수 있습니다. 자세한 내용은 원본 README를 참조하세요.

3단계: 구성 파일 만들기

이 저장소의 config.example.json을 다음으로 복사합니다:

Windows: C:\Users\<你的用户名>\.agent-voice\config.json
macOS / Linux: ~/.agent-voice/config.json

그런 다음 apiKey 필드를 사용자의 X-Api-Key로 교체합니다(둘 중 하나 선택):

• 직접 평문: "apiKey": "你的key"

• 환경 변수 참조(권장): "${VOLCANO_API_KEY}"을 유지하고 시스템 환경 변수 VOLCANO_API_KEY=你的key를 설정합니다(구성 파일은 ${任意环境变量名} 구문을 지원하여 key가 평문으로 디스크에 저장되는 것을 방지)

二、호출 방법(Agent 측 사용)

MCP 서비스는 speak 도구를 등록하며, Agent가 호출하면 재생됩니다:

권장: 프로젝트 규칙과 함께 Agent가 작업 수명 주기를 자동으로 음성 알림하게 하세요. Trae의 .trae/rules/project_rules.md(또는 Claude의 CLAUDE.md)에 다음을 추가합니다:

在每次任务中，调用 agent-voice MCP 进行语音播报：
1. 任务开始时 — scene="task_start"
2. 每个子任务完成时 — scene="milestone"
3. 任务全部完成时 — scene="task_complete"
4. 遇到错误时 — scene="task_error"
5. 需要用户确认时 — scene="need_interaction"

호출 예시:

speak(text="开始执行任务：重构登录模块", scene="task_start", emotion="calm")
speak(text="任务完成，测试全部通过", scene="task_complete", emotion="happy")

기타 도구: stop(현재 재생 중지 및 큐 비우기), get_voices(사용 가능한 음색 나열), get_roles(구성된 역할 나열).

三、대모델 설정 방법(모델 선택)

config.json의 cloud.resourceId가 사용할 음성 합성 대모델을 결정합니다:

⚠️ 음색과 모델 버전이 반드시 일치해야 합니다: _moon_bigtts 음색을 seed-tts-2.0과 함께 사용하면(또는 그 반대) HTTP 403 리소스 미승인 오류가 발생합니다. 모델을 변경할 때 음색 ID도 함께 변경하고, 火山 콘솔에서 해당 모델 서비스를 활성화해야 합니다.

선택 권장: 1.0은 안정적이고 음색이 풍부하며 문서가 성숙했습니다; 2.0은 음성 복제 등 새로운 기능을 지원합니다. 이 프로젝트의 모든 튜닝 실측은 1.0을 기반으로 합니다.

四、음색 변경 방법

config.json의 cloud.voice(및 시나리오 구성의 각 voice 필드)를 수정하고, resourceId 버전과 일치하도록 확인하세요:

seed-tts-1.0 示例：
  zh_female_daimengchuanmei_moon_bigtts   呆萌川妹（甜美女声，本项目默认）
  zh_female_qingxinnvsheng_mars_bigtts    清新女声

seed-tts-2.0 示例：
  zh_female_vv_uranus_bigtts              温柔女声
  zh_male_*.uranus_bigtts                 男声系列

전체 음색 목록은 火山引擎 음색 라이브러리 문서를 참조하세요.

五、볼륨 / 속도 조절 방법

볼륨 volume(기본값 1.3):

• 매핑 관계: loudness_rate = (volume − 1) × 100, 즉 1.0 = 원본 음량, 1.3 = +30%(실측 RMS 게인 약 +29%, 선형에 가까움)

• 값 범위는 0.5 – 2.0 참조; 2.0 = +100%(서버 측 상한)

• 전역 기본값은 최상위 volume이며, 각 시나리오에서 개별적으로 덮어쓸 수 있습니다(scenes.*.volume)

속도 rate(기본값 200):

• 매핑 관계: speech_rate = (rate / 200 − 1) × 100, 즉 200 = 원래 속도, 220 = +10%, 180 = −10%

• 시나리오 기본 기울기(이 프로젝트 실측 권장): 시작 190 → 상호작용 200 → 마일스톤/오류 210 → 완료 220

六、블루투스 선행 무음(중요)

cloud.leadingSilence(기본값 1500, 즉 1.5초):

블루투스 이어폰 사용자를 위해 설계된 파라미터입니다. 블루투스 오디오 링크가 연결되는 데 약 1–2초가 걸리며, 재생 시작 시 이어폰이 연결되지 않은 상태인 경우가 많아 첫 글자가 연결 잡음에 삼켜집니다. 이 파라미터는 음성 데이터 맨 앞에 지정된 밀리초만큼 완전 무음을 삽입하여, 블루투스 링크가 준비된 후 음성이 시작되게 합니다.

• 블루투스 이어폰 사용자: 1500 유지(여전히 글자가 삼켜지면 2000으로 증가)

• 유선 이어폰 / 스피커 사용자: 0으로 변경하면 되며, 재생이 더 간결해집니다.

• 재생 전 알림음 자체도 오디오 출력이므로 블루투스 링크를 미리 깨우며, 이 파라미터와 함께 작동합니다.

七、전체 파라미터 표

예비 재생 채널(watcher, 선택)

watcher/voice-watcher.mjs는 MCP 연결에 의존하지 않는 상주 리스너입니다. ~/.trae-cn/work/.voice-reader/pending.txt를 폴링하여 마커 콘텐츠를 발견하면 주 서비스와 동일한 클라우드 엔진으로 재생합니다(구성, 음색, 볼륨이 실시간으로 동일 소스를 사용하며, 클라우드 실패 시 동일하게 SAPI로 폴백).

용도: Agent 세션에서 MCP 도구를 사용할 수 없을 때(예: 모델 전환, MCP 서비스 충돌)에도 해당 파일에 마커를 작성하여 재생을 트리거함으로써 폴백 채널을 형성합니다:

[VOICE_READER_START:success]
要播报的文本
[VOICE_READER_END]

타입은 info / success / error / warning을 지원하며, 각각 task_start / task_complete / task_error / need_interaction 시나리오 파라미터에 매핑됩니다.

활성화 방법: config.json에서 "watcher": { "enabled": true }로 설정합니다. 주 MCP 서비스 시작 시 자동으로 하위 프로세스로 띄우고, 종료 시 함께 정리합니다(TCP 단일 인스턴스 가드 47613, 다중 세션에서도 하나만 실행). 독립 실행도 가능합니다: node watcher/voice-watcher.mjs.

경로 이식성: 모든 경로는 상대적으로 유도되거나 os.homedir()로 연결되며, 하드코딩된 절대 경로가 없습니다. 환경 변수로 덮어쓸 수 있습니다: AGENT_VOICE_CONFIG(구성 파일 경로), AGENT_VOICE_PENDING_DIR(pending.txt가 있는 디렉터리, 기본값 ~/.trae-cn/work/.voice-reader, 다른 MCP 클라이언트에 맞게 조정).

주의사항

1. 구성은 MCP 시작 시 한 번 로드됩니다. config.json 수정 후에는 클라이언트를 재시작하거나 새 세션을 열어야 적용됩니다(재생할 때마다 다시 읽지 않습니다).

2. 샘플 레이트와 채널: 실측 결과 이 음색의 실제 대역폭은 ≤ 12kHz이며, 32/44.1/48kHz 요청은 단순 보간 업샘플링일 뿐 음질 개선이 없습니다(다중 창 FFT 주파수 대역 분석으로 검증됨). API는 모노 채널만 지원하며, 재생 시 시스템이 양쪽 귀에 자동으로 믹싱합니다. 24000을 유지하는 것이 최적입니다.

3. 감정은 클라이언트 측에서 구현됩니다: seed-tts-1.0의 v3 인터페이스는 서버 측 emotion 파라미터를 지원하지 않으며(실측 결과 전달해도 조용히 무시됨), 이 프로젝트는 음높이(pitch ±12) + 속도/볼륨 오프셋 조합으로 여섯 가지 감정을 표현하고, emotionIntensity가 강도를 제어합니다.

4. SSML을 켜지 마세요: SSML <break> 일시정지 태그는 1.0 + v3 스트리밍 인터페이스에서 실측 결과 오디오를 잘라냅니다(첫 문장만 합성). 긴 텍스트 일시정지는 이미 클라이언트 방식으로 구현되어 SSML이 필요 없습니다.

5. 할당량 및 과금: 火山引擎은 문자 수로 과금하므로 작업 알림 문구는 짧게 권장합니다(이 프로젝트의 기본 200자 잘림도 부분적으로 이 때문입니다). 할당량이 소진되면 자동으로 로컬 SAPI 음성으로 전환됩니다(음색이 바뀌는 것은 정상 현상입니다).

6. Windows 의존성: 알림음은 System.Console::Beep, 음성 재생은 PowerShell Media.SoundPlayer를 사용합니다. Windows에 기본 제공되지만, 그룹 정책에서 PowerShell이 비활성화되면 관련 기능이 저하됩니다.

7. 출력 디렉터리: 합성 오디오는 시스템 임시 디렉터리에 기록되어 재생 후 자동으로 정리되며, 잔여물이 없습니다.

감사의 말

• agent-voice-mcp 및 원저자 Antonio Liang — 이 프로젝트는 그의 MIT 오픈소스 코드를 기반으로 강화되었으며, 음색 역할, 다중 엔진 아키텍처 등 핵심 설계는 모두 원본에서 비롯되었습니다.

• 火山引擎 · 豆包 음성 합성 대모델

License

MIT(원 프로젝트 라이선스를 계승하며, 원작자 서명을 유지합니다)