Simplepush

@simplepush/mcp

Simplepush 的 MCP 服务。Agent 可向人们的手机发送任务和通知，并等待答复、追加后续消息、取消错误操作，还能查询所有返回内容的记录。任务、答案、回复、拒绝和临时提交的内容都会保留，供后续查询，因此这一信息流也兼作工作知识库：询问了什么、谁回答了什么，以及哪些事项仍未解决。

工具

工具	功能
send_notification	推送提醒和提示。可携带一个 input（文本输入、选项或操作按钮）；发送后立即返回，除非设置了 wait_seconds。默认向每位接收者发送一份副本——结果会为每个人列出一个 notification_id；设置 shared: true 则发送一份所有接收者都能看到的通知。
send_task	发送任务并等待答复。接受完整的输入集合（文本、选项、操作、滑块、照片、语音录音、文件、位置）、tag、reply 模式、expires_at、Markdown 和链接。默认向每位接收者发送一份副本：等待所有人答复，并在截止时间报告每位接收者的结果以及仍待答复的人。设置 shared: true 则发送一项所有接收者共同作答的任务，以最先收到的答复为准。每个结果都包含 append_token。
append_subtask	使用 send_task 返回的 append_token，向任务或任务组追加后续问题或清单项。不会等待。
cancel_task	按 ID 撤回任务（tsk_）、子任务（sub_）或整个任务组（grptsk_），可选择填写原因和备注。
get_task_answer	获取先前 send_task 调用所对应的 task_id 的答复，或 append_subtask 调用所对应的 subtask_id 的答复。
get_notification_answer	获取先前带有输入的 send_notification 调用所对应的 notification_id 收到的内容。
query_tasks	返回一页任务摘要：标签、主题、状态、接收者、输入类型、附件类型、答复模式、发送时间、子任务数量。筛选条件：状态、时间范围、主题、成员、群组。
get_task	返回一项任务及其所有子任务：问题、答复、回复、拒绝和文件 ID。
get_group_status	返回任务组（grptsk_）中每位接收者的状态：谁已答复、谁尚未答复。
query_events	组织的活动历史：答复、回复、提交、拒绝、取消、过期记录，以及相关人员和时间。默认查询最近 7 天。
query_submissions	来自一线的临时报告（文本、照片、文件、语音、位置），以及相关人员和时间。默认查询最近 7 天。
search_knowledge	对所有内容进行全文和位置搜索，包括任务和通知、人员的答复和回复，以及所有时间范围内的临时提交。支持字面词匹配，以及最多三种语言的词干提取；也可使用坐标加半径（或由角点构成的多边形），按距离由近到远返回其中记录的位置。每条结果都包含用于读取完整内容的 ID（群组发送的任务只命中一次，使用其 grptsk_ ID），以及片段或带距离的坐标点。仅搜索纯文本记录。
get_activity	一次调用即可获取一位成员或整个组织的所有活动：未完成／已拒绝／已过期的任务，以及所选时间范围内的答复、回复、拒绝、取消和提交。适用于“X 有什么问题吗？”和“告诉我最新情况”等查询。
download_attachment	通过 scope_id（所属任务或提交的 tsk_／sub_／sbm_ ID）和 file_id（答复的 inputId、回复或提交中文件的 ID）获取照片、语音录音或文件。图片会直接内嵌返回。

查询工具支持两种模式：组织凭证（集成令牌，或以组织管理员身份登录的托管连接器）可读取整个组织；个人凭证（API 令牌，或使用个人 API 令牌的托管连接器）可读取你的个人动态（个人账户需要订阅）。在托管传输模式下，这些工具需要 read 作用域；download_attachment 还需要 files:read。加密内容会使用服务端持有的密钥解密；无法解密的内容会保留为密文并报告。

send_task 超时并不代表任务已取消。问题仍会显示在手机上，之后可通过 get_task_answer 或 get_group_status 获取答复。inputs 用于指定任务的答复方式：文本、单选或多选、操作按钮、滑块、照片、语音录音、文件、位置。send_task 默认等待 90 秒；每次调用可通过 wait_seconds 延长等待时间，但不能超过 SP_MAX_WAIT_SECONDS。

设置

服务以两种模式之一运行，具体取决于你设置的凭据。

个人模式

在 Simplepush 应用的 API Token 页面获取 API token，然后：

{
  "mcpServers": {
    "simplepush": {
      "command": "npx",
      "args": ["-y", "@simplepush/mcp"],
      "env": { "SP_API_TOKEN": "your-token" }
    }
  }
}

或者使用 Claude Code：

claude mcp add simplepush --env SP_API_TOKEN=your-token -- npx -y @simplepush/mcp

消息会发送到你自己的设备。传入 topic，则会改为发送给该主题的持有者，作为一项共享任务，由最先回复的人获胜。

组织模式

使用 CLI 创建集成 token（管理员保险库已解锁）：

sp integration create

claude mcp add simplepush --env SP_INTEGRATION_TOKEN=spi_... -- npx -y @simplepush/mcp

