shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 数据与分析无需 API Key

Picsee Short Link

PicSee URL短链接服务（通过MCP）— 缩短链接、生成二维码、查看详细点击分析（每日/平台/来源/地区/受众）及管理链接...

person作者: picseeinchubclawhub
open_in_new仓库download下载资源包

PicSee Short Link

URL shortener with rich click analytics and full link management — exposed to AI agents through the PicSee MCP server at https://api.picsee.io/mcp.

The skill ships no code: it just teaches your agent how to call the MCP server. Authentication is handled by OAuth 2.1 with PKCE (Dynamic Client Registration), so no API tokens are ever stored on disk by the skill.

Installation

Add the PicSee MCP server to your AI client's MCP config. Pick the transport your client supports — most modern clients speak Streamable HTTP directly.

Streamable HTTP (recommended)

{
  "mcpServers": {
    "picsee-short-link": { "url": "https://api.picsee.io/mcp" }
  }
}

Stdio bridge (for clients without remote-MCP support)

{
  "mcpServers": {
    "picsee-short-link": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.picsee.io/mcp"]
    }
  }
}

See README.md for the exact config file path on each platform.

Authentication

Anonymous mode (no setup)

create_short_link is callable with no credentials. Anonymous calls are pinned to pse.is and have no access to externalId filtering / attribution dashboards.

Authenticated mode (OAuth 2.1)

On the first authenticated tool call, the MCP client triggers an OAuth flow:

  1. Dynamic Client Registration → https://public-api-oauth.picsee.io/oauth/register
  2. Browser → https://public-api-oauth.picsee.io/oauth/authorize
  3. User signs in to PicSee and grants user:read + user:write
  4. Client receives access + refresh tokens via PKCE/S256
  5. Token is stored by the MCP client — never by this skill

All 14 authenticated tools become available after this flow.

Tools

15 tools total. create_short_link is callable anonymously; the rest require OAuth.

create_short_link (anonymous OK)

Create a new short link.

| Field | Required | Notes | |-------|----------|-------| | url | ✅ | Destination URL, ≤2048 chars | | encodeId | | Custom slug, 3–90 chars (letters / digits / _ / - / Chinese). Must be globally unique — conflicts return PUB00503 | | domain | | pse.is or a BSD from get_my_domains. Ignored when called anonymously | | externalId | | 1–100 chars. Agents SHOULD default this to their own product name — see Attribution | | utm | | { source, medium, campaign, term, content } | | title | | OG preview title, 3–300 chars | | description | | OG preview description, 3–300 chars | | imageUrl | | OG preview image URL | | tags | | Array of up to 3 tag names — use get_my_tags to offer a picker | | targets | | Device-specific redirects, see below | | fbPixel | | Meta Pixel ID — must already be saved in PicSee (get_my_tracking_tools) | | gTag | | GTM container ID — must already be saved in PicSee (get_my_tracking_tools) | | pathFormat | | { key: "<param-name>" } — Path Parameterization add-on (paid Advanced) |

targets[].target enum: ios_android, ios, ios_store, android, android_store, ios_line, ios_safari, android_fb, pc_mac, pc, mac, facebook, twitter. ios_android = all mobile; pc_mac = all desktop. App-store buckets only fire for users with the app installed.

Returns picseeUrl (the shortened link).

Account / discovery tools

get_api_status

No params. Returns the account's API plan, lifetime quota, current period usage, and plan expiration. Call this before bulk operations to confirm remaining quota.

get_api_usage_by_external_id

| Field | Required | Notes | |-------|----------|-------| | startTime | | Taipei time YYYY-MM-DDTHH:mm:ss. Defaults to 30 days before endTime | | endTime | | Taipei time YYYY-MM-DDTHH:mm:ss. Defaults to current hour. Max 31-day range |

Returns API-link counts grouped by externalId — useful for attributing usage to agents / campaigns.

get_my_domains

No params. Lists every short-link domain on the account: brand short domains (BSDs), PicSee subdomains, shared root. Each entry flags HTTPS support and default status. Call before create_short_link if the user wants a non-default domain.

get_my_tags

No params. Returns { id, name } pairs. name values are what tags accepts on create_short_link / edit_short_link.

get_my_tracking_tools

No params. Returns previously-used UTM sources / mediums, saved Meta Pixels, and saved GTM containers. Use to populate pickers instead of asking the user to retype IDs.

list_short_links

| Field | Notes | |-------|-------| | limit | 1–50, default 20 | | startTime | Taipei time YYYY-MM-DDTHH:mm:ss. Returns links created at or before this timestamp — i.e. queries backward. Default = now | | prevMapId | Cursor: return links with mapId older than this. Combine with startTime for AND filtering | | isAPI | true (default) = only API-created links; false = only website-created | | isStar | true = starred only. Default false | | externalId | Exact-match filter | | search.encodeId | Exact slug — priority 1, overrides all other search fields | | search.authorId | Filter by author's PicSee user ID — priority 2 | | search.tag | Tag name, 3–30 chars — priority 3 | | search.keyword | Substring, 3–30 chars — priority 4 |

Tip: when the user says "links from March 2026", pass startTime: "2026-03-31T23:59:59" (the end of the period) — the server queries backward from there.

edit_short_link

| Field | Required | Notes | |-------|----------|-------| | encodeId | ✅ | Slug of the link to edit | | url | | New destination. May be rejected with PUB00510 if the new origin is on a different brand | | domain | | | | title / description / imageUrl | | 3–300 chars for text fields | | tags | | Up to 3 | | targets | | Same enum as create_short_link | | fbPixel / gTag | | Pass null to clear | | utm | | Pass null to clear all UTM params | | expireTime | | Future Taipei time YYYY-MM-DDTHH:mm:ss, or null to remove. Requires the expiration add-on |

