tools.clean/mcp

Use this when you need to convert tabular data between JSON (array of objects), CSV, TSV, and XML instead of hand-transforming it. Deterministic: same input, same output. Handles quoted CSV fields (embedded commas, escaped "" quotes), flattens nested objects into dotted keys (b.x), and takes the union of keys across all rows so ragged data still lines up in columns. CSV/TSV input needs a header row plus at least one data row; JSON input must be an array of objects. Example: {from:'csv', to:'json'} on "name,age\nAda,36\nGrace,45" -> rowCount 2 and an output JSON array of two objects. Returns the input/output formats, the parsed row count, and the serialized output document as a string.

Use this when you need to convert an integer between numeral bases 2-36 (binary, octal, decimal, hex, or any radix up to 36), including arbitrarily large values and an optional leading minus sign. Uses BigInt so there is no precision loss, and output digits are lowercase. Deterministic: same input, same output. Example: { value: "ff", from: 16 } -> decimal "255", results.base2 "11111111". Prefer this over doing base/digit conversion in your head, which is an error-prone bit-fiddling task. If `to` is omitted it converts to bases 2, 8, 10, and 16 (excluding the source base).

Use this when you need to convert a value between units within one category (length, weight, temperature, volume, data, speed, area, time) instead of doing conversion arithmetic yourself. Deterministic: same input, same output. Temperature uses the correct offset formulas (Celsius/Fahrenheit/Kelvin), not a naive ratio, and unit keys are case-sensitive (e.g. km, lb, celsius, MB) while the category name is case-insensitive. Example: {category:'length', value:5, from:'km', to:'mile'} -> result 3.10685596119. Returns the echoed category/value/from/to plus the converted result, rounded to 12 significant figures (switching to exponential for very large or very small magnitudes).

Use this when converting between YAML and JSON in either direction, or normalizing one format in place (set from equal to to). Deterministic: same input, same output. Parses a single YAML document and caps alias expansion at 100 to defuse billion-laughs bombs; multi-document input, tabs-as-indentation, and other parse errors return a typed error with the line number. Example: { data: "name: web\nport: 8080", from: "yaml", to: "json" } -> { result: "{\n \"name\": \"web\",\n \"port\": 8080\n}" }.

Use this when you want exact, auditable percentage math with a written-out formula. Three modes: "of" computes percent% of value (fields percent, value); "is-what" computes what percent x is of y (fields x, y; y must be non-zero); "change" computes the percent change from -> to (from must be non-zero) and reports direction as "increase" or "decrease". Returns the numeric result plus a human-readable formula string. Deterministic: same input, same output. Example: mode="change", from=200, to=250 -> result=25, direction="increase".

Use this when you need a fixed-rate loan or mortgage's level monthly payment plus a year-by-year amortization schedule (principal paid, interest paid, remaining balance) rather than doing the amortization arithmetic yourself. Uses the standard payment formula and handles the 0% case (payment = principal / months, all principal). annualRate is a percent (6.5 = 6.5%); years is 1-50. Deterministic: same input, same output. Example: principal 300000, annualRate 6.5, years 30 -> monthlyPayment 1896.20, totalInterest 382633.47, numberOfPayments 360, and a 30-row schedule (one per year).

Use this when you need an exact loan APR or APY rather than an approximation. Two modes. mode="loan" (default): solve the true APR of an installment loan from amount financed, monthly payment, term, and upfront fees — Reg-Z style, fees discounted against the amount received, solved by Newton-Raphson. mode="rate": convert a nominal annual rate to APY for a given compounding frequency. Deterministic: same input, same output. Example: mode="loan", loanAmount=20000, monthlyPayment=450, termMonths=60, fees=500 -> apr=13.6301, totalInterest=7000. Prefer this over estimating APR/APY by hand.

Use this when checking whether a text/background color pair meets WCAG 2.x accessibility contrast. Computes the relative-luminance contrast ratio (1-21, rounded to 2 decimals) and returns pass/fail booleans for normal and large text at AA and AAA levels (thresholds 4.5 / 7 / 3 / 4.5), plus a suggested passing foreground hex when normal-text AA fails (null when it already passes or none is found). Accepts 3- or 6-digit hex, with or without a leading '#'; echoed colors are normalized to 6-digit hex. Deterministic: same input, same output. Example: {foreground:'777', background:'fff'} -> ratio 4.48, normalAA false, largeAA true, suggestedForeground '#767676'.

