{
  "markdown": "# Tollbooth Shortlinks\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Version](https://img.shields.io/badge/version-0.1.0-blue)](https://github.com/lonniev/tollbooth-shortlinks)\n[![Python](https://img.shields.io/badge/python-3.10+-green)](https://python.org)\n\n**Don't Pester Your Customer™** (DPYC™) — Ephemeral, human-friendly short URLs for the Tollbooth ecosystem.\n\n> *The metaphors in this project are drawn with admiration from* The Phantom Tollbooth *by Norton Juster, illustrated by Jules Feiffer (1961). Milo, Tock, the Tollbooth, Dictionopolis, and Digitopolis are creations of Mr. Juster's extraordinary imagination. We just built the payment infrastructure.*\n\n---\n\n## Why This Exists\n\nOAuth Authorization URLs are long, ugly, and hostile to copy-paste:\n\n```\nhttps://api.schwab.com/v1/oauth/authorize?client_id=abc123&redirect_uri=https%3A%2F%2F\nfastmcp.cloud%2Foauth%2Fcallback%3Fserver_id%3D...&scope=...&response_type=code&state=...\n```\n\nTraditional link shorteners have become opinionated. They inject interstitial\npages, track clicks, require accounts, gate features behind paywalls, or\nsilently expire links on their own schedule. When an MCP server needs to hand\na patron a one-time URL for an OAuth dance, none of that belongs in the path.\n\nTollbooth Shortlinks is a **community utility** with no monetization. It turns\nany URL into a memorable four-word phrase like `brave-otter-finds-gold`, stores\nthe mapping in Neon Postgres, and expires it after 24 hours. A companion\nVal Town HTTP handler does the 302 redirect with zero interstitial.\n\n## How It Works\n\n```\nMCP Server                    Shortlinks MCP              Val Town\n    |                              |                         |\n    |-- create_shortlink(url) ---->|                         |\n    |<-- brave-otter-finds-gold ---|                         |\n    |                              |                         |\n    |  (patron clicks short URL)   |                         |\n    |                              |    GET /brave-otter-..  |\n    |                              |<------------------------|\n    |                              |    Neon lookup           |\n    |                              |-- 302 redirect -------->|\n    |                              |                         |\n    |        (24h later)           |                         |\n    |                              |  link expires silently   |\n```\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `create_shortlink` | Store a URL, get back a memorable slug (or supply your own) |\n| `resolve_shortlink` | Look up where a slug points without redirecting |\n| `delete_shortlink` | Remove a shortlink before it expires |\n| `shortlink_status` | Health check showing active link count and TTL |\n\nAll tools are **free** -- no credits, no npub, no Tollbooth ledger required.\n\n## Install\n\n```bash\npip install -e \".[dev]\"\n```\n\n## Run Locally\n\n```bash\nexport NEON_SHORTLINKS_URL=\"postgres://user:pass@ep-xyz.us-east-2.aws.neon.tech/shortlinks\"\npython -c \"from server import mcp; mcp.run()\"\n```\n\n## Deploy to Horizon\n\nThe `.fastmcp.yaml` at the repo root is ready for `fastmcp deploy`.\n\n## DPYC Identity\n\nTollbooth Shortlinks is registered as an **Advocate** in the DPYC Social Contract.\nPeer MCP servers discover its URL via registry lookup:\n\n```python\nfrom tollbooth import resolve_service_by_name\n\nshortlinks_url = resolve_service_by_name(\"tollbooth-shortlinks\")\nredirect_base  = resolve_service_by_name(\"tollbooth-shortlinks-redirect\")\n```\n\n## Related Repos\n\nThe Tollbooth DPYC™ ecosystem:\n\n| Repo | Role |\n|------|------|\n| [tollbooth-dpyc](https://github.com/lonniev/tollbooth-dpyc) | The wheel -- operator-side credit ledger, BTCPay client, tool gating, constraint engine |\n| [tollbooth-authority](https://github.com/lonniev/tollbooth-authority) | The institution -- fee collection, Schnorr signing, purchase certification |\n| [dpyc-oracle](https://github.com/lonniev/dpyc-oracle) | The oracle -- Social Contract governance, membership, ban elections |\n| [dpyc-community](https://github.com/lonniev/dpyc-community) | The registry -- governance data, operator catalog, community rules |\n| [tollbooth-sample](https://github.com/lonniev/tollbooth-sample) | Reference operator -- weather API with full Tollbooth wiring |\n| [cypher-mcp](https://github.com/lonniev/cypher-mcp) | Monetized graph answers -- named Cypher over Neo4j/AuraDB |\n| [schwab-mcp](https://github.com/lonniev/schwab-mcp) | Charles Schwab brokerage MCP -- trading, quotes, portfolio access |\n| [excalibur-mcp](https://github.com/lonniev/excalibur-mcp) | eXcalibur -- formatted posting to X (Twitter) |\n| [thebrain-mcp](https://github.com/lonniev/thebrain-mcp) | Personal Brain MCP -- thought graphs, knowledge management |\n| [taxsort-mcp](https://github.com/lonniev/taxsort-mcp) | Tax sorting and classification MCP |\n| [optionality-mcp](https://github.com/lonniev/optionality-mcp) | Options analytics MCP |\n| **tollbooth-shortlinks** (this repo) | Community utility -- ephemeral short URLs for OAuth flows |\n| [tollbooth-oauth2-collector](https://github.com/lonniev/tollbooth-oauth2-collector) | OAuth2 callback collector -- browser-based token exchange |\n| [tollbooth-pricing-studio](https://github.com/lonniev/tollbooth-pricing-studio) | iOS app -- operator dashboard and pricing model editor |\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE) for details.\n",
  "bytes": 5462,
  "sha": "1b428cd53c30f81408329e0aa165daa0a8f76603f7b500281a56de99b488af6e",
  "repo_slug": "lonniev/tollbooth-shortlinks",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_lonniev_tollbooth_shortlinks_fa7431bb/readme"
}