Mcpal

MCPal

アクションボタン、テキスト返信、LLM 対応アイコンを備えた、ネイティブデスクトップ通知用の軽量 MCP サーバーです。
あらゆる MCP クライアントと互換性があります。

使い方

MCP Config に手動で追加します：

// JSON
{
  "mcpServers": {
    "mcpal": {
      "command": "npx",
      "args": ["mcpal@latest"]
    }
  }
}

または TOML（Codex）：

// TOML
[mcp_servers.mcpal]
command = "npx"
args = ["-y", "mcpal@latest"]

Codex CLI

CLI から MCPal を直接追加します：

codex mcp add mcpal -- npx -y mcpal@latest

Claude Code

CLI から MCPal を直接追加します：

# Project scope (current project only)
claude mcp add mcpal -- npx -y mcpal@latest

# User scope (available in all projects)
claude mcp add mcpal --scope user -- npx -y mcpal@latest

プロアクティブ通知の設定

MCPal には、通知の使い方をクライアントに伝える MCP 命令が組み込まれています。アシスタントがいつプロアクティブに通知するかを設定するには、クライアントの指示ファイルに以下を追加します。モデルに応じて、AGENTS.md または CLAUDE.md を指定してください：

## Post Task Completion Hook

ALWAYS use MCPal MCP tool (if available) to notify me when you finish any tasks (this includes reading files, investigating, coding). You should use this tool before you terminate conversations. Refer to tool instructions precisely to craft your response.

好みに合わせてカスタマイズしてください。頻繁な更新を望むユーザーもいれば、重要な判断が必要なときだけ通知を望むユーザーもいます。

その他の MCP クライアント

MCPal は、あらゆる MCP 互換クライアント（Cursor、MCP 拡張機能を備えた VS Code など）で動作します。設定方法はクライアントによって異なるため、MCP サーバーの追加方法については、各クライアントのドキュメントを参照してください。

ツール：send_notification

オプション機能を指定して、ネイティブ通知を送信します。

パラメーター

パラメーター	型	必須	説明
message	string	はい	通知本文のテキスト
title	string	いいえ	通知タイトル（デフォルト：「MCPal」）
actions	string[]	いいえ	アクションボタン（例：["Yes", "No", "Maybe"]）
dropdownLabel	string	いいえ	アクションのドロップダウンのラベル（複数のアクションがある場合に必須）
reply	boolean	いいえ	テキスト返信入力を有効にするかどうか

例

シンプルな通知：

{
  "message": "Build complete!",
  "title": "CI/CD"
}

アクション付き：

{
  "message": "Deploy to production?",
  "title": "Deployment",
  "actions": ["Deploy", "Cancel"],
  "dropdownLabel": "Choose"
}

返信付き：

{
  "message": "What should I name this file?",
  "title": "Question",
  "reply": true
}

アプリを切り替えずに、通知から直接返信できます：

ツールの戻り値の仕様

send_notification は、2 種類の形式で値を返します：

• 解析に推奨される、structuredContent による標準の機械可読出力
• content[0].text による後方互換性のあるテキスト出力

構造化フィールド：

• status：「sent」または「error」
• title?：通知タイトル
• message?：サニタイズ後に実際に送信されたメッセージ
• response?：通知への応答（「timeout」、クリックされたアクションなど）
• activationType?：アクティベーション元（「replied」、「actionClicked」など）
• reply?：ユーザーの自由形式の返信
• error?：status が「error」の場合のエラーメッセージ
• sanitized?：MCPal が入力をサニタイズまたは切り詰めた場合は true

従来のテキスト出力も引き続き行単位ですが、パーサーの安全性を確保するため、各値は 1 行の JSON としてエンコードされます。例：

status: "sent"
title: "MCPal"
message: "Line 1\nLine 2"
response: "timeout"

入力のサニタイズ

通知の送信前に、MCPal は通知機能やパーサーのエラーを減らすため、可能な範囲で入力をサニタイズします：

• 改行を正規化：\r\n / \r -> \n
• 安全でない制御文字を削除（\n と \t は保持）
• 長さの上限：
  • title：256 文字
  • message：4000 文字
  • actions：最大 3 項目、各 64 文字
  • dropdownLabel：64 文字

LLM 対応アイコン

MCPal は、ツールを呼び出している MCP クライアントを検出し、通知に適切なアイコンを表示します。

クライアント	アイコン
Claude Desktop / Claude Code / Opus	Claude のロゴ
Codex / OpenAI / ChatGPT	OpenAI のロゴ
Cursor	Cursor のロゴ
VS Code	VS Code のロゴ
不明	アイコンなし

これは MCP プロトコルのクライアント識別機能を利用しており、各クライアントは初期化時に自身の名前を送信します。

新しいクライアントアイコンの追加

新しい LLM クライアントをサポートするには、src/assets/clients/ に PNG を追加し、src/notify.config.ts のマッピングを更新します。

アイコンの仕様：

プロパティ	要件
形式	透過 PNG（RGBA）
寸法	128×128 ピクセル
ファイルサイズ	<10KB（圧縮には pngquant を使用）

# Optimize a new icon
convert input.png -resize 128x128 -background none -gravity center -extent 128x128 temp.png
pngquant --quality=65-80 --output src/assets/clients/newclient.png temp.png
rm temp.png

カスタムアプリアイコン

このパッケージには、デスクトップのデフォルトの Terminal アイコンを置き換えるカスタム通知アイコンが含まれています。これは、インストール時に postinstall スクリプトによって自動的に設定されます。

通知の許可

最初の通知の後、システムから「MCPal」からの通知を許可するよう求められる場合があります。次の場所で管理できます。

システム設定 > 通知 > MCPal

開発

# Install dependencies
pnpm install

# Build (required after clone - sets up desktop notification app)
pnpm run build

# Type check
pnpm run typecheck

# Lint
pnpm run lint:fix

# Format
pnpm run format:fix

MCP Inspector

公式インスペクターを使用して、MCP サーバーを対話的にテストします。

pnpx @modelcontextprotocol/inspector node dist/index.js

Web UI が開き、次の操作を行えます。

• 利用可能なツールとそのスキーマを確認する
• さまざまなパラメーターを指定してテスト通知を送信する
• MCP プロトコルメッセージの生データを確認する

ローカル開発のトラブルシューティング

dist/index.js からローカルビルドを直接実行して通知が機能しない場合は、エントリーポイントが実行可能であることを確認してください。

chmod +x dist/index.js

通知のテスト

MCP サーバーを実行せずに、通知システムを直接テストします。

# Simple notification (default)
pnpm run test:notification

# With action buttons
pnpm run test:notification actions

# With reply input
pnpm run test:notification reply

# Run all tests
pnpm run test:notification all

ライセンス

コード： MIT License

MCPal のアイコンとブランディング： © 2025 All Rights Reserved. MCPal のロゴおよびアイコンのデザインを、許可なく使用することはできません。