@verifik/mcp 0.1.0 → 0.1.2

package/lib/client-features.js

@@ -0,0 +1,64 @@
+"use strict";
+
+const CLIENT_FEATURES_PATH = "/v2/client-features";
+const PAGE_LIMIT = 500;
+
+/**
+ * @param {import("./types").McpConfig} config
+ */
+const fetchClientFeaturesPage = async (config, page = 1) => {
+	const url = new URL(`${config.apiBase}${CLIENT_FEATURES_PATH}`);
+	url.searchParams.set("page", String(page));
+	url.searchParams.set("limit", String(PAGE_LIMIT));
+
+	const response = await fetch(url, {
+		method: "GET",
+		headers: {
+			Authorization: `Bearer ${config.token}`,
+			Accept: "application/json",
+		},
+	});
+
+	if (!response.ok) {
+		throw new Error(`Client features request failed (${response.status})`);
+	}
+
+	const body = await response.json();
+	const data = Array.isArray(body?.data)
+		? body.data
+		: Array.isArray(body?.data?.docs)
+			? body.data.docs
+			: [];
+
+	return {
+		features: data,
+		page: Number(body?.page) || 1,
+		pages: Number(body?.pages) || 1,
+	};
+};
+
+/**
+ * @param {import("./types").McpConfig} config
+ */
+const fetchGrantedFeatureCodes = async (config) => {
+	const firstPage = await fetchClientFeaturesPage(config, 1);
+	const codes = new Set();
+
+	for (const feature of firstPage.features) {
+		if (feature?.code) codes.add(feature.code);
+	}
+
+	for (let page = firstPage.page + 1; page <= firstPage.pages; page += 1) {
+		const nextPage = await fetchClientFeaturesPage(config, page);
+		for (const feature of nextPage.features) {
+			if (feature?.code) codes.add(feature.code);
+		}
+	}
+
+	return codes;
+};
+
+module.exports = {
+	CLIENT_FEATURES_PATH,
+	fetchGrantedFeatureCodes,
+};

package/lib/config.js

