@verifik/mcp 0.0.0-stage → 0.1.2

package/lib/tool-schema.js

@@ -0,0 +1,245 @@
+"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 BINARY_TYPE_PATTERN = /^(buffer|file|binary|multipart|image|blob|base64)$/i;
+const BINARY_FIELD_PATTERN = /^(image|photo|selfie|file|pdf|attachment|biometric)$/i;
+
+/**
+ * @param {import("./types").AppFeatureDependency} dependency
+ */
+const mapDependencyType = (dependency) => {
+	const type = String(dependency?.type || "String").trim();
+
+	if (/^(number|integer|float|decimal)$/i.test(type)) return "number";
+	if (/^(boolean|bool)$/i.test(type)) return "boolean";
+	return "string";
+};
+
+/**
+ * @param {import("./types").AppFeatureDependency} dependency
+ */
+const isBinaryDependency = (dependency) => {
+	const type = String(dependency?.type || "").trim();
+	const field = String(dependency?.field || "").trim();
+
+	if (BINARY_TYPE_PATTERN.test(type)) return true;
+	if (BINARY_FIELD_PATTERN.test(field) && !/documentType|documentNumber/i.test(field)) return true;
+	return false;
+};
+
+/**
+ * @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 {string} featureCode
+ * @param {import("./types").AppFeatureDependency} dependency
+ */
+const buildDependencyProperty = (featureCode, dependency) => {
+	const meta = resolveFieldEnrichment(featureCode, dependency.field);
+	const property = {
+		type: meta.type || mapDependencyType(dependency),
+	};
+
+	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;
+
+	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 || isHiddenField(dependency.field) || isBinaryDependency(dependency)) {
+			continue;
+		}
+
+		properties[dependency.field] = buildDependencyProperty(feature.code, dependency);
+
+		if (dependency.required) required.push(dependency.field);
+	}
+
+	const schema = {
+		type: "object",
+		properties,
+		additionalProperties: false,
+	};
+
+	if (required.length) schema.required = required;
+
+	return schema;
+};
+
+/**
+ * @param {import("./types").AppFeature[]} features
+ */
+const buildToolRegistry = (features) => {
+	const toolNameToFeature = new Map();
+	const featureCodeToToolName = new Map();
+	const usedNames = new Set();
+
+	for (const feature of features) {
+		if (!feature?.code || !feature?.url || hasUnsupportedDependencies(feature)) continue;
+
+		let toolName = normalizeToolName(feature.code);
+
+		if (usedNames.has(toolName)) {
+			const suffix = createHash("sha1").update(feature.code).digest("hex").slice(0, 6);
+			toolName = `${toolName.slice(0, 121)}_${suffix}`;
+		}
+
+		usedNames.add(toolName);
+		toolNameToFeature.set(toolName, feature);
+		featureCodeToToolName.set(feature.code, toolName);
+	}
+
+	return {
+		toolNameToFeature,
+		featureCodeToToolName,
+	};
+};
+
+/**
+ * @param {import("./types").AppFeature} feature
+ * @param {string} toolName
+ */
+const toMcpToolDefinition = (feature, toolName) => ({
+	name: toolName,
+	description: buildToolDescription(feature),
+	inputSchema: buildInputSchema(feature),
+});
+
+module.exports = {
+	mapDependencyType,
+	isBinaryDependency,
+	hasUnsupportedDependencies,
+	buildInputSchema,
+	buildToolRegistry,
+	toMcpToolDefinition,
+	normalizeToolName,
+};

package/lib/url-builder.js

@@ -0,0 +1,58 @@
+"use strict";
+
+/**
+ * Normalize an AppFeature URL into an absolute API URL.
+ * AppFeature.url is stored without a leading slash and already includes the version prefix (e.g. "v2/co/cedula").
+ * @param {string} apiBase
+ * @param {string} featureUrl
+ */
+const buildFeatureRequestUrl = (apiBase, featureUrl) => {
+	const base = String(apiBase || "").replace(/\/+$/, "");
+	const path = String(featureUrl || "").replace(/^\/+/, "");
+	return `${base}/${path}`;
+};
+
+/**
+ * @param {string} method
+ */
+const normalizeHttpMethod = (method) => {
+	const normalized = String(method || "GET").trim().toUpperCase();
+	return normalized || "GET";
+};
+
+/**
+ * @param {Record<string, unknown>} args
+ */
+const sanitizeRequestParams = (args) => {
+	if (!args || typeof args !== "object") return {};
+
+	const params = {};
+
+	for (const [key, value] of Object.entries(args)) {
+		if (value === undefined || value === null || value === "") continue;
+		params[key] = value;
+	}
+
+	return params;
+};
+
+/**
+ * @param {string} method
+ * @param {Record<string, unknown>} params
+ */
+const splitRequestPayload = (method, params) => {
+	const normalizedMethod = normalizeHttpMethod(method);
+
+	if (normalizedMethod === "GET" || normalizedMethod === "DELETE") {
+		return { query: params, body: undefined };
+	}
+
+	return { query: undefined, body: params };
+};
+
+module.exports = {
+	buildFeatureRequestUrl,
+	normalizeHttpMethod,
+	sanitizeRequestParams,
+	splitRequestPayload,
+};

