parseapi-mcp 0.2.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # parseapi-mcp
 
-Official parseAPI MCP server. Every parseAPI lookup as a tool for AI agents: IP and place data, email, phone and domain validation, weather, currency, timezones, holidays.
+Official parseAPI MCP server. Look up places, addresses, company numbers, email, phone, weather, currency, timezones, dates and more from your AI agent.
 
 ## Hosted
 
@@ -47,7 +47,26 @@ CI and headless setups skip the browser with a key from [parseapi.com](https://p
 
 ## Tools
 
-One tool per endpoint, named after the route: `ip`, `postal`, `city`, `city_search`, `city_nearby`, `email`, `vat`, `iban`, `npi`, `vin`, `tariff`, `tariff_search`, `phone`, `carrier`, `caller`, `hlr`, `weather`, `currency_rate`, `timezone`, `holiday`, `point`, `elevation`, and the rest. Every tool returns the same minimal JSON the API serves.
+51 local tools and 50 hosted tools cover all 53 SDK operations. `ip_self` is local only. `timezone` accepts either a timezone ID or coordinates. `date` parses the supplied date, or returns today in UTC when omitted. Every tool returns the JSON the API serves.
+
+Tools follow the lookup names: `country_states`, `city_search`, `postal_nearby`, `address`, `address_search`, `company`, `email`, `vat`, `iban`, `npi`, `vin`, `tariff`, `asn`, `mac`, `currency_rate`, and the rest. All search tools take `query`.
+
+Example tool arguments:
+
+| Tool | Arguments |
+|---|---|
+| `asn` | `{"asn":"AS13335"}` |
+| `mac` | `{"mac":"00:1B:63:84:45:E6"}` |
+| `country_states` | `{"code":"US"}` |
+| `address_search` | `{"query":"1600 Pennsylvania","country":"US","city":"Washington","state":"DC"}` |
+| `company` | `{"number":"552100554","country":"FR"}` |
+| `timezone` | `{"timezone":"America/New_York","at":"2026-09-05T09:00:00","to":"Asia/Tokyo"}` |
+| `timezone` | `{"lat":40.71,"lon":-74.01}` |
+| `date` | `{"date":"03/04/2026","format":"dmy"}` |
+
+Address lookup returns standardized components and registration status for the US and France. Its `deep` object is currently empty. Company lookup returns validity, registration status and business details when available. `address_search` also accepts `postal` and `ip` to narrow or rank matches. French search needs `country: "FR"` and either `postal` or `city`.
+
+Ordinary lookups retry up to twice after a transient failure. Metered lookups and address deep checks default to no retries. Cancelling a tool call cancels the pending SDK request.
 
 Errors come back as JSON with a machine-readable `code`. Branch on `code`, never on message text. A miss is `not_found`. No key is `invalid_api_key`.
 
@@ -55,9 +74,12 @@ Errors come back as JSON with a machine-readable `code`. Branch on `code`, never
 
 ```bash
 npm install
-npm run build
-npm run smoke     # stdio + http, live calls when PARSEAPI_KEY is set
+npm run typecheck
+npm test          # builds and tests with mocked fetch and in-memory MCP
+npm run smoke     # stdio + http, includes live API authentication checks
 npm run serve     # http on :8080
 ```
 
+Offline tests pin the public tool names and argument schemas in `test/public-api.json`, exercise every operation and query option, and verify errors, retries and cancellation. Review baseline changes as public API changes. Publishing runs typecheck and offline tests first.
+
 MIT licensed.

package/dist/{chunk-FQJPDQPX.js → chunk-2LHHK5F6.js}

@@ -34,8 +34,8 @@ function noKeyResult(transport) {
 }
 
 // src/registry.ts
-var VERSION = "0.2.1";
-var deep = z.boolean().optional().describe("Include the nested deep object with richer fields. Paid on most endpoints.");
+var VERSION = "0.3.0";
+var deep = z.boolean().optional().describe("Include the nested deep object when available. Pricing depends on the operation.");
 var lat = z.number().min(-90).max(90).describe("Latitude in decimal degrees");
 var lon = z.number().min(-180).max(180).describe("Longitude in decimal degrees");
 var iso2 = (what) => z.string().describe(`ISO 3166-1 alpha-2 ${what}, e.g. US`);
@@ -46,24 +46,24 @@ function buildServer(key, transport) {
       name: "parseapi",
       version: VERSION,
       title: "parseAPI",
-      description: "Lookups for agents: IP and place data, email, VAT, IBAN, NPI, phone and domain validation, weather, currency, timezones, holidays. Real reference data instead of guessing.",
+      description: "Lookups for agents: IP and place data, addresses, company numbers, email, VAT, IBAN, NPI, phone, domains, weather, currency, timezones, dates and holidays. Real reference data instead of guessing.",
       websiteUrl: "https://parseapi.com"
     },
     { capabilities: { tools: {} } }
   );
   const parse = key ? parseAPI(key) : null;
