parseapi-mcp 0.1.2 → 0.2.0

package/README.md

@@ -2,16 +2,28 @@
 
 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.
 
-Get a key at [parseapi.com](https://parseapi.com). Free plan works.
-
 ## Hosted
 
-One URL, nothing to install.
+One URL, nothing to install. Add the server and sign in once in the browser. Free plan works.
+
+```json
+{
+  "mcpServers": {
+    "parseAPI": { "url": "https://mcp.parseapi.com" }
+  }
+}
+```
+
+**Cursor:** [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=parseAPI&config=eyJ1cmwiOiJodHRwczovL21jcC5wYXJzZWFwaS5jb20ifQ==)
+
+Repo-root `.mcp.json` is keyless on purpose. [cursor.directory](https://cursor.directory/plugins/parseapi) auto-detects it when you submit or refresh the listing.
+
+CI and headless setups skip the browser with a key from [parseapi.com](https://parseapi.com):
 
 ```json
 {
   "mcpServers": {
-    "parseapi": {
+    "parseAPI": {
       "url": "https://mcp.parseapi.com",
       "headers": { "X-API-Key": "your-api-key" }
     }
@@ -24,7 +36,7 @@ One URL, nothing to install.
 ```json
 {
   "mcpServers": {
-    "parseapi": {
+    "parseAPI": {
       "command": "npx",
       "args": ["-y", "parseapi-mcp"],
       "env": { "PARSEAPI_KEY": "your-api-key" }
@@ -35,7 +47,7 @@ One URL, nothing to install.
 
 ## Tools
 
-One tool per endpoint, named after the route: `ip`, `postal`, `city`, `city_search`, `email`, `phone`, `weather`, `currency_rate`, `timezone`, `holiday`, `point`, `elevation`, and the rest. Every tool returns the same minimal JSON the API serves.
+One tool per endpoint, named after the route: `ip`, `postal`, `city`, `city_search`, `city_nearby`, `email`, `vat`, `iban`, `npi`, `vin`, `hts`, `hts_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.
 
 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`.
 

package/dist/chunk-4GQ2Q7SN.js

@@ -0,0 +1,481 @@
+#!/usr/bin/env node
+
+// src/registry.ts
+import { McpServer } from "@modelcontextprotocol/server";
+import { parseAPI } from "@parseapi/sdk";
+import * as z from "zod";
+
+// src/errors.ts
+import { ParseAPIError } from "@parseapi/sdk";
+function ok(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data) }] };
+}
+function errorJson(code, message, docs, requestId) {
+  return {
+    isError: true,
+    content: [{ type: "text", text: JSON.stringify({ code, message, docs, request_id: requestId }) }]
+  };
+}
+function toErrorResult(err) {
+  if (err instanceof ParseAPIError) {
+    return errorJson(err.code, err.message, err.docs, err.requestId);
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return errorJson("network_error", message, null, null);
+}
+function noKeyResult(transport) {
+  const where = transport === "stdio" ? "set it as the PARSEAPI_KEY environment variable for this MCP server" : "send it in the X-API-Key header";
+  return errorJson(
+    "invalid_api_key",
+    `No API key. Get a free key at https://parseapi.com and ${where}.`,
+    "https://parseapi.com/docs#invalid_api_key",
+    null
+  );
+}
+
+// src/registry.ts
+var VERSION = "0.2.0";
+var deep = z.boolean().optional().describe("Include the nested deep object with richer fields. Paid on most endpoints.");
+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`);
+var countryOpt = z.string().optional().describe("ISO2, ISO3, or a country name. Optional when the lookup is unique.");
+function buildServer(key, transport) {
+  const server = new McpServer(
+    {
+      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.",
+      websiteUrl: "https://parseapi.com"
+    },
+    { capabilities: { tools: {} } }
+  );
+  const parse = key ? parseAPI(key) : null;
+  function tool(name, description, shape, fn) {
+    server.registerTool(
+      name,
+      {
+        description,
+        inputSchema: z.object(shape),
+        annotations: { readOnlyHint: true }
+      },
+      async (args) => {
+        if (!parse) return noKeyResult(transport);
+        try {
+          return ok(await fn(parse, args));
+        } catch (err) {
+          return toErrorResult(err);
+        }
+      }
+    );
+  }
+  tool(
+    "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 })
+  );
+  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 })
+    );
+  }
+  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)
+  );
+  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)
+  );
+  tool(
+    "bloc",
+    "Look up a country group by code: EU, EEA, Schengen, Eurozone, SEPA, NATO, and more. Returns the official name and the current member count.",
+    {
+      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);
+    }
+  );
+  tool(
+    "bloc_countries",
+    "List the current members of a country group, each with name, flag, and calling code.",
+    {
+      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);
+    }
+  );
+  tool(
+    "country",
+    "Look up a country: names, capital, currency, languages, calling code, timezones.",
+    { code: iso2("country code") },
+    (c, a) => c.country(a.code)
+  );
+  tool(
+    "country_states",
+    "List the states, provinces or regions of a country.",
+    { code: iso2("country code") },
+    (c, a) => c.country.states(a.code)
+  );
+  tool(
+    "state",
+    "Look up a state, province or region by code or name. Unique names resolve without a country. A colliding code 404s asking for ?country=. Country takes ISO2, ISO3, or a name.",
+    {
+      code: z.string().describe("State code or name, e.g. colorado, NC"),
+      country: countryOpt
+    },
+    (c, a) => c.state(a.code, { country: a.country })
+  );
+  tool(
+    "state_districts",
+    "List the districts, counties or departments of a state.",
+    {
+      code: z.string().describe("State code or name, e.g. NC, colorado"),
+      country: countryOpt
+    },
+    (c, a) => c.state.districts(a.code, { country: a.country })
+  );
+  tool(
+    "district",
+    "Look up a district, county or department by code or name. Pass state when a name collides.",
+    {
+      code: z.string().describe("District code or name, e.g. 37081, guilford county"),
+      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 })
+  );
+  tool(
+    "city",
+    "Look up a city by name: type, capital status (capital_of), district, elevation, area in km2, coordinates, timezone. Pass country or state to disambiguate name ties.",
+    {
+      name: z.string().describe("City name, e.g. charlotte"),
+      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 })
+  );
+  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)
+  );
+  tool(
+    "city_search",
+    "Search cities by name prefix. Use when the exact name is unknown.",
+    {
+      q: 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 })
+  );
+  tool(
+    "city_nearest",
+    "Find the nearest city to coordinates.",
+    { lat, lon },
+    (c, a) => c.city.nearest(a.lat, a.lon)
+  );
+  tool(
+    "city_nearby",
+    "List cities around a named city, nearest first, with distance. Default radius 40 km.",
+    {
+      name: z.string().describe("Anchor city name, e.g. denver"),
+      country: countryOpt,
+      state: z.string().optional().describe("State code to disambiguate the anchor"),
+      radius: z.number().positive().optional().describe("Search radius, default 40 km"),
+      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, {
+      country: a.country,
+      state: a.state,
+      radius: a.radius,
+      unit: a.unit,
+      limit: a.limit
+    })
+  );
+  tool(
+    "postal",
+    "Look up a postal or ZIP code: place name, country name, coordinates, state, district, area, timezone, elevation. Unique codes resolve without a country. A collision 404s asking for ?country=. Never defaults to US.",
+    {
+      code: z.string().describe("Postal or ZIP code, e.g. SW1A 1AA, 28202"),
+      country: countryOpt
+    },
+    (c, a) => c.postal(a.code, { country: a.country })
+  );
+  tool(
+    "postal_nearby",
+    "List postal codes near a given one, sorted by distance. Unique codes resolve without a country.",
+    {
+      code: z.string().describe("Postal code to search around"),
+      country: countryOpt,
+      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 })
+  );
+  tool(
+    "postal_distance",
+    "Distance between two postal codes in the same country. Unique codes resolve without a country.",
+    {
+      from: z.string().describe("First postal code"),
+      to: z.string().describe("Second postal code"),
+      country: countryOpt
+    },
+    (c, a) => c.postal.distance(a.from, a.to, { country: a.country })
+  );
+  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 })
+  );
+  tool(
+    "elevation",
+    "Elevation in meters at coordinates.",
+    { lat, lon },
+    (c, a) => c.elevation(a.lat, a.lon)
+  );
+  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.",
+    {
+      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 })
+  );
+  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 })
+  );
+  tool(
+    "vat",
+    "Validate a VAT number: format and checksum on every call. Deep asks the live EU registry for registered, legal name, and address. Pass from with your own VAT for a consultation identifier.",
+    {
+      number: z.string().describe("VAT number, with or without the country prefix"),
+      country: iso2("country code when the number has no prefix").optional(),
+      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 })
+  );
+  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.",
+    {
+      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 })
+  );
+  tool(
+    "npi",
+    "Look up an NPI in the CMS NPPES registry: US healthcare provider name, specialty, practice address, active status, and the OIG exclusion flag. 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 })
+  );
+  tool(
+    "phone",
+    "Validate and parse a phone number: country, type, formats. Pass country for national-format numbers.",
+    {
+      number: z.string().describe("Phone number, e.g. +14155552671"),
+      country: iso2("country code for national-format numbers").optional(),
+      deep
+    },
+    (c, a) => c.phone(a.number, { country: a.country, deep: a.deep })
+  );
+  tool(
+    "carrier",
+    "Look up the current carrier serving a phone number: carrier name, network type including voip, burner app flag, issuing city and state. Metered per lookup on a valid number.",
+    {
+      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 })
+  );
+  tool(
+    "caller",
+    "Look up the caller ID name (CNAM) for a US or Canada phone number. caller is the record verbatim, null when no record or outside NANP. Metered per lookup on a NANP number.",
+    {
+      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 })
+  );
+  tool(
+    "hlr",
+    "Live network status for a phone number worldwide: live means assigned, connected means the handset is reachable right now. Outside North America adds roaming and network details. Metered per lookup on a valid number.",
+    {
+      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 })
+  );
+  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 })
+  );
+  tool(
+    "mx",
+    "MX records for a domain.",
+    { domain: z.string().describe("Domain name") },
+    (c, a) => c.mx(a.domain)
+  );
+  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 })
+  );
+  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 })
+  );
+  tool(
+    "hts",
+    "Look up a US Harmonized Tariff Schedule code: description, duty rates verbatim (general, special, column 2), units, parent lineage, and the official revision that answered. Deep with an origin country resolves the Chapter 99 tariff measures that apply from that origin, with a composed effective_rate when the components compose cleanly (null otherwise, null beats a guess). Unknown code is a 404.",
+    {
+      code: z.string().describe("HTS code, 4 to 10 digits, dots optional, e.g. 8471.30.01.00"),
+      origin: iso2("country of origin for duty resolution, only read with deep").optional(),
+      deep
+    },
+    (c, a) => c.hts(a.code, { deep: a.deep, origin: a.origin })
+  );
+  tool(
+    "hts_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.hts.search(a.q)
+  );
+  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)
+  );
+  tool(
+    "currency_rate",
+    "Exchange rate between two currencies from official central bank data. 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"),
+      date: z.string().optional().describe(
+        "YYYY-MM-DD. Official rate for that business day. A weekend or holiday resolves to the last published day on or before it"
+      ),
+      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 })
+  );
+  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)
+  );
+  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)
+  );
+  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"),
+      lat: lat.optional(),
+      lon: lon.optional(),
+      at: z.string().optional().describe(
+        "ISO 8601 time, default now. With to and no UTC offset, reads as wall time in the from zone"
+      ),
+      to: z.string().optional().describe("Convert: the other IANA zone, e.g. Asia/Tokyo. Requires timezone, not lat/lon")
+    },
+    (c, a) => {
+      if (a.lat != null && a.lon != null) {
+        return c.timezone(a.lat, a.lon, { 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 });
+    }
+  );
+  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)"),
+      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 });
+    }
+  );
+  tool(
+    "holiday",
+    "Public holidays and cultural observances for a country and year. Each row carries type: public or observance.",
+    {
+      country: iso2("country code"),
+      year: z.number().int().optional().describe("Year, default current")
+    },
+    (c, a) => c.holiday(a.country, { 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)
+  );
+  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)
+  );
+  tool(
+    "emoji_search",
+    "Search emoji by keyword.",
+    {
+      q: 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 })
+  );
+  return server;
+}
+
+export {
+  VERSION,
+  buildServer
+};

package/dist/http.js

@@ -1,12 +1,79 @@
 #!/usr/bin/env node
 import {
   buildServer
-} from "./chunk-QELYOT3A.js";
+} from "./chunk-4GQ2Q7SN.js";
 
 // src/http.ts
 import { createServer } from "http";
 import { createMcpHandler } from "@modelcontextprotocol/server";
 import { toNodeHandler } from "@modelcontextprotocol/node";
+
+// src/oauth.ts
+var WEB_URL = (process.env.WEB_URL ?? "https://parseapi.com").replace(/\/$/, "");
+var SELF_URL = (process.env.SELF_URL ?? "https://mcp.parseapi.com").replace(/\/$/, "");
+var KEY_TTL_MS = 10 * 60 * 1e3;
+var MISS_TTL_MS = 60 * 1e3;
+var cache = /* @__PURE__ */ new Map();
+function isApiKeyShape(value) {
+  return value.startsWith("parse_") || /^[0-9a-f]{32}$/.test(value);
+}
+async function resolveOAuthKey(token) {
+  const hit = cache.get(token);
+  if (hit && hit.expires > Date.now()) return hit.key;
+  if (cache.size > 5e3) {
+    const now = Date.now();
+    for (const [k, v] of cache) if (v.expires <= now) cache.delete(k);
+  }
+  try {
+    const res = await fetch(`${WEB_URL}/api/internal/mcp/resolve`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-parse-web-internal": process.env.WEB_INTERNAL_TOKEN ?? ""
+      },
+      body: JSON.stringify({ token }),
+      signal: AbortSignal.timeout(3e3)
+    });
+    if (res.ok) {
+      const data = await res.json();
+      if (typeof data.key === "string" && data.key) {
+        const ttl = Math.min(KEY_TTL_MS, Math.max(3e4, (data.expires_in ?? 600) * 1e3));
+        cache.set(token, { key: data.key, expires: Date.now() + ttl });
+        return data.key;
+      }
+    }
+    if (res.status === 401 || res.status === 403 || res.status === 404) {
+      cache.set(token, { key: null, expires: Date.now() + MISS_TTL_MS });
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+var PROTECTED_RESOURCE_METADATA = {
+  resource: SELF_URL,
+  authorization_servers: [WEB_URL],
+  bearer_methods_supported: ["header"],
+  scopes_supported: ["openid", "profile", "email", "offline_access"]
+};
+var WWW_AUTHENTICATE = `Bearer resource_metadata="${SELF_URL}/.well-known/oauth-protected-resource"`;
+var asMetadata = null;
+async function authServerMetadata() {
+  if (asMetadata && asMetadata.expires > Date.now()) return asMetadata.body;
+  try {
+    const res = await fetch(`${WEB_URL}/.well-known/oauth-authorization-server`, {
+      signal: AbortSignal.timeout(3e3)
+    });
+    if (!res.ok) return null;
+    const body = await res.text();
+    asMetadata = { body, expires: Date.now() + 5 * 60 * 1e3 };
+    return body;
+  } catch {
+    return asMetadata?.body ?? null;
+  }
+}
+
+// src/http.ts
 function keyFrom(request) {
   if (!request) return null;
   const headerKey = request.headers.get("x-api-key");
@@ -20,12 +87,88 @@ var handler = createMcpHandler((ctx) => buildServer(keyFrom(ctx.requestInfo), "h
 });
 var nodeHandler = toNodeHandler(handler);
 var port = Number(process.env.PORT ?? 8080);
+var WELL_KNOWN_CORS = {
+  "content-type": "application/json",
+  "access-control-allow-origin": "*",
+  "access-control-allow-methods": "GET, OPTIONS",
+  "access-control-allow-headers": "Content-Type"
+};
+function unauthorized(res) {
+  res.writeHead(401, {
+    "content-type": "application/json",
+    "www-authenticate": WWW_AUTHENTICATE,
+    "access-control-allow-origin": "*",
+    "access-control-expose-headers": "WWW-Authenticate"
+  }).end(
+    JSON.stringify({
+      error: "unauthorized",
+      error_description: "Sign in via OAuth or send an API key in X-API-Key."
+    })
+  );
+}
+function bearerFrom(req) {
+  const auth = req.headers.authorization;
+  if (typeof auth !== "string" || !auth.toLowerCase().startsWith("bearer ")) return null;
+  return auth.slice(7).trim() || null;
+}
+async function gate(req, res) {
+  const headerKey = req.headers["x-api-key"];
+  if (typeof headerKey === "string" && headerKey) {
+    return nodeHandler(req, res);
+  }
+  const bearer = bearerFrom(req);
+  if (!bearer) {
+    unauthorized(res);
+    return;
+  }
+  if (isApiKeyShape(bearer)) {
+    return nodeHandler(req, res);
+  }
+  const key = await resolveOAuthKey(bearer);
+  if (!key) {
+    unauthorized(res);
+    return;
+  }
+  req.headers["x-api-key"] = key;
+  return nodeHandler(req, res);
+}
 createServer((req, res) => {
-  if (req.method === "GET" && req.url === "/health") {
+  const path = (req.url ?? "/").split("?")[0];
+  if (req.method === "GET" && path === "/health") {
     res.writeHead(200, { "content-type": "text/plain" }).end("ok");
     return;
   }
-  void nodeHandler(req, res);
+  if (path === "/.well-known/oauth-protected-resource") {
+    if (req.method === "OPTIONS") {
+      res.writeHead(204, WELL_KNOWN_CORS).end();
+      return;
+    }
+    res.writeHead(200, WELL_KNOWN_CORS).end(JSON.stringify(PROTECTED_RESOURCE_METADATA));
+    return;
+  }
+  if (path === "/.well-known/oauth-authorization-server" || path === "/.well-known/openid-configuration") {
+    if (req.method === "OPTIONS") {
+      res.writeHead(204, WELL_KNOWN_CORS).end();
+      return;
+    }
+    void authServerMetadata().then((body) => {
+      if (body) res.writeHead(200, WELL_KNOWN_CORS).end(body);
+      else res.writeHead(503, WELL_KNOWN_CORS).end(JSON.stringify({ error: "unavailable" }));
+    });
+    return;
+  }
+  if (req.method === "OPTIONS") {
+    void nodeHandler(req, res);
+    return;
+  }
+  void gate(req, res).catch((err) => {
+    console.error("parseapi-mcp gate:", err instanceof Error ? err.message : err);
+    if (!res.headersSent) {
+      res.writeHead(500, { "content-type": "application/json" }).end(
+        JSON.stringify({ error: "server_error" })
+      );
+    }
+  });
 }).listen(port, () => {
   console.error(`parseapi-mcp listening on :${port}`);
 });

package/dist/registry.js

@@ -2,7 +2,7 @@
 import {
   VERSION,
   buildServer
-} from "./chunk-QELYOT3A.js";
+} from "./chunk-4GQ2Q7SN.js";
 export {
   VERSION,
   buildServer

package/dist/stdio.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "parseapi-mcp",
-	"version": "0.1.2",
-	"mcpName": "io.github.parseapi/mcp",
+	"version": "0.2.0",
+	"mcpName": "com.parseapi/mcp",
 	"description": "Official parseAPI MCP server. Location, validate, and decode lookups for AI agents: geo, email, phone, weather, currency.",
 	"keywords": [
 		"parseapi",
@@ -45,7 +45,7 @@
 	"dependencies": {
 		"@modelcontextprotocol/server": "^2.0.0",
 		"@modelcontextprotocol/node": "^2.0.0",
-		"@parseapi/sdk": "^0.1.0",
+		"@parseapi/sdk": "^0.2.0",
 		"zod": "^4.0.0"
 	},
 	"devDependencies": {

package/dist/chunk-QELYOT3A.js

@@ -1,310 +0,0 @@
-#!/usr/bin/env node
-
-// src/registry.ts
-import { McpServer } from "@modelcontextprotocol/server";
-import { parseAPI } from "@parseapi/sdk";
-import * as z from "zod";
-
-// src/errors.ts
-import { ParseAPIError } from "@parseapi/sdk";
-function ok(data) {
-  return { content: [{ type: "text", text: JSON.stringify(data) }] };
-}
-function errorJson(code, message, docs, requestId) {
-  return {
-    isError: true,
-    content: [{ type: "text", text: JSON.stringify({ code, message, docs, request_id: requestId }) }]
-  };
-}
-function toErrorResult(err) {
-  if (err instanceof ParseAPIError) {
-    return errorJson(err.code, err.message, err.docs, err.requestId);
-  }
-  const message = err instanceof Error ? err.message : String(err);
-  return errorJson("network_error", message, null, null);
-}
-function noKeyResult(transport) {
-  const where = transport === "stdio" ? "set it as the PARSEAPI_KEY environment variable for this MCP server" : "send it in the X-API-Key header";
-  return errorJson(
-    "invalid_api_key",
-    `No API key. Get a free key at https://parseapi.com and ${where}.`,
-    "https://parseapi.com/docs#invalid_api_key",
-    null
-  );
-}
-
-// src/registry.ts
-var VERSION = "0.1.0";
-var deep = z.boolean().optional().describe("Include the nested deep object with richer fields. Paid on most endpoints.");
-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`);
-function buildServer(key, transport) {
-  const server = new McpServer(
-    {
-      name: "parseapi",
-      version: VERSION,
-      title: "parseAPI",
-      description: "Lookups for agents: IP and place data, email, phone and domain validation, weather, currency, timezones, 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) {
-    server.registerTool(
-      name,
-      {
-        description,
-        inputSchema: z.object(shape),
-        annotations: { readOnlyHint: true }
-      },
-      async (args) => {
-        if (!parse) return noKeyResult(transport);
-        try {
-          return ok(await fn(parse, args));
-        } catch (err) {
-          return toErrorResult(err);
-        }
-      }
-    );
-  }
-  tool(
-    "ip",
-    "Look up an IPv4 or IPv6 address: country, region, ASN, timezone. Deep adds datacenter, relay and tor 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 })
-  );
-  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 })
-    );
-  }
-  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)
-  );
-  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)
-  );
-  tool(
-    "country",
-    "Look up a country: names, capital, currency, languages, calling code, timezones.",
-    { code: iso2("country code") },
-    (c, a) => c.country(a.code)
-  );
-  tool(
-    "country_states",
-    "List the states, provinces or regions of a country.",
-    { code: iso2("country code") },
-    (c, a) => c.country.states(a.code)
-  );
-  tool(
-    "state",
-    "Look up a state, province or region by its code within a country.",
-    { code: z.string().describe("State code, e.g. NC"), country: iso2("country code") },
-    (c, a) => c.state(a.code, { country: a.country })
-  );
-  tool(
-    "state_districts",
-    "List the districts, counties or departments of a state.",
-    { code: z.string().describe("State code, e.g. NC"), country: iso2("country code") },
-    (c, a) => c.state.districts(a.code, { country: a.country })
-  );
-  tool(
-    "district",
-    "Look up a district, county or department by code.",
-    { code: z.string().describe("District code, e.g. 37081"), country: iso2("country code").optional() },
-    (c, a) => c.district(a.code, { country: a.country })
-  );
-  tool(
-    "city",
-    "Look up a city by name: coordinates, state, population, timezone. Pass country to disambiguate name ties.",
-    {
-      name: z.string().describe("City name, e.g. charlotte"),
-      country: iso2("country code").optional(),
-      state: z.string().optional().describe("State code to disambiguate, e.g. NC")
-    },
-    (c, a) => c.city(a.name, { 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)
-  );
-  tool(
-    "city_search",
-    "Search cities by name prefix. Use when the exact name is unknown.",
-    {
-      q: z.string().describe("Name prefix, e.g. char"),
-      country: iso2("country code").optional(),
-      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 })
-  );
-  tool(
-    "city_nearest",
-    "Find the nearest city to coordinates.",
-    { lat, lon },
-    (c, a) => c.city.nearest(a.lat, a.lon)
-  );
-  tool(
-    "postal",
-    "Look up a postal code: place name, coordinates, state, district, timezone, elevation. Country is required.",
-    { code: z.string().describe("Postal code, e.g. 28202"), country: iso2("country code") },
-    (c, a) => c.postal(a.code, { country: a.country })
-  );
-  tool(
-    "postal_nearby",
-    "List postal codes near a given one, sorted by distance.",
-    {
-      code: z.string().describe("Postal code to search around"),
-      country: iso2("country code"),
-      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 })
-  );
-  tool(
-    "postal_distance",
-    "Distance between two postal codes in the same country.",
-    {
-      from: z.string().describe("First postal code"),
-      to: z.string().describe("Second postal code"),
-      country: iso2("country code")
-    },
-    (c, a) => c.postal.distance(a.from, a.to, { country: a.country })
-  );
-  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 })
-  );
-  tool(
-    "elevation",
-    "Elevation in meters at coordinates.",
-    { lat, lon },
-    (c, a) => c.elevation(a.lat, a.lon)
-  );
-  tool(
-    "weather",
-    "Current weather observation at coordinates from official national agencies. Every measurement ships metric and imperial side by side. Deep adds forecast and alerts where available.",
-    {
-      lat,
-      lon,
-      deep
-    },
-    (c, a) => c.weather(a.lat, a.lon, { deep: a.deep })
-  );
-  tool(
-    "email",
-    "Validate an email address: syntax, domain, MX, disposable and role flags. Deep runs a live mailbox verification.",
-    { email: z.string().describe("Email address to validate"), deep },
-    (c, a) => c.email(a.email, { deep: a.deep })
-  );
-  tool(
-    "phone",
-    "Validate and parse a phone number: country, type, formats. Pass country for national-format numbers.",
-    {
-      number: z.string().describe("Phone number, e.g. +14155552671"),
-      country: iso2("country code for national-format numbers").optional(),
-      deep
-    },
-    (c, a) => c.phone(a.number, { country: a.country, deep: a.deep })
-  );
-  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 })
-  );
-  tool(
-    "mx",
-    "MX records and mail provider for a domain.",
-    { domain: z.string().describe("Domain name") },
-    (c, a) => c.mx(a.domain)
-  );
-  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 })
-  );
-  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)
-  );
-  tool(
-    "currency_rate",
-    "Exchange rate between two currencies from official central bank data.",
-    {
-      base: z.string().describe("Base currency ISO 4217 code, e.g. USD"),
-      quote: z.string().describe("Quote currency ISO 4217 code, e.g. EUR")
-    },
-    (c, a) => c.currency.rate(a.base, a.quote)
-  );
-  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)
-  );
-  tool(
-    "timezone",
-    "Look up an IANA timezone: current offset, DST state, local time. Pass at for a specific instant.",
-    {
-      timezone: z.string().describe("IANA timezone id, e.g. America/New_York"),
-      at: z.string().optional().describe("ISO 8601 instant to evaluate, default now")
-    },
-    (c, a) => c.timezone(a.timezone, { at: a.at })
-  );
-  tool(
-    "holiday",
-    "Public holidays and cultural observances for a country and year. Each row carries type: public or observance.",
-    {
-      country: iso2("country code"),
-      year: z.number().int().optional().describe("Year, default current")
-    },
-    (c, a) => c.holiday(a.country, { 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)
-  );
-  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)
-  );
-  tool(
-    "emoji_search",
-    "Search emoji by keyword.",
-    {
-      q: 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 })
-  );
-  return server;
-}
-
-export {
-  VERSION,
-  buildServer
-};