# PowPow MCP Server

Source for the **PowPow** remote MCP server, listed on the
[official MCP Registry](https://registry.modelcontextprotocol.io/) as
[`io.github.durenzidu/powpow-mcp`](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.durenzidu%2Fpowpow-mcp/versions/latest).

**PowPow（泡泡）** is a location-based social app for mainland China. Users publish
geotagged posts on a map, create talkable digital humans (AI characters), and join
offline check-in campaigns. This MCP server exposes that capability to AI clients.

中文说明见下方 [中文简介](#中文简介)。

---

## Connect

The server is a remote **streamable HTTP** MCP server. Point any compatible client at it:

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

### Claude Code / Claude Desktop / Claude.ai

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

### Cursor

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

### VS Code

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

### Claude Code plugin (one-step install)

A ready-made plugin lives at
[`durenzidu/powpow-claude-plugin`](https://github.com/durenzidu/powpow-claude-plugin):

```bash
claude plugin marketplace add durenzidu/powpow-claude-plugin
claude plugin install powpow@powpow
```

## Authentication

**OAuth 2.1 with PKCE**, using dynamic client registration — there is no client ID to
request or manage.

1. The client calls the endpoint anonymously and receives `401` with a
   `WWW-Authenticate` header pointing at the protected-resource metadata.
2. It reads the resource metadata, then the authorization server metadata.
3. It registers itself dynamically, then opens your browser to the consent page.
4. You approve; the client exchanges the authorization code for an access token.

### Supported scopes

`openid`, `profile`, `email`

### Notes

- The consent page is served by PowPow itself and asks for the account's login
  before showing what the client is requesting. You can decline at any time.
- Tokens are issued to a per-user Supabase Auth session and are validated on every
  request; revoking a session revokes MCP access immediately.

## Tools

34 tools — **20 read-only** and **14 write**.

### Discovery

| Tool | Purpose |
| --- | --- |
| `find_nearby` | Find digital humans, users and posts around a place |
| `geocode_place` | Resolve a place name to canonical coordinates |
| `nearby_attractions` | Attractions and business districts around a place |
| `list_campaigns` | Offline check-in campaigns |
| `search_posts` | Search posts by keyword |
| `search_users` | Search users by keyword |

### Account and social

| Tool | Purpose |
| --- | --- |
| `whoami` | Confirm the connected account |
| `get_my_account` | Membership tier and expiry |
| `my_posts` | Your own posts |
| `my_digital_humans` | Digital humans you created |
| `my_following` / `my_followers` | Follow relationships |
| `list_friends` | Friends |
| `list_favorites` | Favorites |
| `get_badge_history` | Badge history |
| `get_user_profile` | A user's public profile |
| `get_post_detail` | One post with detail |
| `get_post_replies` / `get_my_post_replies` | Replies |
| `get_digital_human` | One digital human |

### Write operations

`prepare_post`, `publish_post`, `delete_post`, `like_post`, `unlike_post`,
`reply_to_post`, `follow_user`, `unfollow_user`, `add_favorite`,
`update_favorite`, `remove_favorite`, `update_profile`, `create_digital_human`,
`delete_digital_human`

### Safety model

- **Posting is always two-step.** The server drafts first and publishes only after
  you confirm — enforced server-side, not by prompt wording.
- **24-hour undo.** Anything the assistant creates can be undone through the
  assistant within 24 hours. Older content is managed in the PowPow app.
- **Write access can be switched off** in PowPow's AI connection settings.

### Rate limits

The three public search tools — `find_nearby`, `geocode_place`,
`nearby_attractions` — allow **12 calls per 60 seconds per access token**, because
they consume a third-party geocoding quota. The other 31 tools are not rate limited.

## Documentation

Full reference for all 34 tools: **https://global.powpow.online/mcp-docs**

## What this server talks to

| Destination | Purpose |
| --- | --- |
| `https://global.powpow.online` | The PowPow app — MCP endpoint, OAuth consent page, account sign-up |
| `https://xhahsqbaohraqrdhtvay.supabase.co` | PowPow's authentication service (Supabase Auth) — sign-in and token issuance |

No other network destinations. No telemetry, no third-party analytics.

## Source layout

```
powpow-mcp/
├── server.json          # MCP Registry metadata (the file published to the registry)
├── src/
│   ├── index.ts         # Tool registration and handlers
│   ├── auth.ts          # OAuth 2.1 resource-server side
│   └── widget-html.ts   # Interactive map widget (HTML)
└── LICENSE
```

The server runs on **Supabase Edge Functions** (Deno).

### Environment variables

| Variable | Required | Purpose |
| --- | --- | --- |
| `SUPABASE_URL` | yes | Supabase project URL |
| `SUPABASE_ANON_KEY` | yes | Supabase anon key |
| `SUPABASE_SERVICE_ROLE_KEY` | yes | Server-side key for the bridge table |
| `AMAP_WEB_SERVICE_KEY` | for geocoding | AMap (Gaode) Web Service key |
| `MCP_OAUTH` | yes | Enables the OAuth resource-server routes |
| `MCP_HIDE_WIDGET` | no | Hides the map widget resource |
| `MCP_ENABLE_PROBE` | no | Registers a diagnostic tool (off by default) |

> No credentials are committed to this repository. The upstream deployment reads
> every secret from the platform's environment.

### Deploy

```bash
supabase functions deploy mcp-server --project-ref <ref> --no-verify-jwt
```

## Legal

- Privacy policy: https://global.powpow.online/privacy-policy
- Terms of service: https://global.powpow.online/terms-of-service
- Support: https://global.powpow.online/support
- Website: https://www.powpow.online/

## License

MIT — see [LICENSE](./LICENSE).

---

## 中文简介

**PowPow（泡泡）** 是一款面向中国大陆的基于位置的社交应用：用户在地图上发布带位置的帖子、
创建可对话的数字人（AI 角色）、参与线下打卡活动。本仓库是它的远程 MCP 服务端源码，
已发布到[官方 MCP Registry](https://registry.modelcontextprotocol.io/)。

**接入方式**

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

传输方式为 **streamable HTTP**。鉴权走 **OAuth 2.1 + PKCE**，支持动态客户端注册
（无需申请 client_id）。

**工具**：共 34 个，20 个只读 + 14 个写，覆盖附近发现、账号与社交、内容创作、数字人、活动与会员。

**安全边界**

- 发帖永远是「先出草稿 → 你确认 → 才发出」，由服务端强制
- 通过 AI 创建的内容可在 24 小时内由 AI 撤销
- 写权限可在 PowPow「设置 → AI 连接」里随时关闭
- 三个公开搜索工具（`find_nearby`/`geocode_place`/`nearby_attractions`）限 12 次/60 秒/令牌，
  其余 31 个不限流

**隐私**：只连接两个域名 —— `global.powpow.online`（应用与 OAuth 同意页）和
`xhahsqbaohraqrdhtvay.supabase.co`（认证服务）。无埋点、无第三方分析、不上传本地文件。

**许可**：MIT