AI导哈

MCP服务器通知工具

MCPal是一个轻量级的MCP服务器，支持原生桌面通知，带有操作按钮、文本回复和LLM感知图标，兼容任何MCP客户端。

  • by mjkid221
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 mjkid221/MCPal

使用说明

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像素
文件大小 <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

自定义应用图标

该软件包包括一个自定义通知图标，用于替换桌面上的默认终端图标。这是在安装过程中通过自动配置的 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检查员

使用官方检查器交互式测试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徽标和图标设计。

相关 MCP