Simple Notify MCP

简单通知mcp

用于Codex和Claude Code的模型上下文协议（MCP）服务器，具有文本到语音（TTS）和电报通知功能。

工具

• simple_notify_status：始终可用；返回功能、缺少的配置和设置web可用性/运行状态。
• simple_notify_setup_web_start：可用时 --enable-setup-web 已设置；按需启动本地设置web UI，并返回当前标记的URL。
• simple_notify_setup_web_stop：可用时 --enable-setup-web 已设置；不再需要时停止本地设置web UI。
• tts_say：纯文本输入；默认情况下为async，使用配置的提供程序(openai, fal-minimax, fal-elevenlabs)使用macOS say 退路。
• telegram_notify：配置Telegram机器人令牌+聊天id时可用；支持 parse_mode (plain, markdown, html)并返回 hasUnreadIncoming 从一个不前进的未读窥视。
• telegram_send_photo：配置Telegram机器人令牌+聊天id时可用；发送本地图像文件(jpg, jpeg, png, webp, gif, bmp)带有可选字幕和 parse_mode.
• telegram_read_incoming：配置Telegram机器人令牌+聊天id时可用；读取已配置聊天的传入更新。
• telegram_read_media：配置Telegram机器人令牌+聊天id时可用；读取图像更新，并可以返回MCP图像内容块。

电报格式化快速示例：

• telegram_notify({ "text": "**Build done**. [Diff](https://example.com)", "parse_mode": "markdown" })
• telegram_send_photo({ "filePath": "/tmp/plan.png", "caption": "Plan snapshot", "parse_mode": "html" })
• Markdown模式支持安全子集： **bold**, *italic*, _italic_, ~~strike~~, ` code , text，以及 #` 标题。
• HTML模式已验证，只允许Telegram安全标签；链接必须 https:// 或 http://.
• 如果Markdown实体解析在Telegram端失败，服务器将使用纯文本重试一次以确保可靠性。
• 发送前强制执行电报限制（消息：4096个字符，标题：1024个字符）。

安装（npx）

1） 推荐：代理管理的安装网站

如果您希望在任何时候都能轻松重新配置，而无需始终保持HTTP端口打开，请使用此选项。

codex mcp remove simple-notify
codex mcp add simple-notify -- \
  npx -y simple-notify-mcp@latest \
  --enable-setup-web

请您的代理（Codex/Claude Code/另一个代理）运行 simple_notify_status，呼叫 simple_notify_setup_web_start 如果需要，然后发送给您 setupWeb.url.

2） 最短运行时间：无需设置网站

如果配置已经完成，并且您不希望安装服务器运行，请使用此选项。

codex mcp remove simple-notify
codex mcp add simple-notify -- npx -y simple-notify-mcp@latest

如果以后需要更改提供者/密钥，请切换回模式1。

可选：添加时通过env传递API密钥：

codex mcp add simple-notify -- \
  --env OPENAI_API_KEY="$OPENAI_API_KEY" \
  --env FAL_KEY="$FAL_KEY" \
  -- npx -y simple-notify-mcp@latest \
  --enable-setup-web \
  --setup-port 21420

可选的遗留行为：

• 添加 --setup-web-autostart 如果您明确希望在MCP启动期间绑定安装web服务器

安装（克劳德代码）

1） 推荐：代理管理的安装网站

如果您希望在任何时候都能轻松重新配置，而无需始终保持HTTP端口打开，请使用此选项。

claude mcp remove simple-notify
claude mcp add --transport stdio simple-notify -- \
  npx -y simple-notify-mcp@latest \
  --enable-setup-web

让Claude Code运行 simple_notify_status，呼叫 simple_notify_setup_web_start 如果需要，然后分享 setupWeb.url.

2） 最短运行时间：无需设置网站

如果配置已经完成，并且您不希望安装服务器运行，请使用此选项。

claude mcp remove simple-notify
claude mcp add --transport stdio simple-notify -- npx -y simple-notify-mcp@latest

如果以后需要更改提供者/密钥，请切换回模式1。

可选：添加时通过env传递API密钥：

claude mcp add --transport stdio \
  --env OPENAI_API_KEY="$OPENAI_API_KEY" \
  --env FAL_KEY="$FAL_KEY" \
  simple-notify -- \
  npx -y simple-notify-mcp@latest \
  --enable-setup-web

可选的遗留行为：

• 添加 --setup-web-autostart 如果您明确希望在MCP启动期间绑定安装web服务器

