PowPow MCP 接口文档

服务名 powpow-mcp · 服务端版本 v0.23.5 · 工具数 34 · 文档更新 2026-11-04
English summary at the end of this page.

只想尽快连上？可以跳过协议细节，直接看 十一、在 AI 客户端中接入 —— 只需要填一条 URL，元数据发现、动态注册与 PKCE 都由客户端自动完成。

服务概览
连接与传输协议
鉴权（OAuth 2.1 + PKCE）
工具清单（34）
调用示例
限流与超时
写操作规则
错误码
隐私与合规
测试账号与联系
在 AI 客户端中接入

一、服务概览

PowPow（泡泡）是一个中文「附近发现」社交应用：用户在地图上发布带位置的帖子、创建可对话的数字人（AI 角色）、参与线下打卡活动。本 MCP 服务把上述内容与账号能力开放给 AI 客户端，让助手可以查询附近有什么、读取账号状态，并在用户确认后代为发帖、点赞、关注、收藏。

项目	值
MCP 端点	`https://global.powpow.online/api/mcp`
传输方式	Streamable HTTP（不是 SSE 长连接）
支持的 HTTP 方法	`POST`（JSON-RPC）、`GET`（可选的服务端推送）、`OPTIONS`
协议版本	2025-06-18 / 2025-11-25 / 2026-07-28（按 `initialize` 协商）
响应格式	`text/event-stream`（SSE，逐行 `data: {json}` 解析）
鉴权	OAuth 2.1 + PKCE（S256），支持动态客户端注册（DCR）
工具数量	34（20 个只读 + 14 个写）。另有一个默认关闭的诊断工具，仅在服务端开启 `MCP_ENABLE_PROBE` 时注册，不对外提供
官方站点	https://global.powpow.online

关于 SSE：即使请求体是普通 JSON-RPC，响应也以 text/event-stream 返回。客户端需要按行读取，取 data: 之后的内容作为 JSON 解析；同一响应内可能有多条事件。不要按 application/json 一次性 JSON.parse 整个响应体。

二、连接与传输协议

所有请求都是标准 MCP JSON-RPC 2.0。必需请求头：

Content-Type: application/json
Accept: application/json, text/event-stream
Authorization: Bearer <access_token>

服务端在响应头返回 Mcp-Session-Id 时，后续请求需带上同名请求头（Mcp-Session-Id）；服务端不强制要求，但带上可复用会话状态。CORS 允许任意来源（Access-Control-Allow-Origin: *），暴露 Mcp-Session-Id、Content-Type、WWW-Authenticate 三个响应头。

服务端同时兼容两种调用形态：传统形态（先 initialize 握手，再 tools/list、tools/call）与无握手的 modern envelope 形态（协议 2026-07-28，工具名与方法名通过 Mcp-Method / Mcp-Name 请求头镜像）。不支持现代化的客户端走传统形态即可。

三、鉴权（OAuth 2.1 + PKCE）

端点受 OAuth 2.1 保护，未携带有效 access token 时任何方法都会返回 401，包括 initialize。 401 响应通过 WWW-Authenticate 指明资源元数据位置：

HTTP/1.1 401 Unauthorized
www-authenticate: Bearer error="invalid_token",
  error_description="missing or invalid access token",
  resource_metadata="https://global.powpow.online/api/mcp/.well-known/oauth-protected-resource"

3.1 资源元数据（RFC 9728）

GET https://global.powpow.online/api/mcp/.well-known/oauth-protected-resource

{
  "resource": "https://global.powpow.online/api/mcp",
  "authorization_servers": ["https://xhahsqbaohraqrdhtvay.supabase.co/auth/v1"],
  "scopes_supported": ["openid", "profile", "email"],
  "resource_name": "PowPow",
  "resource_documentation": "https://www.powpow.online/"
}

3.2 授权服务器元数据

