# China VAT Validator MCP (`neeenja/cn-vat-validator-mcp`) Actor
Offline, zero-dependency validator for Chinese Unified Social Credit Codes (USCC, GB 32100-2015) via the mod-31 checksum. Structural validity only — does not confirm the company exists. 离线零依赖校验中国统一社会信用代码（18位，GB 32100-2015），仅做结构合法性校验，不确认企业是否真实存在。
- **URL**: https://apify.com/neeenja/cn-vat-validator-mcp.md
- **Developed by:** [Neeen Ja](https://apify.com/neeenja) (community)
- **Categories:** MCP servers, AI, Developer tools
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet
## Pricing
from $10.00 / 1,000 uscc validations
This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event
## What's an Apify Actor?
An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.
## How to integrate an Actor?
If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.
For examples already wired to this Actor's own input schema, see the [API](#api) section below.
Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).
# README
## China VAT Validator MCP
**Offline · zero-dependency validator for Chinese Unified Social Credit Codes (USCC, GB 32100-2015)**
**离线 · 零依赖 · 校验统一社会信用代码（18位，GB 32100-2015）**
**離線 · 零依賴 · 校驗統一社會信用代碼（18位，GB 32100-2015）**
`License: MIT` · `Offline: yes` · `External deps (core): zero` · **Current version: 1.0.0**
**Language:** [English](#english) · [简体中文](#简体中文) · [繁體中文](#繁體中文)
| It lives at | Link |
|---|---|
| MCP endpoint | `https://neeenja--cn-vat-validator-mcp.apify.actor/mcp` |
| Apify Store | https://apify.com/neeenja/cn-vat-validator-mcp |
| Source | Available on request (private repository) |
***
## English
For Chinese companies, the **VAT taxpayer ID is the 18-character Unified Social Credit Code**
(统一社会信用代码, **USCC**, national standard **GB 32100-2015**). It carries a built-in
**mod-31 checksum**. This MCP server validates whether a code is **structurally and
mathematically self-consistent** — instantly, offline, with no API key and no network.
> **Honest boundary:** `valid: true` means the code is *well-formed and the checksum matches*.
> It does **NOT** mean the company exists or is active. Existence must be confirmed via
> GSXT (国家企业信用信息公示系统) or a paid registry API. This tool is the cheap **first layer**,
> never a substitute for due diligence.
### Features
- Validate a single USCC (`validate_uscc`) — 18-char, GB 32100-2015 mod-31 checksum.
- Batch-validate an array of codes (`validate_uscc_batch`) — one result per input, in order.
- Detailed bilingual error reasons (length / illegal character / checksum mismatch).
- Normalize input (uppercase, trim spaces and hyphens) before validation.
- Metadata breakdown: registry department, organization category, region code, organization code.
- Bilingual structured output (`zh` + `en` on every error).
- Hosted Streamable-HTTP MCP (Apify Standby) and a zero-install local stdio server.
### Install
The zero-install option is the **hosted MCP** below. Source code is **available on request** (private repository) — there is no public clone.
### Usage
**As an MCP tool (stdio or hosted):**
```jsonc
// validate_uscc
{ "code": "91110108MA01ABC239" }
// -> { "valid": true, "checkDigitOk": true, "type": "uscc",
// "parts": { "registryDept":"9","orgCategory":"1","regionCode":"110108",
// "organizationCode":"MA01ABC23" }, "errors": [], "confidence": 1.0 }
// validate_uscc_batch
{ "codes": ["91110108MA01ABC239", "91110108MA01ABC23X"] }
// -> { "results": [ {valid:true,...}, {valid:false, errors:[{code:"CHECK",...}]} ] }
```
**Programmatic (zero-dependency core):**
```js
import { validate, validateBatch } from './src/core/index.mjs';
console.log(validate('91110108MA01ABC239').valid); // true
```
**MCP client config (stdio):**
```jsonc
{ "mcpServers": { "cn-vat-validator": { "command": "node", "args": ["src/mcp/stdio.mjs"] } } }
```
**Hosted MCP client (Streamable HTTP):**
```jsonc
{ "mcpServers": { "cn-vat-validator": {
"url": "https://neeenja--cn-vat-validator-mcp.apify.actor/mcp",
"headers": { "Authorization": "Bearer " }
} } }
```
### Algorithm (GB 32100-2015)
- Character set (31 chars) **excludes I, O, Z, S, V**: `0123456789ABCDEFGHJKLMNPQRTUWXY`
- Weights for positions 1–17: `[1,3,9,27,19,26,16,17,20,29,25,13,8,24,10,30,28]` (= 3^(i-1) mod 31)
- Check digit: `c = 31 - (Σ v_i·W_i) mod 31`; if `c == 31` → `0` (character `"0"`)
- `valid` iff the computed check digit equals the 18th character
### Monetization (pay-per-call)
| Channel | Model | Price |
|---------|-------|-------|
| **Apify PPE** | pay-per-event | $0.01 / `validate` call |
| **SkillPay** (Phase 2) | pay-per-call via WeChat AI card | ¥0.02 / call (≈80% creator share) |
| **Self-host (source on request)** | private repo | — |
The core algorithm has **zero marginal cost** — revenue comes from the convenience of the
hosted/Skill call, not from the math.
### SkillPay-ready
The product is built so it converts to a WorkBuddy Skill on SkillPay **without changing
`src/core`**. The repo ships:
- `skill.json` — SkillPay listing manifest (name, pricing, capabilities)
- `skill/SKILL.md` — the Skill body, which imports the same `src/core/validate.mjs`
Because `src/core` is pure, dependency-free, and side-effect-free, it runs identically inside the
Skill runtime, the Apify actor, and any stdio client. Phase-2 packaging = publish core + wire
SkillPay billing (a transport concern) + submit to Skill Hub.
### Deploy (maintainers)
```bash
npm install # pulls the MCP SDK + apify (dev/actor only)
npm run build && npm run cf:deploy # optional: Cloudflare Workers
apify login && apify push # Apify Standby + PPE (requires your KYC)
```
### Develop
```bash
node --test tests/ # unit + MCP e2e (AC-01..AC-11, 5 pos / 3 neg)
node scripts/mcp-smoke.mjs # spawn stdio server, exercise initialize/list/call
node scripts/showcase.mjs # generate showcase.html from REAL payloads
node scripts/check-p0.mjs # CI design red-lines (no emoji / gradient / external fonts)
```
### License
MIT — source available on request (private repository).
***
## 简体中文
在中国，企业的 **增值税纳税人识别号就是 18 位统一社会信用代码**（统一社会信用代码，
**USCC**，国家标准 **GB 32100-2015**），自带 **mod-31 校验位**。本 MCP 服务用于判断一个代码是否
**结构合法、校验位匹配**——瞬时、离线、无需 API Key、无需联网。
> **诚实边界：** `valid: true` 表示代码「格式正确且校验位匹配」，**并不**表示该企业真实存在或存续。
> 企业存续需通过 GSXT（国家企业信用信息公示系统）或付费工商接口核实。本工具只是廉价的**第一道防线**，
> 绝不可替代尽职调查。
### 功能
- 校验单个 USCC（`validate_uscc`）——18 位，GB 32100-2015 mod-31 校验位。
- 批量校验一组代码（`validate_uscc_batch`）——逐条返回，保序，不因首条错误而中断。
- 双语详细错误原因（长度 / 非法字符 / 校验位不符）。
- 输入规整（大小写统一、去除空格与连字符）后再校验。
- 元数据拆解：登记管理部门、机构类别、行政区划码、组织机构码。
- 双语结构化输出（每条错误均含 `zh` 与 `en`）。
- 托管 Streamable-HTTP MCP（Apify Standby）与零安装的本地 stdio 服务。
### 安装
零安装的方式是下方的**托管 MCP**。源码**提供申请获取**（私有仓库）——无公开 clone。
### 用法
**作为 MCP 工具（stdio 或托管）：**
```jsonc
// validate_uscc
{ "code": "91110108MA01ABC239" }
// -> { "valid": true, "checkDigitOk": true, "type": "uscc",
// "parts": { "registryDept":"9","orgCategory":"1","regionCode":"110108",
// "organizationCode":"MA01ABC23" }, "errors": [], "confidence": 1.0 }
// validate_uscc_batch
{ "codes": ["91110108MA01ABC239", "91110108MA01ABC23X"] }
// -> { "results": [ {valid:true,...}, {valid:false, errors:[{code:"CHECK",...}]} ] }
```
**编程调用（零依赖核心）：**
```js
import { validate, validateBatch } from './src/core/index.mjs';
console.log(validate('91110108MA01ABC239').valid); // true
```
**MCP 客户端配置（stdio）：**
```jsonc
{ "mcpServers": { "cn-vat-validator": { "command": "node", "args": ["src/mcp/stdio.mjs"] } } }
```
**MCP 客户端配置（托管 Streamable HTTP）：**
```jsonc
{ "mcpServers": { "cn-vat-validator": {
"url": "https://neeenja--cn-vat-validator-mcp.apify.actor/mcp",
"headers": { "Authorization": "Bearer " }
} } }
```
### 算法（GB 32100-2015）
- 字符集（31 位）**排除 I、O、Z、S、V**：`0123456789ABCDEFGHJKLMNPQRTUWXY`
- 第 1–17 位权重：`[1,3,9,27,19,26,16,17,20,29,25,13,8,24,10,30,28]`（= 3^(i-1) mod 31）
- 校验位：`c = 31 - (Σ v_i·W_i) mod 31`；若 `c == 31` → `0`（字符 `"0"`）
- 当且仅当计算校验位等于第 18 位时 `valid`
### 商业化（按次计费）
| 渠道 | 模式 | 价格 |
|------|------|------|
| **Apify PPE** | 按事件付费 | $0.01 / 每次 `validate` 调用 |
| **SkillPay**（第二阶段） | 微信 AI 卡按次 | ¥0.02 / 次（约 80% 创作者分成） |
| **自托管 / 开源** | 免费，MIT | $0 |
核心算法**边际成本为零**——收入来自托管 / Skill 调用的便利，而非算法本身。
### 可转为 WorkBuddy Skill（SkillPay）
本产品无需改动 `src/core` 即可转为 WorkBuddy Skill（SkillPay）。仓库已包含：
- `skill.json`——SkillPay 上架清单（名称、定价、能力）
- `skill/SKILL.md`——Skill 正文，复用同一份 `src/core/validate.mjs`
`src/core` 纯函数、无依赖、无副作用，可在 Skill 运行时、Apify Actor、任意 stdio 客户端中一致运行。
第二阶段打包 = 发布核心 + 接入 SkillPay 计费（纯传输层关注点）+ 提交至 Skill Hub。
### 部署（维护者）
```bash
npm install # 安装 MCP SDK + apify（仅开发/托管需要）
npm run build && npm run cf:deploy # 可选：Cloudflare Workers
apify login && apify push # Apify Standby + PPE（需完成 KYC）
```
### 开发
```bash
node --test tests/ # 单元 + MCP e2e（AC-01..AC-11，5 正 / 3 负）
node scripts/mcp-smoke.mjs # 拉起 stdio 服务，跑 initialize/list/call
node scripts/showcase.mjs # 用真实 payload 生成 showcase.html
node scripts/check-p0.mjs # CI 设计红线（无 emoji/渐变/示例文字/外部字体）
```
### 许可证
MIT——源码提供申请获取（私有仓库）。
***
## 繁體中文
在中國，企業的 **增值稅納稅人識別號就是 18 位統一社會信用代碼**（統一社會信用代碼，
**USCC**，國家標準 **GB 32100-2015**），自帶 **mod-31 校驗位**。本 MCP 服務用於判斷一個代碼是否
**結構合法、校驗位相符**——瞬時、離線、無需 API Key、無需聯網。
> **誠實邊界：** `valid: true` 表示代碼「格式正確且校驗位相符」，**並不**表示該企業真實存在或存續。
> 企業存續需透過 GSXT（國家企業信用信息公示系統）或付費工商介面核實。本工具只是廉價的**第一道防線**，
> 絕不可取代盡職調查。
### 功能
- 校驗單個 USCC（`validate_uscc`）——18 位，GB 32100-2015 mod-31 校驗位。
- 批次校驗一組代碼（`validate_uscc_batch`）——逐條回傳，保序，不因首條錯誤而中斷。
- 雙語詳細錯誤原因（長度 / 非法字元 / 校驗位不符）。
- 輸入規整（大小寫統一、去除空格與連字號）後再校驗。
- 中繼資料拆解：登記管理部門、機構類別、行政區劃碼、組織機構碼。
- 雙語結構化輸出（每條錯誤均含 `zh` 與 `en`）。
- 託管 Streamable-HTTP MCP（Apify Standby）與零安裝的本地 stdio 服務。
### 安裝
零安裝的方式是下方的**託管 MCP**。原始碼**提供申請取得**（私有倉庫）——無公開 clone。
### 用法
**作為 MCP 工具（stdio 或託管）：**
```jsonc
// validate_uscc
{ "code": "91110108MA01ABC239" }
// -> { "valid": true, "checkDigitOk": true, "type": "uscc",
// "parts": { "registryDept":"9","orgCategory":"1","regionCode":"110108",
// "organizationCode":"MA01ABC23" }, "errors": [], "confidence": 1.0 }
// validate_uscc_batch
{ "codes": ["91110108MA01ABC239", "91110108MA01ABC23X"] }
// -> { "results": [ {valid:true,...}, {valid:false, errors:[{code:"CHECK",...}]} ] }
```
**程式呼叫（零依賴核心）：**
```js
import { validate, validateBatch } from './src/core/index.mjs';
console.log(validate('91110108MA01ABC239').valid); // true
```
**MCP 客戶端設定（stdio）：**
```jsonc
{ "mcpServers": { "cn-vat-validator": { "command": "node", "args": ["src/mcp/stdio.mjs"] } } }
```
**MCP 客戶端設定（託管 Streamable HTTP）：**
```jsonc
{ "mcpServers": { "cn-vat-validator": {
"url": "https://neeenja--cn-vat-validator-mcp.apify.actor/mcp",
"headers": { "Authorization": "Bearer " }
} } }
```
### 演算法（GB 32100-2015）
- 字元集（31 位）**排除 I、O、Z、S、V**：`0123456789ABCDEFGHJKLMNPQRTUWXY`
- 第 1–17 位權重：`[1,3,9,27,19,26,16,17,20,29,25,13,8,24,10,30,28]`（= 3^(i-1) mod 31）
- 校驗位：`c = 31 - (Σ v_i·W_i) mod 31`；若 `c == 31` → `0`（字元 `"0"`）
- 當且僅當計算校驗位等於第 18 位時 `valid`
### 商業化（按次計費）
| 管道 | 模式 | 價格 |
|------|------|------|
| **Apify PPE** | 按事件付費 | $0.01 / 每次 `validate` 呼叫 |
| **SkillPay**（第二階段） | 微信 AI 卡按次 | ¥0.02 / 次（約 80% 創作者分成） |
| **自託管 / 開源** | 免費，MIT | $0 |
核心演算法**邊際成本為零**——收入來自託管 / Skill 呼叫的便利，而非演算法本身。
### 可轉為 WorkBuddy Skill（SkillPay）
本產品無須改動 `src/core` 即可轉為 WorkBuddy Skill（SkillPay）。倉庫已包含：
- `skill.json`——SkillPay 上架清單（名稱、定價、能力）
- `skill/SKILL.md`——Skill 正文，復用同一份 `src/core/validate.mjs`
`src/core` 純函數、無依賴、無副作用，可在 Skill 執行環境、Apify Actor、任意 stdio 客戶端中一致執行。
第二階段打包 = 發布核心 + 接入 SkillPay 計費（純傳輸層關注點）+ 提交至 Skill Hub。
### 部署（維護者）
```bash
npm install # 安裝 MCP SDK + apify（僅開發/託管需要）
npm run build && npm run cf:deploy # 選用：Cloudflare Workers
apify login && apify push # Apify Standby + PPE（需完成 KYC）
```
### 開發
```bash
node --test tests/ # 單元 + MCP e2e（AC-01..AC-11，5 正 / 3 負）
node scripts/mcp-smoke.mjs # 拉起 stdio 服務，跑 initialize/list/call
node scripts/showcase.mjs # 用真實 payload 生成 showcase.html
node scripts/check-p0.mjs # CI 設計紅線（無 emoji/漸變/範本文字/外部字體）
```
### 授權
MIT——原始碼提供申請取得（私有倉庫）。
***
## Privacy / 隐私
**English.** The only input processed is a Unified Social Credit Code (USCC) — a *public* organizational identifier, not personal information. It is validated **in memory** against GB 32100-2015 and is **never** persisted, cached, or transmitted to any third party. When used via the hosted endpoint, requests run on Apify; Apify processes billing metadata under its own privacy policy (https://apify.com/legal/privacy-policy). Nothing is stored, so there is no retained data to access or delete. Contact: via the Apify Store page — source available on request.
**简体中文。** 本服务处理的唯一输入是统一社会信用代码（USCC）——*公开*的组织标识符，非个人信息。代码仅在内存中按 GB 32100-2015 核验，**绝不**落盘、缓存或转发给第三方。通过托管端点使用时，请求运行于 Apify；Apify 按其隐私政策处理计费元数据。不存储任何数据，故无需要访问或删除的留存数据。联系：经由 Apify Store 页面——源码提供申请获取。
**繁體中文。** 本服務處理的唯一輸入是統一社會信用代碼（USCC）——*公開*的組織識別碼，非個人資訊。程式碼僅在記憶體中依 GB 32100-2015 校驗，**絕不**落盤、快取或轉發給第三方。透過託管端點使用時，請求運行於 Apify；Apify 依其隱私政策處理計費中繼資料。不儲存任何資料。聯絡：經由 Apify Store 頁面——原始碼提供申請取得。
# Changelog
This Actor's version history is a separate document: https://apify.com/neeenja/cn-vat-validator-mcp/changelog.md
# Actor input Schema
## Actor input object example
```json
{}
```
# Actor output Schema
## `mcpEndpoint` (type: `string`):
Streamable HTTP MCP endpoint of this Actor run. Connect an MCP client here (Authorization: Bearer \). POST JSON-RPC messages: initialize, tools/list, tools/call.
# API
You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.
## JavaScript example
```javascript
import { ApifyClient } from 'apify-client';
// Initialize the ApifyClient with your Apify API token
// Replace the '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {};
// Run the Actor and wait for it to finish
const run = await client.actor("neeenja/cn-vat-validator-mcp").call(input);
// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
console.dir(item);
});
// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs
```
## Python example
```python
from apify_client import ApifyClient
# Initialize the ApifyClient with your Apify API token
# Replace '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = {}
# Run the Actor and wait for it to finish
run = client.actor("neeenja/cn-vat-validator-mcp").call(run_input=run_input)
# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
print(item)
# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start
```
## CLI example
```bash
echo '{}' |
apify call neeenja/cn-vat-validator-mcp --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"type": "http",
"url": "https://mcp.apify.com/?tools=fetch-actor-details,neeenja/cn-vat-validator-mcp"
}
}
}
```
The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).
## OpenAPI specification
Download the OpenAPI definition: https://api.apify.com/v2/actors/3yApL4JuUVMDFZjNz/builds/ZcFDbB9rQrJ7SuRPa/openapi.json