🔗 URL Builder MCP Server - Enterprise Edition

Professional URL construction with intelligent parameter handling for Claude Desktop

Developed by DAOTOMATA FZE - Commercial Private Software

⚠️ PROPRIETARY SOFTWARE NOTICE

This software is proprietary to DAOTOMATA FZE and is licensed for commercial use only. Unauthorized distribution, modification, or reverse engineering is strictly prohibited.

For licensing inquiries: [email protected]

🚀 Overview

The URL Builder MCP Server is an enterprise-grade Model Context Protocol (MCP) server designed specifically for professional URL construction and management. It provides seamless integration with Claude Desktop and other AI assistants, offering comprehensive URL building capabilities with intelligent parameter handling.

Key Benefits

• 🔒 Enterprise Security: Proprietary codebase with commercial-grade security
• 🎯 Focused Functionality: Specialized URL construction without business logic bloat
• ⚡ High Performance: Intelligent parameter validation and encoding
• 🔧 Easy Integration: NPX-based deployment for Claude Desktop
• 📊 Real-time Validation: Built-in parameter validation and error handling

🔗 Features

Core Functionality

• Professional URL Construction: Safe, secure URL building with intelligent parameter handling
• Multiple URL Formats: Support for external booking URLs, internal project URLs, and complete URLs
• Intelligent Validation: Advanced parameter validation with descriptive error messages
• Environment Configuration: Flexible configuration through environment variables

Technical Features

• 5 MCP Tools: Comprehensive URL building and validation toolkit
• TypeScript Support: Full type safety and IntelliSense support
• Cross-platform: macOS, Linux, and Windows support
• Zero-configuration startup: Works out of the box with sensible defaults

📦 Installation & Setup

Prerequisites

• Node.js 18.0+
• Claude Desktop or compatible MCP client

Quick Start

# Install via NPX (recommended)
npx url-builder-mcp --help

# Or install globally
npm install -g url-builder-mcp

Claude Desktop Configuration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "url-builder-mcp": {
      "command": "npx",
      "args": ["url-builder-mcp"],
      "env": {
        "BASE_DOMAIN": "https://hotels.cloudbeds.com/en/reservas/lmKzDQ",
        "DEFAULT_CURRENCY": "eur"
      }
    }
  }
}

📋 Available Tools

🛠️ URL Construction with UTM Tracking

• build_booking_url - Construct external booking URLs with intelligent UTM tracking
• build_internal_url - Construct internal project URLs with UTM analytics
• build_complete_url - Construct complete URLs with configurable UTM parameters
• validate_url_params - Validate URL parameters without building URLs

📊 UTM Tracking Features

• Automatic UTM Parameters: All URLs include intelligent traffic tracking by default
• Customizable UTM Values: Override default UTM parameters for specific campaigns
• Traffic Source Identification: Identify traffic coming from this MCP server
• Analytics Integration: Ready for Google Analytics, Adobe Analytics, and other platforms

📊 UTM Tracking & Analytics

Default UTM Parameters

All URLs generated by this MCP include intelligent UTM tracking parameters:

utm_source=claude-desktop      # Traffic source identification
utm_medium=ai-assistant        # Marketing medium
utm_campaign=url-builder-mcp   # Campaign identification
utm_content=mcp-generated-link # Content differentiation

Custom UTM Parameters

You can customize UTM parameters for specific campaigns:

{
  "addUtmTracking": true,
  "utmCampaign": "summer-promotion",
  "utmSource": "claude-ai",
  "utmMedium": "ai-booking-assistant"
}

Disabling UTM Tracking

To disable UTM tracking for specific URLs:

{
  "addUtmTracking": false
}

Analytics Integration

The UTM parameters are compatible with:

• Google Analytics 4 (GA4) - Automatic campaign tracking
• Adobe Analytics - Marketing channel classification
• HubSpot - Lead source attribution
• Custom Analytics - Any UTM-compatible platform

🔧 Configuration

Set the following environment variables:

# Base domain/URL for all URL generation
# Can be localhost for development or your production domain/booking URL
BASE_DOMAIN=https://hotels.cloudbeds.com/en/reservas/lmKzDQ

# Default currency for bookings
DEFAULT_CURRENCY=eur

# Alternative environment variable names (for backward compatibility)
# MCP_BASE_DOMAIN=https://your-domain.com
# BOOKING_URL_BASE=https://hotels.cloudbeds.com/en/reservas/lmKzDQ

🚀 Usage Methods

Method 1: Direct NPX (Recommended)

# Run directly without installation
npx url-builder-mcp