授权服务器由托管身份服务提供，与资源端点不在同一个域名——这是标准 MCP OAuth 架构： PowPow 自有域名只暴露资源端点，授权服务器地址通过资源元数据下发。 客户端不需要手工配置任何地址：读取 3.1 的资源元数据后，MCP 客户端会按 RFC 8414 自动前往 authorization_servers 指向的位置拉取下面的发现文档。

需要人工核对时，从本站入口获取即可（内容与授权服务器返回一致）：

GET https://global.powpow.online/api/mcp/.well-known/oauth-protected-resource → 读取 authorization_servers 字段

若平台要求手工填写端点（不走自动发现），下表可直接抄写。域名固定，不可替换： issuer 必须与资源元数据中 authorization_servers 的值逐字一致，换成其它域名会导致客户端在发现阶段校验失败、授权流程根本起不来。

端点	URL
issuer	`https://xhahsqbaohraqrdhtvay.supabase.co/auth/v1`
授权	`https://xhahsqbaohraqrdhtvay.supabase.co/auth/v1/oauth/authorize`
令牌	`https://xhahsqbaohraqrdhtvay.supabase.co/auth/v1/oauth/token`
动态注册（DCR）	`https://xhahsqbaohraqrdhtvay.supabase.co/auth/v1/oauth/clients/register`
用户信息	`https://xhahsqbaohraqrdhtvay.supabase.co/auth/v1/oauth/userinfo`
JWKS	`https://xhahsqbaohraqrdhtvay.supabase.co/auth/v1/.well-known/jwks.json`

3.3 授权流程要点

授权码模式，response_type=code；grant_types 支持 authorization_code 与 refresh_token。
PKCE 必填，code_challenge_method 支持 S256（推荐）与 plain。
支持动态客户端注册：无需提前申请 client_id，向 registration_endpoint POST 即可获得 client_id。私有协议回调（如 app://.../callback）与 HTTP 回环回调（http://127.0.0.1:{port}/callback）均被接受。
token_endpoint_auth_methods：client_secret_basic / client_secret_post / none。
scope：openid profile email（offline_access 用于获取 refresh token）。
若平台要求手工配置而非自动发现，可沿用上面的 authorize / token 端点，并自行完成一次 DCR 取得 client_id（及可选的 client_secret）。

四、工具清单（34）

标注说明：本服务未开放匿名访问，下表所有工具（含 initialize 与 tools/list）都必须携带有效 access token。需登录读取公开内容或本人数据，不修改任何数据；写会修改数据，受写权限开关与限流约束。

4.1 附近发现与内容检索（8）

工具名	说明
`find_nearby` 需登录	核心工具。按地名查找附近的公开数字人、真实用户与帖子。入参只要地名（`place`），不接收经纬度；服务端先经高德地图解析地名（返回 `matched_name` 与 `confidence` 匹配度），再检索周边内容。调用后以「PowPow 附近发现」卡片展示结果。
`nearby_attractions` 需登录	按地名查找附近的景点（`attractions`）与商圈（`business_districts`），各带距离。
`geocode_place` 需登录	地名转坐标，返回 `matched_name` 与 `confidence`。地名模糊时用于先核对再检索。
`get_digital_human` 需登录	数字人详情：人设（persona）、简介、头像、所在位置、当前情绪。
`get_post_detail` 需登录	单条公开帖子的完整正文与评论列表。
`get_post_replies` 需登录	某条公开帖子的评论：一级评论分页返回（最新在前），每条内嵌其下的回复，带作者昵称、时间与「评论 id」。要回复某条评论时，`reply_to_comment_id` 就用这里输出的 id。只想看正文用 `get_post_detail`。
`search_posts` 需登录	按关键词检索公开帖子（不区分大小写），返回摘要与位置。
`list_campaigns` 需登录	列出公开活动（如「北京 100 家博物馆」打卡活动）及其打卡点。

4.2 账号与自身数据（6）

