@verifik/mcp 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,53 @@
+"use strict";
+
+/**
+ * @param {import("./types").AppFeature} feature
+ * @param {import("./types").McpConfig} config
+ * @param {Set<string>|null} grantedFeatureCodes
+ */
+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, grantedFeatureCodes = null) => {
+	if (!Array.isArray(features)) return [];
+	return features.filter((feature) => isEligibleFeature(feature, config, grantedFeatureCodes));
+};
+
+/**
+ * @param {import("./types").AppFeature} feature
+ */
+const toFeatureSummary = (feature) => ({
+	code: feature.code,
+	name: feature.name,
+	description: feature.description,
+	country: feature.country,
+	baseCategory: feature.baseCategory,
+	url: feature.url,
+	method: feature.method || "GET",
+	smartCheckEnabled: Boolean(feature.smartCheckEnabled),
+	price: feature.price,
+	smartCheckPrice: feature.smartCheckPrice,
+	dependencyCount: Array.isArray(feature.dependencies) ? feature.dependencies.length : 0,
+});
+
+module.exports = {
+	isEligibleFeature,
+	filterFeatures,
+	toFeatureSummary,
+};

package/lib/meta-tools.js

@@ -0,0 +1,128 @@
+"use strict";
+
+const { toFeatureSummary } = require("./filters");
+const { buildInputSchema } = require("./tool-schema");
+
+const LIST_CATALOG_TOOL = "verifik_list_catalog";
+const GET_FEATURE_TOOL = "verifik_get_feature";
+
+const META_TOOL_DEFINITIONS = [
+	{
+		name: LIST_CATALOG_TOOL,
+		description:
+			"List SmartCheck / Database Screening features available to this client without charging credits.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				country: {
+					type: "string",
+					description: "Optional comma-separated country filter (e.g. Colombia,world).",
+				},
+				baseCategory: {
+					type: "string",
+					description: "Optional comma-separated baseCategory filter.",
+				},
+				code: {
+					type: "string",
+					description: "Optional comma-separated feature code allowlist.",
+				},
+				smartCheckOnly: {
+					type: "boolean",
+					description: "When true, only return smartCheckEnabled features. Defaults to server config.",
+				},
+			},
+			additionalProperties: false,
+		},
+	},
+	{
+		name: GET_FEATURE_TOOL,
+		description: "Get full metadata and dependency schema for one AppFeature by code (no credit charge).",
+		inputSchema: {
+			type: "object",
+			properties: {
+				code: {
+					type: "string",
+					description: "AppFeature code (e.g. colombia_api_identity_lookup).",
+				},
+			},
+			required: ["code"],
+			additionalProperties: false,
+		},
+	},
+];
+
+const META_TOOL_NAMES = new Set(META_TOOL_DEFINITIONS.map((tool) => tool.name));
+
+/**
+ * @param {import("./catalog").CatalogCache} catalogCache
+ * @param {Record<string, unknown>} args
+ */
+const handleListCatalog = async (catalogCache, args = {}) => {
+	const state = await catalogCache.getState();
+	const countryFilter = parseOptionalList(args.country);
+	const baseCategoryFilter = parseOptionalList(args.baseCategory);
+	const codeFilter = parseOptionalList(args.code);
+	const smartCheckOnly =
+		args.smartCheckOnly === undefined ? undefined : Boolean(args.smartCheckOnly);
+
+	const features = state.features.filter((feature) => {
+		if (smartCheckOnly === true && !feature.smartCheckEnabled) return false;
+		if (countryFilter.length && !countryFilter.includes(feature.country)) return false;
+		if (baseCategoryFilter.length && !baseCategoryFilter.includes(feature.baseCategory)) return false;
+		if (codeFilter.length && !codeFilter.includes(feature.code)) return false;
+		return true;
+	});
+
+	return {
+		loadedAt: state.loadedAt,
+		total: features.length,
+		features: features.map(toFeatureSummary),
+	};
+};
+
+/**
+ * @param {import("./catalog").CatalogCache} catalogCache
+ * @param {Record<string, unknown>} args
+ */
+const handleGetFeature = async (catalogCache, args = {}) => {
+	const code = String(args.code || "").trim();
+
+	if (!code) {
+		throw new Error("code is required");
+	}
+
+	const feature = catalogCache.findFeatureByCode(code);
+
+	if (!feature) {
+		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),
+	};
+};
+
+/**
+ * @param {unknown} value
+ */
+const parseOptionalList = (value) => {
+	if (value == null || value === "") return [];
+	return String(value)
+		.split(",")
+		.map((entry) => entry.trim())
+		.filter(Boolean);
+};
+
+module.exports = {
+	LIST_CATALOG_TOOL,
+	GET_FEATURE_TOOL,
+	META_TOOL_DEFINITIONS,
+	META_TOOL_NAMES,
+	handleListCatalog,
+	handleGetFeature,
+};