Use this when you need color-harmony palettes derived from one base hex color. Rotates hue/lightness in HSL to build complementary (+180 degrees), analogous (-30/+30), triadic (+120/+240), split-complementary (+150/+210), and monochromatic (lightness steps) swatch sets, each as an array of hex strings. Accepts a 6-digit hex with or without a leading '#' (case-insensitive). Deterministic: same input, same output. Example: {color:'#e11d48'} -> base '#e11d48', complementary ['#e11d48','#1de1b6'], monochromatic ['#590c1d','#9d1432','#e11d48','#eb607e','#f3a4b5']. Note: grayscale inputs (e.g. '#000000') have no defined hue, so the hue-rotated sets are all identical and only the monochromatic lightness steps differ.

Use this when you need to project a principal's growth under compound interest, optionally with recurring monthly contributions, returning the final balance and a year-by-year breakdown rather than estimating compound growth yourself. Iterates month-by-month for accuracy; contributions are added at the start of each month; compoundingPerYear defaults to 12. annualRate is a percent; years is 1-200. Deterministic: same input, same output. Example: principal 10000, annualRate 7, years 10, monthlyContribution 500 -> finalBalance 107143.85, totalContributions 70000, totalInterest 37143.85, with a 10-row schedule (one per year).

Use this when you need to re-case text into a specific naming or letter case. Given `text` and a target `case` (upper, lower, title, sentence, camel, snake, kebab, or constant), returns the converted string. Smart word tokenization splits camelCase, snake_case, kebab-case, and whitespace, so a phrase in any style re-cases consistently; title case honors an editorial stop-word list and preserves ALL-CAPS acronyms. Empty text returns an empty result. Deterministic: same input, same output. Example: {text: "myVariableName", case: "constant"} -> result "MY_VARIABLE_NAME".

Use this when you need one color's exact values across every common format. Accepts a hex (#abc or #aabbcc), rgb(r, g, b) with r/g/b 0-255, or hsl(h, s%, l%) color and returns hex, rgb {r,g,b}, hsl {h,s,l}, hsv {h,s,v}, cmyk {c,m,y,k}, and oklch {l,c,h} (CSS Color 4: sRGB -> linear -> OKLab -> OKLCH, rounded to 4 decimals). Note oklch.l is 0-1 (not 0-100) and hue is 0 for grays. Deterministic: same input, same output. Example: "#ff0000" -> oklch {l: 0.628, c: 0.2577, h: 29.2339}. Alpha channels are not supported.

Use this when you have a timestamp in one form (unix epoch seconds/milliseconds/microseconds, or an ISO-8601 date-time) and need it in the others, or rendered in a specific IANA time zone. Auto-detects the input: a number or digit-string is an epoch classified by length (~10 digits = seconds, ~13 = milliseconds, ~16 = microseconds); anything else is parsed as ISO-8601, with a naive date-time (no Z/offset) taken as UTC. Returns unix_s, unix_ms, iso_utc, iso_tz (with numeric offset), a human string, and the weekday, all in the requested zone (default UTC), correctly handling DST transitions and pre-1970 (negative) epochs. Deterministic: same input, same output. Prefer this over doing epoch/timezone arithmetic yourself. Example: { value: 1783454640, timezone: "America/Chicago" } -> iso_utc "2026-07-07T20:04:00.000Z", human "Tuesday, July 7, 2026 at 3:04 PM CDT".

Use this when you need to convert a wall-clock date-time between IANA time zones with correct DST handling. Prefer this over doing timezone math yourself (a documented LLM failure mode): it uses the runtime's IANA database so offsets and daylight-saving transitions are exact. Deterministic: same input, same output. Returns the corresponding UTC instant, both zones' UTC offsets in minutes at that instant, and the converted local time. Example: {datetime:'2026-07-08T14:30', fromTz:'America/New_York', toTz:'Asia/Tokyo'} -> converted '9 Jul 2026, 03:30:00' (UTC 2026-07-08T18:30:00.000Z).