工具名	说明
`whoami` 需登录	确认当前授权的账号（用户 ID、用户名、昵称）。
`get_my_account` 需登录	账号概览：昵称、徽章余额、会员等级与到期时间、帖子数、数字人数、加入时间、主页链接。
`my_posts` 需登录	本人发布的帖子（含位置、点赞/评论数、原帖链接）。
`get_my_post_replies` 需登录	别人给我的回音，两类都算：我帖子下的评论与回复，以及别人在他人帖子中回复我的话（自己回自己不算）。默认只返回「上次读过之后」的新内容；回溯历史传 `since_hours`。传 `mark_read=true` 会把本次返回标为已读——只在用户确实看过或已被转述时才传。
`my_digital_humans` 需登录	本人创建的数字人（是否过期、剩余天数、所在位置、对话链接）。
`get_badge_history` 需登录	徽章余额与发放/消耗流水。只读，不能通过接口增减徽章。

4.3 社交关系（7）

工具名	说明
`get_user_profile` 需登录	任意用户的公开主页：昵称、简介、徽章数、帖子/关注/粉丝数、最近 3 条帖子。
`search_users` 需登录	按用户名或昵称模糊搜索用户，最多 20 条。
`my_following` 需登录	我关注的人。
`my_followers` 需登录	关注我的人，每项带 `is_mutual`（是否互关）。
`list_friends` 需登录	好友列表。PowPow 的「好友」= 互相关注，没有好友申请流程。
`follow_user` 需登录写	关注某人。需 `user_id`（先用 `search_users` 查），重复关注不报错。
`unfollow_user` 需登录写	取消关注。未关注时返回 `removed: false`，不报错。

4.4 收藏（4）

工具名	说明
`list_favorites` 需登录	我的收藏，三类：地点 `location`、帖子 `post`、数字人 `digital_human`。
`add_favorite` 需登录写	加入收藏，可带分类、标签、备注。重复收藏不报错。
`update_favorite` 需登录写	修改收藏的分类/标签/备注，只改传入字段，无历史版本。
`remove_favorite` 需登录写	删除收藏，不存在时返回 `removed: false`。

4.5 内容发布与互动（6）

工具名	说明
`prepare_post` 需登录写	只生成草稿，不公开。正文最多 5000 字，可选 1-3 张对话内上传的图片，可带地名。
`publish_post` 需登录写	只有它能真正公开帖子，必须带 `draft_id`。同一 `draft_id` 重复调用不会重复发帖。
`delete_post` 需登录写	撤回通过 AI 发布、且发布后 24 小时内的帖子。站内自己发的帖子不在此列。
`like_post` 需登录写	点赞。已点过不报错；对即将过期的帖子点赞会延长其 24 小时。
`unlike_post` 需登录写	取消点赞。未点过不报错。
`reply_to_post` 需登录写	在某条公开帖子下发表评论；传 `reply_to_comment_id` 即为回复该评论（任意层级都直接回，无需自己判断）。正文 ≤500 字。以用户本人名义公开留言，发出前必须把正文原样念给用户确认。

4.6 资料与数字人（3）

工具名	说明
`update_profile` 需登录写	修改昵称（1-20 字）与简介（≤200 字）。头像不在此修改，需在站内操作。
`create_digital_human` 需登录写	创建数字人：扣 2 枚徽章，30 天后过期，创建后出现在地图上。位置用地名描述，不传坐标。
`delete_digital_human` 需登录写	撤销通过 AI 创建、24 小时内、且尚无人对话的数字人，退还 2 枚徽章。

五、调用示例

5.1 握手

POST /api/mcp HTTP/1.1
Host: global.powpow.online
Content-Type: application/json
Accept: application/json, text/event-stream
Authorization: Bearer <access_token>

{"jsonrpc":"2.0","id":1,"method":"initialize",
 "params":{"protocolVersion":"2025-06-18","capabilities":{},
           "clientInfo":{"name":"my-client","version":"1.0.0"}}}

响应（SSE）：

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18",
  "serverInfo":{"name":"powpow-mcp","version":"0.22.4"},
  "capabilities":{"tools":{}},"instructions":"PowPow 是「附近发现」社交应用…"}}

5.2 列出工具

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

5.3 调用工具（公开工具，无需账号数据）

