Mcpal

MCPal

轻量级 MCP 服务，可发送原生桌面通知，并支持操作按钮、文本回复和识别大模型的图标。
兼容任何 MCP 客户端。

使用方法

手动添加到 MCP 配置中：

// 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 现在会返回双重格式：

• 通过 structuredContent 提供规范的机器可读输出（推荐用于解析）
• 在 content[0].text 中提供向后兼容的文本输出

结构化字段：

• status："sent" 或 "error"
• title?：通知标题
• message?：清理后实际发送的消息
• response?：通知响应（"timeout"、已点击的操作等）
• activationType?：触发来源（"replied"、"actionClicked" 等）
• reply?：用户的自由格式回复
• error?：当 status 为 "error" 时的错误消息
• sanitized?：当 MCPal 必须清理或截断输入时为 true

旧版文本仍按行组织，但为确保解析安全，每个值都会在单独一行以 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 个字符

识别大模型的图标

MCPal 会检测调用工具的 MCP 客户端，并在通知中显示相应图标。

客户端	图标
Claude Desktop / Claude Code / Opus	Claude 标志
Codex / OpenAI / ChatGPT	OpenAI 标志
Cursor	Cursor 标志
VS Code	VS Code 标志
未知	无图标

此功能通过 MCP 协议的客户端标识实现——每个客户端都会在初始化时发送名称。

添加新的客户端图标

要支持新的 LLM 客户端，请将 PNG 添加到 src/assets/clients/，并更新 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 许可证

MCPal 图标与品牌： © 2025 保留所有权利。未经许可，不得使用 MCPal 徽标和图标设计。