Shufti Pro MCP Server / Shufti Pro MCP 服务器

English

Overview

This project is a standalone Model Context Protocol (MCP) server dedicated to Shufti Pro identity verification workflows.
It is designed for premium compliance scenarios that require strong liveness checks and high-quality document OCR extraction.

Server

• Name: mcp-server-shuftipro
• Entry file: server.ts
• Transport: MCP stdio

Exposed Tools

1. shufti_face_liveness_match

• Purpose: 1:1 face match with liveness detection.
• Best for: biometric login and step-up authentication.
• Input:
  • selfie_base64 (string, required)
  • document_face_base64 (string, required)
  • reference_id (string, required)

2. shufti_full_document_ocr

• Purpose: OCR extraction (including MRZ/text) and document authenticity checks.
• Best for: initial KYC data capture.
• Input:
  • document_base64 (string, required)
  • document_type (string, required, e.g. passport, id_card)
  • reference_id (string, required)

Unified Output Schema

Both tools return the same structured output:

{
  "status": "success | failed | error",
  "event": "verification.accepted | verification.declined | ...",
  "decline_reason": "string | null",
  "extracted_data": "object | null"
}

Environment Variables

Set these before running:

• SHUFTI_CLIENT_ID (required)
• SHUFTI_SECRET_KEY (required)
• SHUFTI_API_URL (optional, default: https://api.shuftipro.com/)

Installation

Install dependencies in your TypeScript MCP project:

npm install @modelcontextprotocol/sdk axios

Run

Build and run with your project setup (example):

npx tsc
node dist/server.js

Notes

• The server validates base64 inputs before sending API requests.
• The server uses Basic Auth generated from SHUFTI_CLIENT_ID and SHUFTI_SECRET_KEY.
• Errors are normalized into the same output schema for stable orchestrator parsing.

---

中文

项目简介

本项目是一个专用于 Shufti Pro 身份核验流程的独立 MCP（Model Context Protocol）服务器。
它面向高合规场景，支持高质量活体检测与证件 OCR 数据提取。

服务信息

• 服务名：mcp-server-shuftipro
• 入口文件：server.ts
• 通信方式：MCP stdio

暴露工具

1. shufti_face_liveness_match

• 作用：执行 1:1 人脸比对与活体检测。
• 适用场景：生物识别登录、二次校验（step-up）。
• 输入参数：
  • selfie_base64（字符串，必填）
  • document_face_base64（字符串，必填）
  • reference_id（字符串，必填）

2. shufti_full_document_ocr

• 作用：提取证件 OCR（含 MRZ/文本）并进行证件真实性校验。
• 适用场景：初次 KYC 信息采集。
• 输入参数：
  • document_base64（字符串，必填）
  • document_type（字符串，必填，例如 passport、id_card）
  • reference_id（字符串，必填）

统一输出结构

两个工具都返回统一结构：

{
  "status": "success | failed | error",
  "event": "verification.accepted | verification.declined | ...",
  "decline_reason": "string | null",
  "extracted_data": "object | null"
}

环境变量

运行前请设置：

• SHUFTI_CLIENT_ID（必填）
• SHUFTI_SECRET_KEY（必填）
• SHUFTI_API_URL（可选，默认：https://api.shuftipro.com/）

安装依赖

在你的 TypeScript MCP 项目中安装依赖：

npm install @modelcontextprotocol/sdk axios

运行方式

按你的项目构建流程运行（示例）：

npx tsc
node dist/server.js

说明

• 服务会在调用外部 API 前校验 base64 输入。
• 服务通过 SHUFTI_CLIENT_ID 与 SHUFTI_SECRET_KEY 生成 Basic Auth。
• 所有异常会归一化为统一输出结构，方便上游编排器稳定解析。