{"jsonrpc":"2.0","id":3,"method":"tools/call",
 "params":{"name":"find_nearby","arguments":{"place":"北京天坛公园"}}}

返回为文本摘要（给模型）+ structuredContent（给界面渲染卡片）：

{"jsonrpc":"2.0","id":3,"result":{
  "content":[{"type":"text","text":"天坛公园附近有 3 个数字人、5 条帖子…"}],
  "structuredContent":{"place":"天坛公园","confidence":1.0,"items":[…]},
  "isError":false}}

5.4 两步发帖（写操作必须两次调用）

// 第一步：只生成草稿，用户还看不到任何公开内容
{"jsonrpc":"2.0","id":4,"method":"tools/call",
 "params":{"name":"prepare_post",
           "arguments":{"content":"今天在天坛看人拍汉服，光特别好。","place":"北京天坛公园"}}}
// → result: {"draft_id":"…","expires_at":"…"}

// 第二步：用户明确确认后才发布
{"jsonrpc":"2.0","id":5,"method":"tools/call",
 "params":{"name":"publish_post","arguments":{"draft_id":"…"}}}

六、限流与超时

范围	规则	超限表现
公开检索工具 `find_nearby` / `nearby_attractions` / `geocode_place`	每个访问令牌 60 秒内最多 12 次	返回 `isError: true`，文案「请求太频繁…请 N 秒后再试」，不执行任何外部调用
全部写操作	每个 PowPow 账号 60 秒内最多 20 次（按账号，不按 IP）	`429` / `rate_limited`
外部依赖（高德地图）	单次超时 8 秒	工具内降级为「稍后重试」，不返回 5xx
写操作网关	单次超时 20 秒	同上

限流按访问令牌计数。若同一出口 IP 下有大量客户端同时调用，建议各自完成 OAuth 授权、使用独立令牌，避免相互挤占配额。

七、写操作规则

两步发帖：草稿由 prepare_post 生成，有效期 1 小时；未持有本对话生成的 draft_id 无法发布，模型无法跳过用户确认。
撤回窗口：AI 发布的帖子 24 小时内可撤回；AI 创建的数字人在 24 小时内且无人对话时可撤销并退还徽章。站内自行创建的内容需在 PowPow 内管理。
用户级写权限开关：用户可在 PowPow「设置 → AI 连接」关闭写权限。关闭后所有写工具返回 write_disabled，只读工具不受影响；改动约 1 分钟内生效。
全量审计：每次写操作（含失败）都记录账号、动作、目标、参数摘要、结果与时间，保留 180 天。
不可越权的操作：改头像、私信、通知、订阅与支付均不通过本接口提供。

八、错误码

传输层错误使用 HTTP 状态码；业务错误在工具结果的 isError 与错误码中体现。

code	含义与处理
`unauthorized`	access token 缺失、过期或无效 → 重新走 OAuth 授权
`subscription_required`	账号状态受限（例如会员已过期），暂不能读写账号数据
`write_disabled`	用户在站内关闭了 AI 写权限
`rate_limited`	触发限流，稍后重试
`missing_id` / `missing_user_id` / `missing_item_id`	缺少必填标识
`invalid_target` / `invalid_item_type`	目标不存在或类型不合法
`not_found`	对象不存在或无权限查看
`missing_content` / `content_too_long`	正文为空或超过 5000 字
`missing_draft_id` / `draft_expired` / `draft_deleted`	草稿缺失、超过 1 小时、或已被使用
`publishing`	同一草稿正在发布中（并发保护）
`not_mcp_post` / `too_old`	该帖子不是 AI 发布，或已超过 24 小时撤回窗口
`badge_insufficient`	徽章不足（创建数字人需 2 枚）
`not_mcp_dh` / `has_conversations`	数字人不是 AI 创建，或已有人对话，无法撤销
`name_too_long` / `missing_name` / `missing_location`	创建数字人的入参不合法

九、隐私与合规

