@verifik/mcp 0.0.0-stage → 0.1.2

package/lib/catalog.js

@@ -0,0 +1,183 @@
+"use strict";
+
+const { filterFeatures } = require("./filters");
+const { buildToolRegistry, toMcpToolDefinition } = require("./tool-schema");
+const { fetchGrantedFeatureCodes } = require("./client-features");
+
+const CATALOG_PATH = "/v2/app-features/my-list";
+const PAGE_LIMIT = 500;
+
+/**
+ * @param {import("./types").McpConfig} config
+ */
+const fetchCatalogPage = async (config, page = 1) => {
+	const url = new URL(`${config.apiBase}${CATALOG_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",
+		},
+	});
+
+	const body = await readResponseBody(response);
+
+	if (!response.ok) {
+		throw new Error(`Catalog request failed (${response.status}): ${formatBodyForError(body)}`);
+	}
+
+	return normalizeCatalogResponse(body);
+};
+
+/**
+ * @param {unknown} body
+ */
+const normalizeCatalogResponse = (body) => {
+	const payload = body && typeof body === "object" ? body : {};
+	const data = Array.isArray(payload.data)
+		? payload.data
+		: Array.isArray(payload.data?.docs)
+			? payload.data.docs
+			: [];
+
+	return {
+		features: data,
+		page: Number(payload.page) || 1,
+		pages: Number(payload.pages) || 1,
+		total: Number(payload.total) || data.length,
+	};
+};
+
+/**
+ * @param {import("./types").McpConfig} config
+ */
+const fetchAllCatalogFeatures = async (config) => {
+	const firstPage = await fetchCatalogPage(config, 1);
+	const features = [...firstPage.features];
+
+	for (let page = firstPage.page + 1; page <= firstPage.pages; page += 1) {
+		const nextPage = await fetchCatalogPage(config, page);
+		features.push(...nextPage.features);
+	}
+
+	return features;
+};
+
+/**
+ * @param {import("./types").McpConfig} config
+ * @returns {Promise<Set<string>|null>}
+ */
+const loadGrantedFeatureCodes = async (config) => {
+	try {
+		return await fetchGrantedFeatureCodes(config);
+	} catch {
+		return null;
+	}
+};
+
+/**
+ * @param {import("./types").McpConfig} config
+ */
+const loadCatalogState = async (config) => {
+	const [allFeatures, grantedFeatureCodes] = await Promise.all([
+		fetchAllCatalogFeatures(config),
+		loadGrantedFeatureCodes(config),
+	]);
+	const filteredFeatures = filterFeatures(allFeatures, config, grantedFeatureCodes);
+	const registry = buildToolRegistry(filteredFeatures);
+
+	const tools = [];
+
+	for (const [toolName, feature] of registry.toolNameToFeature.entries()) {
+		tools.push(toMcpToolDefinition(feature, toolName));
+	}
+
+	return {
+		features: filteredFeatures,
+		allFeatures,
+		tools,
+		registry,
+		grantedFeatureCodes,
+		loadedAt: new Date().toISOString(),
+	};
+};
+
+/**
+ * @param {Response} response
+ */
+const readResponseBody = async (response) => {
+	const contentType = response.headers.get("content-type") || "";
+
+	if (contentType.includes("application/json")) {
+		return response.json();
+	}
+
+	return response.text();
+};
+
+/**
+ * @param {unknown} body
+ */
+const formatBodyForError = (body) => {
+	if (typeof body === "string") return body.slice(0, 500);
+	try {
+		return JSON.stringify(body).slice(0, 500);
+	} catch {
+		return "unknown_error";
+	}
+};
+
+class CatalogCache {
+	/**
+	 * @param {import("./types").McpConfig} config
+	 */
+	constructor(config) {
+		this.config = config;
+		this.state = null;
+		this.loadingPromise = null;
+	}
+
+	async getState(forceRefresh = false) {
+		const shouldRefresh =
+			forceRefresh ||
+			!this.state ||
+			(this.config.catalogRefreshMs > 0 &&
+				Date.now() - Date.parse(this.state.loadedAt) >= this.config.catalogRefreshMs);
+
+		if (!shouldRefresh) return this.state;
+		if (this.loadingPromise) return this.loadingPromise;
+
+		this.loadingPromise = loadCatalogState(this.config)
+			.then((state) => {
+				this.state = state;
+				return state;
+			})
+			.finally(() => {
+				this.loadingPromise = null;
+			});
+
+		return this.loadingPromise;
+	}
+
+	findFeatureByCode(code) {
+		if (!this.state) return null;
+		return this.state.features.find((feature) => feature.code === code) || null;
+	}
+
+	resolveFeatureByToolName(toolName) {
+		if (!this.state) return null;
+		return this.state.registry.toolNameToFeature.get(toolName) || null;
+	}
+}
+
+module.exports = {
+	CATALOG_PATH,
+	fetchCatalogPage,
+	fetchAllCatalogFeatures,
+	loadCatalogState,
+	CatalogCache,
+	normalizeCatalogResponse,
+};

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

@@ -0,0 +1,75 @@
+"use strict";
+
+const DEFAULT_API_BASE = "https://api.verifik.co";
+
+/**
+ * @returns {import("./types").McpConfig}
+ */
+const loadConfig = () => {
+	const apiBase = String(process.env.VERIFIK_API_BASE || DEFAULT_API_BASE).replace(/\/+$/, "");
+	const token = String(process.env.VERIFIK_API_TOKEN || "").trim();
+
+	if (!token) {
+		throw new Error("VERIFIK_API_TOKEN is required (client JWT / API bearer token)");
+	}
+
+	const smartCheckOnly = parseBooleanEnv(process.env.VERIFIK_MCP_SMARTCHECK_ONLY, true);
+	const countryFilter = parseListEnv(process.env.VERIFIK_MCP_COUNTRY);
+	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,
+		token,
+		smartCheckOnly,
+		countryFilter,
+		baseCategoryFilter,
+		codeAllowlist,
+		catalogRefreshMs,
+		requestTimeoutMs,
+	};
+};
+
+/**
+ * @param {string|undefined} value
+ * @param {boolean} defaultValue
+ */
+const parseBooleanEnv = (value, defaultValue) => {
+	if (value == null || value === "") return defaultValue;
+	const normalized = String(value).trim().toLowerCase();
+	if (["1", "true", "yes", "on"].includes(normalized)) return true;
+	if (["0", "false", "no", "off"].includes(normalized)) return false;
+	return defaultValue;
+};
+
+/**
+ * @param {string|undefined} value
+ * @returns {string[]}
+ */
+const parseListEnv = (value) => {
+	if (!value || !String(value).trim()) return [];
+	return String(value)
+		.split(",")
+		.map((entry) => entry.trim())
+		.filter(Boolean);
+};
+
+/**
+ * @param {string|undefined} value
+ * @param {number} defaultValue
+ */
+const parsePositiveInt = (value, defaultValue) => {
+	if (value == null || value === "") return defaultValue;
+	const parsed = Number.parseInt(String(value), 10);
+	if (!Number.isFinite(parsed) || parsed < 0) return defaultValue;
+	return parsed;
+};
+
+module.exports = {
+	DEFAULT_API_BASE,
+	loadConfig,
+	parseBooleanEnv,
+	parseListEnv,
+};

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,
+};