Model Context Protocol (MCP)

PushGo 现在原生支持 Model Context Protocol (MCP)。MCP 是一个开放协议，允许 AI 模型（如 Claude, ChatGPT 等）安全地访问本地或远程的工具与数据。

鉴权模式对比

PushGo 的 MCP 服务支持两种主要的鉴权与操作模式：

特性	OAuth2 授权模式 (推荐)	非授权 / Legacy 模式
安全性	高（基于授权令牌，权限受限）	中（基于网关 Token 或公开访问）
频道密码	无需在工具调用中提供密码	必须在每次调用中提供 `password`
配置流程	需进行一次性 OAuth 绑定流程	无需绑定，直接配置 URL
适用场景	生产环境、AI 助理、第三方集成	个人脚本、受信任的本地环境

核心功能介绍

PushGo MCP 服务器提供了以下核心能力：

1. 消息推送工具 (`mcp:tools`)

AI 模型可以使用以下工具进行各种推送操作：

消息发送

pushgo.message.send: 发送标准推送消息。
- 参数: channel_id (必填), title (必填), body, url, images, severity, ttl, metadata, thing_id (可选作用域)。
- 注意: OAuth2 模式下严禁传 password；Legacy 模式下必须传 password。

事件管理 (Event API)

pushgo.event.create: 创建一个新的生命周期事件。
pushgo.event.update: 更新现有事件的状态或信息。
pushgo.event.close: 关闭一个活动中的事件。
- 核心参数: event_id (更新/关闭时必填), status, message, severity, event_time, started_at, ended_at。

对象/实体管理 (Thing API)

pushgo.thing.create: 在频道中创建一个持久化的对象。
pushgo.thing.update: 更新对象属性。
pushgo.thing.archive: 归档对象。
pushgo.thing.delete: 彻底删除对象。
- 核心参数: thing_id (必填), title, description, tags, external_ids, location_type, location_value。

2. 授权与频道管理 (`mcp:channels:manage`)

用于管理 AI 助手与用户频道之间的绑定关系：

pushgo.channel.list: 列出当前 AI 助手已获得授权的所有频道及其基本信息。
pushgo.channel.unbind: 撤销 AI 助手对特定频道的访问权限。
pushgo.channel.bind.start: 发起频道绑定（或撤销）流程。
- 参数: action (“bind” 或 “revoke”), requested_channel_id (可选建议)。
- 返回: bind_url (用户需在浏览器中打开完成 OAuth 授权)。
pushgo.channel.bind.status: 轮询绑定会话的状态。
- 参数: bind_session_id。

3. 资源访问 (`mcp:channels:manage`)

AI 模型可以读取以下资源：

pushgo://channels: 所有已授权频道的列表。
pushgo://channels/{channel_id}: 特定频道的详细状态和最近审计摘要。

如何使用

1. 启用 MCP

在你的私有部署环境中，设置以下环境变量：

PUSHGO_MCP_ENABLED=true
PUSHGO_PUBLIC_BASE_URL=https://your-gateway.com

2. 在 AI 客户端中配置

以 Claude Desktop 为例，在配置文件中添加：

{
  "mcpServers": {
    "pushgo": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/inspector", "https://your-gateway.com/mcp"]
    }
  }
}

(注：PushGo 使用基于 HTTP 的 SSE 或 JSON-RPC 传输，支持标准 OAuth2 鉴权)

3. 授权流程

AI 助手会首先尝试调用 pushgo.channel.bind.start。
它会提供一个授权 URL（如 https://your-gateway.com/mcp/bind/session?...）。
你在浏览器中打开该 URL，选择你想要授权给 AI 的频道。
授权完成后，AI 助手即可自动通过该频道发送消息。

权限说明 (Scopes)

MCP 访问受两个主要权限范围控制：

mcp:tools: 允许调用推送工具。
mcp:channels:manage: 允许管理频道授权和读取资源。

预定义客户端 (可选)

如果你希望避免动态注册，可以在启动时指定客户端：

PUSHGO_MCP_PREDEFINED_CLIENTS="my_client_id:my_client_secret"