Ray notifications

Ray MCP 服务

适用于通知投递 API Ray 的 MCP 服务。它可让 Claude、Cursor、VS Code、Windsurf、Codex、Zed 及其他 MCP 客户端，在你的 Ray 工作区中发送通知并管理模板、投递 Webhook 和用量。

这里的 Ray 是 gege.mn 提供的多租户通知 API（通过 Amazon SES 或 SMTP 发送邮件、Firebase 推送、Slack、Discord、Telegram、通过 Twilio 或 sendsms.mn 发送短信、通用 Webhook 和应用内动态流）。它不是 Ray 分布式计算框架。

托管还是本地？

Ray 会为你运行 MCP 服务。连接方式有两种，使用的工具相同：

	托管（推荐）	本地（此软件包）
运行内容	你的设备上无需运行任何内容	npx -y @gege-mn/ray-mcp，一个 stdio 进程
端点	https://ray-api.gege.mn/mcp（Streamable HTTP）	连接到托管端点
身份验证	Authorization: Bearer <key> 请求头	RAY_API_KEY 环境变量
适用情况	客户端支持带自定义请求头的远程服务	客户端仅运行 stdio 服务（例如 Claude Desktop 配置文件），或你更倾向使用环境变量而不是请求头

此软件包是一个轻量级桥接程序：它使用你的密钥连接到托管端点，并同步其工具列表、说明和指令，因此无需升级软件包即可使用新工具。所有验证、作用域、速率限制和配额均由 Ray API 强制执行。

1. 获取 API 密钥

1. 登录 ray.gege.mn，然后打开 API keys。
2. 创建一个密钥。密钥以 ck_live_ 开头，且仅显示一次。
   • read 作用域：状态、模板、用量、文档。
   • write 作用域：发送通知、创建或更改模板以及管理 Webhook 时也需要此作用域。
3. 在控制面板的 Channels 下至少配置一个渠道。无法通过 API 或 MCP 创建渠道凭据。

以下示例使用 ck_live_... 作为占位符。请勿将真实密钥纳入版本控制。

2. 将 Ray 添加到客户端

Claude Code

托管：

claude mcp add --transport http ray https://ray-api.gege.mn/mcp --header "Authorization: Bearer $RAY_API_KEY"

本地：

claude mcp add ray --env RAY_API_KEY=ck_live_... -- npx -y @gege-mn/ray-mcp

添加 --scope user，即可在每个项目中使用。运行 claude mcp get ray 检查连接。

Claude Desktop

编辑 claude_desktop_config.json（Settings → Developer → Edit Config；macOS：~/Library/Application Support/Claude/claude_desktop_config.json，Windows：%APPDATA%\Claude\claude_desktop_config.json），然后完全重启 Claude Desktop：

{
  "mcpServers": {
    "ray": {
      "command": "npx",
      "args": ["-y", "@gege-mn/ray-mcp"],
      "env": { "RAY_API_KEY": "ck_live_..." }
    }
  }
}

Cursor

在项目中使用 .cursor/mcp.json，或使用 ~/.cursor/mcp.json 配置所有项目。

托管：

{
  "mcpServers": {
    "ray": {
      "url": "https://ray-api.gege.mn/mcp",
      "headers": { "Authorization": "Bearer ck_live_..." }
    }
  }
}

本地：

{
  "mcpServers": {
    "ray": {
      "command": "npx",
      "args": ["-y", "@gege-mn/ray-mcp"],
      "env": { "RAY_API_KEY": "ck_live_..." }
    }
  }
}

Cursor 也可以从环境变量读取密钥："Authorization": "Bearer ${env:RAY_API_KEY}"。

VS Code（GitHub Copilot）

VS Code 的 mcp.json（工作区中的 .vscode/mcp.json，或 MCP: Open User Configuration）使用顶层 servers 键，并且可以提示输入密钥，避免将密钥存储在文件中：

{
  "inputs": [
    { "id": "ray-api-key", "type": "promptString", "description": "Ray API key (ck_live_...)", "password": true }
  ],
  "servers": {
    "ray": {
      "type": "http",
      "url": "https://ray-api.gege.mn/mcp",
      "headers": { "Authorization": "Bearer ${input:ray-api-key}" }
    }
  }
}

