@verifik/mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Open-Verifik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,231 @@
-# Temporary Holding Version
+# @verifik/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Thin [Model Context Protocol](https://modelcontextprotocol.io) adapter for Verifik SmartCheck / Database Screening endpoints.
+
+Each MCP tool maps 1:1 to an `AppFeature` from `GET /v2/app-features/my-list`. Tool calls proxy to the existing Verifik REST API with your API token, so auth, ClientFeature gating, and credit deduction stay unchanged.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  A[MCP Client\nCursor / Claude Desktop] -->|stdio JSON-RPC| B["@verifik/mcp"]
+  B -->|GET /v2/app-features/my-list| C[Verifik API]
+  B -->|Bearer token proxy| C
+  C --> D[Existing middleware chain\nvalidateClient + billing]
+```
+
+Data flow:
+
+1. On boot, the server loads the client catalog from `GET /v2/app-features/my-list`.
+2. Eligible features become MCP tools (name derived from `code`, schema from `dependencies[]`).
+3. `tools/call` proxies to `${VERIFIK_API_BASE}/${feature.url}` using the feature `method`.
+4. Credits are charged by the normal API path — this server does not implement billing.
+
+## Requirements
+
+- Node.js 18+
+- A Verifik **API token** from the Smart-Agent **API Tokens** screen (`/settings/api-key`)
+
+API tokens are client JWTs minted by `POST /v2/auth/renew-and-revoke` while you are logged in. They include `clientId` and `JWTPhrase`, so they work for the catalog call and for feature endpoints the MCP proxies.
+
+## Install (recommended)
+
+```bash
+npx -y @verifik/mcp
+```
+
+No global install required. MCP clients invoke the package via `npx` (see configuration below).
+
+### Local development fallback
+
+```bash
+cd verifik-mcp
+npm install
+node server.js
+```
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `VERIFIK_API_TOKEN` | **Yes** | — | API token / client JWT from Smart-Agent |
+| `VERIFIK_API_BASE` | No | `https://api.verifik.co` | API base URL (use `https://staging-api.verifik.co` for staging) |
+| `VERIFIK_MCP_SMARTCHECK_ONLY` | No | `true` | Only expose `smartCheckEnabled` features |
+| `VERIFIK_MCP_COUNTRY` | No | — | Comma-separated country filter (e.g. `Colombia,world`) |
+| `VERIFIK_MCP_BASE_CATEGORY` | No | — | Comma-separated `baseCategory` filter |
+| `VERIFIK_MCP_CODES` | No | — | Comma-separated feature code allowlist |
+| `VERIFIK_MCP_CATALOG_REFRESH_MS` | No | `0` | Optional in-memory catalog refresh interval |
+
+Security: keep the token in environment variables only. The server never logs the full JWT.
+
+## Cursor configuration (`mcp.json`)
+
+Add to your Cursor MCP settings (global or project-level):
+
+```json
+{
+  "mcpServers": {
+    "verifik-smartcheck": {
+      "command": "npx",
+      "args": ["-y", "@verifik/mcp"],
+      "env": {
+        "VERIFIK_API_TOKEN": "YOUR_API_TOKEN",
+        "VERIFIK_API_BASE": "https://api.verifik.co",
+        "VERIFIK_MCP_SMARTCHECK_ONLY": "true",
+        "VERIFIK_MCP_COUNTRY": "Colombia,world"
+      }
+    }
+  }
+}
+```
+
+## Claude Desktop configuration
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent Claude Desktop config file:
+
+```json
+{
+  "mcpServers": {
+    "verifik-smartcheck": {
+      "command": "npx",
+      "args": ["-y", "@verifik/mcp"],
+      "env": {
+        "VERIFIK_API_TOKEN": "YOUR_API_TOKEN",
+        "VERIFIK_API_BASE": "https://api.verifik.co"
+      }
+    }
+  }
+}
+```
+
+## Generic MCP JSON (other clients)
+
+```json
+{
+  "mcpServers": {
+    "verifik-smartcheck": {
+      "command": "npx",
+      "args": ["-y", "@verifik/mcp"],
+      "env": {
+        "VERIFIK_API_TOKEN": "YOUR_API_TOKEN",
+        "VERIFIK_API_BASE": "https://api.verifik.co",
+        "VERIFIK_MCP_SMARTCHECK_ONLY": "true"
+      }
+    }
+  }
+}
+```
+
+### Local repo fallback (no npm publish yet)
+
+```json
+{
+  "mcpServers": {
+    "verifik-smartcheck": {
+      "command": "node",
+      "args": ["/absolute/path/to/verifik-mcp/server.js"],
+      "env": {
+        "VERIFIK_API_TOKEN": "YOUR_API_TOKEN",
+        "VERIFIK_API_BASE": "https://api.verifik.co"
+      }
+    }
+  }
+}
+```
+
+Restart Cursor / Claude Desktop after editing MCP config.
+
+## Tools
+
+### Meta tools (no credit charge)
+
+- `verifik_list_catalog` — filtered feature summaries from the in-memory catalog
+- `verifik_get_feature` — full metadata + dependency JSON schema for one `code`
+
+### Feature tools
+
+One tool per eligible `AppFeature`:
+
+- **Name:** sanitized `code` (`A-Za-z0-9._-`, max 128 chars)
+- **Description:** name, country, description, credit note
+- **Input schema:** built from `dependencies[]`
+  - `String` → `string`
+  - `Number` / `Integer` → `number`
+  - `Boolean` → `boolean`
+  - `enum`, `min`, `max`, `description`, `required`
+- **Call behavior:** HTTP proxy to the feature `url` using `method` (`GET` query params by default)
+
+Features with binary/file dependencies (images, selfies, uploads) are skipped until a safe transport exists.
+
+## Smoke test
+
+### 1. Unit tests (no live token)
+
+```bash
+cd verifik-mcp
+npm test
+```
+
+### 2. Missing token exits cleanly
+
+```bash
+node server.js
+# stderr: VERIFIK_API_TOKEN is required (client JWT / API bearer token)
+# exit code: 1
+```
+
+### 3. Live catalog load (requires token)
+
+```bash
+export VERIFIK_API_TOKEN="YOUR_API_TOKEN"
+node -e "
+  const { loadConfig } = require('./lib/config');
+  const { loadCatalogState } = require('./lib/catalog');
+  (async () => {
+    const config = loadConfig();
+    const state = await loadCatalogState(config);
+    console.log('tools:', state.tools.length);
+    console.log('sample:', state.tools.slice(0, 3).map(t => t.name));
+  })().catch(err => { console.error(err.message); process.exit(1); });
+"
+```
+
+### 4. MCP stdio handshake
+
+Start the server via Cursor MCP panel, or use any MCP client that supports stdio transport.
+
+## Example tool call result
+
+Non-2xx responses are returned as MCP text with HTTP status and JSON body so agents can handle `404`, `409`, and `402` the same as REST:
+
+```json
+{
+  "httpStatus": 409,
+  "statusText": "Conflict",
+  "durationMs": 142,
+  "request": {
+    "method": "GET",
+    "url": "https://api.verifik.co/v2/co/cedula?documentType=CC"
+  },
+  "body": {
+    "code": "MissingParameter",
+    "message": "documentNumber is required"
+  }
+}
+```
+
+## Publishing
+
+Published as [`@verifik/mcp`](https://www.npmjs.com/package/@verifik/mcp) from this directory.
+
+Release tags use the `v*` prefix (for example `v0.1.0`). See the repository workflow `.github/workflows/publish.yml`.
+
+## Follow-ups
+
+- Streamable HTTP MCP transport for hosted deployments
+- Biometric / multipart endpoints once file upload bridging is defined
+
+## Related
+
+- GitHub issue: https://github.com/Open-Verifik/verifik-backend/issues/370
+- Support ticket: #1313

package/lib/catalog.js

@@ -0,0 +1,166 @@
+"use strict";
+
+const { filterFeatures } = require("./filters");
+const { buildToolRegistry, toMcpToolDefinition } = require("./tool-schema");
+
+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
+ */
+const loadCatalogState = async (config) => {
+	const allFeatures = await fetchAllCatalogFeatures(config);
+	const filteredFeatures = filterFeatures(allFeatures, config);
+	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,
+		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/config.js

@@ -0,0 +1,73 @@
+"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);
+
+	return {
+		apiBase,
+		token,
+		smartCheckOnly,
+		countryFilter,
+		baseCategoryFilter,
+		codeAllowlist,
+		catalogRefreshMs,
+	};
+};
+
+/**
+ * @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/filters.js

@@ -0,0 +1,46 @@
+"use strict";
+
+/**
+ * @param {import("./types").AppFeature} feature
+ * @param {import("./types").McpConfig} config
+ */
+const isEligibleFeature = (feature, config) => {
+	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;
+	return true;
+};
+
+/**
+ * @param {import("./types").AppFeature[]} features
+ * @param {import("./types").McpConfig} config
+ */
+const filterFeatures = (features, config) => {
+	if (!Array.isArray(features)) return [];
+	return features.filter((feature) => isEligibleFeature(feature, config));
+};
+
+/**
+ * @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,125 @@
+"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}`);
+	}
+
+	return {
+		...toFeatureSummary(feature),
+		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,104 @@
+"use strict";
+
+const {
+	buildFeatureRequestUrl,
+	normalizeHttpMethod,
+	sanitizeRequestParams,
+	splitRequestPayload,
+} = require("./url-builder");
+
+/**
+ * @param {import("./types").AppFeature} feature
+ * @param {Record<string, unknown>} args
+ * @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 { query, body } = splitRequestPayload(method, params);
+
+	const requestInit = {
+		method,
+		headers: {
+			Authorization: `Bearer ${config.token}`,
+			Accept: "application/json",
+		},
+	};
+
+	if (body !== undefined) {
+		requestInit.headers["Content-Type"] = "application/json";
+		requestInit.body = JSON.stringify(body);
+	}
+
+	const requestUrl = query ? appendQueryParams(url, query) : 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,
+		},
+	};
+};
+
+/**
+ * @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 } }} result
+ */
+const formatProxyResult = (result) => {
+	const payload = {
+		httpStatus: result.status,
+		statusText: result.statusText,
+		durationMs: result.durationMs,
+		request: result.request,
+		body: result.body,
+	};
+
+	return JSON.stringify(payload, null, 2);
+};
+
+module.exports = {
+	invokeFeature,
+	formatProxyResult,
+	appendQueryParams,
+};

package/lib/tool-schema.js

@@ -0,0 +1,164 @@
+"use strict";
+
+const { createHash } = require("node:crypto");
+
+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}`;
+};
+
+/**
+ * @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) => {
+	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 {import("./types").AppFeatureDependency} dependency
+ */
+const buildDependencyProperty = (dependency) => {
+	const property = {
+		type: mapDependencyType(dependency),
+	};
+
+	if (dependency.description) property.description = dependency.description;
+	if (dependency.default != null) property.default = dependency.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;
+
+	return property;
+};
+
+/**
+ * @param {import("./types").AppFeature} feature
+ */
+const buildInputSchema = (feature) => {
+	const dependencies = Array.isArray(feature?.dependencies) ? feature.dependencies : [];
+	const properties = {};
+	const required = [];
+
+	for (const dependency of dependencies) {
+		if (!dependency?.field || isBinaryDependency(dependency)) continue;
+
+		properties[dependency.field] = buildDependencyProperty(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 = sanitizeToolName(feature.code);
+
+		if (usedNames.has(toolName)) {
+			const suffix = createHash("sha1").update(feature.code).digest("hex").slice(0, 6);
+			toolName = sanitizeToolName(`${feature.code}_${suffix}`);
+		}
+
+		usedNames.add(toolName);
+		toolNameToFeature.set(toolName, feature);
+		featureCodeToToolName.set(feature.code, toolName);
+	}
+
+	return {
+		toolNameToFeature,
+		featureCodeToToolName,
+	};
+};
+
+/**
+ * @param {import("./types").AppFeature} feature
+ */
+const toMcpToolDefinition = (feature, toolName) => ({
+	name: toolName,
+	description: buildToolDescription(feature),
+	inputSchema: buildInputSchema(feature),
+});
+
+module.exports = {
+	sanitizeToolName,
+	mapDependencyType,
+	isBinaryDependency,
+	hasUnsupportedDependencies,
+	buildToolDescription,
+	buildInputSchema,
+	buildToolRegistry,
+	toMcpToolDefinition,
+};

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/package.json

@@ -1,6 +1,45 @@
 {
-  "name": "@verifik/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@verifik/mcp",
+	"version": "0.1.0",
+	"description": "MCP stdio server that exposes Verifik SmartCheck AppFeatures as MCP tools via REST proxy",
+	"main": "server.js",
+	"bin": {
+		"verifik-mcp": "./server.js"
+	},
+	"files": [
+		"server.js",
+		"lib/",
+		"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",
+		"verifik",
+		"smartcheck",
+		"model-context-protocol"
+	],
+	"author": "Open-Verifik",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Open-Verifik/verifik-mcp.git"
+	},
+	"homepage": "https://github.com/Open-Verifik/verifik-mcp#readme",
+	"bugs": {
+		"url": "https://github.com/Open-Verifik/verifik-mcp/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.31.0",
+		"zod": "^3.23.0"
+	}
+}

package/server.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+"use strict";
+
+const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const {
+	CallToolRequestSchema,
+	ListToolsRequestSchema,
+} = require("@modelcontextprotocol/sdk/types.js");
+
+const { loadConfig } = require("./lib/config");
+const { CatalogCache } = require("./lib/catalog");
+const { invokeFeature, formatProxyResult } = require("./lib/proxy");
+const {
+	META_TOOL_DEFINITIONS,
+	META_TOOL_NAMES,
+	handleListCatalog,
+	handleGetFeature,
+} = require("./lib/meta-tools");
+
+const { version: packageVersion } = require("./package.json");
+
+const SERVER_NAME = "verifik-smartcheck";
+const SERVER_VERSION = packageVersion;
+
+const logStderr = (message) => {
+	process.stderr.write(`[${SERVER_NAME}] ${message}\n`);
+};
+
+const createServer = async () => {
+	const config = loadConfig();
+	const catalogCache = new CatalogCache(config);
+
+	logStderr(`Loading catalog from ${config.apiBase} ...`);
+	await catalogCache.getState();
+	logStderr(`Catalog loaded with ${catalogCache.state.tools.length} proxy tools.`);
+
+	const server = new Server(
+		{
+			name: SERVER_NAME,
+			version: SERVER_VERSION,
+		},
+		{
+			capabilities: {
+				tools: {},
+			},
+		}
+	);
+
+	server.setRequestHandler(ListToolsRequestSchema, async () => {
+		const state = await catalogCache.getState();
+		return {
+			tools: [...META_TOOL_DEFINITIONS, ...state.tools],
+		};
+	});
+
+	server.setRequestHandler(CallToolRequestSchema, async (request) => {
+		const toolName = request.params.name;
+		const args = request.params.arguments || {};
+
+		try {
+			if (toolName === "verifik_list_catalog") {
+				const payload = await handleListCatalog(catalogCache, args);
+				return textResult(JSON.stringify(payload, null, 2));
+			}
+
+			if (toolName === "verifik_get_feature") {
+				const payload = await handleGetFeature(catalogCache, args);
+				return textResult(JSON.stringify(payload, null, 2));
+			}
+
+			const feature = catalogCache.resolveFeatureByToolName(toolName);
+
+			if (!feature) {
+				return errorResult(`Unknown tool: ${toolName}`);
+			}
+
+			const proxyResult = await invokeFeature(feature, args, config);
+			return textResult(formatProxyResult(proxyResult), !proxyResult.ok);
+		} catch (error) {
+			return errorResult(error instanceof Error ? error.message : String(error));
+		}
+	});
+
+	return server;
+};
+
+/**
+ * @param {string} text
+ * @param {boolean} isError
+ */
+const textResult = (text, isError = false) => ({
+	content: [{ type: "text", text }],
+	isError,
+});
+
+/**
+ * @param {string} message
+ */
+const errorResult = (message) => textResult(message, true);
+
+const main = async () => {
+	const server = await createServer();
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	logStderr("stdio transport connected.");
+};
+
+main().catch((error) => {
+	logStderr(error instanceof Error ? error.message : String(error));
+	process.exit(1);
+});