package/lib/proxy.js

@@ -0,0 +1,224 @@
+"use strict";
+
+const {
+	buildFeatureRequestUrl,
+	normalizeHttpMethod,
+	sanitizeRequestParams,
+	splitRequestPayload,
+} = require("./url-builder");
+const { getRequestOverride, getParameterAliases } = require("./field-enrichment");
+const { normalizeRequestParams } = require("./field-normalize");
+const {
+	extractCreditsCharged,
+	buildProxyErrorPayload,
+	sanitizeResponseData,
+	classifyUpstreamError,
+	SERVICE_UNAVAILABLE_MESSAGE,
+} = require("./error-response");
+
+/**
+ * @param {import("./types").AppFeature} feature
+ */
+const resolveFeatureRequest = (feature) => {
+	const override = getRequestOverride(feature.code);
+
+	return {
+		method: override?.method || feature.method,
+		url: override?.url || feature.url,
+	};
+};
+
+/**
+ * @param {string} featureCode
+ * @param {Record<string, unknown>} params
+ */
+const applyParameterAliases = (featureCode, params) => {
+	const aliases = getParameterAliases(featureCode);
+	const mapped = { ...params };
+
+	for (const [from, to] of Object.entries(aliases)) {
+		if (mapped[from] !== undefined) {
+			mapped[to] = mapped[from];
+			delete mapped[from];
+		}
+	}
+
+	return mapped;
+};
+
+/**
+ * @param {import("./types").AppFeature} feature
+ * @param {Record<string, unknown>} args
+ * @param {import("./types").McpConfig} config
+ */
+const invokeFeature = async (feature, args, config) => {
+	const requestMeta = resolveFeatureRequest(feature);
+	const method = normalizeHttpMethod(requestMeta.method);
+	const url = buildFeatureRequestUrl(config.apiBase, requestMeta.url);
+	const params = applyParameterAliases(
+		feature.code,
+		normalizeRequestParams(sanitizeRequestParams(args))
+	);
+	const { query, body } = splitRequestPayload(method, params);
+
+	const requestInit = {
+		method,
+		headers: {
+			Authorization: `Bearer ${config.token}`,
+			Accept: "application/json",
+		},
+		signal: AbortSignal.timeout(config.requestTimeoutMs),
+	};
+
+	if (body !== undefined) {
+		requestInit.headers["Content-Type"] = "application/json";
+		requestInit.body = JSON.stringify({ ...body, includeCost: true });
+	}
+
+	const requestUrl = query ? appendQueryParams(url, { ...query, includeCost: "true" }) : url;
+	const startedAt = Date.now();
+
+	try {
+		const response = await fetch(requestUrl, requestInit);
+		const responseBody = await readResponseBody(response);
+		const durationMs = Date.now() - startedAt;
+
+		return {
+			ok: response.ok,
+			status: response.status,
+			statusText: response.statusText,
+			body: responseBody,
+			durationMs,
+			request: {
+				method,
+				url: requestUrl,
+			},
+		};
+	} catch (error) {
+		const durationMs = Date.now() - startedAt;
+
+		if (error?.name === "TimeoutError" || error?.name === "AbortError") {
+			return {
+				ok: false,
+				status: 504,
+				statusText: "Gateway Timeout",
+				body: null,
+				durationMs,
+				timedOut: true,
+				request: {
+					method,
+					url: requestUrl,
+				},
+			};
+		}
+
+		throw error;
+	}
+};
+
+/**
+ * @param {string} url
+ * @param {Record<string, unknown>} query
+ */
+const appendQueryParams = (url, query) => {
+	const target = new URL(url);
+
+	for (const [key, value] of Object.entries(query)) {
+		if (Array.isArray(value)) {
+			for (const entry of value) target.searchParams.append(key, String(entry));
+			continue;
+		}
+
+		target.searchParams.set(key, String(value));
+	}
+
+	return target.toString();
+};
+
+/**
+ * @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 {{ status: number, statusText?: string, body: unknown, durationMs?: number, request?: { method: string, url: string }, timedOut?: boolean }} result
+ */
+const formatProxyResult = (result) => {
+	if (result.timedOut) {
+		const payload = {
+			ok: false,
+			httpStatus: result.status,
+			statusText: result.statusText,
+			durationMs: result.durationMs,
+			error: {
+				code: "ServiceUnavailable",
+				message: SERVICE_UNAVAILABLE_MESSAGE,
+				retryable: true,
+			},
+		};
+
+		return {
+			text: JSON.stringify(payload, null, 2),
+			structuredContent: payload,
+		};
+	}
+
+	const creditsCharged = extractCreditsCharged(result.body);
+	const data = result.ok ? sanitizeResponseData(result.body) : undefined;
+
+	const payload = {
+		ok: result.ok,
+		httpStatus: result.status,
+		statusText: result.statusText,
+		durationMs: result.durationMs,
+		...(creditsCharged != null ? { creditsCharged } : {}),
+		...(result.ok ? { data } : {}),
+	};
+
+	if (!result.ok) {
+		Object.assign(payload, buildProxyErrorPayload(result));
+		delete payload.data;
+	}
+
+	return {
+		text: JSON.stringify(payload, null, 2),
+		structuredContent: payload,
+	};
+};
+
+/**
+ * @param {string} message
+ */
+const formatValidationError = (message) => {
+	const payload = {
+		ok: false,
+		error: {
+			code: "ValidationError",
+			message,
+		},
+	};
+
+	return {
+		text: JSON.stringify(payload, null, 2),
+		structuredContent: payload,
+	};
+};
+
+module.exports = {
+	invokeFeature,
+	formatProxyResult,
+	formatValidationError,
+	appendQueryParams,
+	applyParameterAliases,
+	resolveFeatureRequest,
+	extractCreditsCharged,
+	classifyUpstreamError,
+};

