@verifik/mcp 0.0.0-stage → 0.1.2

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,544 @@
-# 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.
+Connect your AI assistant to **Verifik** — identity verification, document checks, vehicle lookups, business validation, and background screening across Latin America and worldwide. This package is a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that exposes the Verifik APIs your account already has access to as tools in Cursor, Claude Desktop, or any MCP client.
+
+Each paid tool call goes straight to the Verifik REST API with your API token. Credits are charged on your Verifik account the same way as a direct API call.
+
+## Quick start
+
+1. **Get an API token** — sign in to [Smart-Agent](https://ai.verifik.co), open **Settings → API Tokens**, and create a token.
+2. **Add the MCP server** to your client (examples below).
+3. **Restart** your MCP client, then ask your assistant to verify an identity, run a background check, or look up a vehicle.
+
+No install step is required. MCP clients run the server with:
+
+```bash
+npx -y @verifik/mcp
+```
+
+### Cursor (`mcp.json`)
+
+```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"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent config file on your OS:
+
+```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"
+      }
+    }
+  }
+}
+```
+
+### CLI (stdio MCP server)
+
+```bash
+export VERIFIK_API_TOKEN="YOUR_API_TOKEN"
+export VERIFIK_API_BASE="https://api.verifik.co"
+export VERIFIK_MCP_SMARTCHECK_ONLY="true"
+npx -y @verifik/mcp
+```
+
+The server speaks MCP over stdio. Point any MCP-compatible client at the same `npx` command and environment variables.
+
+## How tools are discovered
+
+You do **not** need to upgrade this package when Verifik adds new API endpoints. The server builds its tool list from your live account catalog at startup.
+
+### 1. Catalog load (`lib/catalog.js`)
+
+On boot, the server calls `GET /v2/app-features/my-list` on `VERIFIK_API_BASE` (default `https://api.verifik.co`), paginating through all pages (500 features per page). It sends your `VERIFIK_API_TOKEN` as a `Bearer` token.
+
+Each item in the response is an **AppFeature** with fields such as `code`, `name`, `description`, `url`, `method`, `country`, `baseCategory`, `smartCheckEnabled`, `dependencies[]`, and pricing metadata.
+
+### 2. Filtering (`lib/filters.js`)
+
+Features are kept or dropped based on your environment:
+
+| Filter | Source | Default / behavior |
+| --- | --- | --- |
+| SmartCheck only | `VERIFIK_MCP_SMARTCHECK_ONLY` | `true` — only features with `smartCheckEnabled: true` |
+| Country | `VERIFIK_MCP_COUNTRY` | Optional comma-separated list (e.g. `Colombia,Mexico,world`) |
+| Category | `VERIFIK_MCP_BASE_CATEGORY` | Optional comma-separated `baseCategory` values |
+| Code allowlist | `VERIFIK_MCP_CODES` | Optional comma-separated feature `code` values |
+
+A feature must have both `code` and `url` to become a tool.
+
+### 3. Tool schema (`lib/tool-schema.js`)
+
+Each eligible feature becomes one MCP tool:
+
+- **Tool name** — sanitized from the feature `code` (letters, digits, `.`, `_`, `-`; max 128 characters).
+- **Description** — feature name, country, description, plus a note that the call charges Verifik credits.
+- **Input schema** — built from `dependencies[]`:
+  - `String` → JSON Schema `string`
+  - `Number` / `Integer` → `number`
+  - `Boolean` → `boolean`
+  - `enum`, `min`, `max`, `description`, and `required` are preserved when present.
+
+Features whose dependencies include **binary fields** (images, selfies, file uploads, multipart) are **skipped** for now — the MCP transport cannot safely carry those payloads yet. Scalar-only endpoints (identity lookups, plates, background checks, etc.) are exposed.
+
+### 4. Meta tools (`lib/meta-tools.js`) — free, no credits
+
+Two helper tools are always available and do **not** call paid endpoints:
+
+| Tool | Purpose |
+| --- | --- |
+| `verifik_list_catalog` | List features available in the in-memory catalog, with optional `country`, `baseCategory`, `code`, and `smartCheckOnly` filters |
+| `verifik_get_feature` | Return full metadata and the input JSON Schema for one feature by `code` |
+
+Use these to search what your account can access before spending credits.
+
+### 5. Tool calls (`lib/proxy.js`)
+
+When the assistant calls a feature tool, the server proxies an HTTP request to `${VERIFIK_API_BASE}/${feature.url}` using the feature's `method` (usually `GET`). Arguments become query parameters (GET) or a JSON body (POST/PUT). Your token is sent as `Authorization: Bearer …`.
+
+The catalog can optionally refresh in memory when `VERIFIK_MCP_CATALOG_REFRESH_MS` is set to a positive interval (milliseconds).
+
+**New Verifik endpoints appear automatically** the next time the catalog loads — no package update required.
+
+## Response format
+
+MCP tool results are JSON text. Paid feature calls are wrapped so your assistant always sees the HTTP status and the Verifik body together:
+
+```json
+{
+  "httpStatus": 200,
+  "statusText": "OK",
+  "durationMs": 312,
+  "request": {
+    "method": "GET",
+    "url": "https://api.verifik.co/v2/co/cedula?documentType=CC&documentNumber=1234567890"
+  },
+  "body": { }
+}
+```
+
+### Verifik success envelope (`body` on HTTP 2xx)
+
+Successful Verifik API responses use a consistent envelope:
+
+| Field | Description |
+| --- | --- |
+| `data` | Main result — identity fields, vehicle record, background-check payload, etc. |
+| `signature` | Certification block: `message` (e.g. `"Certified by Verifik.co"`) and `dateTime` |
+| `id` | Short reference id for the certified response |
+| `billing` | Optional — present on some endpoints when dynamic pricing applies (`dynamicQueryApplied`, `chargedCredits`, etc.) |
+
+The examples below show the **full MCP tool result** (wrapper + `body`). All names and document numbers are fictional.
+
+---
+
+### Example 1 — Colombian national ID (cédula)
+
+**Tool:** `colombia_api_identity_lookup` (or the sanitized name for `v2/co/cedula` in your catalog)
+
+**Arguments:**
+
+```json
+{
+  "documentType": "CC",
+  "documentNumber": "1234567890"
+}
+```
+
+**MCP result (HTTP 200):**
+
+```json
+{
+  "httpStatus": 200,
+  "statusText": "OK",
+  "durationMs": 284,
+  "request": {
+    "method": "GET",
+    "url": "https://api.verifik.co/v2/co/cedula?documentType=CC&documentNumber=1234567890"
+  },
+  "body": {
+    "data": {
+      "documentType": "CC",
+      "documentNumber": "1234567890",
+      "firstName": "María",
+      "lastName": "Gómez López",
+      "fullName": "María Gómez López"
+    },
+    "signature": {
+      "message": "Certified by Verifik.co",
+      "dateTime": "January 16, 2024 3:44 PM"
+    },
+    "id": "AB123"
+  }
+}
+```
+
+---
+
+### Example 2 — Peruvian DNI
+
+**Tool:** feature for `v3/pe/cedula`
+
+**Arguments:**
+
+```json
+{
+  "documentType": "DNI",
+  "documentNumber": "87654321"
+}
+```
+
+**MCP result (HTTP 200):**
+
+```json
+{
+  "httpStatus": 200,
+  "statusText": "OK",
+  "durationMs": 410,
+  "request": {
+    "method": "GET",
+    "url": "https://api.verifik.co/v3/pe/cedula?documentType=DNI&documentNumber=87654321"
+  },
+  "body": {
+    "data": {
+      "documentType": "DNI",
+      "documentNumber": "87654321",
+      "firstName": "Carlos",
+      "lastName": "Vega Mendoza",
+      "fullName": "Carlos Vega Mendoza",
+      "dateOfBirth": "19-12-1995",
+      "civilStatus": "SOLTERO",
+      "sex": "M",
+      "address": "Av. Ejemplo 100"
+    },
+    "signature": {
+      "message": "Certified by Verifik.co",
+      "dateTime": "April 16, 2025 2:43 PM"
+    },
+    "id": "FHBCC"
+  }
+}
+```
+
+---
+
+### Example 3 — Mexico CURP
+
+**Tool:** feature for `v2/mx/curp`
+
+**Arguments:**
+
+```json
+{
+  "documentType": "CURP",
+  "documentNumber": "GOML900101HDFRNS09"
+}
+```
+
+**MCP result (HTTP 200):**
+
+```json
+{
+  "httpStatus": 200,
+  "statusText": "OK",
+  "durationMs": 356,
+  "request": {
+    "method": "GET",
+    "url": "https://api.verifik.co/v2/mx/curp?documentType=CURP&documentNumber=GOML900101HDFRNS09"
+  },
+  "body": {
+    "data": {
+      "documentType": "CURP",
+      "documentNumber": "GOML900101HDFRNS09",
+      "firstName": "Luis",
+      "lastName": "Ramírez",
+      "fullName": "Luis Ramírez",
+      "dateOfBirth": "1990-01-01",
+      "nationality": "Mexican"
+    },
+    "signature": {
+      "message": "Certified by Verifik.co",
+      "dateTime": "January 16, 2024 3:44 PM"
+    },
+    "id": "MX001"
+  }
+}
+```
+
+---
+
+### Example 4 — Chile RUN / RUT
+
+**Tool:** feature for `v2/cl/cedula`
+
+**Arguments:**
+
+```json
+{
+  "documentType": "RUN",
+  "documentNumber": "123456789"
+}
+```
+
+**MCP result (HTTP 200):**
+
+```json
+{
+  "httpStatus": 200,
+  "statusText": "OK",
+  "durationMs": 298,
+  "request": {
+    "method": "GET",
+    "url": "https://api.verifik.co/v2/cl/cedula?documentType=RUN&documentNumber=123456789"
+  },
+  "body": {
+    "data": {
+      "documentType": "RUN",
+      "documentNumber": "123456789",
+      "firstName": "Valentina",
+      "lastName": "Soto",
+      "fullName": "Valentina Soto"
+    },
+    "signature": {
+      "message": "Certified by Verifik.co",
+      "dateTime": "January 16, 2024 3:44 PM"
+    },
+    "id": "CL001"
+  }
+}
+```
+
+---
+
+### Example 5 — Colombia vehicle by plate
+
+**Tool:** feature for `v2/co/runt/vehicle-by-plate`
+
+**Arguments:**
+
+```json
+{
+  "plate": "ABC123"
+}
+```
+
+**MCP result (HTTP 200):**
+
+```json
+{
+  "httpStatus": 200,
+  "statusText": "OK",
+  "durationMs": 520,
+  "request": {
+    "method": "GET",
+    "url": "https://api.verifik.co/v2/co/runt/vehicle-by-plate?plate=ABC123"
+  },
+  "body": {
+    "data": {
+      "plate": "ABC123",
+      "brand": "Toyota",
+      "model": "Corolla",
+      "year": 2019,
+      "color": "Blanco",
+      "status": "Activo"
+    },
+    "signature": {
+      "message": "Certified by Verifik.co",
+      "dateTime": "March 10, 2025 11:20 AM"
+    },
+    "id": "RUNT01"
+  }
+}
+```
+
+---
+
+### Example 6 — Brazil background check (CPF)
+
+**Tool:** feature for `v2/br/background-check`
+
+**Arguments:**
+
+```json
+{
+  "documentType": "CPF",
+  "documentNumber": "123.456.789-00",
+  "dateOfBirth": "17/02/1990"
+}
+```
+
+**MCP result (HTTP 200):**
+
+```json
+{
+  "httpStatus": 200,
+  "statusText": "OK",
+  "durationMs": 1840,
+  "request": {
+    "method": "GET",
+    "url": "https://api.verifik.co/v2/br/background-check?documentType=CPF&documentNumber=123.456.789-00&dateOfBirth=17%2F02%2F1990"
+  },
+  "body": {
+    "data": {
+      "documentType": "CPF",
+      "documentNumber": "123.456.789-00",
+      "firstName": "Ana",
+      "lastName": "Oliveira",
+      "fullName": "Ana Oliveira",
+      "dateOfBirth": "17/02/1990",
+      "status": "clear",
+      "canIssueReports": true
+    },
+    "signature": {
+      "message": "Certified by Verifik.co",
+      "dateTime": "April 11, 2023 12:25 PM"
+    },
+    "id": "BR001"
+  }
+}
+```
+
+---
+
+### Document / face / KYC endpoints
+
+Verifik offers document validation, face comparison, liveness, and enrollment flows (e.g. `v2/face-recognition/*`, `v2/biometric-validations/*`, `v2/document-validations/*`). Those APIs often require **image or file uploads**. This MCP server currently exposes only features with scalar parameters — binary dependencies are filtered out at catalog load time. Use the [Verifik REST API](https://docs.verifik.co) or [SmartEnroll](https://docs.verifik.co) directly for full document and biometric workflows until file upload support is added here.
+
+---
+
+### Error responses
+
+Non-2xx responses are still returned as structured JSON (marked as MCP errors) so agents can handle them:
+
+**404 — record not found:**
+
+```json
+{
+  "httpStatus": 404,
+  "statusText": "Not Found",
+  "durationMs": 198,
+  "request": {
+    "method": "GET",
+    "url": "https://api.verifik.co/v2/co/cedula?documentType=CC&documentNumber=9999999999"
+  },
+  "body": {
+    "code": "DOCUMENT_NOT_FOUND",
+    "message": "Document not found"
+  }
+}
+```
+
+**409 — validation / missing parameter:**
+
+```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"
+  }
+}
+```
+
+## Country coverage
+
+The exact tools you see depend on **your Verifik plan and enabled features**. The table below lists countries and representative endpoint paths from the [Verifik API catalog](https://docs.verifik.co/reference/endpoint-doc-index/). Each paid call consumes credits on your account.
+
+| Country / region | Example capabilities | Example API paths |
+| --- | --- | --- |
+| **Argentina** | National ID, business, vehicle, criminal record | `v2/ar/cedula`, `v2/ar/company`, `v2/ar/vehicle` |
+| **Bolivia** | National ID, business, vehicle, SOAT | `v2/bo/cedula`, `v2/bo/company`, `v2/bo/vehicle` |
+| **Brazil** | National ID, CPF background check, business (CNPJ), vehicle | `v2/br/cedula`, `v2/br/background-check`, `v2/br/company` |
+| **Canada** | Business, provincial driver license & plates | `v2/ca/company`, `v2/ca/ontario/driver-license` |
+| **Chile** | National ID (RUN), taxpayer (RUT), vehicle, driver license | `v2/cl/cedula`, `v2/cl/taxpayer`, `v2/cl/vehicle` |
+| **Colombia** | National ID, foreigner ID, police/judicial checks, RUNT vehicles, business (RUES/DIAN) | `v2/co/cedula`, `v2/co/runt/vehicle-by-plate`, `v2/co/policia/consultar` |
+| **Costa Rica** | National ID, business, vehicle | `v2/cr/cedula`, `v2/cr/company`, `v2/cr/vehicle` |
+| **Dominican Republic** | National ID | `v2/do/cedula` |
+| **Ecuador** | National ID, vehicle & fines | `v2/ec/cedula`, `v2/ec/vehiculo/placa` |
+| **El Salvador** | National ID (DUI) | `v2/sv/dui` |
+| **Guatemala** | National ID | `v2/gt/cedula` |
+| **Honduras** | National ID | `v2/hn/cedula` |
+| **India** | Voter ID (EPIC) | `v2/in/epic` |
+| **Mexico** | CURP, INE validation, business, vehicle by plate | `v2/mx/curp`, `v2/mx/ine`, `v2/mx/vehiculo/placa` |
+| **Panama** | National ID, business | `v2/pa/cedula`, `v2/pa/company` |
+| **Paraguay** | National ID (CIC), business, vehicle | `v2/py/cic`, `v2/py/company`, `v2/py/vehicle` |
+| **Peru** | DNI (v3), foreigner ID, driver license, vehicle & SOAT | `v3/pe/cedula`, `v2/pe/vehiculo/placa`, `v2/pe/driver-license` |
+| **Spain** | National ID, business, vehicle | `v2/es/cedula`, `v2/es/company` |
+| **United States** | SSN verification, business, state driver licenses, vehicle/VIN | `v2/usa/ssn`, `v2/usa/company`, `v2/usa/vehicle` |
+| **Uruguay** | National ID | `v2/uy/cedula` |
+| **Venezuela** | National ID, foreigner ID | `v2/ve/cedula`, `v2/ve/foreigner-id` |
+| **Worldwide** | Sanctions & watchlists (DEA, FBI, Interpol, OFAC, UN, Europol), IP geolocation, phone lookup | `v2/dea`, `v2/ofac`, `v2/interpol`, `v2/look-ups/phone` |
+
+Run `verifik_list_catalog` in your MCP client to see the live list for your token. Filter by country with `VERIFIK_MCP_COUNTRY` or the `country` argument on the meta tool.
+
+## Configuration
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `VERIFIK_API_TOKEN` | **Yes** | — | API token from Smart-Agent → API Tokens |
+| `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` | When `true`, only expose SmartCheck-enabled features |
+| `VERIFIK_MCP_COUNTRY` | No | — | Comma-separated country filter (e.g. `Colombia,Mexico,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` | In-memory catalog refresh interval in ms (`0` = load once at startup) |
+| `VERIFIK_MCP_REQUEST_TIMEOUT_MS` | No | `90000` | Per-call HTTP timeout in ms (some endpoints can take 40–60s; increase if you see timeout errors) |
+
+## Security
+
+- Your API token stays on **your machine** in environment variables (or your MCP client's secure config). The server never logs the full token.
+- Tool calls go **directly** from your machine to `api.verifik.co` (or your configured base URL). This package does not proxy through a third-party host.
+- Use a dedicated API token with the minimum access your workflow needs. Rotate tokens from the Smart-Agent dashboard if compromised.
+- Handle personal data according to your privacy policy and applicable regulations. Verifik responses contain sensitive identity information.
+
+## Troubleshooting
+
+| Symptom | What to check |
+| --- | --- |
+| Server exits immediately with `VERIFIK_API_TOKEN is required` | Set `VERIFIK_API_TOKEN` in your MCP config `env` block |
+| No tools / empty catalog | Confirm the token is valid, your account has SmartCheck features enabled, and `VERIFIK_MCP_SMARTCHECK_ONLY` / country filters are not too restrictive |
+| `401` / authentication errors | Regenerate the token in Smart-Agent → API Tokens |
+| `402` / insufficient credits | Top up credits in your Verifik dashboard |
+| `404` on a lookup | The document or record was not found — normal for invalid or non-existent identifiers |
+| `409` on a lookup | Missing or invalid parameters — call `verifik_get_feature` with the feature `code` to see required fields |
+| Expected tool missing | It may require file/image upload (not supported yet), may not be SmartCheck-enabled, or may not be on your plan — use `verifik_list_catalog` to inspect |
+| Stale tool list after Verifik adds endpoints | Restart the MCP server, or set `VERIFIK_MCP_CATALOG_REFRESH_MS` to refresh periodically |
+
+## Links
+
+- [Verifik documentation](https://docs.verifik.co) — API reference, guides, and endpoint index
+- [Smart-Agent dashboard](https://ai.verifik.co) — API tokens, SmartCheck catalog, Check Lists
+- [Verifik website](https://verifik.co) — product overview and contact
+- [Model Context Protocol](https://modelcontextprotocol.io) — MCP specification
+
+## Requirements
+
+- Node.js 18+
+- A Verifik account with API access and available credits