parseapi-mcp 1.0.0 → 1.1.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 +49 -3
- package/dist/chunk-RXWXHORG.js +1016 -0
- package/dist/http.js +5 -3
- package/dist/registry.js +1 -1
- package/dist/stdio.js +5 -3
- package/package.json +5 -2
- package/dist/chunk-CKX2OGWN.js +0 -668
|
@@ -0,0 +1,1016 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
// src/registry.ts
|
|
4
|
+
import { McpServer } from "@modelcontextprotocol/server";
|
|
5
|
+
import { parseAPI } from "@parseapi/sdk";
|
|
6
|
+
import * as z3 from "zod";
|
|
7
|
+
|
|
8
|
+
// src/errors.ts
|
|
9
|
+
import { ParseAPIError } from "@parseapi/sdk";
|
|
10
|
+
function ok(data) {
|
|
11
|
+
return { content: [{ type: "text", text: JSON.stringify(data) }] };
|
|
12
|
+
}
|
|
13
|
+
function errorJson(code, message, docs, requestId) {
|
|
14
|
+
return {
|
|
15
|
+
isError: true,
|
|
16
|
+
content: [{ type: "text", text: JSON.stringify({ code, message, docs, request_id: requestId }) }]
|
|
17
|
+
};
|
|
18
|
+
}
|
|
19
|
+
function toErrorResult(err) {
|
|
20
|
+
if (err instanceof ParseAPIError) {
|
|
21
|
+
return errorJson(err.code, err.message, err.docs, err.requestId);
|
|
22
|
+
}
|
|
23
|
+
const message = err instanceof Error ? err.message : String(err);
|
|
24
|
+
return errorJson("network_error", message, null, null);
|
|
25
|
+
}
|
|
26
|
+
function noKeyResult(transport) {
|
|
27
|
+
const where = transport === "stdio" ? "set it as the PARSEAPI_KEY environment variable for this MCP server" : "send it in the X-API-Key header";
|
|
28
|
+
return errorJson(
|
|
29
|
+
"invalid_api_key",
|
|
30
|
+
`No API key. Get a free key at https://parseapi.com and ${where}.`,
|
|
31
|
+
"https://parseapi.com/docs#invalid_api_key",
|
|
32
|
+
null
|
|
33
|
+
);
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
// src/discovery.ts
|
|
37
|
+
import * as z from "zod";
|
|
38
|
+
|
|
39
|
+
// src/agent-catalog.json
|
|
40
|
+
var agent_catalog_default = {
|
|
41
|
+
schema_version: "1.0.0",
|
|
42
|
+
api_version: "2.0.0",
|
|
43
|
+
operations: {
|
|
44
|
+
email: {
|
|
45
|
+
operation: "email",
|
|
46
|
+
endpoint: "GET /email/{email}",
|
|
47
|
+
determines: ["Email syntax and domain mail routing", "Consumer, disposable and role-address classifications", "With deep=true, a mailbox deliverability observation"],
|
|
48
|
+
does_not_determine: ["Recipient identity, consent or ownership", "Guaranteed delivery to an inbox", "A new mailbox probe on every request"],
|
|
49
|
+
required_context: ["email: a complete email address", "deep=true only when a mailbox check is needed"],
|
|
50
|
+
freshness: {
|
|
51
|
+
mode: "observation_reuse",
|
|
52
|
+
mail_routing: { mode: "dns_ttl", positive_cache_max_seconds: 3600, negative_cache_max_seconds: 300, shorter_dns_ttl_wins: true, stale_if_error: false },
|
|
53
|
+
mailbox_corpus_reuse_max_seconds: { deliverable: 604800, catchall: 2592e3, undeliverable: 7776e3 },
|
|
54
|
+
mailbox_response_cache_ttl_seconds: 86400,
|
|
55
|
+
mailbox_local_cache_ttl_seconds: 3600,
|
|
56
|
+
effective_max_age_seconds: null,
|
|
57
|
+
effective_max_age_status: "not_guaranteed; response-cache refreshes can retain a verdict beyond corpus reuse windows",
|
|
58
|
+
actual_age_seconds: null,
|
|
59
|
+
actual_age_status: "not_exposed"
|
|
60
|
+
},
|
|
61
|
+
uncertainty: {
|
|
62
|
+
valid: { true: "Syntax is valid; this does not establish mailbox existence", false: "Syntax is invalid" },
|
|
63
|
+
domain_valid: { true: "MX or permitted A/AAAA fallback supplies a mail route", false: "When valid=true, no usable mail route, including an explicit null MX. When valid=false, routing was not checked" },
|
|
64
|
+
domain_type: { null: "No supported reserved namespace classification" },
|
|
65
|
+
"deep.deliverable": { true: "Mailbox likely exists", false: "Negative verification, eligible local disposable/no-route rejection, or invalid syntax that skipped verification; check valid first", null: "Mailbox check did not complete; no verification unit is charged" },
|
|
66
|
+
"deep.catchall": { true: "Domain accepts all addresses; an individual mailbox is not established", false: "Not classified as catchall, including invalid input and local rejection where no mailbox probe ran", null: "Mailbox check did not complete" },
|
|
67
|
+
deep: { omitted: "Not requested", empty_object: "Requested with an app key; mailbox verification is locked" }
|
|
68
|
+
},
|
|
69
|
+
billing: {
|
|
70
|
+
pooled_requests_per_success: 1,
|
|
71
|
+
metered: { name: "email", when: "deep=true and a valid-syntax eligible check completes", units_per_completed_check: 1, cache_hits_bill_units: true, incomplete_check_units: 0, eligible_local_negative_check_units: 1, invalid_syntax_check_units: 0, locked_deep_check_units: 0 },
|
|
72
|
+
monetary_quote: null,
|
|
73
|
+
account_state: "unknown; included balance, on-demand access, accepted rates and spend cap require account state"
|
|
74
|
+
},
|
|
75
|
+
access: {
|
|
76
|
+
api_key_required: true,
|
|
77
|
+
key_types: ["secret", "public", "app"],
|
|
78
|
+
key_fences: { public: "Allowed browser origin required", app: "Allowed X-App-Id required" },
|
|
79
|
+
deep: { secret_or_public: "Uses available included verifications or enabled on-demand allowance, including on Free", app: "Locked; returns deep: {} without a verification", restricted_demo_key: "Metered deep is denied" },
|
|
80
|
+
effective_access: null,
|
|
81
|
+
effective_access_status: "not_checked; key fences, account access, quotas and spending controls still apply"
|
|
82
|
+
},
|
|
83
|
+
retry: {
|
|
84
|
+
client: "javascript_sdk_and_mcp",
|
|
85
|
+
default_retries: 2,
|
|
86
|
+
deep_default_retries: 0,
|
|
87
|
+
retry_http_statuses: [429, 500, 502, 503, 504],
|
|
88
|
+
retry_network_errors: true,
|
|
89
|
+
successful_unknown_retried: false,
|
|
90
|
+
guidance: "Do not infer a retry from null. Repeated completed deep checks consume additional verification units; a transport failure does not prove the previous attempt was unbilled. DNS failures can return 503 before mailbox verification."
|
|
91
|
+
},
|
|
92
|
+
docs: { help: "https://api.parseapi.com/version/2.0.0/email/help", guide: "https://parseapi.com/docs/email" }
|
|
93
|
+
},
|
|
94
|
+
domain: {
|
|
95
|
+
operation: "domain",
|
|
96
|
+
endpoint: "GET /domain/{domain}",
|
|
97
|
+
determines: ["Registry registration status", "With entitled deep=true, available registration details"],
|
|
98
|
+
does_not_determine: ["Whether a registrar will sell an unregistered domain", "DNS routing or mailbox deliverability", "A live registry query on every request"],
|
|
99
|
+
required_context: ["domain: a hostname rather than a URL or email address"],
|
|
100
|
+
freshness: {
|
|
101
|
+
mode: "observation_reuse",
|
|
102
|
+
reuse_max_seconds: { registered: 3600, unregistered: 300 },
|
|
103
|
+
stale_if_error: false,
|
|
104
|
+
actual_age_seconds: null,
|
|
105
|
+
actual_age_status: "not_exposed"
|
|
106
|
+
},
|
|
107
|
+
uncertainty: {
|
|
108
|
+
available: { true: "Registry reported unregistered", false: "Registry reported registered", null: "No usable current registry observation; availability is unknown" },
|
|
109
|
+
deep: { omitted: "Not requested", empty_object: "Plan does not unlock registration details, or registration is unavailable" },
|
|
110
|
+
"deep.registration": { omitted: "No entitled, usable registration observation" }
|
|
111
|
+
},
|
|
112
|
+
billing: { pooled_requests_per_success: 1, metered: null, deep_extra_units: 0, monetary_quote: null, account_state: "unknown; pooled allowance and accepted account terms are not checked" },
|
|
113
|
+
access: {
|
|
114
|
+
api_key_required: true,
|
|
115
|
+
key_types: ["secret", "public", "app"],
|
|
116
|
+
key_fences: { public: "Allowed browser origin required", app: "Allowed X-App-Id required" },
|
|
117
|
+
deep: { entitlement: "Paid plan; app keys retain plan-deep access", locked: "Returns deep: {}" },
|
|
118
|
+
effective_access: null,
|
|
119
|
+
effective_access_status: "not_checked; key fences, account access and quotas still apply"
|
|
120
|
+
},
|
|
121
|
+
retry: {
|
|
122
|
+
client: "javascript_sdk_and_mcp",
|
|
123
|
+
default_retries: 2,
|
|
124
|
+
retry_http_statuses: [429, 500, 502, 503, 504],
|
|
125
|
+
retry_network_errors: true,
|
|
126
|
+
successful_unknown_retried: false,
|
|
127
|
+
guidance: "available=null is a completed HTTP response with an unknown fact, not evidence the domain is free. Do not retry automatically from null; respect rate and quota errors."
|
|
128
|
+
},
|
|
129
|
+
docs: { help: "https://api.parseapi.com/version/2.0.0/domain/help", guide: "https://parseapi.com/docs/domain" }
|
|
130
|
+
},
|
|
131
|
+
dns: {
|
|
132
|
+
operation: "dns",
|
|
133
|
+
endpoint: "GET /dns/{domain}",
|
|
134
|
+
determines: ["Published answer records from a recursive DNS view", "Each returned record's remaining TTL"],
|
|
135
|
+
does_not_determine: ["Global propagation or a zone transfer", "Domain registration availability", "Whether a CNAME destination works"],
|
|
136
|
+
required_context: ["domain: a DNS name, including supported underscore or reverse names", "type: one supported record type, or omit for all ten supported types"],
|
|
137
|
+
freshness: {
|
|
138
|
+
mode: "dns_ttl",
|
|
139
|
+
positive_cache_max_seconds: 3600,
|
|
140
|
+
negative_cache_max_seconds: 300,
|
|
141
|
+
shorter_dns_ttl_wins: true,
|
|
142
|
+
stale_if_error: false,
|
|
143
|
+
remaining_ttl_field: "records[].ttl",
|
|
144
|
+
zero_ttl_reusable: false,
|
|
145
|
+
actual_age_seconds: null,
|
|
146
|
+
actual_age_status: "not_exposed; remaining TTL is exposed"
|
|
147
|
+
},
|
|
148
|
+
uncertainty: {
|
|
149
|
+
records: { empty_array: "Successful lookup with no answer records of the requested types", failure: "A failed type returns an error, never an empty or silently partial result" },
|
|
150
|
+
"records[].value": { "MX 0 .": "Explicit null MX; this domain declines mail", CNAME: "Published alias; its target may not exist" },
|
|
151
|
+
http_status: { "404": "DNS name does not exist", "503": "Temporary DNS failure; no negative verdict" },
|
|
152
|
+
deep: { omitted: "Not requested", empty_object: "Requested; this product has no additional deep fields" }
|
|
153
|
+
},
|
|
154
|
+
billing: { pooled_requests_per_success: 1, metered: null, deep_extra_units: 0, all_record_types_extra_units: 0, monetary_quote: null, account_state: "unknown; pooled allowance and accepted account terms are not checked" },
|
|
155
|
+
access: {
|
|
156
|
+
api_key_required: true,
|
|
157
|
+
key_types: ["secret", "public", "app"],
|
|
158
|
+
key_fences: { public: "Allowed browser origin required", app: "Allowed X-App-Id required" },
|
|
159
|
+
deep: { entitlement: "All records are core on every plan", requested: "Returns deep: {}" },
|
|
160
|
+
effective_access: null,
|
|
161
|
+
effective_access_status: "not_checked; key fences, account access and quotas still apply"
|
|
162
|
+
},
|
|
163
|
+
retry: {
|
|
164
|
+
client: "javascript_sdk_and_mcp",
|
|
165
|
+
default_retries: 2,
|
|
166
|
+
retry_http_statuses: [429, 500, 502, 503, 504],
|
|
167
|
+
retry_network_errors: true,
|
|
168
|
+
successful_unknown_retried: false,
|
|
169
|
+
guidance: "An empty records array and a DNS-name 404 are negative answers, not transient failures. Reuse records only within their remaining TTL; respect rate and quota errors."
|
|
170
|
+
},
|
|
171
|
+
docs: { help: "https://api.parseapi.com/version/2.0.0/dns/help", guide: "https://parseapi.com/docs/dns" }
|
|
172
|
+
},
|
|
173
|
+
mx: {
|
|
174
|
+
operation: "mx",
|
|
175
|
+
endpoint: "GET /mx/{domain}",
|
|
176
|
+
determines: ["Published MX hosts sorted by priority and host", "An explicit null MX that declines mail"],
|
|
177
|
+
does_not_determine: ["Mailbox deliverability", "No mail route from an empty MX list alone", "Domain registration availability"],
|
|
178
|
+
required_context: ["domain: a hostname rather than a URL or email address"],
|
|
179
|
+
freshness: {
|
|
180
|
+
mode: "dns_ttl",
|
|
181
|
+
positive_cache_max_seconds: 3600,
|
|
182
|
+
negative_cache_max_seconds: 300,
|
|
183
|
+
shorter_dns_ttl_wins: true,
|
|
184
|
+
stale_if_error: false,
|
|
185
|
+
actual_age_seconds: null,
|
|
186
|
+
actual_age_status: "not_exposed; use dns with type=MX for remaining record TTLs"
|
|
187
|
+
},
|
|
188
|
+
uncertainty: {
|
|
189
|
+
mx: { empty_array: "No MX records; A/AAAA mail fallback may still apply", null_mx: '[{priority: 0, host: "."}] explicitly declines mail' },
|
|
190
|
+
http_status: { "503": "Temporary DNS failure; no negative verdict" },
|
|
191
|
+
deep: { omitted: "This product has no deep response fields" }
|
|
192
|
+
},
|
|
193
|
+
billing: { pooled_requests_per_success: 1, metered: null, monetary_quote: null, account_state: "unknown; pooled allowance and accepted account terms are not checked" },
|
|
194
|
+
access: {
|
|
195
|
+
api_key_required: true,
|
|
196
|
+
key_types: ["secret", "public", "app"],
|
|
197
|
+
key_fences: { public: "Allowed browser origin required", app: "Allowed X-App-Id required" },
|
|
198
|
+
deep: { entitlement: "All MX records are core on every plan" },
|
|
199
|
+
effective_access: null,
|
|
200
|
+
effective_access_status: "not_checked; key fences, account access and quotas still apply"
|
|
201
|
+
},
|
|
202
|
+
retry: {
|
|
203
|
+
client: "javascript_sdk_and_mcp",
|
|
204
|
+
default_retries: 2,
|
|
205
|
+
retry_http_statuses: [429, 500, 502, 503, 504],
|
|
206
|
+
retry_network_errors: true,
|
|
207
|
+
successful_unknown_retried: false,
|
|
208
|
+
guidance: "Do not retry solely because mx is empty. Use email for mail-route validation or dns for explicit A/AAAA records; respect rate and quota errors."
|
|
209
|
+
},
|
|
210
|
+
docs: { help: "https://api.parseapi.com/version/2.0.0/mx/help", guide: "https://parseapi.com/docs/mx" }
|
|
211
|
+
},
|
|
212
|
+
country: {
|
|
213
|
+
operation: "country",
|
|
214
|
+
endpoint: "GET /country/{code}",
|
|
215
|
+
determines: ["Country reference information by ISO2, ISO3 or name", "With entitled deep=true, geography, population and national reference attributes"],
|
|
216
|
+
does_not_determine: ["A live census or uniform observation date for every field", "Tax due on a particular transaction", "Missing facts by inference"],
|
|
217
|
+
required_context: ["code: ISO2, ISO3 or a country name", "deep=true for profile fields such as population and area"],
|
|
218
|
+
freshness: {
|
|
219
|
+
mode: "maintained_reference",
|
|
220
|
+
population_period_field: "deep.population_period",
|
|
221
|
+
uniform_refresh_interval_seconds: null,
|
|
222
|
+
actual_age_seconds: null,
|
|
223
|
+
actual_age_status: "not_exposed; population period describes that statistic only"
|
|
224
|
+
},
|
|
225
|
+
uncertainty: {
|
|
226
|
+
name_local: { null: "Native name unavailable or identical to the original name before display translation" },
|
|
227
|
+
"deep.population_period": { null: "Observation period is unknown; never infer it from an import date" },
|
|
228
|
+
"deep.water_area": { null: "Unknown or inconsistent with the archived total", zero: "Reported zero water area" },
|
|
229
|
+
"deep.coastline": { null: "Unknown", zero: "Reported landlocked coastline" },
|
|
230
|
+
"deep.tax": { null: "No national consumption levy is named; local levies may still apply" },
|
|
231
|
+
"deep.tax_rate": { null: "Unavailable or no national levy applies", zero: "Known zero national reference rate" },
|
|
232
|
+
deep: { omitted: "Not requested", empty_object: "Requested but the plan does not unlock the profile" }
|
|
233
|
+
},
|
|
234
|
+
billing: { pooled_requests_per_success: 1, metered: null, deep_extra_units: 0, monetary_quote: null, account_state: "unknown; pooled allowance and accepted account terms are not checked" },
|
|
235
|
+
access: {
|
|
236
|
+
api_key_required: true,
|
|
237
|
+
key_types: ["secret", "public", "app"],
|
|
238
|
+
key_fences: { public: "Allowed browser origin required", app: "Allowed X-App-Id required" },
|
|
239
|
+
deep: { entitlement: "Paid plan; app keys retain plan-deep access", locked: "Returns deep: {}" },
|
|
240
|
+
effective_access: null,
|
|
241
|
+
effective_access_status: "not_checked; key fences, account access and quotas still apply"
|
|
242
|
+
},
|
|
243
|
+
retry: {
|
|
244
|
+
client: "javascript_sdk_and_mcp",
|
|
245
|
+
default_retries: 2,
|
|
246
|
+
retry_http_statuses: [429, 500, 502, 503, 504],
|
|
247
|
+
retry_network_errors: true,
|
|
248
|
+
successful_unknown_retried: false,
|
|
249
|
+
guidance: "Do not retry to fill null reference fields or a locked deep object. Preserve unknowns and distinguish reported zero from null; respect rate and quota errors."
|
|
250
|
+
},
|
|
251
|
+
docs: { help: "https://api.parseapi.com/version/2.0.0/country/help", guide: "https://parseapi.com/docs/country" }
|
|
252
|
+
}
|
|
253
|
+
}
|
|
254
|
+
};
|
|
255
|
+
|
|
256
|
+
// src/discovery.ts
|
|
257
|
+
function catalogMode(value) {
|
|
258
|
+
if (value === void 0 || value === "full") return "full";
|
|
259
|
+
if (value === "compact") return "compact";
|
|
260
|
+
throw new Error("PARSEAPI_MCP_MODE must be full or compact");
|
|
261
|
+
}
|
|
262
|
+
var policies = agent_catalog_default.operations;
|
|
263
|
+
var object2 = z.record(z.string(), z.unknown());
|
|
264
|
+
var discoveryOutput = z.object({
|
|
265
|
+
schema_version: z.string(),
|
|
266
|
+
api_version: z.string(),
|
|
267
|
+
total_operations: z.number().int(),
|
|
268
|
+
policy_operations: z.array(z.string()),
|
|
269
|
+
effective_access: z.literal("not_evaluated"),
|
|
270
|
+
pricing: z.literal("not_quoted"),
|
|
271
|
+
total_matches: z.number().int(),
|
|
272
|
+
next_offset: z.number().int().nullable(),
|
|
273
|
+
operations: z.array(z.object({
|
|
274
|
+
name: z.string(),
|
|
275
|
+
description: z.string(),
|
|
276
|
+
policy_available: z.boolean(),
|
|
277
|
+
inputSchema: object2.optional(),
|
|
278
|
+
policy: object2.nullable().optional()
|
|
279
|
+
}))
|
|
280
|
+
});
|
|
281
|
+
function invalid(message) {
|
|
282
|
+
return { ...ok({ code: "invalid_request", message, docs: "https://parseapi.com/mcp", request_id: null }), isError: true };
|
|
283
|
+
}
|
|
284
|
+
function registerDiscovery(server, operations, mode, apiVersion) {
|
|
285
|
+
if (agent_catalog_default.api_version !== apiVersion) throw new Error("Agent catalog does not match the MCP API contract");
|
|
286
|
+
const all = [...operations.values()].sort((a, b) => a.name.localeCompare(b.name));
|
|
287
|
+
const reviewed = Object.keys(policies).filter((name) => operations.has(name)).sort();
|
|
288
|
+
server.registerTool("discover", {
|
|
289
|
+
description: "Find ParseAPI operations by keyword, or describe one by its exact name. Returns inputs and reviewed capability, freshness, uncertainty, billing and access policies. Metadata only, no API request or usage charge. Use preflight for effective credential permissions and account-specific cost estimates. Use operation to get full detail before lookup.",
|
|
290
|
+
inputSchema: z.object({
|
|
291
|
+
query: z.string().trim().min(1).max(256).optional().describe("Keywords such as mailbox, DNS, or population"),
|
|
292
|
+
operation: z.string().min(1).max(64).optional().describe("Exact operation name for its input schema and policy"),
|
|
293
|
+
detail: z.enum(["summary", "full"]).optional().describe("Defaults to full for one operation, summary for search"),
|
|
294
|
+
limit: z.number().int().min(1).max(20).default(5),
|
|
295
|
+
offset: z.number().int().min(0).max(1e3).default(0)
|
|
296
|
+
}).refine((args) => args.operation === void 0 || args.query === void 0 && args.offset === 0, {
|
|
297
|
+
message: "Use operation by itself, or query and offset to browse."
|
|
298
|
+
}),
|
|
299
|
+
outputSchema: discoveryOutput,
|
|
300
|
+
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
|
|
301
|
+
}, async (args) => {
|
|
302
|
+
if (args.operation && !operations.has(args.operation)) return invalid("Unknown operation. Use discover with query to find an available operation.");
|
|
303
|
+
const tokens = [...new Set(args.query?.toLowerCase().match(/[\p{L}\p{N}_]+/gu) ?? [])];
|
|
304
|
+
const matches = args.operation ? [operations.get(args.operation)] : all.map((operation) => {
|
|
305
|
+
const text = `${operation.name} ${operation.description} ${JSON.stringify(policies[operation.name] ?? {})}`.toLowerCase();
|
|
306
|
+
const score = tokens.reduce((sum, token) => sum + (operation.name === token ? 10 : text.includes(token) ? 1 : 0), 0);
|
|
307
|
+
return { operation, score };
|
|
308
|
+
}).filter((item) => !args.query || tokens.length > 0 && item.score > 0).sort((a, b) => b.score - a.score || a.operation.name.localeCompare(b.operation.name)).map((item) => item.operation);
|
|
309
|
+
const full = (args.detail ?? (args.operation ? "full" : "summary")) === "full";
|
|
310
|
+
const selected = matches.slice(args.offset, args.offset + args.limit);
|
|
311
|
+
const data = {
|
|
312
|
+
schema_version: agent_catalog_default.schema_version,
|
|
313
|
+
api_version: agent_catalog_default.api_version,
|
|
314
|
+
total_operations: all.length,
|
|
315
|
+
policy_operations: reviewed,
|
|
316
|
+
effective_access: "not_evaluated",
|
|
317
|
+
pricing: "not_quoted",
|
|
318
|
+
total_matches: matches.length,
|
|
319
|
+
next_offset: args.offset + selected.length < matches.length ? args.offset + selected.length : null,
|
|
320
|
+
operations: selected.map((operation) => ({
|
|
321
|
+
name: operation.name,
|
|
322
|
+
description: operation.description,
|
|
323
|
+
policy_available: Object.hasOwn(policies, operation.name),
|
|
324
|
+
...full ? {
|
|
325
|
+
inputSchema: z.toJSONSchema(operation.schema, { io: "input" }),
|
|
326
|
+
policy: policies[operation.name] ?? null
|
|
327
|
+
} : {}
|
|
328
|
+
}))
|
|
329
|
+
};
|
|
330
|
+
return { ...ok(data), structuredContent: data };
|
|
331
|
+
});
|
|
332
|
+
if (mode !== "compact") return;
|
|
333
|
+
server.registerTool("lookup", {
|
|
334
|
+
description: "Run one ParseAPI operation found with discover. Pass its exact name and arguments. Uses the same validation, API 2.0.0 contract, credentials and billing as the named lookup. Reads can consume pooled or paid units. Ordinary lookups can retry twice, metered checks default to no retries.",
|
|
335
|
+
inputSchema: z.object({ operation: z.string().min(1).max(64), arguments: object2 }),
|
|
336
|
+
annotations: { readOnlyHint: true, idempotentHint: false }
|
|
337
|
+
}, async (args, context) => {
|
|
338
|
+
const operation = operations.get(args.operation);
|
|
339
|
+
if (!operation) return invalid("Unknown operation. Use discover to find an available lookup.");
|
|
340
|
+
const parsed = await operation.schema.safeParseAsync(args.arguments);
|
|
341
|
+
if (!parsed.success) return invalid(parsed.error.issues.map((issue) => `${issue.path.join(".") || "arguments"}: ${issue.message}`).join("; "));
|
|
342
|
+
return operation.invoke(parsed.data, context.mcpReq.signal);
|
|
343
|
+
});
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
// src/preflight.ts
|
|
347
|
+
import * as z2 from "zod";
|
|
348
|
+
var task = z2.strictObject({
|
|
349
|
+
operations: z2.array(z2.strictObject({
|
|
350
|
+
operation: z2.enum(["email", "domain", "dns", "mx", "country"]),
|
|
351
|
+
count: z2.number().int().min(1).max(1e5),
|
|
352
|
+
deep: z2.boolean().optional()
|
|
353
|
+
})).min(1).max(20).refine((items) => items.reduce((sum, item) => sum + item.count, 0) <= 1e5, {
|
|
354
|
+
message: "The task can contain at most 100000 total lookups."
|
|
355
|
+
}),
|
|
356
|
+
budget_usd: z2.string().regex(/^(?:0|[1-9]\d{0,11})(?:\.\d{1,2})?$/).optional().describe("Optional USD budget as a decimal string, e.g. 2.50. Advisory, never an enforced cap.")
|
|
357
|
+
});
|
|
358
|
+
function registerPreflight(server, client, transport) {
|
|
359
|
+
server.registerTool("preflight", {
|
|
360
|
+
description: "Estimate whether your secret key permits a proposed Email, Domain, DNS, MX or Country task, its advisory capacity, and additional USD charges under accepted terms. Supply operation counts and optional Deep, without lookup inputs. Uses default SDK retries: up to three attempts per ordinary lookup and one per Email Deep lookup. Authenticated metadata request, no lookup units or paid checks. Reserves no units or money and does not enforce a budget. Check permitted, cost.status, capacity and budget before lookup.",
|
|
361
|
+
inputSchema: task,
|
|
362
|
+
annotations: { readOnlyHint: true, idempotentHint: true }
|
|
363
|
+
}, async (args, context) => {
|
|
364
|
+
if (!client) return noKeyResult(transport);
|
|
365
|
+
try {
|
|
366
|
+
const data = await client.preflight(args, { signal: context.mcpReq.signal });
|
|
367
|
+
return { ...ok(data), structuredContent: data };
|
|
368
|
+
} catch (error) {
|
|
369
|
+
return toErrorResult(error);
|
|
370
|
+
}
|
|
371
|
+
});
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
// src/registry.ts
|
|
375
|
+
var VERSION = "1.1.0";
|
|
376
|
+
var API_VERSION = "2.0.0";
|
|
377
|
+
var deep = z3.boolean().optional().describe("Include the nested deep object when available. Pricing depends on the operation.");
|
|
378
|
+
var lat = z3.number().min(-90).max(90).describe("Latitude in decimal degrees");
|
|
379
|
+
var lon = z3.number().min(-180).max(180).describe("Longitude in decimal degrees");
|
|
380
|
+
var iso2 = (what) => z3.string().describe(`ISO 3166-1 alpha-2 ${what}, e.g. US`);
|
|
381
|
+
var countryOpt = z3.string().optional().describe("ISO2, ISO3, or a country name. Optional when the lookup is unique.");
|
|
382
|
+
var languageTools = /* @__PURE__ */ new Set([
|
|
383
|
+
"ip",
|
|
384
|
+
"ip_self",
|
|
385
|
+
"asn",
|
|
386
|
+
"company",
|
|
387
|
+
"npi",
|
|
388
|
+
"continent",
|
|
389
|
+
"continent_countries",
|
|
390
|
+
"bloc_countries",
|
|
391
|
+
"country",
|
|
392
|
+
"country_states",
|
|
393
|
+
"state",
|
|
394
|
+
"state_districts",
|
|
395
|
+
"district",
|
|
396
|
+
"city",
|
|
397
|
+
"city_id",
|
|
398
|
+
"city_search",
|
|
399
|
+
"city_nearest",
|
|
400
|
+
"city_nearby",
|
|
401
|
+
"postal",
|
|
402
|
+
"postal_nearby",
|
|
403
|
+
"postal_distance",
|
|
404
|
+
"currency",
|
|
405
|
+
"language",
|
|
406
|
+
"date",
|
|
407
|
+
"time",
|
|
408
|
+
"timezone",
|
|
409
|
+
"measure_units",
|
|
410
|
+
"emoji",
|
|
411
|
+
"emoji_search",
|
|
412
|
+
"point"
|
|
413
|
+
]);
|
|
414
|
+
var displayLanguage = z3.string().min(2).max(64).optional().describe("Optional display language, such as fr or zh-Hant. IDs, numeric values and input parsing stay unchanged.");
|
|
415
|
+
function buildServer(key, transport, options = {}) {
|
|
416
|
+
const mode = options.mode ?? "full";
|
|
417
|
+
if (mode !== "full" && mode !== "compact") throw new Error("Unknown MCP catalog mode");
|
|
418
|
+
const operations = /* @__PURE__ */ new Map();
|
|
419
|
+
const server = new McpServer(
|
|
420
|
+
{
|
|
421
|
+
name: "parseapi",
|
|
422
|
+
version: VERSION,
|
|
423
|
+
title: "ParseAPI",
|
|
424
|
+
description: "Lookups for agents: IP and place data, addresses, company numbers, email, VAT, IBAN, NPI, phone, domains, weather, currency, measurements, timezones, dates and holidays. Real reference data instead of guessing.",
|
|
425
|
+
websiteUrl: "https://parseapi.com"
|
|
426
|
+
},
|
|
427
|
+
{ capabilities: { tools: {} } }
|
|
428
|
+
);
|
|
429
|
+
const parse = key ? parseAPI(key, {
|
|
430
|
+
// Tool descriptions and responses share this contract on both transports.
|
|
431
|
+
fetch: (input, init) => {
|
|
432
|
+
const headers = new Headers(init?.headers);
|
|
433
|
+
headers.set("Parse-Version", API_VERSION);
|
|
434
|
+
return fetch(input, { ...init, headers });
|
|
435
|
+
}
|
|
436
|
+
}) : null;
|
|
437
|
+
function tool(name, description, shape, fn, refine) {
|
|
438
|
+
const localized = languageTools.has(name);
|
|
439
|
+
const input = z3.object(localized ? { ...shape, lang: displayLanguage } : shape);
|
|
440
|
+
const schema = refine ? refine(input) : input;
|
|
441
|
+
const invoke = async (args, signal) => {
|
|
442
|
+
if (!parse) return noKeyResult(transport);
|
|
443
|
+
try {
|
|
444
|
+
const requested = args.lang;
|
|
445
|
+
const request = {
|
|
446
|
+
signal,
|
|
447
|
+
...localized && typeof requested === "string" ? { lang: requested } : {}
|
|
448
|
+
};
|
|
449
|
+
return ok(await fn(parse, args, request));
|
|
450
|
+
} catch (err) {
|
|
451
|
+
return toErrorResult(err);
|
|
452
|
+
}
|
|
453
|
+
};
|
|
454
|
+
operations.set(name, { name, description, schema, invoke });
|
|
455
|
+
if (mode === "compact") return;
|
|
456
|
+
server.registerTool(
|
|
457
|
+
name,
|
|
458
|
+
{
|
|
459
|
+
description,
|
|
460
|
+
inputSchema: schema,
|
|
461
|
+
annotations: { readOnlyHint: true }
|
|
462
|
+
},
|
|
463
|
+
(args, context) => invoke(args, context.mcpReq.signal)
|
|
464
|
+
);
|
|
465
|
+
}
|
|
466
|
+
tool(
|
|
467
|
+
"measure",
|
|
468
|
+
"Parse a measurement or convert it to a target unit. Supports mixed measurements such as 5 ft 11 in. Amount is a decimal string. Without to, returns the canonical unit for its type. Ambiguous input returns valid false, reason and choices. Use measure_units to discover accepted units. Pooled request, no separate check charge.",
|
|
469
|
+
{
|
|
470
|
+
measure: z3.string().min(1).max(256).describe("Measurement to parse, e.g. 5 ft 11 in or 10 kg"),
|
|
471
|
+
to: z3.string().min(1).max(128).optional().describe("Target unit, e.g. cm or lb"),
|
|
472
|
+
locale: z3.string().min(1).max(32).optional().describe("Explicit number locale, e.g. de-DE"),
|
|
473
|
+
system: z3.enum(["us", "imperial"]).optional().describe("Resolve an ambiguous customary unit using the stated system")
|
|
474
|
+
},
|
|
475
|
+
(c, a, request) => c.measure(a.measure, { ...request, to: a.to, locale: a.locale, system: a.system })
|
|
476
|
+
);
|
|
477
|
+
tool(
|
|
478
|
+
"measure_units",
|
|
479
|
+
"Discover the reviewed measurement units, canonical codes, types and aliases. With no filters, returns the full catalog. Pass unit to find compatible conversion targets. Combine query and type to narrow results.",
|
|
480
|
+
{
|
|
481
|
+
query: z3.string().max(128).optional().describe("Search text, e.g. foot"),
|
|
482
|
+
type: z3.string().min(1).max(64).optional().describe("Measurement type, e.g. length"),
|
|
483
|
+
unit: z3.string().min(1).max(128).optional().describe("Return units compatible with this unit, e.g. m")
|
|
484
|
+
},
|
|
485
|
+
(c, a, request) => c.measure.units({ ...request, query: a.query, type: a.type, unit: a.unit })
|
|
486
|
+
);
|
|
487
|
+
tool(
|
|
488
|
+
"ip",
|
|
489
|
+
"Look up an IPv4 or IPv6 address: country, region, ASN, timezone. Deep adds datacenter, relay, tor and vpn flags.",
|
|
490
|
+
{ ip: z3.string().describe("IPv4 or IPv6 address, e.g. 8.8.8.8"), deep },
|
|
491
|
+
(c, a, request) => c.ip(a.ip, { ...request, deep: a.deep })
|
|
492
|
+
);
|
|
493
|
+
if (transport === "stdio") {
|
|
494
|
+
tool(
|
|
495
|
+
"ip_self",
|
|
496
|
+
"Look up the public IP of the machine running this MCP server.",
|
|
497
|
+
{ deep },
|
|
498
|
+
(c, a, request) => c.ip.self({ ...request, deep: a.deep })
|
|
499
|
+
);
|
|
500
|
+
}
|
|
501
|
+
tool(
|
|
502
|
+
"continent",
|
|
503
|
+
"Look up a continent by code: name, area and population.",
|
|
504
|
+
{ code: z3.string().describe("Continent code: AF, AN, AS, EU, NA, OC, SA") },
|
|
505
|
+
(c, a, request) => c.continent(a.code, request)
|
|
506
|
+
);
|
|
507
|
+
tool(
|
|
508
|
+
"continent_countries",
|
|
509
|
+
"List every country on a continent.",
|
|
510
|
+
{ code: z3.string().describe("Continent code: AF, AN, AS, EU, NA, OC, SA") },
|
|
511
|
+
(c, a, request) => c.continent.countries(a.code, request)
|
|
512
|
+
);
|
|
513
|
+
tool(
|
|
514
|
+
"bloc",
|
|
515
|
+
"Look up a country group by code: EU, EEA, Schengen, Eurozone, SEPA, NATO, and more. Returns the official name and the current member count.",
|
|
516
|
+
{
|
|
517
|
+
code: z3.string().describe("Bloc code: EU, EEA, EFTA, SCHENGEN, EUROZONE, SEPA, NATO, OECD, G7, ASEAN, GCC, MERCOSUR")
|
|
518
|
+
},
|
|
519
|
+
(c, a, request) => c.bloc(a.code, request)
|
|
520
|
+
);
|
|
521
|
+
tool(
|
|
522
|
+
"bloc_countries",
|
|
523
|
+
"List the current members of a country group, each with name, flag, and calling code.",
|
|
524
|
+
{
|
|
525
|
+
code: z3.string().describe("Bloc code: EU, EEA, EFTA, SCHENGEN, EUROZONE, SEPA, NATO, OECD, G7, ASEAN, GCC, MERCOSUR")
|
|
526
|
+
},
|
|
527
|
+
(c, a, request) => c.bloc.countries(a.code, request)
|
|
528
|
+
);
|
|
529
|
+
tool(
|
|
530
|
+
"country",
|
|
531
|
+
"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.",
|
|
532
|
+
{ code: iso2("country code"), deep: deep.describe("Include the complete detail bag on a paid plan.") },
|
|
533
|
+
(c, a, request) => c.country(a.code, { ...request, deep: a.deep })
|
|
534
|
+
);
|
|
535
|
+
tool(
|
|
536
|
+
"country_states",
|
|
537
|
+
"List the states, provinces or regions of a country.",
|
|
538
|
+
{ code: iso2("country code") },
|
|
539
|
+
(c, a, request) => c.country.states(a.code, request)
|
|
540
|
+
);
|
|
541
|
+
tool(
|
|
542
|
+
"state",
|
|
543
|
+
"Look up a state or province by code or name. Deep adds its demographic and tax profile on paid plans, including population_period when verified. Pass country to resolve a colliding code.",
|
|
544
|
+
{
|
|
545
|
+
code: z3.string().describe("State code or name, e.g. colorado, NC"),
|
|
546
|
+
country: countryOpt,
|
|
547
|
+
deep: deep.describe("Include the complete detail bag on a paid plan.")
|
|
548
|
+
},
|
|
549
|
+
(c, a, request) => c.state(a.code, { ...request, deep: a.deep, country: a.country })
|
|
550
|
+
);
|
|
551
|
+
tool(
|
|
552
|
+
"state_districts",
|
|
553
|
+
"List the districts, counties or departments of a state. Deep adds population and its reporting period to each result on paid plans.",
|
|
554
|
+
{
|
|
555
|
+
code: z3.string().describe("State code or name, e.g. NC, colorado"),
|
|
556
|
+
country: countryOpt,
|
|
557
|
+
deep: deep.describe("Include population and its reporting period in each district detail bag on a paid plan.")
|
|
558
|
+
},
|
|
559
|
+
(c, a, request) => c.state.districts(a.code, { ...request, deep: a.deep, country: a.country })
|
|
560
|
+
);
|
|
561
|
+
tool(
|
|
562
|
+
"district",
|
|
563
|
+
"Look up a district, county or department by code or name. Deep adds area, population and seat on paid plans. Pass state to resolve a colliding name. Population includes a reporting year or period when verified. Paid deep property_tax contains annual_median, currency and period: median annual tax payable on owner-occupied homes in the area, adjusted to the final year of that period. It is not a rate or property bill. Unsupported, missing and censored estimates are null.",
|
|
564
|
+
{
|
|
565
|
+
code: z3.string().describe("District code or name, e.g. 37081, guilford county"),
|
|
566
|
+
country: countryOpt,
|
|
567
|
+
state: z3.string().optional().describe("ADM1 code or name to disambiguate, e.g. NC or louisiana"),
|
|
568
|
+
deep: deep.describe("Include the complete detail bag on a paid plan.")
|
|
569
|
+
},
|
|
570
|
+
(c, a, request) => c.district(a.code, { ...request, deep: a.deep, country: a.country, state: a.state })
|
|
571
|
+
);
|
|
572
|
+
tool(
|
|
573
|
+
"city",
|
|
574
|
+
"Resolve a city name to coordinates, timezone and administrative context. Deep adds demographic and geographic detail on paid plans. Pass country or state for name ties. Population includes a reporting year or period when verified.",
|
|
575
|
+
{
|
|
576
|
+
name: z3.string().describe("City name, e.g. charlotte"),
|
|
577
|
+
country: countryOpt,
|
|
578
|
+
state: z3.string().optional().describe("State code to disambiguate, e.g. NC"),
|
|
579
|
+
deep: deep.describe("Include the complete detail bag on a paid plan.")
|
|
580
|
+
},
|
|
581
|
+
(c, a, request) => c.city(a.name, { ...request, deep: a.deep, country: a.country, state: a.state })
|
|
582
|
+
);
|
|
583
|
+
tool(
|
|
584
|
+
"city_id",
|
|
585
|
+
"Resolve a stable city id. Deep adds the city profile on paid plans.",
|
|
586
|
+
{ id: z3.string().describe("Stable city id, e.g. city_mb8mbqrkz8zb"), deep: deep.describe("Include the complete detail bag on a paid plan.") },
|
|
587
|
+
(c, a, request) => c.city.id(a.id, { ...request, deep: a.deep })
|
|
588
|
+
);
|
|
589
|
+
tool(
|
|
590
|
+
"city_search",
|
|
591
|
+
"Search city names. Deep adds the profile inside each returned city on paid plans.",
|
|
592
|
+
{
|
|
593
|
+
query: z3.string().describe("Name prefix, e.g. char"),
|
|
594
|
+
country: countryOpt,
|
|
595
|
+
state: z3.string().optional().describe("State code filter"),
|
|
596
|
+
limit: z3.number().int().min(1).max(50).optional().describe("Max results"),
|
|
597
|
+
deep: deep.describe("Include the complete detail bag on a paid plan.")
|
|
598
|
+
},
|
|
599
|
+
(c, a, request) => c.city.search(a.query, { ...request, deep: a.deep, country: a.country, state: a.state, limit: a.limit })
|
|
600
|
+
);
|
|
601
|
+
tool(
|
|
602
|
+
"city_nearest",
|
|
603
|
+
"Find the nearest city with distance. Deep adds the city profile on paid plans.",
|
|
604
|
+
{ lat, lon, deep },
|
|
605
|
+
(c, a, request) => c.city.nearest(a.lat, a.lon, { ...request, deep: a.deep })
|
|
606
|
+
);
|
|
607
|
+
tool(
|
|
608
|
+
"city_nearby",
|
|
609
|
+
"Find nearby cities with distances. Deep adds the profile inside each returned city on paid plans.",
|
|
610
|
+
{
|
|
611
|
+
name: z3.string().describe("Anchor city name, e.g. denver"),
|
|
612
|
+
country: countryOpt,
|
|
613
|
+
state: z3.string().optional().describe("State code to disambiguate the anchor"),
|
|
614
|
+
radius: z3.number().positive().optional().describe("Search radius, default 40 km"),
|
|
615
|
+
unit: z3.enum(["km", "mi"]).optional().describe("Radius unit, default km"),
|
|
616
|
+
limit: z3.number().int().min(1).max(50).optional().describe("Max results, default 10"),
|
|
617
|
+
deep: deep.describe("Include the complete detail bag on a paid plan.")
|
|
618
|
+
},
|
|
619
|
+
(c, a, request) => c.city.nearby(a.name, {
|
|
620
|
+
...request,
|
|
621
|
+
deep: a.deep,
|
|
622
|
+
country: a.country,
|
|
623
|
+
state: a.state,
|
|
624
|
+
radius: a.radius,
|
|
625
|
+
unit: a.unit,
|
|
626
|
+
limit: a.limit
|
|
627
|
+
})
|
|
628
|
+
);
|
|
629
|
+
tool(
|
|
630
|
+
"postal",
|
|
631
|
+
"Resolve a postal code to its place, coordinates and timezone. Deep adds area, population with its reporting period, tax references, neighbors and metro associations on paid plans. property_tax is a nullable area statistic with annual_median, currency and period: median annual tax payable on owner-occupied homes, adjusted to the final year of the period. It is not a rate or property bill. Unsupported, missing and censored estimates are null. Tax rates are percentages and alternative geographic references, not additive.",
|
|
632
|
+
{
|
|
633
|
+
code: z3.string().describe("Postal or ZIP code, e.g. SW1A 1AA, 28202"),
|
|
634
|
+
country: countryOpt,
|
|
635
|
+
deep: deep.describe("Include the complete detail bag on a paid plan.")
|
|
636
|
+
},
|
|
637
|
+
(c, a, request) => c.postal(a.code, { ...request, deep: a.deep, country: a.country })
|
|
638
|
+
);
|
|
639
|
+
tool(
|
|
640
|
+
"postal_nearby",
|
|
641
|
+
"Find nearby postal codes with distances. Deep adds metropolitan associations to the origin and each result on paid plans.",
|
|
642
|
+
{
|
|
643
|
+
code: z3.string().describe("Postal code to search around"),
|
|
644
|
+
country: countryOpt,
|
|
645
|
+
radius: z3.number().positive().optional().describe("Search radius"),
|
|
646
|
+
unit: z3.enum(["km", "mi"]).optional().describe("Radius unit, default km"),
|
|
647
|
+
deep: deep.describe("Include the complete detail bag on a paid plan.")
|
|
648
|
+
},
|
|
649
|
+
(c, a, request) => c.postal.nearby(a.code, { ...request, deep: a.deep, country: a.country, radius: a.radius, unit: a.unit })
|
|
650
|
+
);
|
|
651
|
+
tool(
|
|
652
|
+
"postal_distance",
|
|
653
|
+
"Distance between two postal codes. Deep adds metropolitan associations inside each endpoint on paid plans.",
|
|
654
|
+
{
|
|
655
|
+
from: z3.string().describe("First postal code"),
|
|
656
|
+
to: z3.string().describe("Second postal code"),
|
|
657
|
+
country: countryOpt,
|
|
658
|
+
deep: deep.describe("Include the complete detail bag on a paid plan.")
|
|
659
|
+
},
|
|
660
|
+
(c, a, request) => c.postal.distance(a.from, a.to, { ...request, deep: a.deep, country: a.country })
|
|
661
|
+
);
|
|
662
|
+
tool(
|
|
663
|
+
"address",
|
|
664
|
+
"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.",
|
|
665
|
+
{
|
|
666
|
+
address: z3.string().describe("Street address, e.g. 1600 Pennsylvania Ave NW, Washington, DC 20500"),
|
|
667
|
+
country: z3.string().optional().describe("Country: US or FR. Use FR or a written France suffix for France. Defaults to US."),
|
|
668
|
+
deep
|
|
669
|
+
},
|
|
670
|
+
(c, a, request) => c.address(a.address, { ...request, country: a.country, deep: a.deep })
|
|
671
|
+
);
|
|
672
|
+
tool(
|
|
673
|
+
"address_search",
|
|
674
|
+
"Search street addresses from a partial address. Prefer postal, or city and state, from the form. An optional end-user IP hints at locality. Empty results explain themselves with reason: more_input, missing_context or no_matches. With suggestions reason is null. Operational failures use API errors. French search requires country FR and either postal or city.",
|
|
675
|
+
{
|
|
676
|
+
query: z3.string().describe("Partial street address, e.g. 1600 Pennsylvania"),
|
|
677
|
+
country: z3.string().optional().describe("Country: US or FR. Defaults to US."),
|
|
678
|
+
postal: z3.string().optional().describe("Postal code from the address form, preferred for locality context"),
|
|
679
|
+
city: z3.string().optional().describe("City filter"),
|
|
680
|
+
state: z3.string().optional().describe("State code filter"),
|
|
681
|
+
ip: z3.string().optional().describe("End-user IP locality hint for server-side calls. Prefer explicit form context.")
|
|
682
|
+
},
|
|
683
|
+
(c, a, request) => c.address.search(a.query, { ...request, country: a.country, postal: a.postal, city: a.city, state: a.state, ip: a.ip })
|
|
684
|
+
);
|
|
685
|
+
tool(
|
|
686
|
+
"company",
|
|
687
|
+
"Parse a company number and its registered identity, status and address. Paid deep adds business activity and associated identifiers. Geography lookups are separate calls.",
|
|
688
|
+
{
|
|
689
|
+
number: z3.string().describe("Company registration number, e.g. 552100554 with country FR"),
|
|
690
|
+
country: countryOpt,
|
|
691
|
+
deep
|
|
692
|
+
},
|
|
693
|
+
(c, a, request) => c.company(a.number, { ...request, country: a.country, deep: a.deep })
|
|
694
|
+
);
|
|
695
|
+
tool(
|
|
696
|
+
"point",
|
|
697
|
+
"Locate coordinates in their country, state, district and actual IANA timezone. Deep adds terrain and a compact nearest-city summary on every plan. The timezone ID stays in core. Nearest city is null when none is within 200 km.",
|
|
698
|
+
{ lat, lon, deep },
|
|
699
|
+
(c, a, request) => c.point(a.lat, a.lon, { ...request, deep: a.deep })
|
|
700
|
+
);
|
|
701
|
+
tool(
|
|
702
|
+
"elevation",
|
|
703
|
+
"Elevation in meters at coordinates.",
|
|
704
|
+
{ lat, lon },
|
|
705
|
+
(c, a, request) => c.elevation(a.lat, a.lon, request)
|
|
706
|
+
);
|
|
707
|
+
tool(
|
|
708
|
+
"weather",
|
|
709
|
+
"Current weather with observation time and station distance. Paid deep adds specialist current measurements, forecast, alerts, hourly and daily outlook, air quality and optional history. Metric and imperial pairs stay together. A date requires paid deep and adds the past UTC day in deep.history alongside current conditions.",
|
|
710
|
+
{
|
|
711
|
+
lat,
|
|
712
|
+
lon,
|
|
713
|
+
deep,
|
|
714
|
+
date: z3.string().optional().describe("A past UTC day, YYYY-MM-DD. Requires paid deep. Adds deep.history alongside current conditions.")
|
|
715
|
+
},
|
|
716
|
+
(c, a, request) => c.weather(a.lat, a.lon, { ...request, deep: a.deep, date: a.date })
|
|
717
|
+
);
|
|
718
|
+
tool(
|
|
719
|
+
"email",
|
|
720
|
+
"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.",
|
|
721
|
+
{ email: z3.string().describe("Email address to validate"), deep },
|
|
722
|
+
(c, a, request) => c.email(a.email, { ...request, deep: a.deep })
|
|
723
|
+
);
|
|
724
|
+
tool(
|
|
725
|
+
"vat",
|
|
726
|
+
"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.",
|
|
727
|
+
{
|
|
728
|
+
number: z3.string().describe("VAT number, with or without the country prefix"),
|
|
729
|
+
country: iso2("country code when the number has no prefix").optional(),
|
|
730
|
+
from: z3.string().optional().describe("Your own VAT number. Returns a consultation identifier for your audit file"),
|
|
731
|
+
deep
|
|
732
|
+
},
|
|
733
|
+
(c, a, request) => c.vat(a.number, { ...request, country: a.country, from: a.from, deep: a.deep })
|
|
734
|
+
);
|
|
735
|
+
tool(
|
|
736
|
+
"iban",
|
|
737
|
+
"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.",
|
|
738
|
+
{
|
|
739
|
+
iban: z3.string().describe("IBAN, with or without spaces, with or without the country prefix"),
|
|
740
|
+
country: iso2("country code when the number has no prefix").optional(),
|
|
741
|
+
deep: deep.describe("Include optional detail on every plan.")
|
|
742
|
+
},
|
|
743
|
+
(c, a, request) => c.iban(a.iban, { ...request, deep: a.deep, country: a.country })
|
|
744
|
+
);
|
|
745
|
+
tool(
|
|
746
|
+
"bin",
|
|
747
|
+
"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.",
|
|
748
|
+
{
|
|
749
|
+
bin: z3.string().describe("Card prefix as a string, 6-11 digits. Preserve leading zeros. Spaces and hyphens are accepted."),
|
|
750
|
+
deep: z3.boolean().optional().describe("Include an empty deep object. No extra fields or separate charge.")
|
|
751
|
+
},
|
|
752
|
+
(c, a, request) => c.bin(a.bin, { ...request, deep: a.deep })
|
|
753
|
+
);
|
|
754
|
+
tool(
|
|
755
|
+
"npi",
|
|
756
|
+
"Validate an NPI and identify the registered provider, active/exclusion status, specialty and practice contact. Paid deep adds deactivation date and Medicare enrollment evidence.",
|
|
757
|
+
{
|
|
758
|
+
npi: z3.string().describe("10-digit NPI number"),
|
|
759
|
+
deep
|
|
760
|
+
},
|
|
761
|
+
(c, a, request) => c.npi(a.npi, { ...request, deep: a.deep })
|
|
762
|
+
);
|
|
763
|
+
tool(
|
|
764
|
+
"phone",
|
|
765
|
+
"Parse and validate a phone number with national and international display formats. Deep adds numbering-plan state and timezone on every plan. These do not locate a handset.",
|
|
766
|
+
{
|
|
767
|
+
number: z3.string().describe("Phone number, e.g. +14155552671"),
|
|
768
|
+
country: iso2("country code for national-format numbers").optional(),
|
|
769
|
+
deep
|
|
770
|
+
},
|
|
771
|
+
(c, a, request) => c.phone(a.number, { ...request, country: a.country, deep: a.deep })
|
|
772
|
+
);
|
|
773
|
+
tool(
|
|
774
|
+
"carrier",
|
|
775
|
+
"Look up current carrier, real line type and burner flag. Deep adds issuing city and state in the same metered lookup, including Free allowance units. No extra check or second paid gate.",
|
|
776
|
+
{
|
|
777
|
+
number: z3.string().describe("Phone number, e.g. +14155552671"),
|
|
778
|
+
country: iso2("country code for national-format numbers").optional(),
|
|
779
|
+
deep: deep.describe("Include available detail within the same metered core unit. No extra charge or paid-plan gate.")
|
|
780
|
+
},
|
|
781
|
+
(c, a, request) => c.carrier(a.number, { ...request, deep: a.deep, country: a.country })
|
|
782
|
+
);
|
|
783
|
+
tool(
|
|
784
|
+
"caller",
|
|
785
|
+
"Look up the caller ID name (CNAM) for a NANP (+1) phone number. caller is the record verbatim, null when no record or outside NANP. Metered per lookup on a NANP number.",
|
|
786
|
+
{
|
|
787
|
+
number: z3.string().describe("Phone number, e.g. +18004633339"),
|
|
788
|
+
country: iso2("country code for national-format numbers").optional()
|
|
789
|
+
},
|
|
790
|
+
(c, a, request) => c.caller(a.number, { ...request, country: a.country })
|
|
791
|
+
);
|
|
792
|
+
tool(
|
|
793
|
+
"hlr",
|
|
794
|
+
"Phone status at the last check: live means assigned and connected means reachable at that check. Cached results may be returned. Deep adds available roaming and network diagnostics in the same metered lookup, including Free allowance units. Null is unconfirmed.",
|
|
795
|
+
{
|
|
796
|
+
number: z3.string().describe("Phone number, e.g. +447712345678"),
|
|
797
|
+
country: iso2("country code for national-format numbers").optional(),
|
|
798
|
+
deep: deep.describe("Include available detail within the same metered core unit. No extra charge or paid-plan gate.")
|
|
799
|
+
},
|
|
800
|
+
(c, a, request) => c.hlr(a.number, { ...request, deep: a.deep, country: a.country })
|
|
801
|
+
);
|
|
802
|
+
tool(
|
|
803
|
+
"domain",
|
|
804
|
+
"Check whether a domain is registered. Deep adds registration dates, registrar, status and DNSSEC, included on paid plans. Use dns for DNS records and mx for mail routing.",
|
|
805
|
+
{ domain: z3.string().describe("Domain name, e.g. example.com"), deep: deep.describe("Include registration details on a paid plan.") },
|
|
806
|
+
(c, a, request) => c.domain(a.domain, { ...request, deep: a.deep })
|
|
807
|
+
);
|
|
808
|
+
tool(
|
|
809
|
+
"asn",
|
|
810
|
+
"Network name and country for an autonomous system number.",
|
|
811
|
+
{ asn: z3.string().describe("Autonomous system number, such as AS13335 or 13335") },
|
|
812
|
+
(c, a, request) => c.asn(a.asn, request)
|
|
813
|
+
);
|
|
814
|
+
tool(
|
|
815
|
+
"mac",
|
|
816
|
+
"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.",
|
|
817
|
+
{ mac: z3.string().describe("MAC address") },
|
|
818
|
+
(c, a, request) => c.mac(a.mac, request)
|
|
819
|
+
);
|
|
820
|
+
tool(
|
|
821
|
+
"dns",
|
|
822
|
+
"Look up published DNS records with TTLs. Pooled on every plan. Omit type to check all ten supported types. The selected question may include its CNAME chain. Values retain DNS presentation syntax, including TXT quoting.",
|
|
823
|
+
{
|
|
824
|
+
domain: z3.string().describe("Domain or DNS name, including service names such as _dmarc.example.com"),
|
|
825
|
+
type: z3.enum(["A", "AAAA", "CNAME", "MX", "NS", "TXT", "SOA", "CAA", "SRV", "PTR"]).optional().describe("DNS question type. Omit to check all supported types.")
|
|
826
|
+
},
|
|
827
|
+
(c, a, request) => c.dns(a.domain, { ...request, type: a.type })
|
|
828
|
+
);
|
|
829
|
+
tool(
|
|
830
|
+
"mx",
|
|
831
|
+
"MX records for a domain.",
|
|
832
|
+
{ domain: z3.string().describe("Domain name") },
|
|
833
|
+
(c, a, request) => c.mx(a.domain, request)
|
|
834
|
+
);
|
|
835
|
+
tool(
|
|
836
|
+
"useragent",
|
|
837
|
+
"Parse a User-Agent string: browser, OS, device, bot detection.",
|
|
838
|
+
{ ua: z3.string().describe("The User-Agent string to parse"), deep },
|
|
839
|
+
(c, a, request) => c.useragent(a.ua, { ...request, deep: a.deep })
|
|
840
|
+
);
|
|
841
|
+
tool(
|
|
842
|
+
"vin",
|
|
843
|
+
"Decode a VIN to year, make, model, trim, body and vehicle type. Paid deep adds specifications, manufacturing detail and recalls.",
|
|
844
|
+
{ vin: z3.string().describe("The VIN as you have it. Spaces and punctuation fold out"), deep },
|
|
845
|
+
(c, a, request) => c.vin(a.vin, { ...request, deep: a.deep })
|
|
846
|
+
);
|
|
847
|
+
tool(
|
|
848
|
+
"tariff",
|
|
849
|
+
"Look up a tariff code, description, lineage and general rate. Paid deep adds statistical units and the special and other schedule columns. Optional origin with deep resolves country-specific measures. Without origin, schedule detail is available and origin-dependent fields are null. A null effective rate is not a zero rate.",
|
|
850
|
+
{
|
|
851
|
+
code: z3.string().describe("HTS code, 4 to 10 digits, dots optional, e.g. 8471.30.01.00"),
|
|
852
|
+
origin: iso2("country of origin for duty resolution, only read with deep").optional(),
|
|
853
|
+
deep
|
|
854
|
+
},
|
|
855
|
+
(c, a, request) => c.tariff(a.code, { ...request, deep: a.deep, origin: a.origin })
|
|
856
|
+
);
|
|
857
|
+
tool(
|
|
858
|
+
"tariff_search",
|
|
859
|
+
"Search US tariff schedule descriptions by product. Returns up to 20 lines, best match first, each with hts, description, and the general duty rate.",
|
|
860
|
+
{ query: z3.string().describe("Product words, e.g. sunglasses, laptop, coffee") },
|
|
861
|
+
(c, a, request) => c.tariff.search(a.query, request)
|
|
862
|
+
);
|
|
863
|
+
tool(
|
|
864
|
+
"naics",
|
|
865
|
+
"Look up a US NAICS 2022 code, title and parent hierarchy. Deep adds definition, children and exclusions on paid plans.",
|
|
866
|
+
{ code: z3.string().describe("NAICS code, e.g. 541511 or sector range 31-33"), deep: deep.describe("Include the complete detail bag on a paid plan.") },
|
|
867
|
+
(c, a, request) => c.naics(a.code, { ...request, deep: a.deep })
|
|
868
|
+
);
|
|
869
|
+
tool(
|
|
870
|
+
"naics_search",
|
|
871
|
+
"Search US NAICS 2022 titles and activities. Matching text and corrections stay with the result. Deep adds definition, children and exclusions inside each result on paid plans.",
|
|
872
|
+
{
|
|
873
|
+
query: z3.string().min(1).max(100).describe("Industry keywords, e.g. coffee shop"),
|
|
874
|
+
limit: z3.number().int().min(1).max(50).optional().describe("Maximum results, 1-50. Default 10."),
|
|
875
|
+
deep: deep.describe("Include the complete detail bag on a paid plan.")
|
|
876
|
+
},
|
|
877
|
+
(c, a, request) => c.naics.search(a.query, { ...request, deep: a.deep, limit: a.limit })
|
|
878
|
+
);
|
|
879
|
+
tool(
|
|
880
|
+
"currency",
|
|
881
|
+
"Currency name, symbols and decimal places. Deep adds numeric code, plural name and using countries on every plan.",
|
|
882
|
+
{ code: z3.string().describe("ISO 4217 code, e.g. USD"), deep: deep.describe("Include optional detail on every plan.") },
|
|
883
|
+
(c, a, request) => c.currency(a.code, { ...request, deep: a.deep })
|
|
884
|
+
);
|
|
885
|
+
tool(
|
|
886
|
+
"currency_rate",
|
|
887
|
+
"Reference exchange rate between two currencies. Pass date for a past business day, amount to convert.",
|
|
888
|
+
{
|
|
889
|
+
base: z3.string().describe("Base currency ISO 4217 code, e.g. USD"),
|
|
890
|
+
quote: z3.string().describe("Quote currency ISO 4217 code, e.g. EUR"),
|
|
891
|
+
date: z3.string().optional().describe(
|
|
892
|
+
"YYYY-MM-DD. Official rate for that business day. A weekend or holiday resolves to the last published day on or before it"
|
|
893
|
+
),
|
|
894
|
+
amount: z3.number().optional().describe("Appends amount and converted, rounded to the quote currency minor-unit digits")
|
|
895
|
+
},
|
|
896
|
+
(c, a, request) => c.currency.rate(a.base, a.quote, { ...request, date: a.date, amount: a.amount })
|
|
897
|
+
);
|
|
898
|
+
tool(
|
|
899
|
+
"language",
|
|
900
|
+
"Language names, script and writing direction. Deep adds ISO3 and country associations on every plan.",
|
|
901
|
+
{ code: z3.string().describe("Language code, e.g. en, ja, gsw"), deep: deep.describe("Include optional detail on every plan.") },
|
|
902
|
+
(c, a, request) => c.language(a.code, { ...request, deep: a.deep })
|
|
903
|
+
);
|
|
904
|
+
tool(
|
|
905
|
+
"name",
|
|
906
|
+
"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.",
|
|
907
|
+
{
|
|
908
|
+
name: z3.string().describe("The name to parse, e.g. Smith, John or BILLY OSHALL"),
|
|
909
|
+
country: z3.string().optional().describe("ISO2 country context for gender, e.g. IT"),
|
|
910
|
+
name_locale: z3.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."),
|
|
911
|
+
deep: deep.describe("Include the complete detail bag on a paid plan.")
|
|
912
|
+
},
|
|
913
|
+
(c, a, request) => c.name(a.name, { ...request, deep: a.deep, country: a.country, name_locale: a.name_locale })
|
|
914
|
+
);
|
|
915
|
+
tool(
|
|
916
|
+
"time",
|
|
917
|
+
"Current local time, Unix seconds, exact UTC offset and DST. Omit timezone for UTC or pass both coordinates. at selects the moment; to converts it. Deep adds friendly name, numeric offsets and the next source clock transition on every plan.",
|
|
918
|
+
{
|
|
919
|
+
timezone: z3.string().min(1).optional().describe("IANA timezone, e.g. America/New_York. Omit for UTC when coordinates are absent"),
|
|
920
|
+
lat: lat.optional(),
|
|
921
|
+
lon: lon.optional(),
|
|
922
|
+
at: z3.string().min(1).optional().describe("ISO 8601 time, default now. With to, a time without a UTC offset is source wall time. Otherwise it is UTC. Include an offset to disambiguate a repeated local time"),
|
|
923
|
+
to: z3.string().min(1).optional().describe("Destination IANA timezone, e.g. Asia/Tokyo. Returns to.at and to.unix at the same instant"),
|
|
924
|
+
deep: deep.describe("Include optional detail on every plan.")
|
|
925
|
+
},
|
|
926
|
+
(c, a, request) => a.lat !== void 0 && a.lon !== void 0 ? c.time.at(a.lat, a.lon, { ...request, deep: a.deep, at: a.at, to: a.to }) : c.time(a.timezone, { ...request, deep: a.deep, at: a.at, to: a.to }),
|
|
927
|
+
(schema) => schema.refine(
|
|
928
|
+
(a) => a.timezone !== void 0 ? a.lat === void 0 && a.lon === void 0 : a.lat === void 0 === (a.lon === void 0),
|
|
929
|
+
{ message: "Pass a timezone, both lat and lon, or neither for UTC." }
|
|
930
|
+
)
|
|
931
|
+
);
|
|
932
|
+
tool(
|
|
933
|
+
"timezone",
|
|
934
|
+
"Compatibility tool; use time for new integrations. 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.",
|
|
935
|
+
{
|
|
936
|
+
timezone: z3.string().min(1).optional().describe("IANA timezone id, e.g. America/New_York"),
|
|
937
|
+
lat: lat.optional(),
|
|
938
|
+
lon: lon.optional(),
|
|
939
|
+
at: z3.string().optional().describe(
|
|
940
|
+
"ISO 8601 time, default now. With to and no UTC offset, reads as wall time in the from zone"
|
|
941
|
+
),
|
|
942
|
+
to: z3.string().optional().describe("Convert: the other IANA zone, e.g. Asia/Tokyo. Requires timezone, not lat/lon")
|
|
943
|
+
},
|
|
944
|
+
(c, a, request) => {
|
|
945
|
+
if (a.lat != null && a.lon != null) {
|
|
946
|
+
return c.timezone.at(a.lat, a.lon, { ...request, at: a.at });
|
|
947
|
+
}
|
|
948
|
+
if (!a.timezone) {
|
|
949
|
+
return Promise.reject(new Error("Pass timezone or lat and lon"));
|
|
950
|
+
}
|
|
951
|
+
return c.timezone(a.timezone, { ...request, at: a.at, to: a.to });
|
|
952
|
+
},
|
|
953
|
+
(schema) => schema.refine(
|
|
954
|
+
(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,
|
|
955
|
+
{ message: "Pass either timezone (with optional to), or both lat and lon." }
|
|
956
|
+
)
|
|
957
|
+
);
|
|
958
|
+
tool(
|
|
959
|
+
"date",
|
|
960
|
+
"Parse a date to ISO date, validity and Unix midnight. Ambiguous numeric dates need format. to adds signed days between; omit date for UTC today. Deep adds calendar details on every plan.",
|
|
961
|
+
{
|
|
962
|
+
date: z3.string().min(1).optional().describe("The date as you have it, any common format. Omit for today (UTC)"),
|
|
963
|
+
format: z3.enum(["mdy", "dmy"]).optional().describe("Breaks the month-first / day-first tie on numeric dates like 03/04/2026"),
|
|
964
|
+
to: z3.string().optional().describe("Another date. Appends to (normalized ISO) and days (signed days between)"),
|
|
965
|
+
deep: deep.describe("Include optional detail on every plan.")
|
|
966
|
+
},
|
|
967
|
+
(c, a, request) => {
|
|
968
|
+
if (a.date == null) return c.date.today({ ...request, deep: a.deep, to: a.to });
|
|
969
|
+
return c.date(a.date, { ...request, deep: a.deep, format: a.format, to: a.to });
|
|
970
|
+
},
|
|
971
|
+
(schema) => schema.refine(
|
|
972
|
+
(a) => a.format === void 0 || a.date !== void 0,
|
|
973
|
+
{ message: "Pass date when specifying format; omit both for today." }
|
|
974
|
+
)
|
|
975
|
+
);
|
|
976
|
+
tool(
|
|
977
|
+
"holiday",
|
|
978
|
+
"Public holidays and cultural observances for a country and year. Each row carries type: public or observance.",
|
|
979
|
+
{
|
|
980
|
+
country: iso2("country code"),
|
|
981
|
+
year: z3.number().int().optional().describe("Year, default current")
|
|
982
|
+
},
|
|
983
|
+
(c, a, request) => c.holiday(a.country, { ...request, year: a.year })
|
|
984
|
+
);
|
|
985
|
+
tool(
|
|
986
|
+
"holiday_date",
|
|
987
|
+
"Whether a specific date is a holiday or observance in a country. holiday is null when it is not.",
|
|
988
|
+
{ country: iso2("country code"), date: z3.string().describe("Date as YYYY-MM-DD") },
|
|
989
|
+
(c, a, request) => c.holiday.date(a.country, a.date, request)
|
|
990
|
+
);
|
|
991
|
+
tool(
|
|
992
|
+
"emoji",
|
|
993
|
+
"Resolve an emoji character, shortcode or name. Deep adds encoding, keywords and skin variants on every plan.",
|
|
994
|
+
{ emoji: z3.string().describe("Emoji name or the character itself, e.g. rocket"), deep: deep.describe("Include optional detail on every plan.") },
|
|
995
|
+
(c, a, request) => c.emoji(a.emoji, { ...request, deep: a.deep })
|
|
996
|
+
);
|
|
997
|
+
tool(
|
|
998
|
+
"emoji_search",
|
|
999
|
+
"Search emoji by keyword. Deep adds encoding and skin-variant detail inside each result on every plan.",
|
|
1000
|
+
{
|
|
1001
|
+
query: z3.string().describe("Search keyword, e.g. fire"),
|
|
1002
|
+
limit: z3.number().int().min(1).max(50).optional().describe("Max results"),
|
|
1003
|
+
deep: deep.describe("Include optional detail on every plan.")
|
|
1004
|
+
},
|
|
1005
|
+
(c, a, request) => c.emoji.search(a.query, { ...request, deep: a.deep, limit: a.limit })
|
|
1006
|
+
);
|
|
1007
|
+
registerDiscovery(server, operations, mode, API_VERSION);
|
|
1008
|
+
registerPreflight(server, parse, transport);
|
|
1009
|
+
return server;
|
|
1010
|
+
}
|
|
1011
|
+
|
|
1012
|
+
export {
|
|
1013
|
+
catalogMode,
|
|
1014
|
+
VERSION,
|
|
1015
|
+
buildServer
|
|
1016
|
+
};
|