@@ -18,6 +18,7 @@ const loadConfig = () => {
 	const baseCategoryFilter = parseListEnv(process.env.VERIFIK_MCP_BASE_CATEGORY);
 	const codeAllowlist = parseListEnv(process.env.VERIFIK_MCP_CODES);
 	const catalogRefreshMs = parsePositiveInt(process.env.VERIFIK_MCP_CATALOG_REFRESH_MS, 0);
+	const requestTimeoutMs = parsePositiveInt(process.env.VERIFIK_MCP_REQUEST_TIMEOUT_MS, 90_000);
 
 	return {
 		apiBase,
@@ -27,6 +28,7 @@ const loadConfig = () => {
 		baseCategoryFilter,
 		codeAllowlist,
 		catalogRefreshMs,
+		requestTimeoutMs,
 	};
 };
 

package/lib/description.js

@@ -0,0 +1,67 @@
+"use strict";
+
+const ROUTE_PATTERN = /\b(?:GET|POST|PUT|PATCH|DELETE)\s+\/v?\d*\/[^\s.]+\b/gi;
+const ALIAS_PATTERN = /\bAlias:\s*[^\n.]+\.?/gi;
+const INTERNAL_JARGON = /\bNo name sources\.?\b/gi;
+
+/**
+ * @param {string} text
+ */
+const stripCountryPrefix = (text) => {
+	return String(text || "")
+		.replace(/^[A-Za-zÀ-ÿ\s]+?\s*[-—]\s*/u, "")
+		.trim();
+};
+
+/**
+ * @param {string} text
+ */
+const stripParentheticalCountry = (text) => {
+	return String(text || "").replace(/\s*\([A-Za-zÀ-ÿ\s]+\)\s*/gu, " ").trim();
+};
+
+/**
+ * @param {string} text
+ */
+const cleanDescriptionText = (text) => {
+	return String(text || "")
+		.replace(ROUTE_PATTERN, "")
+		.replace(ALIAS_PATTERN, "")
+		.replace(INTERNAL_JARGON, "")
+		.replace(/\s+/g, " ")
+		.trim();
+};
+
+/**
+ * @param {number | null | undefined} price
+ */
+const formatPrice = (price) => {
+	const value = Number(price);
+	if (!Number.isFinite(value)) return null;
+	return value.toFixed(value % 1 === 0 ? 0 : 2);
+};
+
+/**
+ * @param {import("./types").AppFeature} feature
+ */
+const buildToolDescription = (feature) => {
+	const rawDescription = cleanDescriptionText(feature.description || "");
+	const rawName = cleanDescriptionText(feature.name || feature.code || "Verifik feature");
+	const withoutCountryInName = stripParentheticalCountry(stripCountryPrefix(rawName));
+	const descriptionBody = rawDescription || withoutCountryInName;
+	const price = formatPrice(feature.smartCheckPrice ?? feature.price);
+
+	const parts = [descriptionBody];
+
+	if (price != null) {
+		parts.push(`Costs ${price} credit${price === "1" ? "" : "s"} per successful call.`);
+	}
+
+	return parts.join(" ");
+};
+
+module.exports = {
+	cleanDescriptionText,
+	buildToolDescription,
+	formatPrice,
+};

package/lib/error-response.js

@@ -0,0 +1,210 @@
+"use strict";
+
+const SERVICE_UNAVAILABLE_MESSAGE =
+	"The data source is temporarily unavailable; try again later.";
+
+const FEATURE_NOT_ENABLED_MESSAGE =
+	"This feature is not enabled on your Verifik account. Contact support to request access.";
+
+const FEATURE_UNAVAILABLE_MESSAGE =
+	"This feature is currently unavailable; contact support.";
+
+const NOT_FOUND_MESSAGE = "No record was found for the provided data.";
+
+/**
+ * @param {unknown} body
+ */
+const isHtmlBody = (body) => {
+	if (typeof body !== "string") return false;
+	const trimmed = body.trim().toLowerCase();
+	return trimmed.startsWith("<!doctype") || trimmed.startsWith("<html");
+};
+
+/**
+ * @param {unknown} body
+ */
+const isVerifikJsonBody = (body) => {
+	if (!body || typeof body !== "object" || Array.isArray(body)) return false;
+	return typeof body.code === "string" || typeof body.message === "string";
+};
+
+/**
+ * Verifik API error envelope (code + message, often with id).
+ * @param {unknown} body
+ */
+const isVerifikBusinessErrorBody = (body) => {
+	if (!body || typeof body !== "object" || Array.isArray(body)) return false;
+	return typeof body.code === "string" && typeof body.message === "string";
+};
+
+/**
+ * @param {unknown} code
+ * @param {unknown} message
+ */
+const isEndpointOutOfService = (code, message) => {
+	const haystack = `${String(code || "")} ${String(message || "")}`.toLowerCase();
+	return haystack.includes("endpoint_out_of_service") || haystack.includes("endpoint out of service");
+};
+
+/**
+ * @param {unknown} body
+ */
+const extractRequestId = (body) => {
+	if (!body || typeof body !== "object") return undefined;
+	if (typeof body.id === "string" && body.id) return body.id;
+	return undefined;
+};
+
+/**
+ * @param {unknown} body
+ */
+const extractCreditsCharged = (body) => {
+	if (!body || typeof body !== "object") return null;
+
+	const creditsCharged = body.creditsCharged;
+
+	if (typeof creditsCharged === "number" && Number.isFinite(creditsCharged)) {
+		return creditsCharged;
+	}
+
+	return null;
+};
+
+/**
+ * @param {unknown} message
+ */
+const isUpstreamGatewayMessage = (message) => {
+	if (typeof message !== "string") return false;
+	return /request failed with status code 50[234]/i.test(message) || /gateway timeout/i.test(message);
+};
+
+/**
+ * @param {number} status
+ * @param {unknown} body
+ */
+const classifyUpstreamError = (status, body) => {
+	const isJsonObject = isVerifikJsonBody(body);
+	const errorBody = isJsonObject ? body : {};
+	const apiCode = typeof errorBody.code === "string" ? errorBody.code : "";
+	const apiMessage = typeof errorBody.message === "string" ? errorBody.message : "";
+	const plainText = typeof body === "string" ? body.trim() : "";
+
+	if (status === 403 && apiMessage.toLowerCase().includes("no access to this feature")) {
+		return {
+			code: "FeatureNotEnabled",
+			message: FEATURE_NOT_ENABLED_MESSAGE,
+			retryable: false,
+		};
+	}
+
+	if (
+		isEndpointOutOfService(apiCode, apiMessage) ||
+		isEndpointOutOfService("", plainText)
+	) {
+		return {
+			code: "ServiceUnavailable",
+			message: SERVICE_UNAVAILABLE_MESSAGE,
+			retryable: true,
+		};
+	}
+
+	if (
+		status === 502 ||
+		status === 503 ||
+		status === 504 ||
+		status >= 500 ||
+		isUpstreamGatewayMessage(apiMessage) ||
+		isUpstreamGatewayMessage(plainText) ||
+		isHtmlBody(body)
+	) {
+		return {
+			code: "ServiceUnavailable",
+			message: SERVICE_UNAVAILABLE_MESSAGE,
+			retryable: true,
+		};
+	}
+
+	if (status === 404) {
+		if (isVerifikBusinessErrorBody(body)) {
+			return {
+				code: "NotFound",
+				message: NOT_FOUND_MESSAGE,
+				retryable: false,
+			};
+		}
+
+		return {
+			code: "FeatureUnavailable",
+			message: FEATURE_UNAVAILABLE_MESSAGE,
+			retryable: false,
+		};
+	}
+
+	if (apiCode || apiMessage) {
+		return {
+			code: apiCode || "RequestFailed",
+			message: apiMessage || "Request failed",
+			retryable: false,
+		};
+	}
+
+	if (plainText) {
+		return {
+			code: "RequestFailed",
+			message: plainText,
+			retryable: false,
+		};
+	}
+
+	return {
+		code: "RequestFailed",
+		message: "Request failed",
+		retryable: false,
+	};
+};
+
+/**
+ * @param {{ status: number, statusText?: string, body: unknown, durationMs?: number }} result
+ */
+const buildProxyErrorPayload = (result) => {
+	const requestId = extractRequestId(result.body);
+	const classified = classifyUpstreamError(result.status, result.body);
+
+	const payload = {
+		ok: false,
+		httpStatus: result.status,
+		statusText: result.statusText,
+		durationMs: result.durationMs,
+		error: classified,
+	};
+
+	if (requestId) payload.requestId = requestId;
+
+	return payload;
+};
+
+/**
+ * @param {unknown} body
+ */
+const sanitizeResponseData = (body) => {
+	if (isHtmlBody(body)) return null;
+	if (!body || typeof body !== "object") return body;
+	if ("data" in body) return body.data;
+	return body;
+};
+
+module.exports = {
+	SERVICE_UNAVAILABLE_MESSAGE,
+	FEATURE_NOT_ENABLED_MESSAGE,
+	FEATURE_UNAVAILABLE_MESSAGE,
+	NOT_FOUND_MESSAGE,
+	isHtmlBody,
+	isVerifikJsonBody,
+	isVerifikBusinessErrorBody,
+	isEndpointOutOfService,
+	extractRequestId,
+	extractCreditsCharged,
+	classifyUpstreamError,
+	buildProxyErrorPayload,
+	sanitizeResponseData,
+};

package/lib/field-enrichment.js

@@ -0,0 +1,103 @@
+"use strict";
+
+const path = require("node:path");
+
+/** @type {import("./field-enrichment.types")} */
+const enrichmentData = require(path.join(__dirname, "..", "data", "field-enrichment.json"));
+
+/**
+ * @param {string} featureCode
+ */
+const getFeatureEnrichment = (featureCode) => {
+	return enrichmentData.features[featureCode] || {};
+};
+
+/**
+ * @param {string} fieldName
+ */
+const getDefaultFieldEnrichment = (fieldName) => {
+	return enrichmentData.defaultFields[fieldName] || {};
+};
+
+/**
+ * @param {string} featureCode
+ * @param {string} fieldName
+ */
+const resolveFieldEnrichment = (featureCode, fieldName) => {
+	const featureFields = getFeatureEnrichment(featureCode).fields || {};
+	const featureField = featureFields[fieldName] || {};
+	const defaultField = getDefaultFieldEnrichment(fieldName);
+
+	return {
+		...defaultField,
+		...featureField,
+	};
+};
+
+/**
+ * @param {string} featureCode
+ */
+const getToolNameOverride = (featureCode) => {
+	return enrichmentData.toolNameOverrides[featureCode] || null;
+};
+
+/**
+ * @param {string} featureCode
+ */
+const getRequestOverride = (featureCode) => {
+	return enrichmentData.requestOverrides[featureCode] || null;
+};
+
+/**
+ * @param {string} featureCode
+ */
+const getParameterAliases = (featureCode) => {
+	return enrichmentData.parameterAliases[featureCode] || {};
+};
+
+/**
+ * @param {string} fieldName
+ */
+const isHiddenField = (fieldName) => {
+	return enrichmentData.hiddenFields.includes(fieldName);
+};
+
+/**
+ * @param {string} featureCode
+ */
+const getValidationRule = (featureCode) => {
+	const feature = getFeatureEnrichment(featureCode);
+	return feature.validation || null;
+};
+
+/**
+ * @param {string} fieldMeta
+ */
+const buildFieldDescription = (fieldMeta) => {
+	if (!fieldMeta?.description) return undefined;
+
+	const parts = [fieldMeta.description];
+
+	if (fieldMeta.format) {
+		parts.push(`Format: ${fieldMeta.format}.`);
+	}
+
+	if (fieldMeta.example) {
+		parts.push(`Example: ${fieldMeta.example}.`);
+	}
+
+	return parts.join(" ");
+};
+
+module.exports = {
+	enrichmentData,
+	getFeatureEnrichment,
+	getDefaultFieldEnrichment,
+	resolveFieldEnrichment,
+	getToolNameOverride,
+	getRequestOverride,
+	getParameterAliases,
+	isHiddenField,
+	getValidationRule,
+	buildFieldDescription,
+};

package/lib/field-normalize.js

@@ -0,0 +1,65 @@
+"use strict";
+
+/** Fields where common punctuation (dots, dashes, slashes, spaces) may appear but length limits apply to alphanumeric content. */
+const PUNCTUATION_TOLERANT_FIELDS = new Set([
+	"documentNumber",
+	"plate",
+	"card",
+	"serial",
+	"citizenIdentifier",
+	"emissionNumber",
+]);
+
+/**
+ * Remove common formatting characters used in ID numbers and plates.
+ * @param {unknown} value
+ */
+const stripFormatting = (value) => {
+	return String(value).replace(/[.\-\s/]/g, "");
+};
+
+/**
+ * @param {string} fieldName
+ */
+const isPunctuationTolerantField = (fieldName) => {
+	return PUNCTUATION_TOLERANT_FIELDS.has(fieldName);
+};
+
+/**
+ * Value used for minLength/maxLength validation (punctuation ignored for tolerant fields).
+ * @param {string} fieldName
+ * @param {unknown} value
+ */
+const valueForLengthCheck = (fieldName, value) => {
+	const text = String(value);
+	if (!isPunctuationTolerantField(fieldName)) return text;
+	return stripFormatting(text);
+};
+
+/**
+ * Normalize request params: trim plate whitespace; leave document numbers as entered.
+ * @param {Record<string, unknown>} params
+ */
+const normalizeRequestParams = (params) => {
+	if (!params || typeof params !== "object") return {};
+
+	const normalized = { ...params };
+
+	for (const [field, value] of Object.entries(normalized)) {
+		if (value == null || value === "") continue;
+
+		if (field === "plate" || field === "card") {
+			normalized[field] = String(value).replace(/\s+/g, "").trim();
+		}
+	}
+
+	return normalized;
+};
+
+module.exports = {
+	PUNCTUATION_TOLERANT_FIELDS,
+	stripFormatting,
+	isPunctuationTolerantField,
+	valueForLengthCheck,
+	normalizeRequestParams,
+};

package/lib/filters.js

@@ -3,23 +3,30 @@
 /**
  * @param {import("./types").AppFeature} feature
  * @param {import("./types").McpConfig} config
+ * @param {Set<string>|null} grantedFeatureCodes
  */
-const isEligibleFeature = (feature, config) => {
+const isEligibleFeature = (feature, config, grantedFeatureCodes = null) => {
 	if (!feature?.code || !feature?.url) return false;
 	if (config.smartCheckOnly && !feature.smartCheckEnabled) return false;
 	if (config.codeAllowlist.length && !config.codeAllowlist.includes(feature.code)) return false;
 	if (config.countryFilter.length && !config.countryFilter.includes(feature.country)) return false;
 	if (config.baseCategoryFilter.length && !config.baseCategoryFilter.includes(feature.baseCategory)) return false;
+
+	if (feature.requiresClientFeature && grantedFeatureCodes && !grantedFeatureCodes.has(feature.code)) {
+		return false;
+	}
+
 	return true;
 };
 
 /**
  * @param {import("./types").AppFeature[]} features
  * @param {import("./types").McpConfig} config
+ * @param {Set<string>|null} [grantedFeatureCodes]
  */
-const filterFeatures = (features, config) => {
+const filterFeatures = (features, config, grantedFeatureCodes = null) => {
 	if (!Array.isArray(features)) return [];
-	return features.filter((feature) => isEligibleFeature(feature, config));
+	return features.filter((feature) => isEligibleFeature(feature, config, grantedFeatureCodes));
 };
 
 /**

package/lib/meta-tools.js

@@ -97,8 +97,11 @@ const handleGetFeature = async (catalogCache, args = {}) => {
 		throw new Error(`feature_not_found:${code}`);
 	}
 
+	const toolName = catalogCache.state?.registry?.featureCodeToToolName?.get(code) || null;
+
 	return {
 		...toFeatureSummary(feature),
+		toolName,
 		dependencies: feature.dependencies || [],
 		inputSchema: buildInputSchema(feature),
 	};