@utilix-tech/mcp 0.58.0 → 0.60.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Full release notes for all Utilix surfaces (browser tools, REST API, SDKs, MCP server) live at [utilix.tech/changelog](https://utilix.tech/changelog). This file tracks just this package.
 
+## 0.60.0
+- Add `build_retry_after_header`, `parse_retry_after_header` tools: build an HTTP Retry-After response header from a delay in seconds or a target date, or parse an existing one, per RFC 9110.
+- Add `calculate_freelancer_rate` tool: solve for the minimum hourly rate a freelancer must charge to hit a target annual income, given billable hours, weeks worked, overhead, and a profit margin.
+
+## 0.59.0
+- Add `build_prefer_header`, `parse_prefer_header` tools: build an HTTP Prefer request-header value from preferences with optional values and parameters per RFC 7240, or parse an existing one into the same shape.
+- Add `dedupe_ndjson` tool: remove duplicate records from NDJSON input, either by exact structural equality or by a chosen key field, keeping the first occurrence of each duplicate.
+
 ## 0.58.0
 - Add `apply_json_merge_patch` tool: apply an RFC 7396 JSON Merge Patch document to a target JSON document, with null-valued patch keys removing the matching target key.
 - Add `generate_csp_nonce` tool: generate a cryptographically random, base64-encoded Content-Security-Policy nonce with ready-to-paste header directive and script/style tag snippets.

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/mcp
 
-MCP server exposing 205 developer utility tools to Claude, Cursor, VS Code Copilot, and any [Model Context Protocol](https://modelcontextprotocol.io) compatible AI assistant.
+MCP server exposing 211 developer utility tools to Claude, Cursor, VS Code Copilot, and any [Model Context Protocol](https://modelcontextprotocol.io) compatible AI assistant.
 
 No API key required. All tools run locally. Requires Node.js 18 or later.
 
@@ -162,7 +162,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `convert_timezone` | Convert a date/time between timezones |
 | `convert_iso8601_duration` | Parse an ISO 8601 duration into components and total seconds, or format seconds into a duration string |
 
-### Units (35 tools)
+### Units (36 tools)
 | Tool | Description |
 |------|-------------|
 | `convert_bytes` | Convert between B, KB, MB, GB, TB, KiB, MiB, GiB, TiB |
@@ -200,8 +200,9 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `calculate_credit_utilization` | Compute per-account and overall credit utilization (balance / limit) from one or more credit accounts, plus a qualitative tier matching common credit-scoring guidance |
 | `calculate_debt_to_income_ratio` | Compute the debt-to-income ratio (total monthly debt payments / gross monthly income) from one or more monthly debts, plus a qualitative tier matching common mortgage-lending guidance |
 | `calculate_blended_loan_rate` | Compute the single weighted-average interest rate across a list of loan balances, weighted by each loan's share of the combined balance, plus combined monthly and annual interest accrual |
+| `calculate_freelancer_rate` | Solve for the minimum hourly rate a freelancer must charge to hit a target annual income, given billable hours, weeks worked, overhead, and a profit margin |
 
-### API / Network (31 tools)
+### API / Network (33 tools)
 | Tool | Description |
 |------|-------------|
 | `decode_jwt` | Decode a JWT: header, payload, and expiry |
@@ -235,6 +236,10 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `build_x_content_type_options_header` | Build the fixed X-Content-Type-Options: nosniff header, validate a pasted value, or assess MIME-sniffing risk for a given Content-Type |
 | `build_accept_language` | Build an Accept-Language request-header value from locale/quality pairs, sorted by descending preference |
 | `parse_accept_language` | Parse an existing Accept-Language header value into its ranked locale/quality pairs |
+| `build_prefer_header` | Build an HTTP Prefer request-header value from preferences with optional values/params, per RFC 7240 |
+| `parse_prefer_header` | Parse an existing Prefer header value into its list of preferences, values, and parameters |
+| `build_retry_after_header` | Build a Retry-After response header from a delay in seconds or a target date, per RFC 9110 |
+| `parse_retry_after_header` | Parse an existing Retry-After header value into the same shape |
 
 ### Color (4 tools)
 | Tool | Description |
@@ -272,6 +277,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `xml_to_json` | Convert XML to JSON |
 | `parse_csv` | Parse a CSV string and return the data as JSON |
 | `format_ndjson` | Validate and pretty-print newline-delimited JSON (NDJSON) |
+| `dedupe_ndjson` | Remove duplicate records from NDJSON, by exact match or by a key field |
 | `diff_env_example` | Diff a .env file against its .env.example template: flags keys missing from either side, plus empty placeholder values |
 | `parse_markdown_front_matter` | Split a Markdown document into its YAML front matter fields and body content |
 | `generate_markdown_toc` | Scan a Markdown document's ATX headings and build a nested table of contents with GitHub-style anchor slugs |

package/dist/index.js

@@ -2606,6 +2606,53 @@ server.tool(
     return text(formatted);
   }
 );
+function _dedupeNdjsonMcp(input, keyField) {
+  const validated = _validateNdjson(input);
+  if (!validated.valid) {
+    const firstError = validated.lines.find((l) => !l.valid);
+    return { error: firstError ? `Line ${firstError.line}: ${firstError.error}` : "Invalid NDJSON" };
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const keptRaw = [];
+  const removedLines = [];
+  for (const l of validated.lines) {
+    const parsed = JSON.parse(l.raw);
+    let key;
+    if (keyField) {
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed) || !(keyField in parsed)) {
+        return { error: `Line ${l.line}: missing key field "${keyField}"` };
+      }
+      key = JSON.stringify(parsed[keyField]);
+    } else {
+      key = JSON.stringify(parsed);
+    }
+    if (seen.has(key)) removedLines.push(l.line);
+    else {
+      seen.add(key);
+      keptRaw.push(l.raw.trim());
+    }
+  }
+  return {
+    totalLines: validated.totalLines,
+    uniqueLines: keptRaw.length,
+    duplicatesRemoved: removedLines.length,
+    output: keptRaw.join("\n"),
+    removedLines
+  };
+}
+server.tool(
+  "dedupe_ndjson",
+  "Remove duplicate records from NDJSON (newline-delimited JSON) input. With no keyField, two lines are duplicates when their parsed JSON values are structurally identical. With a keyField, two lines are duplicates when that field's value matches, keeping the first occurrence of each key.",
+  {
+    input: z.string().describe("NDJSON content: one JSON value per line"),
+    keyField: z.string().optional().describe("Optional field name to dedupe by instead of exact structural equality")
+  },
+  async ({ input, keyField }) => {
+    const result = _dedupeNdjsonMcp(input, keyField);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
 function _decodePdfString(raw, isHex) {
   const bytes = [];
   if (isHex) {
@@ -9445,6 +9492,132 @@ server.tool(
     return text(JSON.stringify(result, null, 2));
   }
 );
+var _PREFER_TOKEN_RE_MCP = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+function _isPreferTokenMcp(s) {
+  return _PREFER_TOKEN_RE_MCP.test(s);
+}
+function _splitPreferTopLevelMcp(input, delim) {
+  const parts = [];
+  let current = "";
+  let inQuotes = false;
+  for (const ch of input) {
+    if (ch === '"') inQuotes = !inQuotes;
+    if (ch === delim && !inQuotes) {
+      parts.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  parts.push(current);
+  return parts;
+}
+function _parsePreferTokenValueMcp(part) {
+  const trimmed = part.trim();
+  if (!trimmed) return null;
+  const eq = trimmed.indexOf("=");
+  if (eq === -1) return { token: trimmed };
+  const token = trimmed.slice(0, eq).trim();
+  let value = trimmed.slice(eq + 1).trim();
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) value = value.slice(1, -1);
+  return { token, value };
+}
+function _formatPreferWordMcp(value) {
+  return _isPreferTokenMcp(value) ? value : `"${value.replace(/"/g, '\\"')}"`;
+}
+function _formatPreferPreferencesMcp(preferences) {
+  return preferences.map((p) => {
+    let s = p.token;
+    if (p.value !== void 0) s += `=${_formatPreferWordMcp(p.value)}`;
+    for (const param of p.params ?? []) {
+      s += `;${param.name}`;
+      if (param.value !== void 0) s += `=${_formatPreferWordMcp(param.value)}`;
+    }
+    return s;
+  }).join(", ");
+}
+function _buildPreferHeaderMcp(preferences) {
+  if (!Array.isArray(preferences) || preferences.length === 0) {
+    return { error: "At least one preference is required" };
+  }
+  const built = [];
+  for (let i = 0; i < preferences.length; i++) {
+    const { token, value, params } = preferences[i];
+    if (typeof token !== "string" || !_isPreferTokenMcp(token.trim())) {
+      return { error: `preference ${i + 1}: token is required and must be a valid HTTP token` };
+    }
+    const cleanParams = [];
+    if (params !== void 0) {
+      if (!Array.isArray(params)) return { error: `preference ${i + 1}: params must be an array` };
+      for (const param of params) {
+        if (typeof param?.name !== "string" || !_isPreferTokenMcp(param.name.trim())) {
+          return { error: `preference ${i + 1}: parameter name is required and must be a valid HTTP token` };
+        }
+        cleanParams.push({ name: param.name.trim(), value: param.value !== void 0 ? String(param.value) : void 0 });
+      }
+    }
+    built.push({
+      token: token.trim(),
+      value: value !== void 0 ? String(value) : void 0,
+      params: cleanParams.length > 0 ? cleanParams : void 0
+    });
+  }
+  const headerValue = _formatPreferPreferencesMcp(built);
+  return { header: `Prefer: ${headerValue}`, headerValue, preferences: built };
+}
+function _parsePreferHeaderMcp(raw) {
+  if (!raw || raw.trim() === "") return { error: "Input is empty" };
+  const withoutLabel = raw.trim().replace(/^prefer:\s*/i, "");
+  const parts = _splitPreferTopLevelMcp(withoutLabel, ",").map((p) => p.trim()).filter((p) => p.length > 0);
+  if (parts.length === 0) return { error: "Input is empty" };
+  const preferences = [];
+  for (const part of parts) {
+    const segments = _splitPreferTopLevelMcp(part, ";").map((s) => s.trim()).filter((s) => s.length > 0);
+    if (segments.length === 0) return { error: `Invalid preference: "${part}"` };
+    const main = _parsePreferTokenValueMcp(segments[0]);
+    if (!main || !_isPreferTokenMcp(main.token)) return { error: `Invalid preference token in "${part}"` };
+    const params = [];
+    for (const seg of segments.slice(1)) {
+      const p = _parsePreferTokenValueMcp(seg);
+      if (!p || !_isPreferTokenMcp(p.token)) return { error: `Invalid parameter in "${part}"` };
+      params.push({ name: p.token, value: p.value });
+    }
+    preferences.push({ token: main.token, value: main.value, params: params.length > 0 ? params : void 0 });
+  }
+  const headerValue = _formatPreferPreferencesMcp(preferences);
+  return { header: `Prefer: ${headerValue}`, headerValue, preferences };
+}
+server.tool(
+  "build_prefer_header",
+  "Build a Prefer request-header value from a list of preferences, each with an optional value and optional parameters, per RFC 7240. A value or parameter value that is not a valid HTTP token is quoted automatically.",
+  {
+    preferences: z.array(z.object({
+      token: z.string().describe('The preference token, e.g. "respond-async" or "return"'),
+      value: z.string().optional().describe("Optional value for the preference"),
+      params: z.array(z.object({
+        name: z.string(),
+        value: z.string().optional()
+      })).optional().describe("Optional parameters following the preference")
+    })).min(1).describe("Preferences to build the header from")
+  },
+  async ({ preferences }) => {
+    const result = _buildPreferHeaderMcp(preferences);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+server.tool(
+  "parse_prefer_header",
+  'Parse an existing Prefer header value (with or without a leading "Prefer:" label) into its list of preferences, each with an optional value and optional parameters, per RFC 7240.',
+  {
+    header: z.string().min(1).describe("The Prefer header value to parse")
+  },
+  async ({ header }) => {
+    const result = _parsePreferHeaderMcp(header);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
 function _calculateBlendedLoanRateMcp(loans) {
   if (!Array.isArray(loans) || loans.length === 0) {
     return { error: "loans must be a non-empty array" };
@@ -9519,5 +9692,113 @@ server.tool(
     }, null, 2));
   }
 );
+function _buildRetryAfterHeaderMcp(input) {
+  const { seconds, date } = input;
+  const hasSeconds = seconds !== void 0;
+  const hasDate = date !== void 0 && date !== "";
+  if (hasSeconds && hasDate) return { error: "Provide either seconds or date, not both" };
+  if (!hasSeconds && !hasDate) return { error: "seconds or date is required" };
+  if (hasSeconds) {
+    if (typeof seconds !== "number" || !Number.isFinite(seconds) || !Number.isInteger(seconds) || seconds < 0) {
+      return { error: "seconds must be a non-negative integer" };
+    }
+    return { header: `Retry-After: ${seconds}`, headerValue: String(seconds), type: "seconds", seconds };
+  }
+  const parsed = new Date(date);
+  if (Number.isNaN(parsed.getTime())) return { error: "date must be a valid date/time string" };
+  const httpDate = parsed.toUTCString();
+  return { header: `Retry-After: ${httpDate}`, headerValue: httpDate, type: "http-date", httpDate, iso: parsed.toISOString() };
+}
+function _parseRetryAfterHeaderMcp(raw) {
+  if (!raw || raw.trim() === "") return { error: "Input is empty" };
+  const value = raw.trim().replace(/^retry-after:\s*/i, "").trim();
+  if (value === "") return { error: "Input is empty" };
+  if (/^\d+$/.test(value)) {
+    const seconds = parseInt(value, 10);
+    return { header: `Retry-After: ${seconds}`, headerValue: String(seconds), type: "seconds", seconds };
+  }
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    return { error: "Value is neither a non-negative integer (seconds) nor a valid HTTP-date" };
+  }
+  const httpDate = parsed.toUTCString();
+  return { header: `Retry-After: ${httpDate}`, headerValue: httpDate, type: "http-date", httpDate, iso: parsed.toISOString() };
+}
+server.tool(
+  "build_retry_after_header",
+  'Build a Retry-After response header value from either a non-negative delay in seconds or a target date/time, per RFC 9110 Section 10.2.3. A date is formatted as an HTTP-date (IMF-fixdate, e.g. "Wed, 21 Oct 2026 07:28:00 GMT"), the only date format the header allows.',
+  {
+    seconds: z.number().int().min(0).optional().describe("A non-negative delay in seconds (required unless date is given)"),
+    date: z.string().optional().describe("A target date/time string to format as an HTTP-date (required unless seconds is given)")
+  },
+  async ({ seconds, date }) => {
+    const result = _buildRetryAfterHeaderMcp({ seconds, date });
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+server.tool(
+  "parse_retry_after_header",
+  'Parse an existing Retry-After header value (with or without a leading "Retry-After:" label) into either its delay-in-seconds form or its HTTP-date form, per RFC 9110 Section 10.2.3.',
+  {
+    header: z.string().min(1).describe("The Retry-After header value to parse")
+  },
+  async ({ header }) => {
+    const result = _parseRetryAfterHeaderMcp(header);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+function _calculateFreelancerRateMcp(input) {
+  const { targetAnnualIncome, billableHoursPerWeek, weeksPerYear } = input;
+  const annualOverheadCosts = input.annualOverheadCosts ?? 0;
+  const profitMarginPercent = input.profitMarginPercent ?? 0;
+  if (!Number.isFinite(targetAnnualIncome) || targetAnnualIncome < 0) {
+    return { error: "targetAnnualIncome must be a finite, non-negative number" };
+  }
+  if (!Number.isFinite(billableHoursPerWeek) || billableHoursPerWeek <= 0 || billableHoursPerWeek > 168) {
+    return { error: "billableHoursPerWeek must be a finite number greater than zero and at most 168" };
+  }
+  if (!Number.isFinite(weeksPerYear) || weeksPerYear <= 0 || weeksPerYear > 52) {
+    return { error: "weeksPerYear must be a finite number greater than zero and at most 52" };
+  }
+  if (!Number.isFinite(annualOverheadCosts) || annualOverheadCosts < 0) {
+    return { error: "annualOverheadCosts must be a finite, non-negative number" };
+  }
+  if (!Number.isFinite(profitMarginPercent) || profitMarginPercent < 0) {
+    return { error: "profitMarginPercent must be a finite, non-negative number" };
+  }
+  const round2 = (n) => Math.round(n * 100) / 100;
+  const annualBillableHours = billableHoursPerWeek * weeksPerYear;
+  const baseRevenueNeeded = targetAnnualIncome + annualOverheadCosts;
+  const requiredAnnualRevenue = baseRevenueNeeded * (1 + profitMarginPercent / 100);
+  const hourlyRate = requiredAnnualRevenue / annualBillableHours;
+  return {
+    targetAnnualIncome: round2(targetAnnualIncome),
+    annualOverheadCosts: round2(annualOverheadCosts),
+    profitMarginPercent: round2(profitMarginPercent),
+    annualBillableHours: round2(annualBillableHours),
+    requiredAnnualRevenue: round2(requiredAnnualRevenue),
+    hourlyRate: round2(hourlyRate),
+    dailyRate: round2(hourlyRate * 8),
+    monthlyRevenueTarget: round2(requiredAnnualRevenue / 12)
+  };
+}
+server.tool(
+  "calculate_freelancer_rate",
+  "Solve for the minimum hourly rate a freelancer must charge to hit a target annual take-home income, given billable hours per week, weeks actually worked per year, annual business overhead, and an optional profit margin/buffer applied on top.",
+  {
+    targetAnnualIncome: z.number().min(0).describe("Desired annual take-home income"),
+    billableHoursPerWeek: z.number().gt(0).max(168).describe("Billable hours worked per week"),
+    weeksPerYear: z.number().gt(0).max(52).describe("Weeks actually worked per year, after vacation/holidays"),
+    annualOverheadCosts: z.number().min(0).optional().describe("Annual business expenses (software, insurance, etc.), default 0"),
+    profitMarginPercent: z.number().min(0).optional().describe("Extra buffer/profit margin percent applied on top of income plus overhead, default 0")
+  },
+  async ({ targetAnnualIncome, billableHoursPerWeek, weeksPerYear, annualOverheadCosts, profitMarginPercent }) => {
+    const result = _calculateFreelancerRateMcp({ targetAnnualIncome, billableHoursPerWeek, weeksPerYear, annualOverheadCosts, profitMarginPercent });
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
 var transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utilix-tech/mcp",
-  "version": "0.58.0",
+  "version": "0.60.0",
   "description": "MCP server exposing 198 Utilix developer tools to Claude, Cursor, VS Code Copilot, and any MCP-compatible AI assistant.",
   "author": "Utilix <hello@utilix.tech>",
   "license": "MIT",