-  function tool(name, description, shape, fn) {
+  function tool(name, description, shape, fn, refine) {
     server.registerTool(
       name,
       {
         description,
-        inputSchema: z.object(shape),
+        inputSchema: refine ? refine(z.object(shape)) : z.object(shape),
         annotations: { readOnlyHint: true }
       },
-      async (args) => {
+      async (args, context) => {
         if (!parse) return noKeyResult(transport);
         try {
-          return ok(await fn(parse, args));
+          return ok(await fn(parse, args, { signal: context.mcpReq.signal }));
         } catch (err) {
           return toErrorResult(err);
         }
@@ -74,27 +74,27 @@ function buildServer(key, transport) {
     "ip",
     "Look up an IPv4 or IPv6 address: country, region, ASN, timezone. Deep adds datacenter, relay, tor and vpn flags.",
     { ip: z.string().describe("IPv4 or IPv6 address, e.g. 8.8.8.8"), deep },
-    (c, a) => c.ip(a.ip, { deep: a.deep })
+    (c, a, request) => c.ip(a.ip, { ...request, deep: a.deep })
   );
   if (transport === "stdio") {
     tool(
       "ip_self",
       "Look up the public IP of the machine running this MCP server.",
       { deep },
-      (c, a) => c.ip.self({ deep: a.deep })
+      (c, a, request) => c.ip.self({ ...request, deep: a.deep })
     );
   }
   tool(
     "continent",
     "Look up a continent by code: name, area, population.",
     { code: z.string().describe("Continent code: AF, AN, AS, EU, NA, OC, SA") },
-    (c, a) => c.continent(a.code)
+    (c, a, request) => c.continent(a.code, request)
   );
   tool(
     "continent_countries",
     "List every country on a continent.",
     { code: z.string().describe("Continent code: AF, AN, AS, EU, NA, OC, SA") },
-    (c, a) => c.continent.countries(a.code)
+    (c, a, request) => c.continent.countries(a.code, request)
   );
   tool(
     "bloc",
@@ -102,10 +102,7 @@ function buildServer(key, transport) {
     {
       code: z.string().describe("Bloc code: EU, EEA, EFTA, SCHENGEN, EUROZONE, SEPA, NATO, OECD, G7, ASEAN, GCC, MERCOSUR")
     },
-    (c, a) => {
-      const client = c;
-      return client.bloc(a.code);
-    }
+    (c, a, request) => c.bloc(a.code, request)
   );
   tool(
     "bloc_countries",
@@ -113,22 +110,19 @@ function buildServer(key, transport) {
     {
       code: z.string().describe("Bloc code: EU, EEA, EFTA, SCHENGEN, EUROZONE, SEPA, NATO, OECD, G7, ASEAN, GCC, MERCOSUR")
     },
-    (c, a) => {
-      const client = c;
-      return client.bloc.countries(a.code);
-    }
+    (c, a, request) => c.bloc.countries(a.code, request)
   );
   tool(
     "country",
     "Look up a country: names, capital, currency, languages, calling code, timezones.",
     { code: iso2("country code") },
-    (c, a) => c.country(a.code)
+    (c, a, request) => c.country(a.code, request)
   );
   tool(
     "country_states",
     "List the states, provinces or regions of a country.",
     { code: iso2("country code") },
-    (c, a) => c.country.states(a.code)
+    (c, a, request) => c.country.states(a.code, request)
   );
   tool(
     "state",
@@ -137,7 +131,7 @@ function buildServer(key, transport) {
       code: z.string().describe("State code or name, e.g. colorado, NC"),
       country: countryOpt
     },
-    (c, a) => c.state(a.code, { country: a.country })
+    (c, a, request) => c.state(a.code, { ...request, country: a.country })
   );
   tool(
     "state_districts",
@@ -146,7 +140,7 @@ function buildServer(key, transport) {
       code: z.string().describe("State code or name, e.g. NC, colorado"),
       country: countryOpt
     },
-    (c, a) => c.state.districts(a.code, { country: a.country })
+    (c, a, request) => c.state.districts(a.code, { ...request, country: a.country })
   );
   tool(
     "district",
@@ -156,7 +150,7 @@ function buildServer(key, transport) {
       country: countryOpt,
       state: z.string().optional().describe("ADM1 code or name to disambiguate, e.g. NC or louisiana")
     },
-    (c, a) => c.district(a.code, { country: a.country, state: a.state })
+    (c, a, request) => c.district(a.code, { ...request, country: a.country, state: a.state })
   );
   tool(
     "city",
@@ -166,30 +160,30 @@ function buildServer(key, transport) {
       country: countryOpt,
       state: z.string().optional().describe("State code to disambiguate, e.g. NC")
     },
-    (c, a) => c.city(a.name, { country: a.country, state: a.state })
+    (c, a, request) => c.city(a.name, { ...request, country: a.country, state: a.state })
   );
   tool(
     "city_id",
     "Refetch a city by its stable parse id from an earlier response.",
     { id: z.string().describe("Stable city id, e.g. city_mb8mbqrkz8zb") },
-    (c, a) => c.city.id(a.id)
+    (c, a, request) => c.city.id(a.id, request)
   );
   tool(
     "city_search",
     "Search cities by name prefix. Use when the exact name is unknown.",
     {
-      q: z.string().describe("Name prefix, e.g. char"),
+      query: z.string().describe("Name prefix, e.g. char"),
       country: countryOpt,
       state: z.string().optional().describe("State code filter"),
       limit: z.number().int().min(1).max(50).optional().describe("Max results")
     },
-    (c, a) => c.city.search(a.q, { country: a.country, state: a.state, limit: a.limit })
+    (c, a, request) => c.city.search(a.query, { ...request, country: a.country, state: a.state, limit: a.limit })
   );
   tool(
     "city_nearest",
     "Find the nearest city to coordinates.",
     { lat, lon },
-    (c, a) => c.city.nearest(a.lat, a.lon)
+    (c, a, request) => c.city.nearest(a.lat, a.lon, request)
   );
   tool(
     "city_nearby",
@@ -202,7 +196,8 @@ function buildServer(key, transport) {
       unit: z.enum(["km", "mi"]).optional().describe("Radius unit, default km"),
       limit: z.number().int().min(1).max(50).optional().describe("Max results, default 10")
     },
-    (c, a) => c.city.nearby(a.name, {
+    (c, a, request) => c.city.nearby(a.name, {
+      ...request,
       country: a.country,
       state: a.state,
       radius: a.radius,
@@ -217,7 +212,7 @@ function buildServer(key, transport) {
       code: z.string().describe("Postal or ZIP code, e.g. SW1A 1AA, 28202"),
       country: countryOpt
     },
-    (c, a) => c.postal(a.code, { country: a.country })
+    (c, a, request) => c.postal(a.code, { ...request, country: a.country })
   );
   tool(
     "postal_nearby",
@@ -228,7 +223,7 @@ function buildServer(key, transport) {
       radius: z.number().positive().optional().describe("Search radius"),
       unit: z.enum(["km", "mi"]).optional().describe("Radius unit, default km")
     },
-    (c, a) => c.postal.nearby(a.code, { country: a.country, radius: a.radius, unit: a.unit })
+    (c, a, request) => c.postal.nearby(a.code, { ...request, country: a.country, radius: a.radius, unit: a.unit })
   );
   tool(
     "postal_distance",
@@ -238,36 +233,69 @@ function buildServer(key, transport) {
       to: z.string().describe("Second postal code"),
       country: countryOpt
     },
-    (c, a) => c.postal.distance(a.from, a.to, { country: a.country })
+    (c, a, request) => c.postal.distance(a.from, a.to, { ...request, country: a.country })
+  );
+  tool(
+    "address",
+    "Look up a US or French street address: house number, street, unit, city, state, postal code and registration status. Registration does not establish deliverability or verify an apartment. Deep is currently an empty object.",
+    {
+      address: z.string().describe("Street address, e.g. 1600 Pennsylvania Ave NW, Washington, DC 20500"),
+      country: z.string().optional().describe("Country: US or FR. Use FR or a written France suffix for France. Defaults to US."),
+      deep
+    },
+    (c, a, request) => c.address(a.address, { ...request, country: a.country, deep: a.deep })
+  );
+  tool(
+    "address_search",
+    "Search US or French street addresses from a partial address. Postal code, city, state and user IP can narrow or rank matches. French search requires country FR and either postal or city.",
+    {
+      query: z.string().describe("Partial street address, e.g. 1600 Pennsylvania"),
+      country: z.string().optional().describe("Country: US or FR. Defaults to US."),
+      postal: z.string().optional().describe("Postal code filter"),
+      city: z.string().optional().describe("City filter"),
+      state: z.string().optional().describe("State code filter"),
+      ip: z.string().optional().describe("User IP address for ranking nearby matches")
+    },
+    (c, a, request) => c.address.search(a.query, { ...request, country: a.country, postal: a.postal, city: a.city, state: a.state, ip: a.ip })
+  );
+  tool(
+    "company",
+    "Look up a company registration number: validity, registration status, name, activity and address when available. Pass country when more than one scheme can match. Deep adds country, postal and city data.",
+    {
+      number: z.string().describe("Company registration number, e.g. 552100554 with country FR"),
+      country: countryOpt,
+      deep
+    },
+    (c, a, request) => c.company(a.number, { ...request, country: a.country, deep: a.deep })
   );
   tool(
     "point",
     "Reverse geocode coordinates to country, state, district and nearest city. Deep adds richer admin data.",
     { lat, lon, deep },
-    (c, a) => c.point(a.lat, a.lon, { deep: a.deep })
+    (c, a, request) => c.point(a.lat, a.lon, { ...request, deep: a.deep })
   );
   tool(
     "elevation",
     "Elevation in meters at coordinates.",
     { lat, lon },
-    (c, a) => c.elevation(a.lat, a.lon)
+    (c, a, request) => c.elevation(a.lat, a.lon, request)
   );
   tool(
     "weather",
-    "Current weather observation at coordinates from official national agencies. Every measurement ships metric and imperial side by side. Deep adds minute-by-minute rain, hourly and daily rows worldwide, alerts, and air quality. With deep, date returns a past day as deep.history.",
+    "Current weather observation at coordinates. Every measurement ships metric and imperial side by side. Deep adds minute-by-minute rain, hourly and daily rows worldwide, alerts, and air quality. With deep, date returns a past day as deep.history.",
     {
       lat,
       lon,
       deep,
       date: z.string().optional().describe("A past UTC day, YYYY-MM-DD. Requires deep. Returns that day as deep.history")
     },
-    (c, a) => c.weather(a.lat, a.lon, { deep: a.deep, date: a.date })
+    (c, a, request) => c.weather(a.lat, a.lon, { ...request, deep: a.deep, date: a.date })
   );
   tool(
     "email",
     "Validate an email address: syntax, domain, MX, disposable, role, and a typo suggestion when the host looks misspelled. Deep runs a live mailbox verification.",
     { email: z.string().describe("Email address to validate"), deep },
-    (c, a) => c.email(a.email, { deep: a.deep })
+    (c, a, request) => c.email(a.email, { ...request, deep: a.deep })
   );
   tool(
     "vat",
@@ -278,25 +306,25 @@ function buildServer(key, transport) {
       from: z.string().optional().describe("Your own VAT number. Returns a consultation identifier for your audit file"),
       deep
     },
-    (c, a) => c.vat(a.number, { country: a.country, from: a.from, deep: a.deep })
+    (c, a, request) => c.vat(a.number, { ...request, country: a.country, from: a.from, deep: a.deep })
   );
   tool(
     "iban",
-    "Parse an IBAN: checksum and structure. Returns the normalized number, the print form for display, country, checksum digits, and the bank, branch, and account identifiers sitting inside it. bank and branch are codes, not names. Junk answers valid false, never a 404. Pass country when the value has no prefix.",
+    "Parse an IBAN: checksum and structure. Returns the normalized number, the print form for display, country, checksum digits, bank, branch, and account identifiers, plus bank_name and bic when available. Junk answers valid false, never a 404. Pass country when the value has no prefix.",
     {
       iban: z.string().describe("IBAN, with or without spaces, with or without the country prefix"),
       country: iso2("country code when the number has no prefix").optional()
     },
-    (c, a) => c.iban(a.iban, { country: a.country })
+    (c, a, request) => c.iban(a.iban, { ...request, country: a.country })
   );
   tool(
     "npi",
-    "Look up an NPI in the CMS NPPES registry: US healthcare provider name, specialty, practice address, deactivation date, and the OIG exclusion flag. Deep adds Medicare enrollment on paid plans.",
+    "Look up a US healthcare provider by NPI: name, specialty, practice address, deactivation date, and exclusion status. Deep adds Medicare enrollment on paid plans.",
     {
       npi: z.string().describe("10-digit NPI number"),
       deep
     },
-    (c, a) => c.npi(a.npi, { deep: a.deep })
+    (c, a, request) => c.npi(a.npi, { ...request, deep: a.deep })
   );
   tool(
     "phone",
@@ -306,7 +334,7 @@ function buildServer(key, transport) {
       country: iso2("country code for national-format numbers").optional(),
       deep
     },
-    (c, a) => c.phone(a.number, { country: a.country, deep: a.deep })
+    (c, a, request) => c.phone(a.number, { ...request, country: a.country, deep: a.deep })
   );
   tool(
     "carrier",
@@ -315,7 +343,7 @@ function buildServer(key, transport) {
       number: z.string().describe("Phone number, e.g. +14155552671"),
       country: iso2("country code for national-format numbers").optional()
     },
-    (c, a) => c.carrier(a.number, { country: a.country })
+    (c, a, request) => c.carrier(a.number, { ...request, country: a.country })
   );
   tool(
     "caller",
@@ -324,7 +352,7 @@ function buildServer(key, transport) {
       number: z.string().describe("Phone number, e.g. +18004633339"),
       country: iso2("country code for national-format numbers").optional()
     },
-    (c, a) => c.caller(a.number, { country: a.country })
+    (c, a, request) => c.caller(a.number, { ...request, country: a.country })
   );
   tool(
     "hlr",
@@ -333,31 +361,43 @@ function buildServer(key, transport) {
       number: z.string().describe("Phone number, e.g. +447712345678"),
       country: iso2("country code for national-format numbers").optional()
     },
-    (c, a) => c.hlr(a.number, { country: a.country })
+    (c, a, request) => c.hlr(a.number, { ...request, country: a.country })
   );
   tool(
     "domain",
     "Look up a domain: registration, DNS, mail setup. Deep adds richer checks.",
     { domain: z.string().describe("Domain name, e.g. example.com"), deep },
-    (c, a) => c.domain(a.domain, { deep: a.deep })
+    (c, a, request) => c.domain(a.domain, { ...request, deep: a.deep })
+  );
+  tool(
+    "asn",
+    "Network name and country for an autonomous system number.",
+    { asn: z.string().describe("Autonomous system number, such as AS13335 or 13335") },
+    (c, a, request) => c.asn(a.asn, request)
+  );
+  tool(
+    "mac",
+    "Normalize a 48-bit MAC address and return its registered assignment holder, local flag, and multicast flag. Vendor is null for local or multicast addresses.",
+    { mac: z.string().describe("MAC address") },
+    (c, a, request) => c.mac(a.mac, request)
   );
   tool(
     "mx",
     "MX records for a domain.",
     { domain: z.string().describe("Domain name") },
-    (c, a) => c.mx(a.domain)
+    (c, a, request) => c.mx(a.domain, request)
   );
   tool(
     "useragent",
     "Parse a User-Agent string: browser, OS, device, bot detection.",
     { ua: z.string().describe("The User-Agent string to parse"), deep },
-    (c, a) => c.useragent(a.ua, { deep: a.deep })
+    (c, a, request) => c.useragent(a.ua, { ...request, deep: a.deep })
   );
   tool(
     "vin",
     "Decode a 17-character VIN: year, make, model, trim, body, engine, drive, transmission, manufacturer, and assembly plant. Junk or a failed check digit answers valid false, never a 404. Deep adds open recall campaigns on paid plans.",
     { vin: z.string().describe("The VIN as you have it. Spaces and punctuation fold out"), deep },
-    (c, a) => c.vin(a.vin, { deep: a.deep })
+    (c, a, request) => c.vin(a.vin, { ...request, deep: a.deep })
   );
   tool(
     "tariff",
@@ -367,23 +407,23 @@ function buildServer(key, transport) {
       origin: iso2("country of origin for duty resolution, only read with deep").optional(),
       deep
     },
-    (c, a) => c.tariff(a.code, { deep: a.deep, origin: a.origin })
+    (c, a, request) => c.tariff(a.code, { ...request, deep: a.deep, origin: a.origin })
   );
   tool(
     "tariff_search",
     "Search US tariff schedule descriptions by product. Returns up to 20 lines, best match first, each with hts, description, and the general duty rate.",
-    { q: z.string().describe("Product words, e.g. sunglasses, laptop, coffee") },
-    (c, a) => c.tariff.search(a.q)
+    { query: z.string().describe("Product words, e.g. sunglasses, laptop, coffee") },
+    (c, a, request) => c.tariff.search(a.query, request)
   );
   tool(
     "currency",
     "Look up a currency: name, symbol, decimal places, countries using it.",
     { code: z.string().describe("ISO 4217 code, e.g. USD") },
-    (c, a) => c.currency(a.code)
+    (c, a, request) => c.currency(a.code, request)
   );
   tool(
     "currency_rate",
-    "Exchange rate between two currencies from official central bank data. Pass date for a past business day, amount to convert.",
+    "Reference exchange rate between two currencies. Pass date for a past business day, amount to convert.",
     {
       base: z.string().describe("Base currency ISO 4217 code, e.g. USD"),
       quote: z.string().describe("Quote currency ISO 4217 code, e.g. EUR"),
@@ -392,25 +432,25 @@ function buildServer(key, transport) {
       ),
       amount: z.number().optional().describe("Appends amount and converted, rounded to the quote currency minor-unit digits")
     },
-    (c, a) => c.currency.rate(a.base, a.quote, { date: a.date, amount: a.amount })
+    (c, a, request) => c.currency.rate(a.base, a.quote, { ...request, date: a.date, amount: a.amount })
   );
   tool(
     "language",
     "Look up a language by BCP 47 or ISO 639-3 code: names, script, direction.",
     { code: z.string().describe("Language code, e.g. en, ja, gsw") },
-    (c, a) => c.language(a.code)
+    (c, a, request) => c.language(a.code, request)
   );
   tool(
     "name",
     "Parse a person name: prefix, first, middle, last, suffix, gender, salutation. Junk input returns valid false. Gender comes from dictionary data and is null when the data does not decide.",
     { name: z.string().describe("The name to parse, e.g. Smith, John or BILLY OSHALL") },
-    (c, a) => c.name(a.name)
+    (c, a, request) => c.name(a.name, request)
   );
   tool(
     "timezone",
     "Look up a timezone from an IANA id or from lat and lon. Offset, DST, local time. Pass at for a specific instant. Pass to with another IANA id to convert a time between zones: the response appends at (wall time in the from zone) and to.at (the converted time). Open ocean answers the nautical Etc/GMT zone.",
     {
-      timezone: z.string().optional().describe("IANA timezone id, e.g. America/New_York"),
+      timezone: z.string().min(1).optional().describe("IANA timezone id, e.g. America/New_York"),
       lat: lat.optional(),
       lon: lon.optional(),
       at: z.string().optional().describe(
@@ -418,29 +458,36 @@ function buildServer(key, transport) {
       ),
       to: z.string().optional().describe("Convert: the other IANA zone, e.g. Asia/Tokyo. Requires timezone, not lat/lon")
     },
-    (c, a) => {
+    (c, a, request) => {
       if (a.lat != null && a.lon != null) {
-        return c.timezone(a.lat, a.lon, { at: a.at });
+        return c.timezone.at(a.lat, a.lon, { ...request, at: a.at });
       }
       if (!a.timezone) {
         return Promise.reject(new Error("Pass timezone or lat and lon"));
       }
-      return c.timezone(a.timezone, { at: a.at, to: a.to });
-    }
+      return c.timezone(a.timezone, { ...request, at: a.at, to: a.to });
+    },
+    (schema) => schema.refine(
+      (a) => a.timezone !== void 0 ? a.lat === void 0 && a.lon === void 0 : a.lat !== void 0 && a.lon !== void 0 && a.to === void 0,
+      { message: "Pass either timezone (with optional to), or both lat and lon." }
+    )
   );
   tool(
     "date",
     "Parse a date in any common format (2026-03-29, March 29, 2026, 3/29/2026, 20260829) into calendar facts: ISO date, weekday, ISO week, day of year, quarter, leap year, unix time. Ambiguous numeric dates answer valid false unless format asserts a reading, never a guess. Pass to with another date for the signed days between. Omit date for today (UTC), so to alone answers days from today.",
     {
-      date: z.string().optional().describe("The date as you have it, any common format. Omit for today (UTC)"),
+      date: z.string().min(1).optional().describe("The date as you have it, any common format. Omit for today (UTC)"),
       format: z.enum(["mdy", "dmy"]).optional().describe("Breaks the month-first / day-first tie on numeric dates like 03/04/2026"),
       to: z.string().optional().describe("Another date. Appends to (normalized ISO) and days (signed days between)")
     },
-    (c, a) => {
-      const client = c;
-      if (a.date == null || a.date === "") return client.date.today({ to: a.to });
-      return client.date(a.date, { format: a.format, to: a.to });
-    }
+    (c, a, request) => {
+      if (a.date == null) return c.date.today({ ...request, to: a.to });
+      return c.date(a.date, { ...request, format: a.format, to: a.to });
+    },
+    (schema) => schema.refine(
+      (a) => a.format === void 0 || a.date !== void 0,
+      { message: "Pass date when specifying format; omit both for today." }
+    )
   );
   tool(
     "holiday",
@@ -449,28 +496,28 @@ function buildServer(key, transport) {
       country: iso2("country code"),
       year: z.number().int().optional().describe("Year, default current")
     },
-    (c, a) => c.holiday(a.country, { year: a.year })
+    (c, a, request) => c.holiday(a.country, { ...request, year: a.year })
   );
   tool(
     "holiday_date",
     "Whether a specific date is a holiday or observance in a country. holiday is null when it is not.",
     { country: iso2("country code"), date: z.string().describe("Date as YYYY-MM-DD") },
-    (c, a) => c.holiday.date(a.country, a.date)
+    (c, a, request) => c.holiday.date(a.country, a.date, request)
   );
   tool(
     "emoji",
     "Look up an emoji by name or character: unicode, hex, skin tones.",
     { emoji: z.string().describe("Emoji name or the character itself, e.g. rocket") },
-    (c, a) => c.emoji(a.emoji)
+    (c, a, request) => c.emoji(a.emoji, request)
   );
   tool(
     "emoji_search",
     "Search emoji by keyword.",
     {
-      q: z.string().describe("Search keyword, e.g. fire"),
+      query: z.string().describe("Search keyword, e.g. fire"),
       limit: z.number().int().min(1).max(50).optional().describe("Max results")
     },
-    (c, a) => c.emoji.search(a.q, { limit: a.limit })
+    (c, a, request) => c.emoji.search(a.query, { ...request, limit: a.limit })
   );
   return server;
 }

package/dist/http.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   buildServer
-} from "./chunk-FQJPDQPX.js";
+} from "./chunk-2LHHK5F6.js";
 
 // src/http.ts
 import { createServer } from "http";

package/dist/registry.js

@@ -2,7 +2,7 @@
 import {
   VERSION,
   buildServer
-} from "./chunk-FQJPDQPX.js";
+} from "./chunk-2LHHK5F6.js";
 export {
   VERSION,
   buildServer

package/dist/stdio.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   buildServer
-} from "./chunk-FQJPDQPX.js";
+} from "./chunk-2LHHK5F6.js";
 
 // src/stdio.ts
 import { serveStdio } from "@modelcontextprotocol/server/stdio";

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "parseapi-mcp",
-	"version": "0.2.1",
+	"version": "0.3.0",
 	"mcpName": "com.parseapi/mcp",
-	"description": "Official parseAPI MCP server. Location, validate, and decode lookups for AI agents: geo, email, phone, weather, currency.",
+	"description": "Official parseAPI MCP server. Look up places, addresses, company numbers, email, phone, weather, dates and more.",
 	"keywords": [
 		"parseapi",
 		"mcp",
@@ -40,12 +40,14 @@
 		"build": "tsup",
 		"typecheck": "tsc --noEmit",
 		"smoke": "npm run build && node smoke/smoke.mjs",
-		"serve": "npm run build && node dist/http.js"
+		"serve": "npm run build && node dist/http.js",
+		"test": "npm run build && node --test test/*.test.mjs",
+		"prepublishOnly": "npm run typecheck && npm test"
 	},
 	"dependencies": {
 		"@modelcontextprotocol/server": "^2.0.0",
 		"@modelcontextprotocol/node": "^2.0.0",
-		"@parseapi/sdk": "^0.2.1",
+		"@parseapi/sdk": "^0.3.0",
 		"zod": "^4.0.0"
 	},
 	"devDependencies": {