parseapi-mcp 0.4.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -47,9 +47,11 @@ CI and headless setups skip the browser with a key from [parseapi.com](https://p
47
47
 
48
48
  ## API versions
49
49
 
50
- The team's API version is selected in [Dashboard → API version](https://parseapi.com/dashboard/versions). One setting applies to every key and connected app in the team. Existing teams keep `1.0.0`; new teams start on `2.0.0`. Owners and admins can change it after reviewing and testing the target contract. Keys and app identities stay the same. Signing in or upgrading MCP does not change the team's version.
50
+ Version 1.0.0 explicitly selects the API contract supported by this MCP package. Every API tool request sends `Parse-Version: 2.0.0`, matching this release's tool descriptions and SDK response types. The contract is fixed for both local stdio and hosted HTTP, including retries. Your key, OAuth identity and team's saved default stay the same.
51
51
 
52
- Published MCP/SDK `0.3.2` matches API `1.0.0`. This source tree's tool descriptions and SDK dependency expect API `2.0.0`; use a matching MCP release before changing the team's version. Test in a separate development team first; the change applies to all of the production team's integrations. The API returns the selected contract, so an upgrade can change the fields an agent receives. There is no version argument to add to tool calls. See [API versions and migration](https://parseapi.com/docs/versioning).
52
+ For local stdio, pin the MCP package version in your application configuration and test the new release before deploying it. A future major MCP upgrade can select a newer API contract. There is no version argument to add to individual tool calls. The hosted service uses the API contract supported by its deployed MCP release.
53
+
54
+ Previously published MCP packages keep their existing behavior and use the team's default. Keep that default unchanged while older applications depend on it. Rolling back to a package without a version header restores the team default, so rollback only restores the old contract when that default has stayed unchanged. See [API versions and migration](https://parseapi.com/docs/versioning).
53
55
 
54
56
  ## Tools
55
57
 
@@ -85,6 +87,18 @@ Ordinary lookups retry up to twice after a transient failure. Metered lookups an
85
87
 
86
88
  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`.
87
89
 
90
+ ## Display language
91
+
92
+ This source candidate adds optional `lang` to supported tools. For example,
93
+ `country` accepts `{"code":"DE","lang":"fr"}`. It requires a matching API
94
+ localization release, data, and JS SDK package; installing the existing published
95
+ package does not activate it.
96
+
97
+ Display names follow available source translations. IDs, native-name fields,
98
+ numbers and input parsing stay unchanged. Omitted language keeps the default
99
+ behavior. Measure parsing, currency rates, Holiday and prove tools have no new
100
+ language argument.
101
+
88
102
  ## Measurements
89
103
 
90
104
  Call `measure` with `{ "measure": "5 ft 11 in", "to": "cm" }`. The result keeps the amount as the decimal string `"180.34"`. Without `to`, the result uses the canonical unit for its type. Optional `locale` and `system` (`us` or `imperial`) resolve explicit number or customary-unit ambiguity.
@@ -110,4 +124,4 @@ MIT licensed.
110
124
 
111
125
  Start with the default tool call. Use the same tool with `deep: true` for richer facts. Time, Date, Currency, Language, Emoji, Phone, IBAN and Point include detail on every plan. Geographic profiles, Name evidence and NAICS definitions require a paid plan. Carrier and HLR detail stays inside the same metered core unit, including Free allowance units, with no additional charge or second gate.
112
126
 
113
- Search detail belongs to each returned entity. Time conversion puts target display detail in `to.deep`; only the source returns `deep.next_dst`. Name core parsing needs no dictionary lookup. Country, State and Postal tax references are in their paid deep bags.
127
+ Search detail belongs to each returned entity. Time conversion puts target display detail in `to.deep`; only the source returns `deep.next_dst`. Name core parsing needs no dictionary lookup. Paid Name deep also returns flat `short`, `directory`, and `initials`. Optional `name_locale` selects CLDR formatting rules, defaults to `en`, and leaves parsing and gender context unchanged. Unavailable formatting is null, and older responses may omit these fields. Country, State and Postal tax references are in their paid deep bags.
@@ -34,12 +34,46 @@ function noKeyResult(transport) {
34
34
  }
35
35
 
36
36
  // src/registry.ts
37
- var VERSION = "0.4.0";
37
+ var VERSION = "1.0.0";
38
+ var API_VERSION = "2.0.0";
38
39
  var deep = z.boolean().optional().describe("Include the nested deep object when available. Pricing depends on the operation.");
39
40
  var lat = z.number().min(-90).max(90).describe("Latitude in decimal degrees");
40
41
  var lon = z.number().min(-180).max(180).describe("Longitude in decimal degrees");
41
42
  var iso2 = (what) => z.string().describe(`ISO 3166-1 alpha-2 ${what}, e.g. US`);
42
43
  var countryOpt = z.string().optional().describe("ISO2, ISO3, or a country name. Optional when the lookup is unique.");
44
+ var languageTools = /* @__PURE__ */ new Set([
45
+ "ip",
46
+ "ip_self",
47
+ "asn",
48
+ "company",
49
+ "npi",
50
+ "continent",
51
+ "continent_countries",
52
+ "bloc_countries",
53
+ "country",
54
+ "country_states",
55
+ "state",
56
+ "state_districts",
57
+ "district",
58
+ "city",
59
+ "city_id",
60
+ "city_search",
61
+ "city_nearest",
62
+ "city_nearby",
63
+ "postal",
64
+ "postal_nearby",
65
+ "postal_distance",
66
+ "currency",
67
+ "language",
68
+ "date",
69
+ "time",
70
+ "timezone",
71
+ "measure_units",
72
+ "emoji",
73
+ "emoji_search",
74
+ "point"
75
+ ]);
76
+ var displayLanguage = z.string().min(2).max(64).optional().describe("Optional display language, such as fr or zh-Hant. IDs, numeric values and input parsing stay unchanged.");
43
77
  function buildServer(key, transport) {
44
78
  const server = new McpServer(
45
79
  {
@@ -51,19 +85,33 @@ function buildServer(key, transport) {
51
85
  },
52
86
  { capabilities: { tools: {} } }
53
87
  );
54
- const parse = key ? parseAPI(key) : null;
88
+ const parse = key ? parseAPI(key, {
89
+ // Tool descriptions and responses share this contract on both transports.
90
+ fetch: (input, init) => {
91
+ const headers = new Headers(init?.headers);
92
+ headers.set("Parse-Version", API_VERSION);
93
+ return fetch(input, { ...init, headers });
94
+ }
95
+ }) : null;
55
96
  function tool(name, description, shape, fn, refine) {
97
+ const localized = languageTools.has(name);
98
+ const input = z.object(localized ? { ...shape, lang: displayLanguage } : shape);
56
99
  server.registerTool(
57
100
  name,
58
101
  {
59
102
  description,
60
- inputSchema: refine ? refine(z.object(shape)) : z.object(shape),
103
+ inputSchema: refine ? refine(input) : input,
61
104
  annotations: { readOnlyHint: true }
62
105
  },
63
106
  async (args, context) => {
64
107
  if (!parse) return noKeyResult(transport);
65
108
  try {
66
- return ok(await fn(parse, args, { signal: context.mcpReq.signal }));
109
+ const requested = args.lang;
110
+ const request = {
111
+ signal: context.mcpReq.signal,
112
+ ...localized && typeof requested === "string" ? { lang: requested } : {}
113
+ };
114
+ return ok(await fn(parse, args, request));
67
115
  } catch (err) {
68
116
  return toErrorResult(err);
69
117
  }
@@ -107,7 +155,7 @@ function buildServer(key, transport) {
107
155
  }
108
156
  tool(
109
157
  "continent",
110
- "Look up a continent by code: name, area, population and population_period. The period is a reporting year or range, null when unknown or unverifiable.",
158
+ "Look up a continent by code: name, area and population.",
111
159
  { code: z.string().describe("Continent code: AF, AN, AS, EU, NA, OC, SA") },
112
160
  (c, a, request) => c.continent(a.code, request)
113
161
  );
@@ -135,7 +183,7 @@ function buildServer(key, transport) {
135
183
  );
136
184
  tool(
137
185
  "country",
138
- "Country names, language codes, currency, calling code and timezones. Deep adds the country reference profile, including population with its reporting period, tax and locale conventions, on paid plans.",
186
+ "Country names, language codes, currency, calling code and timezones. Deep adds the country reference profile on paid plans, including population with its reporting period, land/water area in km2, coastline in km, mean and extreme elevations in metres, tax and locale conventions. Unknown geography values stay null.",
139
187
  { code: iso2("country code"), deep: deep.describe("Include the complete detail bag on a paid plan.") },
140
188
  (c, a, request) => c.country(a.code, { ...request, deep: a.deep })
141
189
  );
@@ -324,7 +372,7 @@ function buildServer(key, transport) {
324
372
  );
325
373
  tool(
326
374
  "email",
327
- "Validate an email address: syntax, domain, MX, disposable, role, and a typo suggestion when the host looks misspelled. Deep returns mailbox deliverability and catch-all results, reusing a recent verification when available.",
375
+ "Validate an email address: syntax, domain, MX, consumer mailbox, disposable, role, reserved domain type, and a typo suggestion when the host looks misspelled. Deep returns mailbox deliverability and catch-all results, reusing a recent verification when available.",
328
376
  { email: z.string().describe("Email address to validate"), deep },
329
377
  (c, a, request) => c.email(a.email, { ...request, deep: a.deep })
330
378
  );
@@ -341,7 +389,7 @@ function buildServer(key, transport) {
341
389
  );
342
390
  tool(
343
391
  "iban",
344
- "Parse an IBAN and check its format and checksum, with known bank identifiers. Deep adds check digits, branch and account decomposition on every plan. Does not verify an account exists.",
392
+ "Parse an IBAN and check its format, ISO checksum, and published national BBAN checks, with known bank identifiers. Deep adds check digits, branch and account decomposition on every plan. Does not verify an account exists.",
345
393
  {
346
394
  iban: z.string().describe("IBAN, with or without spaces, with or without the country prefix"),
347
395
  country: iso2("country code when the number has no prefix").optional(),
@@ -351,7 +399,7 @@ function buildServer(key, transport) {
351
399
  );
352
400
  tool(
353
401
  "bin",
354
- "Look up a 6-11 digit payment-card prefix. Returns the actual longest matched prefix, issuer, country, brand, card type and prepaid status where known. Unknown fields are null. Does not confirm a card or account exists. Pooled request on every plan.",
402
+ "Look up a 6-11 digit payment-card prefix. Returns the actual longest matched prefix, issuer, country, brand key, brand name, card type and prepaid status where known. Unknown fields are null. Does not confirm a card or account exists. Pooled request on every plan.",
355
403
  {
356
404
  bin: z.string().describe("Card prefix as a string, 6-11 digits. Preserve leading zeros. Spaces and hyphens are accepted."),
357
405
  deep: z.boolean().optional().describe("Include an empty deep object. No extra fields or separate charge.")
@@ -510,13 +558,14 @@ function buildServer(key, transport) {
510
558
  );
511
559
  tool(
512
560
  "name",
513
- "Parse a name into prefix, first, middle, last and suffix. Paid deep adds dictionary membership, gender evidence, salutation and country associations. Country scopes evidence, never nationality. Junk returns valid false.",
561
+ "Parse a name into prefix, first, middle, last and suffix. Paid deep adds gender evidence, salutation, short and directory formats, and initials. Country scopes gender evidence. name_locale selects formatting rules. Junk returns valid false.",
514
562
  {
515
563
  name: z.string().describe("The name to parse, e.g. Smith, John or BILLY OSHALL"),
516
564
  country: z.string().optional().describe("ISO2 country context for gender, e.g. IT"),
565
+ name_locale: z.string().min(2).max(64).optional().describe("Name-formatting locale, e.g. en or ja. Defaults to en. Changes formatting only, not parsing or gender evidence."),
517
566
  deep: deep.describe("Include the complete detail bag on a paid plan.")
518
567
  },
519
- (c, a, request) => c.name(a.name, { ...request, deep: a.deep, country: a.country })
568
+ (c, a, request) => c.name(a.name, { ...request, deep: a.deep, country: a.country, name_locale: a.name_locale })
520
569
  );
521
570
  tool(
522
571
  "time",
package/dist/http.js CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import {
3
3
  buildServer
4
- } from "./chunk-M5FQI2AW.js";
4
+ } from "./chunk-CKX2OGWN.js";
5
5
 
6
6
  // src/http.ts
7
7
  import { createServer } from "http";
package/dist/registry.js CHANGED
@@ -2,7 +2,7 @@
2
2
  import {
3
3
  VERSION,
4
4
  buildServer
5
- } from "./chunk-M5FQI2AW.js";
5
+ } from "./chunk-CKX2OGWN.js";
6
6
  export {
7
7
  VERSION,
8
8
  buildServer
package/dist/stdio.js CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import {
3
3
  buildServer
4
- } from "./chunk-M5FQI2AW.js";
4
+ } from "./chunk-CKX2OGWN.js";
5
5
 
6
6
  // src/stdio.ts
7
7
  import { serveStdio } from "@modelcontextprotocol/server/stdio";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "parseapi-mcp",
3
- "version": "0.4.0",
3
+ "version": "1.0.0",
4
4
  "mcpName": "com.parseapi/mcp",
5
5
  "description": "Official ParseAPI MCP server. Look up places, addresses, company numbers, email, phone, weather, dates and more.",
6
6
  "keywords": [
@@ -47,7 +47,7 @@
47
47
  "dependencies": {
48
48
  "@modelcontextprotocol/server": "^2.0.0",
49
49
  "@modelcontextprotocol/node": "^2.0.0",
50
- "@parseapi/sdk": "^0.4.0",
50
+ "@parseapi/sdk": "^1.0.0",
51
51
  "zod": "^4.0.0"
52
52
  },
53
53
  "devDependencies": {