Url Shortener MCP Server

URL-Shortener

Overview

hrva.cc is a privacy-first URL shortener with built-in link safety. This repository is the backend: a Spring Boot API that creates and redirects short links, checks them for phishing and malware, and counts clicks without tracking anyone. The frontend lives in HrvaLabs/URL-Shortener-FE.

The changelog is shown at app.hrva.cc/changelog and kept in CHANGELOG.md. AGENTS.md documents the architecture, commands, endpoints and configuration.

Features

Links

• Random short links, or a custom alias when you're signed in. Links can also be made without an account, with a stricter rate limit.
• Expiry dates, visit limits, password protection and tags.
• Bulk creation, and an API with API keys (X-Api-Key). Each key makes up to 600 requests an hour by default (Site settings); every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, and a key over the limit gets a 429 with Retry-After. A key expires after the days you choose (1 to 3,650), after 12 months by default, or never. Keys are stored as SHA-256 hashes: the full key is shown once, when it is made, and the lists show its first characters.
• A campaign tag (UTM) builder.
• QR codes that count their scans.
• Opt-in notifications by email or to Discord, Slack, Telegram, ntfy or a webhook: dead destinations, expiry reminders, and daily or weekly summaries.

Custom domains

• Short links on your own subdomain, like go.example.com/menu. You apply in Settings; once an admin approves, you add one CNAME record and the certificate is issued through Cloudflare for SaaS.
• Aliases on your domain are separate from hrva.cc's, and its links get the same stats, limits, passwords and expiry dates.

Bio pages

• One page at hrva.cc/@yourname, with a button for each of your short links.
• Views are counted per day, and changing your handle keeps the old one held for 30 days.

Safety

• Every new link, every click and a nightly rescan go through:
  • Google Safe Browsing
  • admin-managed blocklists (HaGeZi, OpenPhish, PhishTank, Phishing.Database, URLhaus)
  • Spamhaus DBL
  • domain age (RDAP)
  • redirect-chain and look-alike checks
• Visitors can report links and bio pages.
• Suspicious links go to a review queue rather than being blocked blindly.
• A phishing-wave alert warns when many new links point at the same new domain.

Privacy-first analytics

• Clicks are stored only as daily totals per link: visitors, referrers, devices, browsers, countries, and QR scans against other clicks.
• Unique visitors come from a one-way hash under a key that changes every day, kept only in Redis.
• Bots are counted apart.
• The public hrva.cc in numbers page shows site-wide totals.

Accounts

• Sign in with email and password, Google, or a passkey or security key.
• Two-step verification works with every sign-in method, using an authenticator app or a passkey, with recovery codes.
• You can export your data and delete your account.

AI connector

• AI apps such as Claude use hrva.cc over MCP at https://hrva.cc/mcp, signing in with OAuth 2.1.

Admin

• Pages for stats, the review queue, moderation, blocklists, domain rules, reserved aliases, bio pages, custom domains and the audit log.
• Discord alerts, a weekly summary and a daily decisions email.

Technologies Used

• Backend: Java 25, Spring Boot 4.1, Spring Security and Spring Authorization Server, Spring AI (MCP)
• Database: PostgreSQL with Liquibase migrations, and Redis
• Frontend: Next.js 16 on Cloudflare Workers (separate repository)
• Deploy: GitHub Actions builds the Docker image and triggers a Portainer stack webhook. The site runs behind Cloudflare.

Running it

Build, test and run commands, local dev users and the end-to-end check (scripts/mcp-e2e.sh) are in AGENTS.md. The short version: docker compose -f docker/docker-compose.yml up -d for Postgres and Redis, then mvn spring-boot:run -Dspring-boot.run.profiles=local. For tests, run mvn -B test.

Production requirements

