A clean, production-ready URL shortener with analytics and native MCP tooling — built on FastAPI + FastMCP and Next.js, served from a single backend port.
- Fast URL shortening with optional custom aliases
- Redirect tracking with per-click event data (IP, user-agent, referrer)
- MCP tools for agent-native access — shorten, lookup, list, and analytics
- Single service surface: REST API + MCP on the same port
- Next.js frontend with analytics charts
| Doc | Description |
|---|---|
| docs/backend.md | FastAPI service — routes, architecture, database schema, deployment |
| docs/mcp.md | MCP endpoint — tools, transport, client setup (Claude Desktop, Cursor, …) |
| docs/frontend.md | Next.js frontend — pages, API client, environment variables |
cd backend
$env:DATABASE_URL = "postgresql+psycopg://postgres:postgres@localhost:5432/smolurls"
$env:BASE_URL = "http://127.0.0.1:8000/api/v1"
uv sync
uv run uvicorn main:app --reloadcd frontend
pnpm install
pnpm devsmolurls/
├── backend/ # FastAPI + FastMCP service
├── frontend/ # Next.js application
└── docs/ # Documentation
├── backend.md
├── mcp.md
└── frontend.md