# Deterministic URL Engine MCP MCP

> Deterministic URL Engine provides flawless, programmatic control over web links. Stop fighting broken URLs. This MCP lets your AI client accurately parse complex URIs, extract specific tracking parameters from messy query strings, and inject new data points—all without risking double ampersands or malformed question marks.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** uri-parsing, url-manipulation, query-string, data-normalization, v8-engine, parameter-injection

## Description

When you're building any system that touches the internet—be it analytics, marketing funnels, or API calls—URL structure is everything. The problem is simple: standard LLMs are terrible at URL mechanics. They treat links like plain text and will mangle them when they try to add a tracking parameter or split a deep query string. You end up with broken links that just don't work.

The Deterministic URL Engine fixes this by running all link manipulation through a reliable V8 engine. It handles the messy mechanics of web addresses so you don't have to worry about syntax errors, concatenation failures, or missing components. Instead of guessing how to split a path into its host and query parameters, your agent simply calls `parse_url` for an atomic breakdown. Need to add a campaign tag? Use `inject_query`. It guarantees the link remains valid every time. This kind of reliable data plumbing is exactly what Vinkius provides in their catalog, letting you trust your AI client with mission-critical web links.

## Tools

### extract_query
Pulls a single parameter value from a URL's query string without using complex regular expressions.

### inject_query
Updates or adds new parameters to a URL, guaranteeing perfect placement of question marks and ampersands.

### parse_url
Breaks down any complex URL into its fundamental components: protocol, host, path, query string, and hash.

## Prompt Examples

**Prompt:** 
```
Parse this tracking URL and show me its base hostname: https://google.com/search?q=test&lang=en
```

**Response:** 
```
Using the parse_url tool: The base hostname is 'google.com'.
```

**Prompt:** 
```
Inject a UTM campaign parameter into this link: https://vinkius.com/pricing
```

**Response:** 
```
Using the inject_query tool (params: {"utm_campaign": "summer"}): The new URL is https://vinkius.com/pricing?utm_campaign=summer.
```

**Prompt:** 
```
Extract just the 'token' value from this callback URL.
```

**Response:** 
```
Using the extract_query tool (paramKey='token'): The extracted token value is 'ABC123XYZ'.
```

## Capabilities

### Structural URL Breakdown
Deconstructs any complete URL into its core parts: the protocol, host, path, query parameters, and hash tag.

### Safe Parameter Injection
Adds or updates specific tracking parameters in a URL, ensuring mathematically correct addition of question marks and ampersands.

### Targeted Query Extraction
Pulls the value for one specified parameter from a long query string without resorting to unreliable regular expressions.

## Use Cases

### Attribution Tracking Link Generation
A marketer needs to generate 50 unique links, each requiring a different campaign ID. Instead of manually checking the syntax for every link, they ask their agent to use `inject_query` five times, ensuring flawless parameter placement across all resulting URLs.

### Deep Link Data Retrieval
A customer service bot receives a support ticket with a complex callback URL. It uses `extract_query` to pull out the specific 'ticket_id' and 'user_session' parameters, passing only that clean data to the backend system.

### API Endpoint Normalization
A developer is writing a script that needs to know if an incoming URL points to a staging or production environment. They use `parse_url` first to check the hostname component, letting them route the request correctly.

### Data Context Mining
An agent processes raw logs containing many URLs. It uses `parse_url` and then `extract_query` in sequence: first getting the base path, then pulling a specific 'user_id' from that path's query string.

## Benefits

- Prevents broken marketing funnels: Use `inject_query` to safely add UTM tags, knowing the link will always validate correctly, saving you hours of QA time.
- Accurate data extraction: Pull specific codes or tokens using `extract_query` without writing risky regex. It isolates exactly what you need from long query strings.
- Structural integrity: Never guess how a URL is built again. Run `parse_url` to get the absolute breakdown of every component, making your agent's understanding rock solid.
- Reliable API payloads: When building agents that interact with webhooks or endpoints, this MCP ensures the required parameters are formatted correctly before sending data.
- Frictionless development: Developers gain a predictable layer for link manipulation. They don't have to build custom parser logic; they just call `parse_url`.

## How It Works

The bottom line is, you get predictable, reliable web address mechanics every single time. No guesswork required.

1. You feed your agent a URL and specify what you need: maybe just the base host, or perhaps a new tracking tag.
2. Your AI client invokes the appropriate tool—for example, running `parse_url` to analyze structure, or `extract_query` to pull data.
3. The engine returns the clean, processed output (like the separated hostname or the newly modified link), ready for your next step.

## Frequently Asked Questions

**How does the Deterministic URL Engine MCP fix broken links?**
The engine uses a pristine V8 deterministic mechanism to handle all URI mechanics, eliminating common errors like double question marks or misplaced ampersands that manual LLM manipulation causes.

**Can I use the inject_query tool if the URL already has parameters?**
Yes. The `inject_query` tool is built specifically to handle existing parameters, safely appending new ones using correct syntax whether it's the first parameter or the tenth.

**What should I use if I only need one piece of data from a query string?**
Use `extract_query`. It lets you specify exactly which parameter key you want and pulls out just that value, keeping it clean and free of regex errors.

**Do I need to use parse_url before calling inject_query?**
Not necessarily. `inject_query` can handle the structure itself. However, running `parse_url` first is smart practice; it lets you verify the link's existing components and build confidence in your data flow.

**How does the `extract_query` tool handle sensitive data like authentication tokens within a URL?**
It securely extracts only the requested parameter value. You pass the key (e.g., 'token'), and it returns the clean value without manipulating or exposing the surrounding URI structure.

**If I pass an invalid or malformed URI to `parse_url`, will the deterministic engine fail?**
No, the V8 engine is designed for resilience. It handles invalid inputs gracefully by returning nulls or partial data for components it can't parse, preventing a hard failure.

**When using `inject_query`, can I inject multiple JSON key-value pairs in one request?**
Yes, you provide all new parameters within the single JSON string input. The engine processes them as a set of additions, guaranteeing correct separation with ampersands (&) for every pair.

**Is there a performance difference between using `parse_url` and implementing URL logic manually with regex?**
Yes. Since it runs on a pure Javascript V8 deterministic engine, the processing is extremely fast. It avoids the overhead and complexity associated with custom code or bloated external packages.