MCPal
Lightweight MCP server for native desktop notifications with action buttons, text replies, and LLM-aware icons.
Compatible with any MCP client.
用法
手动添加到MCP配置中：
// JSON
{
"mcpServers": {
"mcpal": {
"command": "npx",
"args": ["mcpal@latest"]
}
}
}或TOML（食品法典委员会）：
// TOML
[mcp_servers.mcpal]
command = "npx"
args = ["-y", "mcpal@latest"]Codex CLI
直接通过CLI添加MCPal：
codex mcp add mcpal -- npx -y mcpal@latest克劳德代码
直接通过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的客户端（游标、带MCP扩展的VS代码等）。设置因客户端而异-有关添加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?:true当MCPal必须对输入进行消毒或截断时
遗留文本仍然是基于行的，但为了解析器的安全性，每个值都是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客户端正在调用该工具，并在通知中显示相应的图标。
| 客户端 | 图标 |
|---|---|
| 克劳德桌面/克劳德代码/作品 | 克劳德标志 |
| Codex/OpenAI/ChatGPT | OpenAI标志 |
| 光标 | 光标标志 |
| VS代码 | VS代码徽标 |
| 未知 | 无图标 |
这是通过MCP协议的客户端标识来实现的——每个客户端在初始化过程中发送其名称。
添加新客户端图标
要添加对新LLM客户端的支持，请将PNG添加到 src/assets/clients/ 并在中更新映射 src/notify.config.ts.
图标规格：
| 财产 | 要求 |
|---|---|
| 格式 | 透明PNG（RGBA） |
| 尺寸 | 128×128像素 |
| 文件大小 | \通知>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:fixMCP检查员
使用官方检查器交互式测试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徽标和图标设计。