package/lib/validate-args.js

@@ -0,0 +1,230 @@
+"use strict";
+
+const {
+	getValidationRule,
+	resolveFieldEnrichment,
+	buildFieldDescription,
+} = require("./field-enrichment");
+const { valueForLengthCheck } = require("./field-normalize");
+
+const DD_MM_YYYY = /^(0[1-9]|[12][0-9]|3[01])\/(0[1-9]|1[0-2])\/\d{4}$/;
+
+const CRIMINAL_DOB_TYPES = new Set(["CCPA", "CI", "CPF", "DUI", "CCUY"]);
+const CRIMINAL_EXPEDITION_TYPES = new Set(["CE", "PPT", "PEP"]);
+
+/**
+ * @param {unknown} value
+ */
+const hasValue = (value) => value !== undefined && value !== null && value !== "";
+
+/**
+ * @param {unknown} value
+ */
+const isTruthyBoolean = (value) => value === true || value === "true";
+
+/**
+ * @param {Record<string, unknown>} args
+ * @param {string} field
+ * @param {Record<string, unknown>} meta
+ */
+const validateStringField = (args, field, meta) => {
+	const value = args[field];
+
+	if (!hasValue(value)) return null;
+
+	const text = String(value);
+	const measured = valueForLengthCheck(field, text);
+
+	if (meta.minLength != null && measured.length < Number(meta.minLength)) {
+		return `${field} must be at least ${meta.minLength} characters (punctuation such as dots or dashes is ignored).`;
+	}
+
+	if (meta.maxLength != null && measured.length > Number(meta.maxLength)) {
+		return `${field} must be at most ${meta.maxLength} characters (punctuation such as dots or dashes is ignored).`;
+	}
+
+	if (meta.pattern) {
+		const regex = new RegExp(meta.pattern);
+		if (!regex.test(text)) {
+			const formatHint = meta.format ? ` Expected format: ${meta.format}.` : "";
+			return `${field} has an invalid format.${formatHint}`;
+		}
+	}
+
+	if (meta.format === "DD/MM/YYYY" && !DD_MM_YYYY.test(text)) {
+		return `${field} must be DD/MM/YYYY (example: 15/03/1990).`;
+	}
+
+	return null;
+};
+
+/**
+ * @param {Record<string, unknown>} args
+ * @param {import("./types").AppFeature} feature
+ * @param {object} inputSchema
+ */
+const validateRequiredFields = (args, feature, inputSchema) => {
+	const required = Array.isArray(inputSchema.required) ? inputSchema.required : [];
+
+	for (const field of required) {
+		if (!hasValue(args[field])) {
+			const meta = resolveFieldEnrichment(feature.code, field);
+			const hint = buildFieldDescription(meta);
+			return hint ? `${field} is required. ${hint}` : `${field} is required.`;
+		}
+	}
+
+	return null;
+};
+
+/**
+ * @param {Record<string, unknown>} args
+ * @param {import("./types").AppFeature} feature
+ * @param {object} inputSchema
+ */
+const validateFieldConstraints = (args, feature, inputSchema) => {
+	const properties = inputSchema.properties || {};
+
+	for (const [field, schema] of Object.entries(properties)) {
+		if (!hasValue(args[field])) continue;
+
+		if (schema.enum && !schema.enum.includes(args[field])) {
+			return `${field} must be one of: ${schema.enum.join(", ")}.`;
+		}
+
+		if (schema.type === "number" && Number.isNaN(Number(args[field]))) {
+			return `${field} must be a number.`;
+		}
+
+		if (schema.type === "boolean" && typeof args[field] !== "boolean") {
+			return `${field} must be true or false.`;
+		}
+
+		if (schema.type === "string") {
+			const meta = resolveFieldEnrichment(feature.code, field);
+			const error = validateStringField(args, field, { ...meta, ...schema });
+			if (error) return error;
+		}
+	}
+
+	return null;
+};
+
+/**
+ * @param {Record<string, unknown>} args
+ */
+const validateCriminalSearch = (args) => {
+	const fullName = hasValue(args.fullName);
+	const documentType = hasValue(args.documentType);
+	const documentNumber = hasValue(args.documentNumber);
+
+	if (!fullName && !(documentType && documentNumber)) {
+		return "Provide fullName, or both documentType and documentNumber.";
+	}
+
+	if (!fullName) {
+		if (!documentType) return "documentType is required when searching by document.";
+		if (!documentNumber) return "documentNumber is required when searching by document.";
+	}
+
+	if (documentType && CRIMINAL_DOB_TYPES.has(String(args.documentType)) && !hasValue(args.dateOfBirth)) {
+		return `dateOfBirth is required for documentType ${args.documentType}. Format: DD/MM/YYYY.`;
+	}
+
+	if (
+		documentType &&
+		CRIMINAL_EXPEDITION_TYPES.has(String(args.documentType)) &&
+		!hasValue(args.expirationDate)
+	) {
+		return `expirationDate is required for documentType ${args.documentType}. Format: DD/MM/YYYY.`;
+	}
+
+	if (hasValue(args.dateOfBirth) && !DD_MM_YYYY.test(String(args.dateOfBirth))) {
+		return "dateOfBirth must be DD/MM/YYYY (example: 15/03/1990).";
+	}
+
+	if (hasValue(args.expirationDate) && !DD_MM_YYYY.test(String(args.expirationDate))) {
+		return "expirationDate must be DD/MM/YYYY (example: 01/12/2023).";
+	}
+
+	return null;
+};
+
+/**
+ * @param {Record<string, unknown>} args
+ */
+const validateMatrimonioSearch = (args) => {
+	const hasSerial = hasValue(args.serial);
+	const hasDocument = hasValue(args.documentNumber);
+	const hasName =
+		hasValue(args.primerNombre) &&
+		hasValue(args.primerApellido) &&
+		hasValue(args.sexo) &&
+		hasValue(args.fecha);
+
+	if (!hasSerial && !hasDocument && !hasName) {
+		return "Provide serial, or documentNumber with sexo, or primerNombre + primerApellido + sexo + fecha.";
+	}
+
+	if (hasDocument && !hasValue(args.sexo)) {
+		return "sexo is required when searching by documentNumber.";
+	}
+
+	if (hasName && !DD_MM_YYYY.test(String(args.fecha))) {
+		return "fecha must be DD/MM/YYYY (example: 15/06/2010).";
+	}
+
+	return null;
+};
+
+/**
+ * @param {Record<string, unknown>} args
+ */
+const validateDocumentLiveness = (args) => {
+	if (!hasValue(args.image)) {
+		return "image is required. Provide a base64-encoded JPEG/PNG string or a public HTTPS URL.";
+	}
+
+	const validations = [
+		"validateScreenReplay",
+		"validatePrintedCopy",
+		"validatePortraitSubstitution",
+		"validateDigitalManipulation",
+	];
+
+	if (!validations.some((field) => isTruthyBoolean(args[field]))) {
+		return "Enable at least one validation: validateScreenReplay, validatePrintedCopy, validatePortraitSubstitution, or validateDigitalManipulation.";
+	}
+
+	return null;
+};
+
+/**
+ * @param {Record<string, unknown>} args
+ * @param {import("./types").AppFeature} feature
+ * @param {object} inputSchema
+ */
+const validateToolArgs = (args, feature, inputSchema) => {
+	const params = args && typeof args === "object" ? args : {};
+
+	const requiredError = validateRequiredFields(params, feature, inputSchema);
+	if (requiredError) return requiredError;
+
+	const constraintError = validateFieldConstraints(params, feature, inputSchema);
+	if (constraintError) return constraintError;
+
+	const rule = getValidationRule(feature.code);
+
+	if (rule === "criminal_search") return validateCriminalSearch(params);
+	if (rule === "matrimonio_search") return validateMatrimonioSearch(params);
+	if (rule === "document_liveness") return validateDocumentLiveness(params);
+
+	return null;
+};
+
+module.exports = {
+	validateToolArgs,
+	validateCriminalSearch,
+	validateMatrimonioSearch,
+	validateDocumentLiveness,
+};