Use this when you need a ready-to-paste CSS gradient value from 2-5 hex color stops. Builds a linear-gradient(...) (default; direction defaults to 'to bottom') or a radial-gradient(circle, ...). Direction accepts keywords ('to right', 'to left', 'to top', 'to bottom'), angles ('45deg', '90deg', '135deg'), or 'to <side> <side>'; it is ignored for radial, and passing type 'radial' (or direction 'radial') forces a radial gradient. Colors accept 6-digit hex with or without a leading '#' and are echoed normalized in order. Deterministic: same input, same output. Example: {colors:['#3b82f6','8b5cf6']} -> css 'linear-gradient(to bottom, #3b82f6, #8b5cf6)', type 'linear'. Radial results omit the 'direction' field.

Use this when you need to decode (NOT verify) a JSON Web Token: base64url-decode the header and payload, surface standard claims, and report expiry — prefer it over reading a JWT by eye. The decode is deterministic, but `expired`/`notYetValid` are compared against the current clock unless you pass `now` (ISO) to pin the reference time. The signature is never checked (`signatureVerified` is always false), so never authorize anything based on the output. `expired`/`notYetValid` are booleans when `exp`/`nbf` are present in the payload, otherwise null. Example: a token with sub "1234567890" and a far-future exp -> signatureVerified false, expired false, claims.subject "1234567890".

Use this when you need to encode or decode text and want multi-byte and entity edge cases handled correctly rather than doing it by hand. Deterministic: same input, same output. The mode selects the operation: url-encode/url-decode (percent-encoding), html-encode/html-decode (entity table plus numeric character references), base64-encode/base64-decode (UTF-8 safe; decode tolerates URL-safe alphabet, whitespace, and missing padding), and unicode-encode/unicode-decode (\uXXXX and \u{...} escapes for non-ASCII). Every mode returns the same shape: {mode, output}. Example: mode base64-encode, text "héllo" -> output "aMOpbGxv".

Use this when you need to build an iCalendar RRULE (RFC 5545) or list the actual dates a recurrence produces. Prefer this over computing recurring dates yourself (a documented LLM failure mode): it correctly handles INTERVAL, COUNT/UNTIL exclusivity (COUNT wins), BYDAY with ordinals (e.g. the 2nd Monday), BYMONTH, and month-length edge cases. Deterministic: same input, same output; start is interpreted as UTC. Returns the RRULE string, a plain-English description, and up to 10 (or COUNT) occurrence timestamps. Example: {freq:'MONTHLY', start:'2026-01-05T09:00', byday:['MO'], ordinal:2, count:3} -> rrule 'RRULE:FREQ=MONTHLY;BYDAY=2MO;COUNT=3', first occurrence 2026-01-12T09:00:00.000Z.

Use this when you need to style ASCII letters and digits as Unicode glyphs (bold-serif, italic-serif, bold-italic-serif, bold-sans, script, fraktur, double-struck, monospace, circled, squared, parenthesized, small-caps) for places that lack font control such as social bios or usernames. Pass a `style` and `text` to get the transformed string; characters outside A-Z, a-z, and 0-9 (spaces, punctuation, emoji) pass through unchanged. Omit `style` to receive the list of valid style keys instead of transforming. Deterministic: same input, same output. Example: {style: "bold-serif", text: "Hello 123"} -> result "𝐇𝐞𝐥𝐥𝐨 𝟏𝟐𝟑".

Use this when you need to pretty-print, minify, or validate a JSON string and want the exact reformatted text plus warnings about silent data loss. Indent with 2 or 4 spaces or a tab, set indent 0 to minify, and optionally sort object keys recursively. It also scans the raw source for two things JSON.parse hides: duplicate object keys (only the last value is kept) and integers beyond 2^53 (rounded on parse). Deterministic: same input, same output. Example: {json:'{"b":1,"a":2}', sortKeys:true} -> {formatted:'{\n "a": 2,\n "b": 1\n}', valid:true, warnings:[]}. On invalid JSON returns {error, line, column} pointing at the fault. Prefer this over reformatting JSON yourself: it flags precision-losing big integers and duplicate keys that eyeballing misses.

