Parse and build URLs (protocol, hostname, port, path, query, hash, auth) via @mukundakatta/url-mcp

@mukundakatta/url-mcp v0.1.0 — Verified Recipe

Install: npm install @mukundakatta/url-mcp Entry: dist/server.js (stdio transport) Tools: 2

Tool Schema

1. `parse` ({url: string}) — decompose a URL into components. Returns {href, protocol, username, password, host, hostname, port, pathname, search, hash, query: {key: value}}.
2. `build` ({protocol: string, hostname: string, port?: string|int, pathname?: string, query?: object, hash?: string, username?: string, password?: string}) — construct a URL from parts. Returns {url: string}.

Execution Trace (20 calls, 100% tool correctness)

Key Gotchas

1. ⚠️ `build` param is `hostname` NOT `host` — using host silently produces undefined in the URL string (no error thrown). The schema is explicit ("hostname") but the naming differs from Node's url.parse() convention where host includes port.
2. ⚠️ `build` param is `pathname` NOT `path` — same silent undefined issue. Must include leading /.
3. ⚠️ `build` param is `hash` NOT `fragment` — the hash value should NOT include # prefix (just "overview", not "#overview").
4. `parse` returns `hash` WITH `#` prefix ("#results") — must strip # when feeding into build for round-trip.
5. `parse` returns `query` as decoded key-value map — %20 and + both decoded to spaces. Percent-encoded path stays encoded.
6. `build` auto-encodes query values — spaces → +, & → %26, = → %3D.
7. Array query values supported — {tags: ["js","ts"]} → tags=js&tags=ts (repeated keys).
8. Relative URLs NOT supported — parse requires a protocol; /api/v1/... returns "Invalid URL".
9. Non-HTTP protocols work for parsing — mailto, data, ftp all parsed correctly.
10. Port returned as string — "8443" not 8443, but build accepts both string and integer.
11. Unicode in paths → percent-encoded, Unicode in query values → decoded in the query map.
12. No URL validation beyond parsability — any parseable URL is accepted.