# With help
npx url-builder-mcp --help

Method 2: Global Installation

# Install globally
npm install -g url-builder-mcp

# Run from anywhere
url-builder-mcp

Method 3: Development Mode

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm test:watch

# Run linter
npm run lint

# Format code
npm run format

Usage

As MCP Tool

Start the server:

npm start

The server will run on stdio and provide the following tools:

build_booking_url

Constructs booking URLs with smart format detection:

• External URLs (Cloudbeds): Hash fragment parameters
• Localhost URLs: Query parameters with correct path

Parameters:

• checkIn (required): Check-in date in YYYY-MM-DD format
• checkOut (required): Check-out date in YYYY-MM-DD format
• guestName (required): Guest name
• guestPhone (required): Guest phone
• adults (optional): Number of adults (1-20, default: 2)
• children (optional): Number of children (0-10, default: 0)
• roomType (optional): Room type name (e.g., "garden-deluxe", "standard", "suite")
• guestEmail (optional): Guest email

Example:

{
  "checkIn": "2024-06-01",
  "checkOut": "2024-06-03",
  "guestName": "Juan Pérez",
  "guestPhone": "+34612345678",
  "adults": 2,
  "children": 1,
  "roomType": "garden-deluxe",
  "guestEmail": "[email protected]"
}

Result (localhost):

http://localhost:8080/accommodation/reservations?checkIn=2024-06-01&checkOut=2024-06-03&adults=2&children=1&roomType=garden-deluxe&guestName=Juan+P%C3%A9rez&guestPhone=%2B34612345678&guestEmail=juan%40email.com

Result (external Cloudbeds with BASE_DOMAIN env var):

https://hotels.cloudbeds.com/en/reservas/lmKzDQ#checkin=2024-06-01&checkout=2024-06-03&currency=eur&adults=2&children=1&roomType=garden-deluxe&guestName=Juan+P%C3%A9rez&guestPhone=%2B34612345678&guestEmail=juan%40email.com

build_internal_url

Constructs internal project URLs with query parameters.

Parameters:

• checkIn (required): Check-in date in YYYY-MM-DD format
• checkOut (required): Check-out date in YYYY-MM-DD format
• adults (optional): Number of adults
• children (optional): Number of children
• roomType (optional): Room type name (e.g., "garden-deluxe", "standard", "suite")
• guestName (optional): Guest name
• guestEmail (optional): Guest email
• guestPhone (optional): Guest phone

Example:

{
  "checkIn": "2024-01-20",
  "checkOut": "2024-01-24",
  "adults": 2,
  "children": 1,
  "roomType": "garden-deluxe",
  "guestName": "María García López",
  "guestEmail": "[email protected]",
  "guestPhone": "+34665789123"
}

Result:

/accommodation/reservations?checkIn=2024-01-20&checkOut=2024-01-24&roomType=garden-deluxe&adults=2&children=1&guestName=Mar%C3%ADa+Garc%C3%ADa+L%C3%B3pez&guestEmail=maria.garcia%40email.com&guestPhone=%2B34665789123

build_complete_url

Constructs complete URLs using configurable base domain from environment variables.

Parameters:

• relativePath (required): Relative path to append to base domain
• checkIn (optional): Check-in date in YYYY-MM-DD format
• checkOut (optional): Check-out date in YYYY-MM-DD format
• adults (optional): Number of adults
• children (optional): Number of children
• guestName (optional): Guest name
• guestEmail (optional): Guest email
• guestPhone (optional): Guest phone

Example:

{
  "relativePath": "/api/bookings",
  "checkIn": "2024-06-01",
  "checkOut": "2024-06-03"
}