如何使用

想到 simple-notify-mcp 作为您的“代理通信层”：

• 工作完成时的语音信息(tts_say)
• 工作完成或进行中时，电报ping(telegram_notify)
• 可选的Telegram收件箱读取(telegram_read_incoming, telegram_read_media)

典型流程

1. 首先启用设置web（上面推荐的模式）。这暴露了安装web启动/停止工具，但尚未打开本地端口。

1. 向您的代理询问安装链接：

• “跑 simple_notify_status。如果安装网站未运行，请调用 simple_notify_setup_web_start 并发送给我 setupWeb.url."

1. 打开链接，设置密钥/提供者/聊天id，然后单击“保存”。

在某些客户端中，您可能需要在添加密钥后重新启动代理进程，以便所有工具都可用。

1. 配置完成后，请您的代理致电 simple_notify_setup_web_stop.

1. 之后，请您的代理人始终：

• 发言完毕
• 完成后发送电报
• 在长任务期间发送Telegram更新

问你的代理人什么（示例）

• 设置：

- “请配置简单通知并给我设置链接。”

• 完成行为：

- “当你完成一项任务时，打电话给TTS和Telegram通知。”

• 长任务行为：

- “如果任务很长，请在进度里程碑和升级请求之前通知我。”

• 读取收到的电报：

- “如果通知结果显示未读传入，请阅读并继续。”

TTS/通知风格提示（简单实用）

您可以调整：

• 语言（EN/RU/等）
• 语气（平静/精力充沛/正式/随意）
• 情绪（中性/愉快/严肃）
• 俚语水平
• 步调

示例：

• EN冷静：

- Task complete. Build passed. I left a short summary.

• EN乐观：

- Done. All checks are green.

• RU中性：

- Готово. Проверки прошли успешно.

• RU休闲装：

- Запилил фичу, всё пашет, тесты зеленые.

复制粘贴到AGENTS.md/CLAUDE.md

调整代理行为的最简单方法是在代理配置中添加明确的工具使用说明。 您可以复制粘贴此块并根据需要进行调整：

If user uses simple-notify-mcp:

1) Setup flow
- Call simple_notify_status.
- If setupWeb.enabled=true and setupWeb.running=false, call simple_notify_setup_web_start.
- If setupWeb.running=true, return setupWeb.url to user.
- When setup is finished or user asks to close it, call simple_notify_setup_web_stop.
- If setup web is disabled, tell user to run MCP with --enable-setup-web.

2) Completion flow
- On task completion, call tts_say with a short completion message.
- Then call telegram_notify with a short completion summary.
- If telegram_notify returns hasUnreadIncoming=true, optionally call telegram_read_incoming.

3) Long-task flow
- For long tasks, send milestone progress via telegram_notify.
- Send a notify before asking user for escalation/approval.
- Keep updates useful (no spam).

4) Safety
- Never include secrets/tokens in TTS or Telegram messages.

配置架构

配置文件路径（默认）：

• $XDG_CONFIG_HOME/simple-notify-mcp/config.json
• 或 ~/.config/simple-notify-mcp/config.json

Env键优先级：

• OPENAI_API_KEY 覆盖 keys.openai.apiKey
• FAL_KEY / FAL_API_KEY 以（权力）否决 keys.fal.apiKey

{
  "tts": {
    "provider": "openai",
    "params": {
      "openai": {
        "model": "gpt-4o-mini-tts",
        "voice": "alloy",
        "speed": 1,
        "responseFormat": "mp3",
        "instructions": "Speak calmly and clearly."
      },
      "falMinimax": {
        "voiceId": "Wise_Woman",
        "speed": 1,
        "vol": 1,
        "pitch": 0,
        "emotion": "neutral",
        "englishNormalization": false,
        "languageBoost": "auto",
        "outputFormat": "url",
        "audioFormat": "mp3",
        "audioSampleRate": 32000,
        "audioChannel": 1,
        "audioBitrate": 128000,
        "normalizationEnabled": true,
        "normalizationTargetLoudness": -18,
        "normalizationTargetRange": 8,
        "normalizationTargetPeak": -0.5,
        "voiceModifyPitch": 0,
        "voiceModifyIntensity": 0,
        "voiceModifyTimbre": 0,
        "pronunciationToneList": [
          "燕少飞/(yan4)(shao3)(fei1)"
        ]
      },
      "falElevenlabs": {
        "voice": "Rachel",
        "stability": 0.5,
        "similarityBoost": 0.75,
        "style": 0,
        "speed": 1,
        "timestamps": false,
        "languageCode": "en",
        "applyTextNormalization": "auto"
      }
    }
  },
  "telegram": {
    "chatId": "123456789"
  },
  "keys": {
    "openai": {
      "apiKey": "sk-..."
    },
    "fal": {
      "apiKey": "fal_..."
    },
    "telegram": {
      "botToken": "123:ABC"
    }
  },
  "misc": {
    "ttsAsyncByDefault": true
  }
}

