mpm-url-shortener

CRUD manager for mpm.to short URLs via the YOURLS 1.10.2 API and admin session fallback.

Version: 1.0.0
Author: MPM / Jason
Repo: https://git.alwisp.com/jason/mpm-url-shortener
CoWork Project: CW-013 — MPM URL Shortener

Overview

This skill gives Claude full create, read, update, and delete control over short URLs on mpm.to, which runs YOURLS 1.10.2. Create and read always use the static signature token via yourls-api.php. Update and delete first attempt the signature token path (which requires the optional mpm-api-extras PHP plugin to be active on the server); if the plugin is not installed, they automatically fall back to an admin browser session authenticated via admin/ with a time-limited login nonce. All credentials are stored in macOS Keychain under the service name mpm.to-yourls. The skill also includes the companion PHP plugin (mpm-api-extras.php) that extends the YOURLS API to support update and delete actions natively, eliminating the need for the session fallback.

Skills

Skill What It Does

mpm-url-shortener Manages short URLs on mpm.to. Triggers on: "shorten this URL", "create a short link", "make a short URL", "mpm.to", "short link for", "short URL for", "delete this short link", "update the short URL for", "what does mpm.to/XXX point to", "list our short URLs", "change the short code", "rename the keyword". Supports all CRUD operations: create (with optional keyword and title), read (expand + click stats), list (top/bottom/last/random), update (URL, keyword, and/or title), and delete (with confirmation prompt).

Skill	What It Does
`mpm-url-shortener`	Manages short URLs on mpm.to. Triggers on: "shorten this URL", "create a short link", "make a short URL", "mpm.to", "short link for", "short URL for", "delete this short link", "update the short URL for", "what does mpm.to/XXX point to", "list our short URLs", "change the short code", "rename the keyword". Supports all CRUD operations: create (with optional keyword and title), read (expand + click stats), list (top/bottom/last/random), update (URL, keyword, and/or title), and delete (with confirmation prompt).

Tools Reference

Module	Tools
YOURLS API	`yourls-api.php` — `shorturl` (create), `expand` (read), `url-stats` (read stats), `stats` (list), `db-stats` (connection check)
YOURLS Admin Ajax	`admin/admin-ajax.php` — `delete` (admin fallback), `edit_display` (admin fallback), `edit_save` (admin fallback)
mpm-api-extras plugin	Adds `update` and `delete` actions to `yourls-api.php`, enabling signature-token-only operation without admin credentials
macOS Keychain	`security find-generic-password`, `security add-generic-password`, `security delete-generic-password` — stores `signature`, `username`, `password`

Setup Instructions

Step-by-step:

Install Python dependency: pip3 install requests --break-system-packages
Run setup to store credentials: python3 scripts/yourls_manager.py setup
- Signature token (required): found in YOURLS admin → Tools → Secure Token
- Admin username + password (optional): used as fallback when the mpm-api-extras plugin is not active
Verify the connection: python3 scripts/yourls_manager.py check
(Optional) Install the PHP plugin on the YOURLS server to enable API-based update and delete:
- Copy plugin/mpm-api-extras.php to the YOURLS server at user/plugins/mpm-api-extras/mpm-api-extras.php
- Log in to YOURLS admin → Manage Plugins → activate MPM API Extras
- Re-run check — the plugin status line should show ✓ active
To add the SKILL.md to Cowork: install the .skill file via the Cowork plugin manager

Setup Checklist

Python 3.9+ available (python3 --version)
requests library installed (pip3 install requests --break-system-packages)
Signature token stored via setup command
check command succeeds — shows link count and click total
(Optional) mpm-api-extras plugin installed and active on server
(Optional) Admin credentials stored for session fallback

Connection Details

Field	Value
Instance	https://mpm.to
API endpoint	https://mpm.to/yourls-api.php
Admin URL	https://mpm.to/admin/
Auth method (create/read)	Static signature token via `?signature=` POST param
Auth method (update/delete, plugin)	Signature token + `mpm-api-extras` plugin
Auth method (update/delete, fallback)	Username + password session cookie via admin/ nonce login
Keychain service	`mpm.to-yourls`
Keychain accounts	`signature`, `username`, `password`
YOURLS version	1.10.2

Workflow Notes

Keyword charset: mpm.to is configured with a lowercase alphanumeric charset only. Uppercase letters, hyphens, underscores, and all other special characters are silently stripped by YOURLS. The script normalises keywords client-side before sending (re.sub(r'[^a-z0-9]', '', raw.lower())) and warns the user if normalisation changed their requested keyword.

Admin login flow: YOURLS 1.10.2 does not have a standalone login.php. The login form is served by admin/ (index.php), which embeds a time-limited <input name="nonce"> on the page. The script GETs admin/ to extract this nonce, then POSTs to admin/ with {username, password, nonce, submit}. Successful login is confirmed by the absence of name="password" in the response body.

Admin page search: With 671+ links in the database, the target keyword would not appear on page 1 of the admin table. The script searches the admin page using ?s=KEYWORD&search_in=keyword so YOURLS filters the table to a single matching row before scraping nonce links from admin-ajax.php hrefs.

Plugin detection: On every update/delete attempt, the script probes for the mpm-api-extras plugin by checking whether YOURLS returns errorCode: 400 with "unknown"/"missing"/"action" in the message body. If it does, the script falls back to the admin session path automatically.

mpm.to root redirect: mpm.to/ 302-redirects to www.mpmedia.tv (WordPress). Admin session cookies are scoped to .mpm.to. Do not follow redirects when fetching admin/ for the initial login nonce GET.

Requirements

Python 3.9+
requests library (pip3 install requests --break-system-packages)
macOS (for Keychain via security CLI)
Network access to mpm.to
YOURLS signature token (required)
YOURLS admin username + password (optional, for update/delete fallback without plugin)

Troubleshooting

Symptom	Fix
`Error: No signature token found`	Run `yourls_manager.py setup` and enter your signature token
`Error: Admin login failed`	Re-run `setup` and re-enter admin username + password; verify at mpm.to/admin/
`Error: Could not find login nonce on admin page`	YOURLS admin page structure changed — check `mpm.to/admin/` manually; update regex if needed
`Error: Short code 'X' not found on admin page`	Keyword doesn't exist or was deleted; check with `read --keyword X` first
`requests` not found	Run `pip3 install requests --break-system-packages`
Update/delete via API returns "unknown action"	mpm-api-extras plugin is not active; either install it or ensure admin credentials are stored for session fallback
Admin cookies not persisting	`mpm.to/` root redirects to WordPress; do not follow redirects on the initial nonce GET (`allow_redirects=False`)
`Error: Could not extract edit-save nonce`	Admin page structure changed for the edit form; activate the plugin instead as a workaround

7.0 KiB Raw Blame History