@verifik/mcp 0.1.0 → 0.1.2

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,14 +1,16 @@
 {
 	"name": "@verifik/mcp",
-	"version": "0.1.0",
-	"description": "MCP stdio server that exposes Verifik SmartCheck AppFeatures as MCP tools via REST proxy",
+	"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"
+		"verifik-mcp": "server.js"
 	},
 	"files": [
 		"server.js",
 		"lib/",
+		"data/",
+		"docs/",
 		"README.md"
 	],
 	"scripts": {
@@ -21,9 +23,23 @@
 	},
 	"keywords": [
 		"mcp",
+		"model-context-protocol",
 		"verifik",
 		"smartcheck",
-		"model-context-protocol"
+		"identity-verification",
+		"kyc",
+		"kyb",
+		"aml",
+		"background-check",
+		"database-screening",
+		"latin-america",
+		"colombia",
+		"mexico",
+		"peru",
+		"chile",
+		"brazil",
+		"cursor",
+		"claude"
 	],
 	"author": "Open-Verifik",
 	"license": "MIT",
@@ -31,9 +47,9 @@
 		"type": "git",
 		"url": "git+https://github.com/Open-Verifik/verifik-mcp.git"
 	},
-	"homepage": "https://github.com/Open-Verifik/verifik-mcp#readme",
+	"homepage": "https://docs.verifik.co",
 	"bugs": {
-		"url": "https://github.com/Open-Verifik/verifik-mcp/issues"
+		"url": "https://verifik.co"
 	},
 	"publishConfig": {
 		"access": "public"

package/server.js

@@ -10,13 +10,14 @@ const {
 
 const { loadConfig } = require("./lib/config");
 const { CatalogCache } = require("./lib/catalog");
-const { invokeFeature, formatProxyResult } = require("./lib/proxy");
+const { invokeFeature, formatProxyResult, formatValidationError } = require("./lib/proxy");
 const {
 	META_TOOL_DEFINITIONS,
-	META_TOOL_NAMES,
 	handleListCatalog,
 	handleGetFeature,
 } = require("./lib/meta-tools");
+const { buildInputSchema } = require("./lib/tool-schema");
+const { validateToolArgs } = require("./lib/validate-args");
 
 const { version: packageVersion } = require("./package.json");
 
@@ -61,12 +62,12 @@ const createServer = async () => {
 		try {
 			if (toolName === "verifik_list_catalog") {
 				const payload = await handleListCatalog(catalogCache, args);
-				return textResult(JSON.stringify(payload, null, 2));
+				return structuredResult(payload);
 			}
 
 			if (toolName === "verifik_get_feature") {
 				const payload = await handleGetFeature(catalogCache, args);
-				return textResult(JSON.stringify(payload, null, 2));
+				return structuredResult(payload);
 			}
 
 			const feature = catalogCache.resolveFeatureByToolName(toolName);
@@ -75,8 +76,26 @@ const createServer = async () => {
 				return errorResult(`Unknown tool: ${toolName}`);
 			}
 
+			const inputSchema = buildInputSchema(feature);
+			const validationError = validateToolArgs(args, feature, inputSchema);
+
+			if (validationError) {
+				const formatted = formatValidationError(validationError);
+				return {
+					content: [{ type: "text", text: formatted.text }],
+					structuredContent: formatted.structuredContent,
+					isError: true,
+				};
+			}
+
 			const proxyResult = await invokeFeature(feature, args, config);
-			return textResult(formatProxyResult(proxyResult), !proxyResult.ok);
+			const formatted = formatProxyResult(proxyResult);
+
+			return {
+				content: [{ type: "text", text: formatted.text }],
+				structuredContent: formatted.structuredContent,
+				isError: !proxyResult.ok,
+			};
 		} catch (error) {
 			return errorResult(error instanceof Error ? error.message : String(error));
 		}
@@ -86,18 +105,27 @@ const createServer = async () => {
 };
 
 /**
- * @param {string} text
- * @param {boolean} isError
+ * @param {unknown} payload
  */
-const textResult = (text, isError = false) => ({
-	content: [{ type: "text", text }],
-	isError,
-});
+const structuredResult = (payload) => {
+	const text = JSON.stringify(payload, null, 2);
+	return {
+		content: [{ type: "text", text }],
+		structuredContent: payload,
+	};
+};
 
 /**
  * @param {string} message
  */
-const errorResult = (message) => textResult(message, true);
+const errorResult = (message) => {
+	const formatted = formatValidationError(message);
+	return {
+		content: [{ type: "text", text: formatted.text }],
+		structuredContent: formatted.structuredContent,
+		isError: true,
+	};
+};
 
 const main = async () => {
 	const server = await createServer();