@verifik/mcp 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +152 -37
  2. package/data/catalog-snapshot.json +7677 -0
  3. package/docs/endpoints.md +626 -0
  4. package/lib/config.js +1 -1
  5. package/lib/filters.js +105 -2
  6. package/lib/meta-tools.js +4 -3
  7. package/package.json +3 -2
package/README.md CHANGED
@@ -26,8 +26,7 @@ npx -y @verifik/mcp
26
26
  "args": ["-y", "@verifik/mcp"],
27
27
  "env": {
28
28
  "VERIFIK_API_TOKEN": "YOUR_API_TOKEN",
29
- "VERIFIK_API_BASE": "https://api.verifik.co",
30
- "VERIFIK_MCP_SMARTCHECK_ONLY": "true"
29
+ "VERIFIK_API_BASE": "https://api.verifik.co"
31
30
  }
32
31
  }
33
32
  }
@@ -46,8 +45,7 @@ npx -y @verifik/mcp
46
45
  "args": ["-y", "@verifik/mcp"],
47
46
  "env": {
48
47
  "VERIFIK_API_TOKEN": "YOUR_API_TOKEN",
49
- "VERIFIK_API_BASE": "https://api.verifik.co",
50
- "VERIFIK_MCP_SMARTCHECK_ONLY": "true"
48
+ "VERIFIK_API_BASE": "https://api.verifik.co"
51
49
  }
52
50
  }
53
51
  }
@@ -59,7 +57,6 @@ npx -y @verifik/mcp
59
57
  ```bash
60
58
  export VERIFIK_API_TOKEN="YOUR_API_TOKEN"
61
59
  export VERIFIK_API_BASE="https://api.verifik.co"
62
- export VERIFIK_MCP_SMARTCHECK_ONLY="true"
63
60
  npx -y @verifik/mcp
64
61
  ```
65
62
 
@@ -81,12 +78,39 @@ Features are kept or dropped based on your environment:
81
78
 
82
79
  | Filter | Source | Default / behavior |
83
80
  | --- | --- | --- |