• Docker image: two stages on eclipse-temurin:25-jre, run by the non-root user app (uid 10001), listening on 8080, with a HEALTHCHECK that asks /actuator/health/liveness every 30 s (120 s start period, so the first boot and its Liquibase run aren't marked unhealthy). The check names a primary host (HEALTHCHECK_HOST, else the first APP_DOMAINS_PRIMARY_HOSTS entry, else hrva.cc), because every other host answers 404. CI pushes :latest and an immutable :<commit sha>. Java is PID 1, so docker stop ends the app cleanly with SIGTERM, well inside a 30 s stop_grace_period.
  • Pin by commit (optional): in the Portainer stack, change image: ghcr.io/hrvalabs/url-shortener:latest to image: ghcr.io/hrvalabs/url-shortener:<full commit sha> and update the stack. The webhook then redeploys the same sha, so the stack changes only when you edit it; a rollback is one edit back to the earlier sha. Keep :latest if you want every push to deploy.
  • Port: the app needs no published port, because Nginx Proxy Manager reaches url-shortener-backend:8080 on the Docker network. The Portainer stack publishes none, so nobody can reach the origin around Cloudflare; keep it that way (or bind to 127.0.0.1 if a host port is ever needed).
• Actuator: health is exposed over HTTP, plus its liveness and readiness probes, and (v2.30) prometheus only when APP_METRICS_TOKEN is set: it answers with Authorization: Bearer <APP_METRICS_TOKEN>, 401 for a wrong or missing token, and 404 when the variable is unset. env, beans, metrics, caches and info are off the web. https://hrva.cc/actuator/health checks the database and Redis (a 503 when either is down), disk space, ping and SSL, and not the mail server (management.health.mail.enabled: false): that check opened an SMTP connection on every call, about 110 of 185 ms in a local run with 30 ms of network delay to each service. The container check uses liveness.
• How long a sign-in lasts (v2.31): a sign-in ends app.jwt-token-validity-seconds (10 hours) after the last time the web app renewed it, which it does while you use it, and never later than APP_JWT_SESSION_MAX_SECONDS after the sign-in (default 2592000, 30 days). Remember me keeps its 30 days.
• Daily Browser Run allowance (v2.30): APP_INSPECTION_BROWSER_SECONDS_DAILY_LIMIT (default 600, Cloudflare's free allowance) is what the admin Health page compares today's screenshot seconds with.
• Redis down: the rate limits let requests through, except three that refuse until Redis is back: links made without an account, the link-password unlock and the password sign-in (each a 503 with Retry-After: 60). Signed-in, API-key and MCP creates go on.
• Admin accounts need two-step sign-in (v2.23): turn it on for every admin account before or right after the deploy. Until then, admin pages and the MCP moderation tools answer "Turn on two-step sign-in to use admin pages."
• Outbound egress (v2.23): every fetch the app makes is pinned to a checked public address, but block the container's egress to 169.254.169.254 and the private ranges other than the stack's Docker network on the host as well (DOCKER-USER iptables rules).
• Code scanning (v2.23): codeql.yml needs code scanning on the repository and dependencies.yml's PR review needs the dependency graph; for a private repository both need GitHub Advanced Security.
• Inactive accounts get an email 30 days before they are deactivated after 5 years without use (a sign-in, an API key or a connected MCP app counts as use). Nothing to set up; the first run after the deploy warns every account that is already past the limit and deactivates it 30 days later.
• PostgreSQL 15 or newer (the analytics counters use MERGE) and Redis 6.2 or newer (GETDEL, SMISMEMBER).
• Environment variables: the full list is in AGENTS.md (CI / Deploy, and MCP connector → Configuration). APP_MCP_SIGNING_KEY is required, and the app won't start without it. Generate a private RSA JWK and keep it out of git and logs:

  node -e "const {generateKeyPairSync, randomUUID} = require('node:crypto'); const {privateKey} = generateKeyPairSync('rsa', {modulusLength: 2048}); console.log(JSON.stringify({...privateKey.export({format: 'jwk'}), kid: randomUUID(), use: 'sig', alg: 'RS256'}))"
  

• APP_NOTIFICATIONS_KEY is required too, and the app won't start without it. It encrypts the notification channels' URLs and tokens and signs the unsubscribe links, so keep it next to the MCP signing key: losing it means everyone re-adds their channels. Generate 32 random bytes:

  openssl rand -base64 32
  

• The human check on links made without an account needs APP_TURNSTILE_SITE_KEY and APP_TURNSTILE_SECRET_KEY (the Turnstile widget's keys); without them the app starts and no check runs. Keep the secret key out of git and logs.
• Custom domains need CLOUDFLARE_API_TOKEN and CLOUDFLARE_ZONE_ID; without them the app starts and refuses approvals. The other variables (APP_DOMAINS_ENABLED, APP_DOMAINS_MAX_ACTIVE, APP_DOMAINS_FREE_ALLOWANCE, APP_DOMAINS_PER_USER, APP_DOMAINS_RESERVED, APP_DOMAINS_PRIMARY_HOSTS, APP_DOMAINS_IGNORED_HOSTNAMES, APP_DOMAINS_CNAME_TARGET, APP_CLOUDFLARE_API_BASE) have working defaults, listed in AGENTS.md (Config Profiles). Before the first deploy with custom domains:
  • O1: CLOUDFLARE_ZONE_ID is the hrva.cc zone's id, and the token has Zone, SSL and Certificates, Edit on the hrva.cc zone only. Use that token nowhere else.
  • O2: the reverse proxy's catch-all default_server refuses non-Cloudflare addresses (444), like the proxy hosts. Custom hostnames reach the origin through it.
  • O3: every hostname that must keep reaching the backend is in APP_DOMAINS_PRIMARY_HOSTS (default hrva.cc,domains.hrva.cc; the host of app.server-url always counts). Any other Host answers 404 after the deploy, including a request to the container by IP or localhost, so health checks go through https://hrva.cc/actuator/health.
  • O4: APP_DOMAINS_IGNORED_HOSTNAMES lists the Cloudflare hostnames that aren't custom domains (default test.karlo.cc), so the nightly reconcile doesn't flag them. They answer 404.
  • O5: the admin System tab shows PostgreSQL 15 or newer; migration 032 stops startup otherwise.
  • O6: custom hostnames run through the hrva.cc zone's Cloudflare rules. Check that no cache, configuration, redirect or WAF skip rule they also need matches only http.host eq "hrva.cc", and that redirects are never cached.
• Cloudflare-only origin. The per-network rate limits trust CF-Connecting-IP, and the country counts trust CF-IPCountry. The origin must therefore accept traffic only from Cloudflare, through a Cloudflare Tunnel or a firewall limited to Cloudflare's IP ranges. Otherwise anyone can forge those headers.
• Cloudflare rules for the MCP paths and one-click unsubscribe. MCP clients aren't browsers, and neither are the mail providers that POST a one-click unsubscribe (RFC 8058) from the email's List-Unsubscribe header. A challenge breaks both:
  • Exempt /mcp, /oauth2/*, /.well-known/* and /api/v1/notifications/unsubscribe from WAF managed challenges and Super Bot Fight Mode. If Bot Fight Mode on the Free plan challenges them, turn it off.
  • Don't cache GET /oauth2/authorize or /.well-known/* at the edge.
• Smoke test after a deploy. Expect issuer https://hrva.cc, resource https://hrva.cc/mcp, and 401 from /mcp without a token:

  curl -s https://hrva.cc/actuator/health
  curl -s https://hrva.cc/.well-known/oauth-authorization-server | jq '{issuer, registration_endpoint}'
  curl -s https://hrva.cc/.well-known/oauth-protected-resource/mcp | jq '{resource, authorization_servers}'
  curl -s -o /dev/null -w '%{http_code}\n' -X POST https://hrva.cc/mcp
  

Contribution

We welcome contributions from the community!

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.

Contact

For questions, issues, or feature requests, please open an issue on GitHub or contact me directly via email.

Thank you for using URL-Shortener or just viewing this page!