@verifik/mcp 0.1.0 → 0.1.2

package/lib/proxy.js

@@ -6,6 +6,45 @@ const {
 	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
@@ -13,9 +52,13 @@ const {
  * @param {import("./types").McpConfig} config
  */
 const invokeFeature = async (feature, args, config) => {
-	const method = normalizeHttpMethod(feature.method);
-	const url = buildFeatureRequestUrl(config.apiBase, feature.url);
-	const params = sanitizeRequestParams(args);
+	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 = {
@@ -24,30 +67,53 @@ const invokeFeature = async (feature, args, config) => {
 			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);
+		requestInit.body = JSON.stringify({ ...body, includeCost: true });
 	}
 
-	const requestUrl = query ? appendQueryParams(url, query) : url;
+	const requestUrl = query ? appendQueryParams(url, { ...query, includeCost: "true" }) : url;
 	const startedAt = Date.now();
-	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,
-		},
-	};
+	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;
+	}
 };
 
 /**
@@ -83,22 +149,76 @@ const readResponseBody = async (response) => {
 };
 
 /**
- * @param {{ status: number, statusText?: string, body: unknown, durationMs?: number, request?: { method: string, url: string } }} result
+ * @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,
-		request: result.request,
-		body: result.body,
+		...(creditsCharged != null ? { creditsCharged } : {}),
+		...(result.ok ? { data } : {}),
 	};
 
-	return JSON.stringify(payload, null, 2);
+	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,
+};

package/lib/tool-schema.js

@@ -1,29 +1,18 @@
 "use strict";
 
 const { createHash } = require("node:crypto");
+const {
+	resolveFieldEnrichment,
+	isHiddenField,
+	getValidationRule,
+	buildFieldDescription,
+	getFeatureEnrichment,
+} = require("./field-enrichment");
+const { buildToolDescription } = require("./description");
+const { normalizeToolName } = require("./tool-naming");
 
-const TOOL_NAME_REGEX = /^[A-Za-z0-9._-]{1,128}$/;
 const BINARY_TYPE_PATTERN = /^(buffer|file|binary|multipart|image|blob|base64)$/i;
-const BINARY_FIELD_PATTERN = /(image|photo|selfie|file|document|pdf|attachment|biometric)/i;
-
-/**
- * @param {string} code
- */
-const sanitizeToolName = (code) => {
-	const raw = String(code || "")
-		.trim()
-		.replace(/[^A-Za-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}`;
-};
+const BINARY_FIELD_PATTERN = /^(image|photo|selfie|file|pdf|attachment|biometric)$/i;
 
 /**
  * @param {import("./types").AppFeatureDependency} dependency
@@ -52,53 +41,145 @@ const isBinaryDependency = (dependency) => {
  * @param {import("./types").AppFeature} feature
  */
 const hasUnsupportedDependencies = (feature) => {
+	if (getValidationRule(feature.code) === "document_liveness") return false;
+
 	const dependencies = Array.isArray(feature?.dependencies) ? feature.dependencies : [];
 	return dependencies.some((dependency) => isBinaryDependency(dependency));
 };
 
 /**
- * @param {import("./types").AppFeature} feature
- */
-const buildToolDescription = (feature) => {
-	const parts = [
-		feature.name || feature.code,
-		feature.country ? `(${feature.country})` : null,
-		feature.description ? `- ${feature.description}` : null,
-		"Charges Verifik credits via the REST API.",
-	].filter(Boolean);
-
-	return parts.join(" ");
-};
-
-/**
+ * @param {string} featureCode
  * @param {import("./types").AppFeatureDependency} dependency
  */
-const buildDependencyProperty = (dependency) => {
+const buildDependencyProperty = (featureCode, dependency) => {
+	const meta = resolveFieldEnrichment(featureCode, dependency.field);
 	const property = {
-		type: mapDependencyType(dependency),
+		type: meta.type || mapDependencyType(dependency),
 	};
 
-	if (dependency.description) property.description = dependency.description;
+	const description = buildFieldDescription(meta) || dependency.description;
+	if (description) property.description = description;
+
 	if (dependency.default != null) property.default = dependency.default;
+	if (meta.default != null) property.default = meta.default;
 	if (Array.isArray(dependency.enum) && dependency.enum.length) property.enum = dependency.enum;
-	if (dependency.min != null) property.minimum = dependency.min;
-	if (dependency.max != null) property.maximum = dependency.max;
+
+	const minLength = meta.minLength ?? parseLength(dependency.min);
+	const maxLength = meta.maxLength ?? parseLength(dependency.max);
+
+	if (minLength != null) property.minLength = minLength;
+	if (maxLength != null) property.maxLength = maxLength;
+	if (meta.pattern) property.pattern = meta.pattern;
 
 	return property;
 };
 
+/**
+ * @param {unknown} value
+ */
+const parseLength = (value) => {
+	if (value == null || value === "") return undefined;
+	const parsed = Number(value);
+	return Number.isFinite(parsed) ? parsed : undefined;
+};
+
+/**
+ * @param {import("./types").AppFeature} feature
+ */
+const buildDocumentLivenessSchema = (feature) => {
+	const fields = getFeatureEnrichment(feature.code).fields || {};
+	const properties = {};
+
+	for (const [field, meta] of Object.entries(fields)) {
+		const property = {
+			type: meta.type || "string",
+		};
+
+		const description = buildFieldDescription(meta);
+		if (description) property.description = description;
+		if (meta.default != null) property.default = meta.default;
+		if (meta.enum) property.enum = meta.enum;
+
+		properties[field] = property;
+	}
+
+	return {
+		type: "object",
+		properties,
+		required: ["image"],
+		additionalProperties: false,
+	};
+};
+
+/**
+ * @param {import("./types").AppFeature} feature
+ */
+const buildCriminalSearchSchema = (feature) => {
+	const dependencies = Array.isArray(feature?.dependencies) ? feature.dependencies : [];
+	const properties = {};
+
+	for (const dependency of dependencies) {
+		if (!dependency?.field || isHiddenField(dependency.field)) continue;
+		properties[dependency.field] = buildDependencyProperty(feature.code, dependency);
+	}
+
+	return {
+		type: "object",
+		properties,
+		anyOf: [
+			{ required: ["fullName"] },
+			{ required: ["documentType", "documentNumber"] },
+		],
+		additionalProperties: false,
+	};
+};
+
+/**
+ * @param {import("./types").AppFeature} feature
+ */
+const buildMatrimonioSearchSchema = (feature) => {
+	const dependencies = Array.isArray(feature?.dependencies) ? feature.dependencies : [];
+	const properties = {};
+
+	for (const dependency of dependencies) {
+		if (!dependency?.field || isHiddenField(dependency.field)) continue;
+		properties[dependency.field] = buildDependencyProperty(feature.code, dependency);
+	}
+
+	return {
+		type: "object",
+		properties,
+		description:
+			"Search by one of: (1) serial alone, (2) documentNumber + sexo, or (3) primerNombre + primerApellido + sexo + fecha.",
+		anyOf: [
+			{ required: ["serial"] },
+			{ required: ["documentNumber", "sexo"] },
+			{ required: ["primerNombre", "primerApellido", "sexo", "fecha"] },
+		],
+		additionalProperties: false,
+	};
+};
+
 /**
  * @param {import("./types").AppFeature} feature
  */
 const buildInputSchema = (feature) => {
+	const validationRule = getValidationRule(feature.code);
+
+	if (validationRule === "document_liveness") return buildDocumentLivenessSchema(feature);
+	if (validationRule === "criminal_search") return buildCriminalSearchSchema(feature);
+	if (validationRule === "matrimonio_search") return buildMatrimonioSearchSchema(feature);
+
 	const dependencies = Array.isArray(feature?.dependencies) ? feature.dependencies : [];
 	const properties = {};
 	const required = [];
 
 	for (const dependency of dependencies) {
-		if (!dependency?.field || isBinaryDependency(dependency)) continue;
+		if (!dependency?.field || isHiddenField(dependency.field) || isBinaryDependency(dependency)) {
+			continue;
+		}
 
-		properties[dependency.field] = buildDependencyProperty(dependency);
+		properties[dependency.field] = buildDependencyProperty(feature.code, dependency);
 
 		if (dependency.required) required.push(dependency.field);
 	}
@@ -125,11 +206,11 @@ const buildToolRegistry = (features) => {
 	for (const feature of features) {
 		if (!feature?.code || !feature?.url || hasUnsupportedDependencies(feature)) continue;
 
-		let toolName = sanitizeToolName(feature.code);
+		let toolName = normalizeToolName(feature.code);
 
 		if (usedNames.has(toolName)) {
 			const suffix = createHash("sha1").update(feature.code).digest("hex").slice(0, 6);
-			toolName = sanitizeToolName(`${feature.code}_${suffix}`);
+			toolName = `${toolName.slice(0, 121)}_${suffix}`;
 		}
 
 		usedNames.add(toolName);
@@ -145,6 +226,7 @@ const buildToolRegistry = (features) => {
 
 /**
  * @param {import("./types").AppFeature} feature
+ * @param {string} toolName
  */
 const toMcpToolDefinition = (feature, toolName) => ({
 	name: toolName,
@@ -153,12 +235,11 @@ const toMcpToolDefinition = (feature, toolName) => ({
 });
 
 module.exports = {
-	sanitizeToolName,
 	mapDependencyType,
 	isBinaryDependency,
 	hasUnsupportedDependencies,
-	buildToolDescription,
 	buildInputSchema,
 	buildToolRegistry,
 	toMcpToolDefinition,
+	normalizeToolName,
 };