组织模式支持完整的目标选择：每次发送必须且只能指定 topic、member（名称或 usr_ ID）或 broadcast 之一。只会列出该 token 的作用域所涵盖的工具：使用 read files:read 创建的 token 会公开查询和下载工具，不会公开任何发送工具，从而最大限度地减少 Agent 在每次请求中携带的只读工具架构。如果组织启用了加密，token 的后半部分会在启动时解封组织主密钥，所有发送内容都会进行端到端加密；回复也会以相同方式解密。

如果同时设置了两种凭据，则以集成 token 为准，并向 stderr 输出提示。MCP 客户端会在附带 shell 环境的情况下启动 stdio 服务，因此其他 CLI 操作中导出的 SP_API_TOKEN 也会随之传入；设置 SP_INTEGRATION_TOKEN 则始终是有意为之。

环境变量（stdio）

变量	默认值	含义
SP_API_TOKEN	需要一种凭据	来自应用的个人 API token。
SP_INTEGRATION_TOKEN	需要一种凭据	通过 sp integration create 创建的组织集成 token。
SP_KEYS	未设置	个人加密密钥，见下文。
SP_BASE_URL	https://api.simplepu.sh	API 源地址。本地开发时指向 http://localhost:8000。
SP_MAX_WAIT_SECONDS	900	send_task 可能阻塞的最长时间。单次调用的 wait_seconds 不会超过此值。
SP_POLL_INTERVAL_MS	2000	阻塞等待时，两次轮询回复之间的间隔。
SP_SCOPES	未设置	以空格或逗号分隔的作用域代码（send、read、files:read）；只会列出其涵盖的工具。用于缩小集成 token 自身的作用域；对于个人 API token，这是缩减工具列表的唯一方式，因为后端始终将其视为拥有完整访问权限。

加密

如上所述，当组织启用加密时，组织模式会自动加密。

个人模式的发送内容默认为明文，除非你提供密钥。在应用中，加密任务和明文任务一目了然：加密任务会显示锁形图标。

密钥从 Simplepush 应用导出：在 Encryption 页面点击 Copy Key for Integrations，获取 Personal Password 密钥；在 Topics 页面点击主题旁边的复制操作，获取主题密钥。

SP_KEYS 是以逗号分隔的列表。单独的 base64 密钥是 Personal Password 密钥，用于向自己发送内容。topic=key 将密钥绑定到一个主题：

SP_KEYS="AbC...="                        # default key only
SP_KEYS="alerts=AbC...=,deploys=XyZ...="  # two topic keys
SP_KEYS="AbC...=,alerts=XyZ...="          # both

如果密钥匹配，则发送到该目标的内容会加密，回复也会解密。对于服务器没有密钥的回复，会返回 undecryptable: true，而不会悄悄返回错误内容。

仅支持密钥。没有 SP_PASSWORD。

托管式 HTTP 传输

simplepush-mcp-http 通过 Streamable HTTP 提供相同的工具，并作为 OAuth 资源服务器运行。不会使用环境凭据：每个请求都携带自己的访问令牌，并通过向授权服务器进行内省来验证，同时根据 SP_CANONICAL_URI 检查受众。发现元数据位于 /.well-known/oauth-protected-resource；MCP 端点为 /mcp。GET /status 是供运行时间监控使用的公开摘要：授权服务器和 API 均有响应时返回 200，否则返回 503；其结构与后端的 /v1/status 相同。工具按作用域进行限制：send 适用于 send_notification、send_task、append_subtask 和 cancel_task；read 适用于答案和查询工具；files:read 适用于 download_attachment。授权只会列出其作用域所涵盖的工具；直接调用其他工具时会被拒绝，并收到指出缺少作用域的质询。

托管模式仅支持个人 OAuth 授权。按设计，此模式不接受集成令牌，且托管发送内容为明文：能够替你解密的服务器就不可能实现端到端加密。

变量	默认值	含义
SP_INTROSPECTION_SECRET	必填	用于 AS 内省端点的 Bearer。必须与后端的 oauth.introspectionSecret 匹配。
SP_CANONICAL_URI	必填	客户端访问此服务器所用的公开 URL，例如 https://mcp.simplepu.sh/mcp。令牌的受众绑定到此 URL。
SP_OAUTH_ISSUER	https://api.simplepu.sh	客户端所见的授权服务器源站。
SP_AUTH_SERVER_URL	SP_OAUTH_ISSUER	此服务器用于访问授权服务器以进行令牌内省的地址。当后端通过内部地址更易访问时，请设置此项。
SP_BASE_URL	https://api.simplepu.sh	此服务器调用的 API 源站。
SP_MCP_PORT	8787	监听端口。

开发

npm install
npm run build
npm run typecheck

无需 MCP 客户端，即可针对本地后端进行冒烟测试：

npx @modelcontextprotocol/inspector --cli node dist/index.mjs \
  -e SP_API_TOKEN=testtoken5678 -e SP_BASE_URL=http://localhost:8000 \
  --method tools/list

请注意，Inspector 不会将 shell 环境传递给启动的服务器。请使用 -e 传递凭据，而不要通过导出环境变量来传递。