package/lib/tool-naming.js

@@ -0,0 +1,51 @@
+"use strict";
+
+const { createHash } = require("node:crypto");
+const { getToolNameOverride } = require("./field-enrichment");
+
+const TOOL_NAME_REGEX = /^[a-z][a-z0-9_]{0,127}$/;
+
+/**
+ * Normalize a catalog feature code into a stable MCP tool name.
+ * @param {string} code
+ */
+const normalizeToolName = (code) => {
+	const override = getToolNameOverride(code);
+	if (override) return override;
+
+	const raw = String(code || "")
+		.trim()
+		.toLowerCase()
+		.replace(/-/g, "_")
+		.replace(/[^a-z0-9_]+/g, "_")
+		.replace(/_+/g, "_")
+		.replace(/^_+|_+$/g, "");
+
+	if (!raw) return "verifik_feature";
+
+	if (raw.length <= 128 && TOOL_NAME_REGEX.test(raw)) return raw;
+
+	const hash = createHash("sha1").update(String(code)).digest("hex").slice(0, 8);
+	const prefix = raw.slice(0, 119).replace(/_+$/g, "");
+	return `${prefix}_${hash}`;
+};
+
+/**
+ * @param {import("./types").AppFeature[]} features
+ */
+const buildToolNameMapping = (features) => {
+	const mapping = new Map();
+
+	for (const feature of features) {
+		if (!feature?.code) continue;
+		mapping.set(feature.code, normalizeToolName(feature.code));
+	}
+
+	return mapping;
+};
+
+module.exports = {
+	normalizeToolName,
+	buildToolNameMapping,
+	TOOL_NAME_REGEX,
+};