本地配置：将服务条目替换为 { "type": "stdio", "command": "npx", "args": ["-y", "@gege-mn/ray-mcp"], "env": { "RAY_API_KEY": "${input:ray-api-key}" } }。

Windsurf

~/.codeium/windsurf/mcp_config.json（Windsurf 将 URL 字段称为 serverUrl，并支持 ${env:VAR}）：

{
  "mcpServers": {
    "ray": {
      "serverUrl": "https://ray-api.gege.mn/mcp",
      "headers": { "Authorization": "Bearer ${env:RAY_API_KEY}" }
    }
  }
}

本地配置：使用与 Cursor 示例中相同的 command / args / env 条目。

Codex

~/.codex/config.toml，本地配置：

[mcp_servers.ray]
command = "npx"
args = ["-y", "@gege-mn/ray-mcp"]
env = { RAY_API_KEY = "ck_live_..." }

托管配置，从 shell 环境中读取密钥：

[mcp_servers.ray]
url = "https://ray-api.gege.mn/mcp"
bearer_token_env_var = "RAY_API_KEY"

也可以通过 CLI 添加：codex mcp add ray --env RAY_API_KEY=ck_live_... -- npx -y @gege-mn/ray-mcp。

Zed

在 Zed 的 settings.json 中：

{
  "context_servers": {
    "ray": {
      "url": "https://ray-api.gege.mn/mcp",
      "headers": { "Authorization": "Bearer ck_live_..." }
    }
  }
}

本地配置："ray": { "command": "npx", "args": ["-y", "@gege-mn/ray-mcp"], "env": { "RAY_API_KEY": "ck_live_..." } }。

其他客户端

任何可运行 stdio 服务的客户端：

{
  "mcpServers": {
    "ray": {
      "command": "npx",
      "args": ["-y", "@gege-mn/ray-mcp"],
      "env": { "RAY_API_KEY": "ck_live_..." }
    }
  }
}

任何支持 Streamable HTTP 的客户端：URL 为 https://ray-api.gege.mn/mcp，请求头为 Authorization: Bearer ck_live_...。

环境变量（本地包）

变量	必填	默认值	说明
RAY_API_KEY	是		Ray API 密钥（ck_live_...）。空格、引号和 Bearer 前缀会被移除。
RAY_MCP_URL	否	https://ray-api.gege.mn/mcp	要桥接到的托管端点。仅在暂存环境或本地开发时更改。

CLI 标志：--help、--version。需要 Node.js 18 或更高版本。

工具

工具列表来自托管服务，因此会随时间扩充；客户端会显示权威的说明和输入架构。当前工具：

工具	功能
whoami	显示当前使用的 API 密钥所属的工作区、密钥 ID 和权限范围。
get_usage	显示套餐、订阅状态以及本月相对于配额的用量。
list_channels	列出已配置的渠道及其 ID 和各自接受的收件人格式。请先调用此工具。
send_notification	发送通知（单条、扇出、多渠道或仅写入信息流）。需要 write 权限。
get_send_status	查看发送的投递状态，包含逐个收件人的记录。
list_templates	列出消息模板。
get_template	查看一个模板及其已发布版本和草稿。
create_template	创建模板，可选择是否发布。需要 write 权限。
update_template_draft	替换模板草稿。需要 write 权限。
publish_template	将模板草稿发布为当前生效版本。需要 write 权限。
archive_template	归档模板。需要 write 权限。
unarchive_template	恢复已归档的模板。需要 write 权限。
test_send_template	将已发布的模板实际发送给一位收件人进行测试。需要 write 权限。
list_feed_notifications	读取一位终端用户的应用内通知信息流。
get_click_stats	查看某次发送或营销活动的邮件链接点击次数。
list_webhooks	列出出站事件 Webhook 及其投递健康状况。
get_webhook	查看一个出站 Webhook。
create_webhook	创建出站 Webhook；签名密钥只返回一次。需要 write 权限。
update_webhook	修改 Webhook 或轮换其密钥。需要 write 权限。
delete_webhook	删除 Webhook。需要 write 权限。
read_docs	以 Markdown 格式读取 Ray 文档。