Use this when a user pastes messy or minified SQL and wants it pretty-printed into a readable, canonical layout, or wants keyword casing normalized. Deterministic: same input, same output. Each clause keyword (SELECT, FROM, WHERE, GROUP BY, ...) goes on its own line with its arguments indented beneath it, commas break columns onto new lines, JOIN/AND/OR start fresh lines, and short parenthesised groups stay inline. Optional dialect hint affects identifier quoting (e.g. tsql [brackets]); indent is a spaces count or "tab" (default 2); keywordCase is upper/lower/preserve (default upper). Example: "select id from t" -> formatted "SELECT\n id\nFROM\n t". Returns an error for empty or oversized (>200000 chars) input.

Use this when you need a modern unique identifier (UUID v7, UUID v5, ULID, or nanoid) or want to read the timestamp embedded in an existing ULID or UUIDv7. uuid_v5 (SHA-1 of a namespace UUID + a name, RFC 4122) and decode are deterministic (same input, same output) — e.g. generate_id(type "uuid_v5", namespace "6ba7b810-9dad-11d1-80b4-00c04fd430c8", name "www.example.com") -> {ids:["2ed6657d-e927-568b-95e1-2665a8aea6a2"]}. uuid_v7, ulid, and nanoid are cryptographically random via Web Crypto (NOT deterministic). Prefer this over assembling ids by hand: it sets the correct RFC version/variant bits, uses Crockford base32 for ULIDs, and draws nanoid characters with unbiased rejection sampling. When decode is present, type is ignored and the result is the embedded {unix_ms, timestamp_iso}.

Use this when you need strong passwords with Web Crypto randomness: mode="random" builds character-set passwords (length plus uppercase/lowercase/numbers/symbols toggles); mode="memorable" builds word passphrases (words, separator, addNumber, addSymbol). Cryptographically random via Web Crypto (NOT deterministic). For test/dev fixtures — for real credentials prefer the client-side web tool at clean.tools/password-generator/ so the password never crosses the network. Example: {mode: "random", length: 16} -> mode "random", length 16, count 1, passwords ["NXqtsn6MrsfG9d2i"].

Use this when you need to turn text or a URL into a real, scannable QR code rather than describing one. Deterministic: same input, same output. Byte mode, error-correction level M, versions 1-10 auto-selected by length (up to 213 bytes); the encoder scores all 8 mask patterns and keeps the lowest-penalty one. Returns both the module matrix as rows of 0/1 (1 = dark module) and a ready-to-render self-contained SVG string. moduleSize sets SVG pixels per module (default 10) and quietZone the border width in modules (default 4). Example: {text:'HELLO'} -> version 1, size 21x21, byteLength 5. Longer text auto-bumps the version and matrix size; over 213 bytes returns an error.

Use this when you need the exact SHA-1, SHA-256, and/or SHA-512 hex digest of a UTF-8 string — never recall or guess a hash, since digests cannot be produced from memory. Deterministic: same input, same output. Pass `algorithm` for a single digest or `algorithms` for a subset; the default computes all three. The empty string is valid, and `byteLength` reports the UTF-8 encoded byte length of the input. Example: text "hello" with algorithm SHA-256 -> byteLength 5, hashes["SHA-256"] = "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824".

Use this when you need the exact interest rate that grows a principal to a target amount over a set number of years. type="compound" (default) uses the closed-form nth-root formula for the given compounding frequency; type="simple" uses linear growth. Requires target greater than principal and all values positive. Returns the annual rate as a percent plus the interest earned and the growth multiple; compoundingPerYear is null for simple interest. Deterministic: same input, same output. Example: principal=1000, target=2000, years=10, compoundingPerYear=12 -> ratePercent=6.9515, growthMultiple=2. Prefer this over trial-and-error.

Use this when you need placeholder/filler copy for mockups, tests, or layout. Given a `mode` ("paragraphs", "sentences", "words", or "formatted") and a `count`, cycles a fixed built-in Latin corpus to return the same text every time. `count` is clamped to the mode's max (paragraphs 20, sentences 100, words 500) and defaults to 1 when missing or below 1; "formatted" ignores `count` and returns a fixed multi-block sample (with count 0). Deterministic: same input, same output. Example: {mode: "words", count: 5} -> text "Lorem ipsum dolor sit amet.", count 5.