84
- | SmartCheck only | `VERIFIK_MCP_SMARTCHECK_ONLY` | `true` — only features with `smartCheckEnabled: true` |
85
- | Country | `VERIFIK_MCP_COUNTRY` | Optional comma-separated list (e.g. `Colombia,Mexico,world`) |
81
+ | SmartCheck only | `VERIFIK_MCP_SMARTCHECK_ONLY` | `false` — expose every catalog feature your account can access; set `true` to limit to SmartCheck-enabled features |
82
+ | Country | `VERIFIK_MCP_COUNTRY` | Optional comma-separated list (see [accepted country values](#verifik_mcp_country-values) below) |
86
83
  | Category | `VERIFIK_MCP_BASE_CATEGORY` | Optional comma-separated `baseCategory` values |
87
84
  | Code allowlist | `VERIFIK_MCP_CODES` | Optional comma-separated feature `code` values |
85
+ | Client access | `clientHasAccess` on catalog items | When present on `my-list`, preferred over the `/v2/client-features` grant check |
88
86
 
89
- A feature must have both `code` and `url` to become a tool.
87
+ A feature must have both `code` and `url`, and must not be marked `legacy`, to become a tool.
88
+
89
+ ### Narrowing a large tool list
90
+
91
+ By default the server exposes **175+ tools** (every non-legacy scalar endpoint in the catalog that your account can access). Some MCP clients struggle with very large tool lists. Use environment filters to narrow what is registered at startup:
92
+
93
+ ```bash
94
+ # Colombia only (70 tools)
95
+ VERIFIK_MCP_COUNTRY=Colombia
96
+
97
+ # Multiple countries by catalog name
98
+ VERIFIK_MCP_COUNTRY=Colombia,Mexico,world
99
+
100
+ # ISO 3166-1 alpha-2 codes also work
101
+ VERIFIK_MCP_COUNTRY=CO,MX,world
102
+
103
+ # SmartCheck subset only (46 tools)
104
+ VERIFIK_MCP_SMARTCHECK_ONLY=true
105
+
106
+ # Category filter (identity, transit, business, background_check, …)
107
+ VERIFIK_MCP_BASE_CATEGORY=identity,transit
108
+
109
+ # Explicit feature codes
110
+ VERIFIK_MCP_CODES=colombia_api_identity_lookup,colombia_api_vehicle
111
+ ```
112
+
113
+ Filters can be combined. Use the free meta tools `verifik_list_catalog` and `verifik_get_feature` to search the in-memory catalog before spending credits — pass the same `country`, `baseCategory`, `code`, or `smartCheckOnly` arguments to preview what would match.
90
114
 
91
115
  ### 3. Tool schema (`lib/tool-schema.js`)
92
116
 
@@ -469,32 +493,66 @@ Non-2xx responses are still returned as structured JSON (marked as MCP errors) s
469
493
 
470
494
  ## Country coverage
471
495
 
472
- 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.
473
-
474
- | Country / region | Example capabilities | Example API paths |
475
- | --- | --- | --- |
476
- | **Argentina** | National ID, business, vehicle, criminal record | `v2/ar/cedula`, `v2/ar/company`, `v2/ar/vehicle` |
477
- | **Bolivia** | National ID, business, vehicle, SOAT | `v2/bo/cedula`, `v2/bo/company`, `v2/bo/vehicle` |
478
- | **Brazil** | National ID, CPF background check, business (CNPJ), vehicle | `v2/br/cedula`, `v2/br/background-check`, `v2/br/company` |
479
- | **Canada** | Business, provincial driver license & plates | `v2/ca/company`, `v2/ca/ontario/driver-license` |
480
- | **Chile** | National ID (RUN), taxpayer (RUT), vehicle, driver license | `v2/cl/cedula`, `v2/cl/taxpayer`, `v2/cl/vehicle` |
481
- | **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` |
482
- | **Costa Rica** | National ID, business, vehicle | `v2/cr/cedula`, `v2/cr/company`, `v2/cr/vehicle` |
483
- | **Dominican Republic** | National ID | `v2/do/cedula` |
484
- | **Ecuador** | National ID, vehicle & fines | `v2/ec/cedula`, `v2/ec/vehiculo/placa` |
485
- | **El Salvador** | National ID (DUI) | `v2/sv/dui` |
486
- | **Guatemala** | National ID | `v2/gt/cedula` |
487
- | **Honduras** | National ID | `v2/hn/cedula` |
488
- | **India** | Voter ID (EPIC) | `v2/in/epic` |
489
- | **Mexico** | CURP, INE validation, business, vehicle by plate | `v2/mx/curp`, `v2/mx/ine`, `v2/mx/vehiculo/placa` |
490
- | **Panama** | National ID, business | `v2/pa/cedula`, `v2/pa/company` |
491
- | **Paraguay** | National ID (CIC), business, vehicle | `v2/py/cic`, `v2/py/company`, `v2/py/vehicle` |
492
- | **Peru** | DNI (v3), foreigner ID, driver license, vehicle & SOAT | `v3/pe/cedula`, `v2/pe/vehiculo/placa`, `v2/pe/driver-license` |
493
- | **Spain** | National ID, business, vehicle | `v2/es/cedula`, `v2/es/company` |
494
- | **United States** | SSN verification, business, state driver licenses, vehicle/VIN | `v2/usa/ssn`, `v2/usa/company`, `v2/usa/vehicle` |
495
- | **Uruguay** | National ID | `v2/uy/cedula` |
496
- | **Venezuela** | National ID, foreigner ID | `v2/ve/cedula`, `v2/ve/foreigner-id` |
497
- | **Worldwide** | Sanctions & watchlists (DEA, FBI, Interpol, OFAC, UN, Europol), IP geolocation, phone lookup | `v2/dea`, `v2/ofac`, `v2/interpol`, `v2/look-ups/phone` |
496
+ The exact tools you see depend on **your Verifik plan and enabled features**. The production catalog currently has **183** non-legacy endpoints; **175** become MCP tools (8 require binary/image uploads and are not exposed via MCP).
497
+
498
+ See the full generated catalog in [docs/endpoints.md](docs/endpoints.md) — tool name, description, method, path, and price per call.
499
+
500
+ | Country / region | Endpoints | Full list |
501
+ | --- | ---: | --- |
502
+ | Argentina | 9 | [docs/endpoints.md#argentina](docs/endpoints.md#argentina) |
503
+ | Bolivia | 5 | [docs/endpoints.md#bolivia](docs/endpoints.md#bolivia) |
504
+ | Brazil | 4 | [docs/endpoints.md#brazil](docs/endpoints.md#brazil) |
505
+ | Canada | 3 | [docs/endpoints.md#canada](docs/endpoints.md#canada) |
506
+ | Chile | 12 | [docs/endpoints.md#chile](docs/endpoints.md#chile) |
507
+ | **Colombia** | **70** | [docs/endpoints.md#colombia](docs/endpoints.md#colombia) |
508
+ | Costa Rica | 5 | [docs/endpoints.md#costa-rica](docs/endpoints.md#costa-rica) |
509
+ | Ecuador | 6 | [docs/endpoints.md#ecuador](docs/endpoints.md#ecuador) |
510
+ | El Salvador | 1 | [docs/endpoints.md#el-salvador](docs/endpoints.md#el-salvador) |
511
+ | Guatemala | 2 | [docs/endpoints.md#guatemala](docs/endpoints.md#guatemala) |
512
+ | Honduras | 2 | [docs/endpoints.md#honduras](docs/endpoints.md#honduras) |
513
+ | India | 2 | [docs/endpoints.md#india](docs/endpoints.md#india) |
514
+ | Mexico | 5 | [docs/endpoints.md#mexico](docs/endpoints.md#mexico) |
515
+ | Panama | 2 | [docs/endpoints.md#panama](docs/endpoints.md#panama) |
516
+ | Paraguay | 3 | [docs/endpoints.md#paraguay](docs/endpoints.md#paraguay) |
517
+ | Peru | 8 | [docs/endpoints.md#peru](docs/endpoints.md#peru) |
518
+ | República Dominicana | 1 | [docs/endpoints.md#republica-dominicana](docs/endpoints.md#republica-dominicana) |
519
+ | Spain | 3 | [docs/endpoints.md#spain](docs/endpoints.md#spain) |
520
+ | United States | 4 | [docs/endpoints.md#united-states](docs/endpoints.md#united-states) |
521
+ | Uruguay | 1 | [docs/endpoints.md#uruguay](docs/endpoints.md#uruguay) |
522
+ | Venezuela | 2 | [docs/endpoints.md#venezuela](docs/endpoints.md#venezuela) |
523
+ | Worldwide | 25 | [docs/endpoints.md#world](docs/endpoints.md#world) |
524
+
525
+ Representative Colombia paths: `v2/co/cedula`, `v2/co/runt/vehiculo`, `v2/co/procuraduria`, `v3/co/rues`, `v2/co/simit/consultar`.
526
+
527
+ <details>
528
+ <summary><strong>All 70 Colombia endpoints</strong> (click to expand)</summary>
529
+
530
+ | Tool | Description | Method & path | Price |
531
+ | --- | --- | --- | --- |
532
+ | `colombia_api_identity_lookup` | Colombia - Colombian Citizen | `GET` `v2/co/cedula` | $0.30 |
533
+ | `colombia_api_identity_lookup_extra` | Colombia - Colombian Citizen (Extra) | `GET` `v2/co/cedula/extra` | $0.40 |
534
+ | `colombia_api_identity_lookup_vigencia` | Colombia - Colombian Citizen (Vigencia) | `GET` `v2/co/cedula/vigencia` | $0.10 |
535
+ | `colombia_api_identity_lookup_premium` | Colombia - Colombian Citizen (Premium) | `GET` `v2/co/cedula/premium` | $2.00 |
536
+ | `colombia_api_identity_lookup_by_name` | Colombia - Colombian Citizen (By Name) | `GET` `v2/co/cedula/by-name` | $0.30 |
537
+ | `colombia_api_identity_lookup_procuraduria` | Colombia - Procuraduría | `GET` `v2/co/procuraduria` | $0.30 |
538
+ | `colombia_api_criminal_history` | Colombia - Criminal History | `GET` `v2/co/procuraduria/antecedentes` | $0.30 |
539
+ | `colombia_api_rues_v3` | Colombia - RUES Business | `GET` `v3/co/rues` | $0.30 |
540
+ | `colombia_api_rues_full_v3` | Colombia - RUES Complete | `GET` `v3/co/rues-complete` | $0.40 |
541
+ | `colombia_api_vehicle` | Colombia - RUNT Vehicle | `GET` `v2/co/runt/vehiculo` | $0.30 |
542
+ | `colombia_api_vehicle_complete_by_plate` | Colombia - RUNT Vehicle by Plate | `GET` `v2/co/runt/vehicle-by-plate` | $0.40 |
543
+ | `colombia_api_simit_complete` | Colombia - SIMIT Complete | `GET` `v2/co/simit/consultar` | $0.30 |
544
+ | `colombia_api_simit_plate` | Colombia - SIMIT by Plate | `GET` `v2/co/simit/consultar/placa` | $0.30 |
545
+ | `colombia_api_driver` | Colombia - RUNT Driver | `GET` `v2/co/runt/conductor` | $0.60 |
546
+ | `colombia_api_driver_basic` | Colombia - RUNT Driver (Basic) | `GET` `v3/co/runt/conductor` | $0.30 |
547
+ | `colombia_api_dian` | Colombia - DIAN Business | `GET` `v2/co/company/dian` | $0.30 |
548
+ | `colombia_api_judicial_processes` | Colombia - Judicial Processes | `GET` `v2/co/rama/procesos` | $0.30 |
549
+ | `colombia_api_judicial_process_details` | Colombia - Judicial Process Details | `GET` `v2/co/rama/proceso` | $0.30 |
550
+ | `colombia_api_adres` | Colombia - ADRES Affiliation | `GET` `v2/co/adres` | $0.30 |
551
+ | `colombia_api_affiliations` | Colombia - Affiliations | `GET` `v2/co/afiliaciones` | $0.30 |
552
+
553
+ *…and 50 more — see [docs/endpoints.md#colombia](docs/endpoints.md#colombia) for the complete list.*
554
+
555
+ </details>
498
556
 
499
557
  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.
500
558
 
@@ -504,8 +562,8 @@ Run `verifik_list_catalog` in your MCP client to see the live list for your toke
504
562
  | --- | --- | --- | --- |
505
563
  | `VERIFIK_API_TOKEN` | **Yes** | — | API token from Smart-Agent → API Tokens |
506
564
  | `VERIFIK_API_BASE` | No | `https://api.verifik.co` | API base URL (use `https://staging-api.verifik.co` for staging) |
507
- | `VERIFIK_MCP_SMARTCHECK_ONLY` | No | `true` | When `true`, only expose SmartCheck-enabled features |
508
- | `VERIFIK_MCP_COUNTRY` | No | — | Comma-separated country filter (e.g. `Colombia,Mexico,world`) |
565
+ | `VERIFIK_MCP_SMARTCHECK_ONLY` | No | `false` | When `true`, only expose SmartCheck-enabled features |
566
+ | `VERIFIK_MCP_COUNTRY` | No | — | Comma-separated country filter — see [accepted values](#verifik_mcp_country-values) |
509
567
  | `VERIFIK_MCP_BASE_CATEGORY` | No | — | Comma-separated `baseCategory` filter |
510
568
  | `VERIFIK_MCP_CODES` | No | — | Comma-separated feature code allowlist |
511
569
  | `VERIFIK_MCP_CATALOG_REFRESH_MS` | No | `0` | In-memory catalog refresh interval in ms (`0` = load once at startup) |
@@ -523,7 +581,7 @@ Run `verifik_list_catalog` in your MCP client to see the live list for your toke
523
581
  | Symptom | What to check |
524
582
  | --- | --- |
525
583
  | Server exits immediately with `VERIFIK_API_TOKEN is required` | Set `VERIFIK_API_TOKEN` in your MCP config `env` block |
526
- | 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 |
584
+ | No tools / empty catalog | Confirm the token is valid, your account has features enabled, and `VERIFIK_MCP_SMARTCHECK_ONLY` / country filters are not too restrictive |
527
585
  | `401` / authentication errors | Regenerate the token in Smart-Agent → API Tokens |
528
586
  | `402` / insufficient credits | Top up credits in your Verifik dashboard |
529
587
  | `404` on a lookup | The document or record was not found — normal for invalid or non-existent identifiers |
@@ -542,3 +600,60 @@ Run `verifik_list_catalog` in your MCP client to see the live list for your toke
542
600
 
543
601
  - Node.js 18+
544
602
  - A Verifik account with API access and available credits
603
+
604
+ ## Changelog
605
+
606
+ ### 0.1.3
607
+
608
+ - Default `VERIFIK_MCP_SMARTCHECK_ONLY` to `false` — expose the full catalog your account can access (175+ tools)
609
+ - Add `docs/endpoints.md` generated from `data/catalog-snapshot.json` with every non-legacy endpoint
610
+ - Country filter accepts catalog names (case/accent-insensitive) and ISO 3166-1 alpha-2 aliases
611
+ - Prefer `clientHasAccess` from `my-list` when present; exclude `legacy` features from tools and docs
612
+ - Document narrowing filters for large MCP tool lists
613
+
614
+ ### 0.1.2
615
+
616
+ - Agent-ready tool schemas, local validation, and clean error responses
617
+
618
+ ### 0.1.1
619
+
620
+ - Initial npm release with SmartCheck catalog support
621
+
622
+ ## `VERIFIK_MCP_COUNTRY` values
623
+
624
+ `VERIFIK_MCP_COUNTRY` uses the **catalog country names** stored on each AppFeature (the same values Smart-Agent writes, e.g. `Colombia`). Matching is **case-insensitive** and **accent-insensitive** (`republica dominicana` matches `República Dominicana`).
625
+
626
+ You may also use **ISO 3166-1 alpha-2** codes as aliases. Separate multiple values with commas.
627
+
628
+ | Catalog name | ISO alias |
629
+ | --- | --- |
630
+ | `Argentina` | `AR` |
631
+ | `Bolivia` | `BO` |
632
+ | `Brazil` | `BR` |
633
+ | `Canada` | `CA` |
634
+ | `Chile` | `CL` |
635
+ | `Colombia` | `CO` |
636
+ | `Costa Rica` | `CR` |
637
+ | `Ecuador` | `EC` |
638
+ | `El Salvador` | `SV` |
639
+ | `Guatemala` | `GT` |
640
+ | `Honduras` | `HN` |
641
+ | `India` | `IN` |
642
+ | `Mexico` | `MX` |
643
+ | `Panama` | `PA` |
644
+ | `Paraguay` | `PY` |
645
+ | `Peru` | `PE` |
646
+ | `República Dominicana` | `DO` |
647
+ | `Spain` | `ES` |
648
+ | `United States` | `US` |
649
+ | `Uruguay` | `UY` |
650
+ | `Venezuela` | `VE` |
651
+ | `world` (global features) | `world` |
652
+
653
+ Examples:
654
+
655
+ ```bash
656
+ VERIFIK_MCP_COUNTRY=Colombia
657
+ VERIFIK_MCP_COUNTRY=CO,MX,world
658
+ VERIFIK_MCP_COUNTRY=republica dominicana,peru
659
+ ```