delete_short_link

| Field | Required | Notes | |-------|----------|-------| | encodeId | ✅ | | | value | | delete (default) = move to trash; recover = restore from trash |

  • Starred links can't be deleted (PUB00706) — unstar via web first.
  • Links trashed for >30 days can't be recovered (PUB00704).

Per-link analytics

All five tools share the same shape: required encodeId, optional startTime / endTime (Taipei YYYY-MM-DDTHH:mm:ss). Default window is the last 30 days; Advanced plan can look back up to 365 days.

| Tool | Returns | |------|---------| | get_link_overview | Total clicks, unique clicks, destination URL, domain, HTTPS flag, creation time. Use for at-a-glance summaries | | get_link_daily_clicks | Time-series of total + unique clicks aggregated by day. Use as raw data for chart rendering | | get_link_platforms | Unique-click breakdown by device (iphone, android, windows, macintosh, …). Aggregate to mobile/desktop client-side if needed | | get_link_referrers | Unique-click breakdown by referrer (search engines, social, AI agents, long-tail). Clicks without referrer info → direct | | get_link_regions | Unique-click breakdown by country (no city-level data). Unknown countries → Others (code: "others") | | get_link_audience_labels | Interest + brand labels. Privacy guard: only returns data when the link has >100 lifetime unique clicks; otherwise both arrays come back empty. No startTime / endTime — covers link lifetime |

Attribution

The create_short_link schema asks the calling agent to set externalId to its own product name when the user hasn't specified one. PicSee account owners use this to attribute API usage in their dashboard.

| Agent | Recommended externalId | |-------|--------------------------| | Claude Code | Claude Code | | Cursor | Cursor | | Codex / Codex CLI | Codex | | Antigravity | Antigravity | | OpenClaw / ClawHub | OpenClaw | | Gemini CLI | Gemini CLI | | GitHub Copilot | Copilot | | ChatGPT | ChatGPT |

Rules:

  • Canonical product name only — no version numbers, session IDs, or user names.
  • If the user explicitly provides an externalId, always honor their value instead.

Agent Recipes

The MCP server intentionally doesn't ship QR or chart-rendering tools — those are easier to compose client-side from public services.

Generate a QR code from a short link

Construct a URL against api.qrserver.com:

https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=<URL-encoded-short-link>

Surface the URL inline if your client renders images; otherwise return it as a link. For a larger code, change size=500x500.

Render a daily-clicks chart

  1. Call get_link_daily_clicks to get the time series.
  2. Build a QuickChart URL from the data:
https://quickchart.io/chart?c={type:'line',data:{labels:['2026-03-01',...],datasets:[{label:'Clicks',data:[12,38,...]}]}}

URL-encode the c parameter. Display inline if possible; otherwise return the link.

Common Workflows

Shorten a URL with full attribution

  1. Call create_short_link with url and externalId = your agent name.
  2. Return picseeUrl to the user.
  3. If the user wanted a custom slug and got PUB00503, suggest an alternative.

Pick a branded short domain

  1. get_my_domains to enumerate BSDs + PicSee subdomains.
  2. Offer the user a picker (note which is isDefault).
  3. Pass the chosen domain to create_short_link.

Show analytics for a link

  1. get_link_overview for the headline numbers.
  2. If the user wants breakdowns, call one or more of get_link_daily_clicks / get_link_platforms / get_link_referrers / get_link_regions / get_link_audience_labels.
  3. For audience labels: warn the user if the link has ≤100 unique clicks (data will be empty due to the privacy guard).

List the user's recent links

  1. Call list_short_links with the user's filters.
  2. If they say "March 2026", pass startTime: "2026-03-31T23:59:59".
  3. Paginate with prevMapId from the last result if they ask for more.

Migrate a link to a new destination

  1. edit_short_link with encodeId + new url.
  2. If you get PUB00510, the brand of the new URL doesn't match. Tell the user.

Track API usage by agent

get_api_usage_by_external_id with no params returns the last 30 days, grouped by attribution tag. Useful for "which AI created most of my links?"

Migration from v2.x

v2.x was a Node.js CLI that stored an encrypted API token under ~/.openclaw/. v3.0.0 removes that entirely — no CLI, no token files, no Node.js requirement on the agent side.

# Clean up v2 artifacts
rm -f ~/.openclaw/.picsee_token ~/.openclaw/.picsee_salt
rm -rf ~/.claude/skills/picsee-short-link/cli
rm -rf ~/.openclaw/workspace/skills/picsee-short-link/cli

Behavioral changes:

  • Auth: long-lived API token → OAuth 2.1 + PKCE (browser sign-in on first authenticated call)
  • QR / chart: were CLI subcommands → now agent recipes against api.qrserver.com / quickchart.io
  • delete vs recover: were two CLI commands → one tool delete_short_link with value: "delete" | "recover"
  • Analytics: was a single analytics command → split into 6 granular tools (get_link_overview + 5 dimensional breakdowns)
  • Per-account discovery: new tools get_my_domains, get_my_tags, get_my_tracking_tools, get_api_status, get_api_usage_by_external_id have no v2 equivalent

Error codes

| Code | Meaning | |------|---------| | PUB00503 | encodeId (custom slug) already taken | | PUB00510 | New url rejected on edit — different brand than the original | | PUB00704 | Cannot recover a link that has been in trash >30 days | | PUB00706 | Cannot delete a starred link — unstar it via the PicSee web app first |

References

  • PicSee website: https://picsee.io
  • Developer docs: https://picsee.io/developers
  • MCP spec: https://modelcontextprotocol.io
  • OAuth 2.1 (MCP profile): https://modelcontextprotocol.io/specification/draft/basic/authorization