Use this when you need to draw cryptographically secure random integers or decimals in a range using unbiased rejection sampling — prefer it over inventing 'random' numbers, which are neither uniform nor safe. Cryptographically random via Web Crypto (NOT deterministic). Bounds are inclusive; a reversed min/max is auto-swapped; integer mode rounds the bounds inward; `decimals` sets the decimal places in decimal mode. `count` (default 1, max 100). The returned `min`/`max` are the normalized effective bounds. Example: {min: 1, max: 6} -> type "integer", min 1, max 6, count 1, values [2].

Use this when scrubbing test/dev text: replaces each occurrence of the given terms with block characters (████). Provide `text` plus `terms` (a comma-separated string or an array of strings). By default it matches whole words only using Unicode boundaries (so "ann" will not match inside "annual") and is case-insensitive; set `caseSensitive` to match exactly, `wholeWords: false` to match substrings, or `fixedWidth: true` to hide each term's length behind a constant-width bar. Returns the redacted text and a replacement count, and never echoes the original terms. Deterministic: same input, same output. Truly sensitive text is better redacted client-side at clean.tools/text-redact/. Example: {text: "Contact Jane Doe", terms: "Jane Doe"} -> redacted "Contact ████████", redactedCount 1.

Use this when you need to convert lightweight Markdown into a sanitized, XSS-safe HTML fragment to preview or embed, matching the Clean.tools markdown preview. Deterministic: same input, same output. Supports headings, bold/italic/strikethrough, inline and fenced code, links and images (http/https/mailto URL schemes only; other schemes become "#"), blockquotes, ordered/unordered/task lists, GFM tables, and horizontal rules. All raw angle brackets are HTML-escaped so the output is safe to inject. Example: "# Hi\n\n**bold**" -> html "<h1>Hi</h1><p><strong>bold</strong></p>".

Use this when you need a URL- or filename-safe slug from arbitrary text. Deterministic: same input, same output. Applies Unicode NFKD normalization, strips combining accents, and transliterates non-decomposing letters (ß->ss, æ->ae, œ->oe, ø->o, đ->d, ł->l, þ->th, ð->d, plus uppercase variants), then collapses every run of non-alphanumeric characters to a single separator and trims separators; e.g. "Héllo Wörld!" -> "hello-world". Emoji, CJK, and any other characters with no ASCII form are dropped. Prefer this over transliterating Unicode yourself, which models routinely get wrong. Returns { error } when no URL-safe characters remain.