不索取设备位置。接口不接收经纬度，位置一律由用户口述地名，服务端解析，不采集 GPS。
数据范围。仅返回公开内容与本账号数据；不提供私信、支付信息、密码、其他用户的非公开数据。
日志保留。请求日志与写操作审计保留 180 天，用于安全与排障。
不涉及支付。接口不提供订阅、套餐、价格或任何支付能力。
隐私政策：global.powpow.online/privacy-policy · 用户协议：/terms-of-service · 支持：/support

十、测试账号与联系

测试账号

为避免公开账号被滥用，测试账号与密码不在本页展示。需要审核或联调时，请发邮件至下方地址索取，我们会在 1 个工作日内提供账号、密码与样例数据说明（含公开帖子、数字人、徽章与账号状态；密码登录即可，无 MFA、无邮件验证码）。

该账号仅用于审核与联调，审核结束后会重置密码或停用。请勿将其用于任何其他用途。

技术支持：dongtao@outlook.com

十一、在 AI 客户端中接入

前面几节是协议细节。日常使用只要把下面这一条 URL 填进客户端即可，其余步骤（资源元数据发现、动态客户端注册、PKCE）由客户端自动完成，不需要手工配置任何 client_id 或授权地址：

https://global.powpow.online/api/mcp

11.1 Claude（网页版 / 桌面版）

打开设置 → 连接器 → 添加自定义连接器
名称填 PowPow，URL 填上面那条端点
点「连接」，浏览器会跳到 PowPow 授权页，用 PowPow 账号登录并确认授权

11.2 Claude Code

claude mcp add --transport http powpop https://global.powpow.online/api/mcp

11.3 Cursor

写入项目级 .cursor/mcp.json 或全局 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "powpop": {
      "url": "https://global.powpow.online/api/mcp"
    }
  }
}

11.4 VS Code（Copilot Chat）

写入 .vscode/mcp.json：

{
  "servers": {
    "powpop": {
      "type": "http",
      "url": "https://global.powpow.online/api/mcp"
    }
  }
}

11.5 ChatGPT

打开 chatgpt.com/plugins，点加号 → Add custom MCP server
填写名称与描述；Connection 选公开端点，URL 填上面那条端点
Authentication 选 OAuth，确认风险提示后选择 Create as a plugin
新开一个对话，输入 @ 选中该插件即可调用

三个常见卡点：

一直 401 或反复要求登录：本服务不开放匿名访问，必须先完成一次 OAuth 授权， initialize 也不例外。这是预期行为，不是配置错误。
连接成功但工具列表为空：确认客户端请求头带 Accept: application/json, text/event-stream。本服务响应是 SSE，只认 application/json 的客户端会解析失败。
写操作返回 write_disabled：在 PowPow App 的「设置 → AI 连接」里打开 AI 写权限。

English summary

PowPow is a Chinese location-based social app (posts pinned to places, conversational AI characters called "digital humans", offline check-in campaigns). This document describes its MCP server:

Endpoint: https://global.powpow.online/api/mcp — Streamable HTTP, SSE responses, JSON-RPC 2.0, MCP protocol 2025-06-18 / 2025-11-25 / 2026-07-28.
Auth: OAuth 2.1 with PKCE (S256) and dynamic client registration. Resource metadata at /api/mcp/.well-known/oauth-protected-resource; authorization server is hosted on Supabase Auth (…/auth/v1/.well-known/oauth-authorization-server). Every method, including initialize, requires a bearer token.
Tools: 34 — 20 read-only tools (nearby search, attractions, place geocoding, digital human, post and comment details, keyword search, campaigns, plus account and social reads) and 14 write tools (two-step publishing, comments, likes, follows, favorites, profile and digital-human creation). No tool, including initialize and tools/list, is callable anonymously.
Safety: no precise GPS is requested or stored; publishing requires a two-step draft-then-confirm flow (drafts expire in 1 hour); AI-created posts and digital humans can be undone within 24 hours; users can switch off AI write access from the app at any time; every write is rate limited and audited for 180 days.
No payment surface: the integration exposes no plans, prices or payment flows.