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 経由の SMS、汎用 Webhook、アプリ内フィード）を指します。Ray 分散コンピューティングフレームワークではありません。

ホスト型とローカル型

Ray が MCP サーバーを実行します。同じツールを使う接続方法は 2 つあります。

	ホスト型（推奨）	ローカル型（このパッケージ）
実行するもの	お使いのマシンでは何も実行しません	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 で、少なくとも 1 つのチャネルを設定します。チャネルの認証情報は 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_..." }
    }
  }
}

環境変数からキーを読み込むこともできます："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_..." }

ホスト型の場合は、シェル環境からキーを読み込みます。

[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	公開済みバージョンと下書きを含むテンプレートを1つ取得します。
create_template	テンプレートを作成し、必要に応じて公開します。write が必要です。
update_template_draft	テンプレートの下書きを置き換えます。write が必要です。
publish_template	テンプレートの下書きを公開し、現在のバージョンにします。write が必要です。
archive_template	テンプレートをアーカイブします。write が必要です。
unarchive_template	アーカイブ済みのテンプレートを復元します。write が必要です。
test_send_template	公開済みテンプレートを1人の受信者に実際にテスト送信します。write が必要です。
list_feed_notifications	1人のエンドユーザーのアプリ内通知フィードを読み取ります。
get_click_stats	送信またはキャンペーンのメールリンクのクリック数を取得します。
list_webhooks	送信イベント用 Webhook とその配信状態を一覧表示します。
get_webhook	送信 Webhook を1つ取得します。
create_webhook	送信 Webhook を作成します。署名シークレットは一度だけ返されます。write が必要です。
update_webhook	Webhook を変更するか、シークレットをローテーションします。write が必要です。
delete_webhook	Webhook を削除します。write が必要です。
read_docs	Ray のドキュメントを Markdown として読み取ります。

読み取り専用ツールには readOnlyHint、アーカイブおよび削除ツールには destructiveHint の注釈が付いているため、クライアントは実行前に確認できます。

プロンプトの例

• 「Ray 経由で自分にテストメールを送信して。」
• 「Ray のチャネルは何があり、それぞれにどのような受信者を指定する必要がありますか？」
• 「Ray で firstName パラメーターを使ったウェルカムメールテンプレートを作成して公開し、自分にテスト送信して。」
• 「送信 snd_... は配信されましたか？失敗があれば表示してください。」
• 「今月は通知をいくつ送信しましたか？クォータはあとどれくらい残っていますか？」
• 「配信失敗用に https://example.com/hooks/ray への Ray Webhook を設定して。」

トラブルシューティング

ローカルパッケージは、問題が発生しても常に起動し、クラッシュする代わりに 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 スコープを持つキーを使用してください。
• 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 の GUI アプリではシェルの 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。エージェント向けのインデックスは ray.gege.mn/llms.txt にあります（ドキュメントの URL に .md を追加すると、Markdown の生データを取得できます）。MCP セットアップガイドはAI コーディングエージェントで Ray を使うです。
• API リファレンス：ray-api.gege.mn/docs、OpenAPI：ray-api.gege.mn/openapi.json。
• TypeScript SDK：@gege-mn/ray（gege-mn/ray-node）。
• エージェントスキルと 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