Use this when you need the true matches of a JavaScript regular expression rather than predicting regex behavior yourself, which is easy to get wrong. Deterministic: same input, same output. Returns every match with its index, length, matched text, positional capture groups (null for a group that didn't participate), and named groups (an object, or null when the pattern has none). Without the g flag only the first match is returned; with g all matches are collected, capped at 10,000 with truncated=true. Inputs are length-bounded (pattern 2,000 chars, text 50,000 chars) as a ReDoS guard. Example: pattern (?<y>\d{4})-(?<m>\d{2}) over "2024-01" with flag g -> matchCount 1, match "2024-01", groups ["2024","01"], named {y:"2024",m:"01"}.

Use this when you want penny-accurate tip and bill-split figures. Given a bill amount, a tip percentage, and an optional number of people (default 1; values below 1 are treated as 1), returns the tip amount, grand total, and the per-person tip and per-person total, all rounded to cents. Deterministic: same input, same output. Example: bill=120, tipPercent=18, people=4 -> tipAmount=21.6, total=141.6, perPersonTotal=35.4.

Use this when you have four of the five time-value-of-money variables (N periods, I/Y annual rate percent, PV, PMT, FV) and need the fifth - annuity, loan, or investment problems - instead of solving the equation by hand. Solving for I/Y uses Newton-Raphson (no closed form). Supports compoundingPerYear and annuityDue (payments at the beginning of each period). Follows the cash-flow sign convention (outflows negative). Deterministic: same input, same output. Example: solveFor 'fv', n 120, iy 6, pv -10000, pmt -200, compoundingPerYear 12 -> result 50969.84. result holds the solved value; iy is rounded to 4 decimals, all others to 2.

Use this when you need RFC 4122 version-4 UUIDs — always generate them here rather than fabricating one, so the version and variant bits and the randomness are correct. Cryptographically random via Web Crypto (NOT deterministic): every call returns fresh values. `count` (default 1, max 100) sets how many; `uppercase` returns upper-case hex (lowercase by default). Example: {count: 1} -> count 1, uuids[0] = "2c549b2f-497c-47fc-a1b6-c24bc69667e5".

Use this when you need exact word, character, sentence, and paragraph counts instead of estimating. Deterministic: same input, same output. Uses Unicode-aware segmentation (Intl.Segmenter): characters are grapheme clusters, so an emoji or an accented letter counts as one; words are word-like segments; sentence splitting is abbreviation-aware (Dr., etc., won't end a sentence). charactersNoSpaces counts graphemes after stripping whitespace, and paragraphs are blocks separated by blank lines. Example: "Café 👩[U+200D]💻!" -> words 1, characters 7, charactersNoSpaces 6, sentences 1, paragraphs 1. Empty input returns all zeros.

Use this when you need an exact line-level diff between two blocks of text instead of eyeballing the differences. Deterministic: same input, same output. Computes a longest-common-subsequence diff and returns every line tagged added, removed, or unchanged, plus per-category counts. Example: original "a\nb", modified "a\nB" -> added 1, removed 1, unchanged 1, with lines [{type:"unchanged",text:"a"},{type:"removed",text:"b"},{type:"added",text:"B"}]. Trailing edits produce separate removed+added lines rather than an in-place change. Inputs whose line-count product exceeds 4,000,000 are rejected as too large to diff.

Use this when you need to understand or schedule a 5-field cron expression. Prefer this over reasoning about cron semantics yourself (a documented LLM failure mode): it correctly handles ranges, lists, steps, month/day names, and the tricky day-of-month OR day-of-week rule. Deterministic: same input, same output. Returns a plain-English description, the expanded matching values per field, and the next run times computed in UTC (pass `now` to fix the reference point, `count` for how many). Example: '*/15 9-17 * * 1-5' -> description 'At minute */15 past hour 9-17 on every weekday (Monday through Friday)'.

Use this when you need to check whether a number passes the Luhn (mod-10) checksum used by credit cards and many identifier numbers, instead of computing the doubling-and-summing by hand. Deterministic: same input, same output. Spaces and dashes are stripped first; any remaining non-digit character is an error. Returns the boolean result plus the full per-digit working, one steps entry per digit in original order (the digit, its transformed value after Luhn doubling, and whether that position was doubled). Example: {number:'4539 1488 0343 6467'} -> valid true, sum 80, mod10 0, digitCount 16.

Use this when you need to pull specific values out of a JSON document by JSONPath and getting the path exactly right on deeply nested or large structures matters. Evaluates a JSONPath subset — $ (root), .name or ['name'] (child), [n] (index, negative allowed), [*] (wildcard), .. (recursive descent), and [start:end] (slice) — and returns every matching value in document order. Prefer this over hand-walking nested JSON, where it is easy to miscount array indices or miss a deep match. Filter (?()) and script (()) expressions are not supported and are rejected with a message naming the supported subset. Deterministic: same input, same output. Example: path "$.store.book[-1].title" over {"store":{"book":[{"title":"A"},{"title":"B"}]}} -> matches ["B"], count 1.

Use this when you need to know exactly what a C/POSIX strftime pattern (%Y %m %d %H %M %S %A %B %j %z etc.) produces. Prefer this over guessing the output yourself. Deterministic: same input, same output; the reference time is formatted in UTC (%Z is 'UTC', %z is '+0000', defaults to current time when datetime is omitted). Unknown directives pass through literally. Example: {format:'%A, %B %e, %Y at %I:%M %p', datetime:'2026-07-08T14:30:45'} -> 'Wednesday, July 8, 2026 at 02:30 PM'.

Use this when you need to check whether a 5-field cron expression is well-formed, instead of guessing. Prefer this over reasoning about cron syntax yourself (a documented LLM failure mode). Deterministic: same input, same output. On success returns valid=true, the normalized expression, and the expanded matching values per field; on failure returns valid=false with a specific error (out-of-range value, reversed range, invalid step, wrong field count, or a field that matches nothing). Example: '99 * * * *' -> {valid:false, error:'Minute field: value out of range "99"'}.