url-builder-mcp/README.md

URL Builder MCP Server - Professional URL construction with intelligent parameter handling for Claude Desktop

# 🔗 URL Builder MCP Server - Enterprise Edition

**Professional URL construction with intelligent parameter handling for Claude Desktop**

*Developed by DAOTOMATA FZE - Commercial Private Software*

[![NPM Version](https://img.shields.io/npm/v/url-builder-mcp)](https://www.npmjs.com/package/url-builder-mcp)
[![License](https://img.shields.io/badge/license-PROPRIETARY-red.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/node.js-18+-blue.svg)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-green.svg)](https://typescriptlang.org)

---

## ⚠️ 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**: contact@daotomata.com

---

## 🚀 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

```bash
# 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:

```json
{
  "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:

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

### Disabling UTM Tracking

To disable UTM tracking for specific URLs:

```json
{
  "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:

```bash
# 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)
```bash
# Run directly without installation
npx url-builder-mcp

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

### Method 2: Global Installation
```bash
# Install globally
npm install -g url-builder-mcp

# Run from anywhere
url-builder-mcp
```

### Method 3: Development Mode
```bash
# 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:

```bash
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:**
```json
{
  "checkIn": "2024-06-01",
  "checkOut": "2024-06-03",
  "guestName": "Juan Pérez",
  "guestPhone": "+34612345678",
  "adults": 2,
  "children": 1,
  "roomType": "garden-deluxe",
  "guestEmail": "juan@email.com"
}
```

**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:**
```json
{
  "checkIn": "2024-01-20",
  "checkOut": "2024-01-24",
  "adults": 2,
  "children": 1,
  "roomType": "garden-deluxe",
  "guestName": "María García López",
  "guestEmail": "maria.garcia@email.com",
  "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:**
```json
{
  "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

```typescript
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&guestEmail=maria.garcia@email.com&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:

```typescript
// 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:

```bash
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**: contact@daotomata.com
- **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](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.*