Mayanet Verify MCP

Stdio MCP that checks a volunteer against Colombian public sources (Croma) and stores a Pass / Alert / Fail report in an isolated Neon schema verify. It never reads or alters intake (public.volunteers).

License: MIT. LinkedIn is URL-normalize only — no profile fetch.

Quick path

1. npm install (Node 20+).

2. Put a verify-scoped Postgres URL and a Croma key in .env (copy .env.example).

3. Apply schema once: psql "$DATABASE_URL" -f sql/001_verify_schema.sql

4. Point Cursor at this repo (stdio block below) and reload MCP.

5. Call verify_volunteer with volunteer_id: "verify-operator-001" after the document is bound.

Expected: a JSON report with overall_status and per-check statuses. Seed fixture is Example Operator / CC 1000000000 / id verify-operator-001.

Related MCP server: checkyourself

Explain

Out of scope: UI, WhatsApp/email, numeric scores, biometrics, LinkedIn scraping, Registraduría, bulk-copy of intake rows.

Stand up

Requirements

• Node.js 20+

• DATABASE_URL — Postgres role that can DML verify only

• CROMA_API_KEY — org bearer (croma_live_…)

• psql once, to apply SQL

DATABASE_URL=<verify-scoped-postgres-url>
CROMA_API_KEY=<croma-api-key>

Do not commit .env. Runtime never runs DDL.

Schema (once)

psql "$DATABASE_URL" -f sql/001_verify_schema.sql

Creates verify.volunteers, verify.verification_requests, verify.verification_reports, and seeds verify-operator-001. Re-apply is safe (ON CONFLICT (document_number) DO NOTHING).

Rollback: DROP SCHEMA verify CASCADE. Never ALTER public.volunteers.

Cursor (stdio)

npm install, then user ~/.cursor/mcp.json or project .cursor/mcp.json:

{
  "mcpServers": {
    "mayanet-verify": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "/absolute/path/to/mallanet-verify",
      "env": {
        "DATABASE_URL": "<verify-scoped-postgres-url>",
        "CROMA_API_KEY": "<croma-api-key>"
      }
    }
  }
}

Missing env aborts before tools register. Reload MCP after edits.

Smoke (stdin close exits 0 if env is set):

printf '' | DATABASE_URL="<verify-scoped-postgres-url>" CROMA_API_KEY="<croma-api-key>" npx tsx src/index.ts

Operate

First verify (seed)

The SQL seed is already bound (document_number = 1000000000). After MCP is live:

1. list_pending_volunteers { "limit": 20, "status_filter": "pending" } — expect verify-operator-001 until a report exists.

2. get_volunteer { "volunteer_id": "verify-operator-001" } — confirm the row.

3. verify_volunteer { "volunteer_id": "verify-operator-001" } — Croma + persist.

To bind a different person (never commit a real cédula):

{
  "volunteer_id": "verify-operator-001",
  "document_type": "CC",
  "document_number": "<document-number>",
  "linkedin_url": "https://www.linkedin.com/in/example"
}

That is request_verification_data. Then verify_volunteer again. Without document_number the orchestrator throws identity unbound. Unknown id throws volunteer not found.

Tools

Report shape

{
  "volunteer_id": "verify-operator-001",
  "name": "Example Operator",
  "overall_status": "Pass",
  "checks": {
    "judicial": "Pass",
    "criminal_records": "Pass",
    "procuraduria": "Pass",
    "rues": "N/A",
    "linkedin_consistency": "Alert"
  },
  "findings": [],
  "linkedin_summary": { "headline": "", "experience": [], "education": [] },
  "timestamp": "2026-08-16T00:00:00.000Z"
}

Heuristics

Overall: any Fail → Fail; else any Alert → Alert; else Pass. N/A is ignored. One source failing does not abort the others.

Limits and failures

• Croma default quota is 100 requests/day/org. One verify_volunteer is several calls.

• Policía can take ~55s (202 poll in-process). Host MCP timeouts may fire first.

• Logs may include volunteer_id and document type. They must never include document_number.

Tests

npm test

No live Croma in CI. Isolation tests assert the SQL never touches public.

Checklist

• .env set, not committed

• sql/001_verify_schema.sql applied to a verify-scoped database

• Cursor MCP reloaded; tools visible

• get_volunteer returns verify-operator-001

• verify_volunteer returns overall_status + checks

• npm test is green