# Plumbkit

> Exact, deterministic utilities for AI agents: current time, time zone conversion, date math, business days, calculator, unit conversion, text counting, hashing/encoding, regex testing, and validation of emails, phone numbers, URLs, IBANs and JSON.

## Connect
- MCP (Streamable HTTP): https://plumbkit.dev/mcp
- REST: POST https://plumbkit.dev/v1/tools/{tool_name} with a JSON body of arguments
- Tool list with input schemas: https://plumbkit.dev/v1/tools
- OpenAPI: https://plumbkit.dev/openapi.json
- Auth: optional. Header "Authorization: Bearer <key>" (or ?key=<key>). Without a key: 100 free calls/day per IP.
- Usage: GET https://plumbkit.dev/v1/usage

## Tools
- current_time: Returns the exact current date, time, weekday and UTC offset in any time zone. Use this whenever you need to know today's date or the current time instead of guessing — your training data does not know what day it is. Example input: {"timezone":"America/New_York"}
- convert_timezone: Converts a date/time from one time zone to another, correctly handling daylight saving time. If the input already includes an offset or 'Z', from_timezone is ignored. Example input: {"datetime":"2026-11-01T09:00","from_timezone":"America/Toronto","to_timezone":"Asia/Kolkata"}
- date_add: Adds or subtracts a duration (years, months, weeks, days, hours, minutes, seconds) to a date/time. Use negative numbers to subtract. Calendar-aware: adding 1 month to Jan 31 gives Feb 28/29, and adding days keeps the same local clock time across daylight-saving changes. Example input: {"datetime":"2026-01-31","months":1}
- date_diff: Calculates the exact time between two dates/times: a calendar breakdown (years, months, days, hours, minutes, seconds) plus totals in days, hours, minutes and seconds, and the number of calendar days. Negative if end is before start. Example input: {"start":"2026-01-15","end":"2026-10-08"}
- business_days: Works with business (working) days. mode "add": returns the date N business days after start_date (start_date itself is not counted; negative N goes backward; 0 returns start_date, or the next business day if start_date is not one). mode "count": counts business days from start_date to end_date, including both ends. Weekends default to Saturday and Sunday. Public holidays are NOT built in — pass them in "holidays". Example input: {"mode":"add","start_date":"2026-12-23","days":3,"holidays":["2026-12-25","2026-12-28"]}
- calculate: Evaluates an arithmetic expression exactly, so you don't have to do mental math. Supports + - * / % ^ (or **), parentheses, constants pi/e/tau and functions: sqrt, cbrt, abs, round(x, digits), floor, ceil, trunc, sign, ln, log(x[, base]), log10, log2, exp, pow, sin, cos, tan, asin, acos, atan, atan2, min, max, hypot, factorial. Trig uses radians. Example: "(1250 * 1.08^5) - 1250". Example input: {"expression":"(1250 * 1.08^5) - 1250","decimals":2}
- convert_units: Converts a value between units of length, mass, volume (US and imperial), area, speed, time, digital data (KB vs KiB, bits vs bytes), energy, pressure and temperature. Accepts common abbreviations (km, lb, fl oz, mph, °F, GiB). US customary units are used for cup/pint/quart/gallon unless you say imperial. Example input: {"value":26.2,"from":"miles","to":"km"}
- text_stats: Counts exactly what language models are bad at counting: characters (as humans see them), words, lines, sentences, paragraphs, UTF-8 bytes, and occurrences of a letter or substring (e.g. how many "r" in "strawberry"). Use it to check length limits (tweets, SMS, meta descriptions, form fields) before submitting text. Example input: {"text":"strawberry","count":"r"}
- hash_text: Computes a cryptographic hash (SHA-1, SHA-256, SHA-384, SHA-512) of text, or encodes/decodes it as Base64, Base64URL, hex or URL-encoding. Text is treated as UTF-8. Example input: {"text":"hello world","operation":"sha256"}
- regex_test: Runs a JavaScript regular expression against text and returns every match with its position and capture groups, or the text after replacement. Use it to verify a regex actually works before relying on it. Example input: {"pattern":"(\\d{3})-(\\d{4})","text":"Call 555-1234 or 555-9876"}
- validate_email: Checks whether an email address is correctly formatted and returns a normalized version. Set check_dns=true to also confirm the domain exists and can receive mail (MX records). Does not send email and cannot confirm that a specific mailbox exists. Example input: {"email":"Jane.Doe@Example.com","check_dns":true}
- validate_phone: Validates a phone number using Google's libphonenumber rules and returns it in E.164 (+14155552671), international and national formats, plus the country and line type (mobile, fixed line, toll free...). For numbers without a +country code, pass default_country. Example input: {"phone":"(415) 555-2671","default_country":"US"}
- validate_url: Checks that a URL is well-formed, normalizes it (lowercase host, punycode, default ports removed, spaces encoded) and splits it into parts including each query parameter. Flags common problems such as missing scheme, private/localhost addresses and credentials embedded in the URL. Does not fetch the URL. Example input: {"url":"HTTPS://Example.COM:443/path to/page?utm_source=x&id=7#top"}
- validate_iban: Validates an International Bank Account Number: country, length for that country, and the mod-97 check digits. Returns electronic and printed formats. A valid IBAN is correctly formed; this does not confirm the account exists. Example input: {"iban":"GB82 WEST 1234 5698 7654 32"}
- json_repair: Turns almost-JSON into valid JSON: removes markdown code fences, comments and trailing commas, adds missing quotes, commas and closing brackets, converts single quotes, Python True/False/None and truncated output. Returns the repaired JSON string and whether the input was already valid. Example input: {"text":"```json\n{name: 'Ada', tags: ['x', 'y',], active: True\n```"}
- json_schema_validate: Checks a JSON value against a JSON Schema (drafts 4, 7, 2019-09 and 2020-12) and lists every violation with its location. Use it to confirm structured output or an API payload is correct before sending it. `data` and `schema` may be JSON values or JSON strings. Example input: {"data":{"name":"Ada","age":"36"},"schema":{"type":"object","required":["name","age"],"properties":{"name":{"type":"string"},"age":{"type":"integer"}}}}

## Pricing
- Free: 100 calls/day, no key
- Starter: $4.99/month for 100,000 calls (https://plumbkit.dev/buy/starter)
- Pro: $39.99/month for 1,000,000 calls (https://plumbkit.dev/buy/pro)
- Scale: $499/month for 20,000,000 calls (https://plumbkit.dev/buy/scale)