设置UI中提供MiniMax语音：

• Wise_Woman, Friendly_Person, Inspirational_girl, Deep_Voice_Man, Calm_Woman, Casual_Guy, Lively_Girl, Patient_Man, Young_Knight, Determined_Man, Lovely_Girl, Decent_Boy, Imposing_Manner, Elegant_Man, Abbess, Sweet_Girl_2, Exuberant_Girl

设置Web UI标志（默认禁用）

旗帜：

• --enable-setup-web （默认关闭）
• --setup-web-autostart （默认关闭；可选的传统急启动行为）
• --setup-host （默认值 127.0.0.1；非环回值被限制为 127.0.0.1)
• --setup-port （默认值 21420)
• --setup-token （可选；如果省略，则每次运行生成）

行为：

• --enable-setup-web 公开按需设置web工具，但不自行绑定端口
• simple_notify_setup_web_start 仅在代理需要时启动本地安装服务器
• simple_notify_setup_web_stop 完成后关闭本地安装服务器
• --setup-web-autostart 如果您明确希望恢复之前的行为，则恢复渴望启动
• 仅限本地绑定
• 如果 --setup-port 已占用，服务器使用下一个空闲的本地端口
• 安装URL包含当前运行令牌查询参数
• 如果 --setup-token 省略，每次重新开始都会生成一个新的令牌
• 使用 simple_notify_status 发现安装网站是否正在运行，另外 setupWeb.url 和 missingConfig

工具合同

simple_notify_status

输入：

{}

simple_notify_setup_web_start

输入：

{}

输出注释：

• 仅在以下情况下启动设置web --enable-setup-web 已设置
• 返回当前设置web状态，包括 setupWeb.url
• 如果已运行，则返回现有URL而不重新绑定

simple_notify_setup_web_stop

输入：

{}

输出注释：

• 可以安全地反复呼叫
• 回报 wasRunning=false 当安装web已停止时

tts_say

输入：

{ "text": "Job done" }

输出注释：

• 默认模式为异步(misc.ttsAsyncByDefault=true)，因此工具在排队发言后立即返回
• 集 misc.ttsAsyncByDefault=false 在“设置web杂项”选项卡中设置阻止/同步行为

电报通知

输入：

{ "text": "Job done" }

输出注释：

• 回报 { "accepted": true } 默认情况下
• 添加 hasUnreadIncoming: true 仅当检测到未读消息时
• 执行非前进的未读窥视(limit=6)返回之前

telegram_read_income

输入：

{
  "limit": 20,
  "timeoutSeconds": 0,
  "advanceCursor": true
}

输出注释：

• 读取筛选到配置的更新 telegram.chatId
• 跟踪当前服务器运行时内存中的光标
• 集 advanceCursor=false 在不移动光标的情况下偷看

telegram_read_media

输入：

{
  "limit": 20,
  "timeoutSeconds": 0,
  "advanceCursor": true,
  "includeData": true,
  "maxImages": 1,
  "maxBytesPerImage": 8000000
}

输出注释：

• 仅返回图像媒体（忽略纯文本更新）
• 当 includeData=true，工具可以返回MCP image 内容块（base64+mime类型）
• 根据以下内容跳过大文件 maxBytesPerImage
• 在内存中跟踪当前服务器运行的媒体光标

自检

npm run self-test -- --text "Task complete. Build passed and your results are ready."

禁用一侧：

npm run self-test -- --no-tts
npm run self-test -- --no-telegram

备注

• tts_say 仅为文本；提供者/模型/语音等是服务器配置。
• tts_say 默认情况下运行async；在设置网站中切换 Misc 如果您需要同步模式，请使用选项卡。
• OpenAI和FAL网络错误追溯到macOS say 如果可用。
• 开放人工智能 responseFormat=pcm 不能通过此本地玩家路径直接播放。
• 在调用工具之前，会从磁盘重新加载运行时配置，因此无需重新启动MCP进程即可进行手动配置编辑。