只读工具会标注 readOnlyHint；归档和删除工具会标注 destructiveHint，客户端可以在运行前询问确认。

示例提示词

• “通过 Ray 给我发送一封测试邮件。”
• “我有哪些 Ray 渠道？每个渠道需要什么收件人信息？”
• “在 Ray 中创建并发布一封欢迎邮件模板，使用 firstName 参数，然后向我发送测试邮件。”
• “发送 snd_... 是否已投递？请列出所有失败项。”
• “本月已发送多少条通知？还剩多少配额？”
• “为失败的投递配置一个 Ray Webhook，地址为 https://example.com/hooks/ray。”

故障排除

本地软件包始终会启动，即使出现问题也是如此；它会通过 MCP 说明问题，而不会崩溃。诊断信息会输出到 stderr（客户端的 MCP 日志）；stdout 仅传输 MCP 消息。

• 只列出了 setup_help 工具。 服务无法加载 Ray 的工具。工具描述会说明原因。未设置 RAY_API_KEY 时，每次工具调用都会返回设置步骤。如果端点无法访问，请修复原因后调用 setup_help：它会重试，成功后会通知客户端工具列表已更改。如果客户端没有刷新，请重新加载服务。
• “Ray rejected the API key (HTTP 401)”。 密钥错误、已撤销或粘贴不完整。请在 ray.gege.mn 创建新密钥，更新配置并重启客户端。
• “write scope required” 或 HTTP 403。 密钥为只读，或者你的套餐不包含此功能（webhook 需要 Pro 或更高级别套餐）。请使用具有 write scope 的密钥。
• HTTP 402 / 配额。 工作区已用完月度配额。请使用 get_usage 查看。
• HTTP 429。 请求受到速率限制；错误信息会说明需要等待多少秒。请参阅速率限制。
• “Could not reach Ray's MCP endpoint (ECONNREFUSED / ENOTFOUND / ...)”。 网络、代理或防火墙问题，或者 RAY_MCP_URL 设置错误。
• 找不到 npx 或 Node 版本过旧。 请安装 Node.js 18+，并确保客户端使用的 PATH 中包含 npx。在 macOS 上，图形界面应用可能无法获取 shell PATH 的更改；如有需要，请使用 npx 的绝对路径。
• 手动检查服务： RAY_API_KEY=ck_live_... npx -y @gege-mn/ray-mcp 应在 stderr 中记录 connected to https://ray-api.gege.mn/mcp，然后等待输入（按 Ctrl+C 退出）。或者使用 npx @modelcontextprotocol/inspector npx -y @gege-mn/ray-mcp 检查。

相关链接

• 文档：ray.gege.mn/docs，其中包含面向 Agent 的索引 ray.gege.mn/llms.txt（在任意文档 URL 后添加 .md 即可获取原始 Markdown）。MCP 设置指南：将 Ray 与 AI 编码 Agent 搭配使用。
• API 参考：ray-api.gege.mn/docs，OpenAPI 文档见 ray-api.gege.mn/openapi.json。
• TypeScript SDK：@gege-mn/ray（gege-mn/ray-node）。
• Agent 技能和 Claude Code 插件：gege-mn/ray-skills（npx skills add gege-mn/ray-skills）。

开发

pnpm install
pnpm typecheck
pnpm test        # vitest: bridge end to end against an in-process fake Ray endpoint
pnpm build       # tsup -> dist/index.js
pnpm smoke       # the built binary over real stdio
RAY_MCP_URL=http://localhost:8787/mcp RAY_API_KEY=ck_live_... node dist/index.js

发布：更新 package.json、server.json（两个 version 字段）和 src/version.ts 中的版本号，更新 CHANGELOG.md，然后发布标记为 vX.Y.Z 的 GitHub 版本。发布工作流会将软件包发布到 npm 和 MCP Registry。如需手动发布：运行 pnpm publish --access public，然后运行 MCP Registry 工作流（个人账号执行 mcp-publisher login github 无法在 gege-mn 命名空间下发布）。

许可证

MIT © gege.mn