mpm-url-shortener/SKILL.md

name, description

name

description

mpm-url-shortener

Manages short URLs on MPM's mpm.to YOURLS instance. Use this skill whenever the user wants to create, look up, expand, update, or delete short links at mpm.to. Triggers on phrases like "create a short link", "make a short URL for", "what does mpm.to/X go to", "delete the mpm.to link", "update the short code", "list our short URLs", "add a short link", "mpm link", "short code", "shortcode", "shorten this URL", or any mention of mpm.to URLs. Also use when the user says things like "can you shorten that" or "set up a link for the new campaign".

MPM URL Shortener

Manages short URLs on MPM's YOURLS instance at https://mpm.to. Supports full CRUD — create, read/list, update, and delete — using only the API signature token. No username or password is stored.

How it works

• Create & Read always use the YOURLS API with the signature token — no password needed.
• Update & Delete use one of two methods, tried in order:
  1. API + plugin (preferred): If the mpm-api-extras plugin is active on the server, the signature token handles everything.
  2. Admin session fallback: If the plugin isn't installed, the script logs into the YOURLS admin interface using a stored username + password.

The bundled script scripts/yourls_manager.py handles the switching automatically — you don't need to think about which method is in use.

---

One-time plugin installation (recommended)

Installing the plugin means only the signature token is ever needed. No passwords in Keychain.

See plugin/INSTALL.md for instructions to pass to your server admin.

---

First-time credential setup

Run once:

python3 <SKILL_DIR>/scripts/yourls_manager.py setup

• Signature token — always required
• Admin username + password — optional; only needed if the plugin is not installed

Credentials are stored in macOS Keychain under service mpm.to-yourls. To verify and test the live connection:

python3 <SKILL_DIR>/scripts/yourls_manager.py check

The check command also tells you whether the plugin is active.

---

Operations

Replace <SKILL_DIR> with the actual path to this skill's directory.

Create a short URL

python3 <SKILL_DIR>/scripts/yourls_manager.py create \
  --url "https://the-long-url.com/path" \
  [--keyword "mycode"] \
  [--title "Human-readable title"]

• --keyword is optional; YOURLS auto-generates one if omitted
• --title is optional but good practice
• Returns the new short URL and confirmation

Read / look up a short URL

python3 <SKILL_DIR>/scripts/yourls_manager.py read --keyword "mycode"

Returns: long URL, title, click count, date created.

List short URLs

python3 <SKILL_DIR>/scripts/yourls_manager.py list [--limit 50] [--filter top|bottom|last|rand]

Defaults to the 50 most-clicked links. Use --filter last to see the most recently created.

Update a short URL

python3 <SKILL_DIR>/scripts/yourls_manager.py update \
  --keyword "mycode" \
  [--url "https://new-destination.com"] \
  [--newkeyword "newcode"] \
  [--title "Updated Title"]

Requires admin credentials. At least one of --url, --newkeyword, or --title must be provided.

Delete a short URL

python3 <SKILL_DIR>/scripts/yourls_manager.py delete --keyword "mycode"

Requires admin credentials. Asks for confirmation before deleting unless --force is passed.

---

Presenting results

After running any operation, present results conversationally:

• Create: "Done! mpm.to/mycode now points to [long URL]."
• Read: Show short URL, destination, title, click count, and age.
• List: Render as a clean table with columns: Short Code | Destination | Clicks | Created.
• Update: Confirm what changed.
• Delete: Confirm deletion.

If an operation fails, read the error output and explain it clearly to the user — don't just dump the raw error.

---

Troubleshooting

Error	Likely cause	Fix
No signature token	First-time use	Run setup
'delete'/'update' action not recognised	Plugin not installed	Script will auto-fall back to admin session if credentials are stored
Plugin not active; no admin credentials	Neither method available	Install plugin OR run setup to add username + password
Admin login failed	Wrong password	Re-run setup to update stored credentials
Keyword already exists	Short code taken	Choose a different --keyword
Short URL not found	Keyword doesn't exist	Check spelling; use list to browse
requests module not found	Missing dependency	Run pip3 install requests --break-system-packages