package/package.json

@@ -1,6 +1,61 @@
 {
-  "name": "@verifik/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@verifik/mcp",
+	"version": "0.1.2",
+	"description": "Use Verifik identity verification, document checks, and background-screening APIs from Cursor, Claude Desktop, or any MCP client — across Latin America and worldwide.",
+	"main": "server.js",
+	"bin": {
+		"verifik-mcp": "server.js"
+	},
+	"files": [
+		"server.js",
+		"lib/",
+		"data/",
+		"docs/",
+		"README.md"
+	],
+	"scripts": {
+		"start": "node server.js",
+		"test": "node --test tests/*.test.js",
+		"test:sandbox": "node --test tests/*.test.js"
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"keywords": [
+		"mcp",
+		"model-context-protocol",
+		"verifik",
+		"smartcheck",
+		"identity-verification",
+		"kyc",
+		"kyb",
+		"aml",
+		"background-check",
+		"database-screening",
+		"latin-america",
+		"colombia",
+		"mexico",
+		"peru",
+		"chile",
+		"brazil",
+		"cursor",
+		"claude"
+	],
+	"author": "Open-Verifik",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Open-Verifik/verifik-mcp.git"
+	},
+	"homepage": "https://docs.verifik.co",
+	"bugs": {
+		"url": "https://verifik.co"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.31.0",
+		"zod": "^3.23.0"
+	}
+}