picsee-short-link

# 🔗 Skill for PicSee URL Shortener

[![Agent Skills](https://img.shields.io/badge/Agent_Skills-Open_Standard-blue.svg)](https://agentskills.io)
[![MCP](https://img.shields.io/badge/MCP-Streamable_HTTP-green.svg)](https://modelcontextprotocol.io)
[![OAuth 2.1](https://img.shields.io/badge/OAuth_2.1-PKCE-orange.svg)](https://modelcontextprotocol.io/specification/draft/basic/authorization)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An **MCP-based [Agent Skill](https://agentskills.io)** for [PicSee](https://picsee.io) — URL shortening, QR code generation, click analytics, and link management.

The skill is just documentation: it points your AI agent at the public PicSee MCP server (`https://api.picsee.io/mcp`) and explains how to use the tools. No Node.js install, no CLI, no local token files — authentication is handled by **OAuth 2.1 + PKCE** via the MCP client.

---

## 🌟 What's new in v3.0.0

- **CLI → MCP**: the entire v2.x CLI (`node cli/dist/cli.js …`) is gone. All functionality is now exposed as MCP tools served from `api.picsee.io/mcp`.
- **OAuth 2.1 + PKCE**: replaces local AES-256 token encryption. Tokens are managed by your MCP client, not by this skill. Dynamic Client Registration means there's no manual app setup.
- **Anonymous mode still works**: `create_short_link` is callable without auth — perfect for one-off shortenings.
- **No Node.js requirement**: works in any MCP-capable client, including ones that can't execute Node (e.g. Cursor, web-based agents).
- **Agent attribution built in**: the server documents the convention of setting `externalId` to the AI agent's name (`Claude Code`, `Cursor`, `Codex`, …) so account owners can see which agent created which link.

Migrating from v2.x? See the [Migration](#migration-from-v2x) section.

---

## ⚙️ Installation by Platform

The skill consists of two parts:

1. **Skill content** (`SKILL.md` + this README) — placed in the platform's skills directory so the agent auto-discovers usage instructions.
2. **MCP server registration** — added to the platform's MCP config so the agent can actually call the tools.

### Claude Code

```bash
# 1. Install the skill
cp -r picsee-short-link ~/.claude/skills/picsee-short-link

# 2. Register the MCP server
claude mcp add --transport http picsee-short-link https://api.picsee.io/mcp
```

Or add manually to `~/.claude.json` (or project `.mcp.json`):

```json
{
  "mcpServers": {
    "picsee-short-link": { "type": "http", "url": "https://api.picsee.io/mcp" }
  }
}
```

### Cursor

Place the skill in `.cursor/skills/picsee-short-link/`, then edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):

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

> For Cursor, use `https://api.picsee.io/mcp/auth` when you need to sign in (OAuth). Anonymous use (`create_short_link` only) can stay on `https://api.picsee.io/mcp`.

### Antigravity

Antigravity speaks MCP Streamable HTTP **natively**. Edit `~/.gemini/config/mcp_config.json` (it shares Gemini's config dir, and uses the key `serverUrl`):

```json
{
  "mcpServers": {
    "picsee-short-link": { "serverUrl": "https://api.picsee.io/mcp" }
  }
}
```

Then open **Settings → Customizations → Installed MCP Servers**, click **Refresh**, and the server appears. Click **Authenticate** next to it to sign in via OAuth and unlock the full authenticated tool set (anonymous mode exposes only `create_short_link`).

Place `SKILL.md` in Antigravity's skills directory so the agent picks up usage guidance.

### Hermes Agent

[Hermes Agent](https://hermes-agent.nousresearch.com) (Nous Research) speaks MCP **natively** as both client and server. Edit `~/.hermes/config.yaml` and add the server under `mcp_servers`, using `auth: oauth` so Hermes runs the browser sign-in flow on the first authenticated call:

```yaml
mcp_servers:
  picsee-short-link:
    url: "https://api.picsee.io/mcp"
    auth: oauth
```

On first authenticated call, Hermes prints an authorize URL (and opens your browser when possible), then waits for the OAuth callback on a local loopback port. Tokens are cached at `~/.hermes/mcp-tokens/picsee-short-link.json` (mode `0o600`) and reused silently until refresh fails. For anonymous use (`create_short_link` only), drop the `auth: oauth` line.

Drop the skill folder into `~/.hermes/skills/picsee-short-link/` (containing `SKILL.md`) — Hermes loads it immediately, no registration needed.

### Codex / Codex CLI

Add the server with the Codex CLI:

```bash
codex mcp add picsee-short-link --url https://api.picsee.io/mcp
```

Or add it directly to `~/.codex/config.toml`:

```toml
[mcp_servers.picsee-short-link]
url = "https://api.picsee.io/mcp"
```

Then authenticate it with OAuth:

```bash
codex mcp login picsee-short-link --scopes user:read,user:write
```

Codex supports remote MCP servers over Streamable HTTP via --url, and MCP
server configuration is shared between the CLI and the IDE extension.
[platform.openai.com](https://platform.openai.com/docs/docs-mcp)

If you use skills, place SKILL.md at:

`~/.codex/skills/picsee-short-link/SKILL.md`

### OpenClaw / ClawHub

```bash
clawhub install picsee-short-link
```

Or browse: [https://clawhub.ai/PicSeeInc/picsee-short-link](https://clawhub.ai/PicSeeInc/picsee-short-link)

ClawHub auto-registers the MCP server from the skill's metadata.

### claude.ai (Web)

Upload the skill folder under **Customize → Skills**. Add the MCP server in **Settings → Connectors → Add custom connector** with URL `https://api.picsee.io/mcp`.

### Generic MCP client

Any client that speaks **MCP Streamable HTTP** can register the server directly:

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

For clients that only support stdio, use the `mcp-remote` bridge from npm:

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

---

## 🤖 Compatibility Matrix

| Platform | Skill discovery | MCP transport | OAuth flow | Status |
|:---------|:----------------|:--------------|:-----------|:-------|
| Claude Code | `~/.claude/skills/` | HTTP (native) | Browser popup, token in `~/.claude` | ✅ |
| Cursor | `.cursor/skills/` | HTTP (native) | Browser popup, token in Cursor config | ✅ |
| Antigravity | Antigravity skills dir | HTTP (native, `serverUrl`) | Browser popup (Authenticate button) | ✅ |
| Hermes Agent | `~/.hermes/skills/` | HTTP (native, `config.yaml`) | Browser popup, token in `~/.hermes/mcp-tokens/` | ✅ |
| Codex CLI | `.codex/skills/` | stdio via `mcp-remote` | Browser popup via `mcp-remote` | ✅ |
| OpenClaw / ClawHub | auto (via `clawhub install`) | HTTP | Browser popup | ✅ |
| claude.ai | Customize → Skills | HTTP connector | Browser popup | ✅ |
| Gemini CLI | `.gemini/skills/` | stdio via `mcp-remote` | Browser popup via `mcp-remote` | ✅ |
| VS Code Copilot | `.github/skills/` | HTTP (1.95+) | Browser popup | ✅ |

> Any MCP-compliant client should work — the matrix above is just the integrations we've tested.

---

## 🧩 Tools

`create_short_link` is the only tool callable anonymously. The other 14 require OAuth.

| Group | Tool | Auth |
|:------|:-----|:-----|
| **Create** | `create_short_link` | optional |
| **Account** | `get_api_status` | required |
| | `get_api_usage_by_external_id` | required |
| | `get_my_domains` | required |
| | `get_my_tags` | required |
| | `get_my_tracking_tools` | required |
| **Manage** | `list_short_links` | required |
| | `edit_short_link` | required |
| | `delete_short_link` (covers delete + recover) | required |
| **Analytics** | `get_link_overview` | required |
| | `get_link_daily_clicks` | required |
| | `get_link_platforms` | required |
| | `get_link_referrers` | required |
| | `get_link_regions` | required |
| | `get_link_audience_labels` | required |

> **No QR or chart tool on the server** — those are agent recipes against public services (`api.qrserver.com`, `quickchart.io`). See [SKILL.md → Agent Recipes](SKILL.md#agent-recipes).

Full parameter tables for every tool live in [SKILL.md](SKILL.md). The MCP server is also self-describing via `tools/list` — that is the source of truth.

---

## 🔑 Authentication

1. Register the MCP server in your client (see [Installation](#-installation-by-platform)).
2. Ask the agent to do something that requires auth (e.g. "show me analytics for my last link").
3. The MCP client opens a browser to `https://public-api-oauth.picsee.io/oauth/authorize`.
4. Sign in to PicSee and approve the `user:read` / `user:write` scopes.
5. Done — the client stores the token. Future calls are silent until the refresh token expires.

The skill folder never touches your token. All credential handling lives in your MCP client.

---

## 🔒 Security

| Aspect | v2.x (legacy) | v3.0.0 (current) |
|:-------|:--------------|:-----------------|
| Auth model | Long-lived API token | OAuth 2.1 + PKCE (S256) |
| Token storage | Local file, AES-256-CBC | MCP client (per-client policy) |
| Scopes | All-or-nothing | `user:read`, `user:write` |
| Revocation | Manual via PicSee dashboard | Per-client, revocable from PicSee account |
| Dynamic Client Registration | n/a | ✅ (RFC 7591) |

OAuth metadata is published at [`https://api.picsee.io/.well-known/oauth-protected-resource`](https://api.picsee.io/.well-known/oauth-protected-resource), with the authorization server at [`https://public-api-oauth.picsee.io/.well-known/oauth-authorization-server`](https://public-api-oauth.picsee.io/.well-known/oauth-authorization-server).

---

## 🧭 Agent attribution

The MCP server asks calling agents to set `externalId` to their own product name on `create_short_link`, so PicSee account owners can attribute API usage. The skill tells your agent to default to:

`Claude Code` · `Cursor` · `Codex` · `Antigravity` · `OpenClaw` · `Gemini CLI` · `Copilot