Result (with BASE_DOMAIN=https://example.com):

https://example.com/api/bookings

validate_url_params

Validates URL parameters without building URLs.

Parameters: Same as other tools

Result: Returns validation status and any error messages.

As TypeScript Library

import { buildBookingUrl, buildInternalUrl, buildCompleteUrl, validateUrlParams } from './src/urlBuilder';

// Build booking URL
const bookingUrl = buildBookingUrl({
  checkIn: '2024-06-01',
  checkOut: '2024-06-03',
  adults: 2
});

// Build internal URL (relative by default)
const internalUrl = buildInternalUrl({
  checkIn: '2024-06-01',
  checkOut: '2024-06-03',
  guestName: 'Juan Pérez'
});

// Build internal URL with base domain (requires BASE_DOMAIN env var)
const completeInternalUrl = buildInternalUrl({
  checkIn: '2024-06-01',
  checkOut: '2024-06-03'
}, { useBaseDomain: true });

// Build complete URL with custom path (requires BASE_DOMAIN env var)
const completeUrl = buildCompleteUrl('/api/custom-endpoint');

// Build complete URL with parameters
const completeUrlWithParams = buildCompleteUrl('/api/bookings', {
  checkIn: '2024-06-01',
  checkOut: '2024-06-03'
});

// Validate parameters
const validation = validateUrlParams({
  checkIn: '2024-06-01',
  checkOut: '2024-06-03'
});

URL Formats

External Booking URL (Cloudbeds)

Uses hash fragment format:

https://hotels.cloudbeds.com/en/reservas/lmKzDQ#checkin=YYYY-MM-DD&checkout=YYYY-MM-DD&currency=eur&adults=N&children=N&roomType=ROOM_TYPE

Internal Project URL

Uses query parameters format:

/accommodation/reservations?roomType=ROOM_TYPE&checkIn=YYYY-MM-DD&checkOut=YYYY-MM-DD&adults=N&children=N&guestName=NAME&guestEmail=EMAIL&guestPhone=PHONE

Example with room type:

/accommodation/reservations?roomType=garden-deluxe&checkIn=2024-01-20&checkOut=2024-01-24&adults=2&children=1&guestName=María%20García%20López&[email protected]&guestPhone=+34665789123

Complete URL with Base Domain

Uses configurable base domain with relative paths:

https://your-domain.com/custom/path?param1=value1&param2=value2

Environment Variables:

• BASE_DOMAIN (primary) with fallbacks to MCP_BASE_DOMAIN or BOOKING_URL_BASE
• If not set, defaults to http://localhost:8080 for development

Validation Rules

• Dates: Must be in YYYY-MM-DD format
• Date Range: Check-out must be after check-in
• Adults: 1-20 (optional, default: 2)
• Children: 0-10 (optional, default: 0)
• Children=0: Not included in external URLs

Error Handling

All functions validate input parameters and throw descriptive errors:

// Invalid date format
validateUrlParams({ checkIn: '01/06/2024', checkOut: '2024-06-03' });
// Error: "Formato de checkIn inválido. Use YYYY-MM-DD"

// Invalid date range  
validateUrlParams({ checkIn: '2024-06-03', checkOut: '2024-06-01' });
// Error: "La fecha de salida debe ser posterior a la de entrada"

Testing

Run the test suite:

npm test

The tests cover:

• ✅ Parameter validation with various invalid inputs
• ✅ URL construction with different parameter combinations
• ✅ Environment variable configuration
• ✅ Special character encoding
• ✅ Edge cases and error conditions

🏢 Enterprise Support

Commercial Licensing

• Internal Use: Licensed for DAOTOMATA FZE operations
• Partner Access: Available for authorized partners and clients
• Custom Development: Tailored solutions for specific requirements
• Integration Support: Professional integration assistance

Support Services

• Technical Support: Direct access to DAOTOMATA development team
• Custom Features: Bespoke development for specific needs
• Training: Staff training and onboarding assistance
• Maintenance: Regular updates and security patches

Contact Information

• Company: DAOTOMATA FZE
• Email: [email protected]
• Support: Available through service agreement

📊 Technical Specifications

Performance

• Response Time: < 100ms average
• Concurrent Users: 50+ simultaneous connections
• Uptime: 99.9% availability target

Security

• Data Validation: Comprehensive input validation
• Parameter Encoding: Safe URL encoding for all parameters
• Error Handling: Graceful error handling with descriptive messages
• Compliance: Enterprise security standards

📁 Project Structure

url-builder-mcp/
├── bin/
│   └── url-builder-mcp.js        # NPX launcher script
├── scripts/
│   ├── postinstall.js            # Post-installation guidance
│   └── preuninstall.js           # Clean uninstallation
├── src/
│   ├── __tests__/
│   │   └── urlBuilder.test.ts    # Test suite
│   ├── types.ts                  # TypeScript interfaces
│   ├── urlBuilder.ts             # Core URL building logic
│   ├── server.ts                 # HTTP server
│   └── index.ts                  # MCP server
├── dist/                         # Compiled JavaScript
├── package.json                  # NPM package configuration
├── tsconfig.json                 # TypeScript configuration
├── jest.config.js                # Test configuration
├── LICENSE                       # Proprietary license
└── README.md                     # This file

📄 License

This software is proprietary to DAOTOMATA FZE. See LICENSE for complete terms and conditions.

Copyright © 2025 DAOTOMATA FZE. All rights reserved.

For technical documentation, API references, and integration guides, please contact DAOTOMATA FZE support.