url_parse

Parse a URL string into its individual components. Returns the scheme, host, optional port, path, raw query string, fragment, and optional credentials from the authority component.

Parameters

Parameter	Type	Required	Description
url	string	Yes	The URL string to parse (e.g. https://example.com/path?key=value#section).

Response

Field	Type	Description
scheme	string	URL scheme (e.g. "https", "http", "ftp").
host	string	Hostname or IP address (e.g. "example.com").
port	number or null	Port number if explicitly present in the URL; null if absent.
path	string	Path component (e.g. "/path/to/resource"); always present, "/" if absent.
query	string or null	Raw query string without the leading ? (e.g. "key=value&other=x"); null if absent.
fragment	string or null	Fragment identifier without the leading # (e.g. "section"); null if absent.
username	string or null	Username from the authority component; null if absent.
password	string or null	Password from the authority component; null if absent.

Examples

Input:

{
	"url": "https://user:pass@api.example.com:8080/v1/users?page=2&limit=10#results"
}

Result:

{
	"scheme": "https",
	"host": "api.example.com",
	"port": 8080,
	"path": "/v1/users",
	"query": "page=2&limit=10",
	"fragment": "results",
	"username": "user",
	"password": "pass"
}

---

Input (minimal URL):

{
	"url": "https://example.com"
}

Result:

{
	"scheme": "https",
	"host": "example.com",
	"port": null,
	"path": "/",
	"query": null,
	"fragment": null,
	"username": null,
	"password": null
}

Errors

Each failure carries a precise code in the response. Argument-schema and server errors are JSON-RPC protocol errors; a rejected value is returned as a tool result with isError: true (so the agent can read the code and self-correct).

Code	When	Delivered as
invalid_arguments	An argument is missing or the wrong type.	protocol error (invalid_params)
invalid_url	The input string is not a valid URL, or has no host (e.g. bare data: or mailto: URIs).	tool error (isError)
internal_error	An unexpected server error.	protocol error (internal_error)

Notes

• The query field is the raw query string. Individual key-value pairs are not split — use string manipulation or url_build to reconstruct query strings.
• port is only set when the port is explicitly present in the URL. Standard ports (443 for HTTPS, 80 for HTTP) are not returned unless written literally in the input.
• Credentials (username, password) are extracted from the authority component (user:pass@host). They are not percent-decoded.