Skip to main content
Glama
ChinaVisaCalc MCP Server

ChinaVisaCalc MCP Server

README.md
# ChinaVisaCalc MCP Server — China SAFEA Work Permit Points, Z-Visa, Apostille & Expat IIT Engine

![ChinaVisaCalc MCP Banner](./assets/cover.png)

## Overview & Production Architecture

**ChinaVisaCalc** ([https://chinavisacalc.com](https://chinavisacalc.com)) exposes a stateless, zero-authentication **Model Context Protocol (MCP)** server (`streamable-http` at `https://chinavisacalc.com/api/mcp`) backed directly by TypeScript immigration and taxation engines covering China SAFEA Category A/B/C work-permit points, score-deficit optimization levers, MOF/STA Circular [2023] No. 29 expatriate tax allowances (extended through Dec 31, 2027), 30-day job-switching runway deadlines under PRC Labor Contract Law Articles 37 and 50, Hague Apostille rules across 21 countries, and municipal work permit comparisons across 7 Chinese economic hubs. All 8 tools are public, deterministic, and annotated `readOnlyHint: true` with zero API keys required.

![ChinaVisaCalc Interactive Assessment Workbench](./assets/screenshot.png)

## Available MCP Tools (8 Read-Only Tools)

| Tool Name | Purpose & Deterministic Engine | Key Parameters | Safety |
| :--- | :--- | :--- | :---: |
| `calculate_safea_work_permit_points` | Evaluate foreign applicant eligibility across standard points, native English teacher (7-country passport + 120h TEFL), or WFOE entrepreneur trac | `track`*, `cityTier`, `salary`, `education` (+11 more) | `readOnly` |
| `optimize_work_permit_score_deficit` | Diagnose exact point gaps below Category B (60) or Category A (85) thresholds and rank concrete SAFEA upgrade levers such as HSK certification, > | `cityTier`, `salary`, `education`, `experience` (+4 more) | `readOnly` |
| `simulate_expat_iit_and_tax_refund` | Compare Option A fapiao-backed tax-exempt fringe benefits extended through 2027 (Circular [2023] No. 29) against Option B Tax App Special Additio | `monthlySalaryGross`*, `monthlyRentAllowance`, `monthlyHomeLeaveAllowance`, `hasChildrenEducation` (+3 more) | `readOnly` |
| `calculate_job_transfer_runway_deadlines` | Compute statutory dates under PRC Labor Contract Law Articles 37 and 50 from a resignation date, pinpointing the 15-day release letter deadline,  | `resignationDate`*, `employerWithholdingRelease` | `readOnly` |
| `verify_country_apostille_and_legalization` | Look up document authentication requirements across 21 issuing jurisdictions to distinguish single-step domestic Hague Apostille from dual-step C | `countryQuery`*, `includeTranslationRules` | `readOnly` |
| `compare_municipal_work_permit_policies` | Inspect and compare municipal processing speeds, Greater Bay Area or Hainan FTP 15% income tax rebates, Category B age-65 exceptions, and designa | `cityId`*, `compareWithCityId`, `applicantAge` | `readOnly` |
| `evaluate_fast_track_and_no_degree_pathways` | Check statutory fast-track exemptions (6x local average wage by city, Top-100 postdoc, Fortune 500 executive, Top-100/Chinese Master recent gradu | `annualSalaryRmb`, `targetCity`, `hasBachelorDegree`, `yearsExperience` (+1 more) | `readOnly` |
| `generate_visa_execution_roadmap_and_arrival_kit` | Retrieve end-to-end procedural checklists for overseas Z-visa onboarding, in-country employer changes, X1/S1 status switches, 24h police accommod | `scenarioId`*, `includeArrivalSurvivalKit`, `guideSlug` | `readOnly` |

## Live JSON-RPC 2.0 Verification Sample

Request (`POST https://chinavisacalc.com/api/mcp`):

```bash
curl -s -X POST https://chinavisacalc.com/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"calculate_job_transfer_runway_deadlines","arguments":{"resignationDate":"2026-12-01","employerWithholdingRelease":true}}}'
```

Verified Production Response:

```json
{
  "sourceEngine": "src/components/TransitionRunwayCalculator.tsx + src/data/visaScenarios.ts",
  "resignationDate": "2026-12-01",
  "milestones": {
    "step1WrittenNoticeDate": {
      "date": "2026-11-01",
      "rule": "30 days written advance notice required under PRC Labor Contract Law Art. 37."
    },
    "step2CancellationDeadline": {
      "date": "2026-12-16",
      "dayOffset": "Day +15",
      "rule": "Former employer legally mandated to issue Release Letter (离职证明) & cancel work permit within 15 days (Labor Contract Law Art. 50)."
    },
    "step3SafeTransferSubmissionCutoff": {
      "date": "2026-12-21",
      "dayOffset": "Day +20",
      "rule": "Recommended safe deadline for new sponsor to lodge online SAFEA transfer before Stay Permit expiry pressure mounts."
    },
    "step4StayPermitHardExpiry": {
      "date": "2026-12-31",
      "dayOffset": "Day +30",
      "rule": "30-Day Humanitarian Stay Permit (T-Visa / 停留证) hard cutoff; must exit Mainland China if transfer application is not locked in."
    }
  },
  "withholdingRemediationSop": {
    "legalBasis": "PRC Labor Contract Law Article 50 (《劳动合同法》第五十条) — employers cannot legally withhold release papers over commercial disputes.",
    "steps": [
      "1. Formal Evidence Trail: Demand 《离职证明》 and 《外国人工作许可证注销证明》 within 3 business days via EMS or registered WeChat.",
      "2. File Labor Arbitration: Apply at District Labor Dispute Arbitration Commission (劳动人事争议仲裁委员会) and secure 《仲裁立案通知书》.",
      "3. SAFEA Unilateral Administrative Cancellation: Present Arbitration Notice + resignation proof + contract at Science & Technology Bureau window."
    ]
  },
  "transferSteps": [
    {
      "stepNumber": "01",
      "title": "Cancellation of Current Work Permit by Former Employer",
      "duration": "3 - 5 Business Days",
      "partyResponsible": "Former Employer HR (via SAFEA system)",
      "description": "Upon resigning, your former employer must submit a work permit cancellation request on the SAFEA system and issue you the official \"Work Permit Cancellation Certificate\" (外国人工作许可证注销证明) along with an Employment Release / Recommendation Letter.",
      "requiredDocuments": [
        "Work Permit Cancellation Certificate",
        "Official Release Letter (离职证明) stating good standing and departure date"
      ],
      "criticalTips": "Ensure the cancellation reason states \"Contract Expiration\" or \"Mutual Agreement Resignation\" to facilitate a seamless transfer without dispute notes."
    },
    {
      "stepNumber": "02",
      "title": "New Employer Submits Work Permit Transfer (Change of Employer)",
      "duration": "5 - 10 Business Days",
      "partyResponsible": "New Sponsoring Employer HR",
      "description": "New employer logs into SAFEA to initiate an employer transfer. If the new job role falls in the same category/industry, re-authentication of overseas degrees and background checks is normally waived.",
      "requiredDocuments": [
        "Work Permit Cancellation Certificate",
        "New Signed Labor Contract",
        "New Company Business License",
        "Previous Work Permit Card scan",
        "Valid Passport & Residence Permit"
      ],
      "criticalTips": "If your existing Residence Permit is expiring during the transfer window, apply for a 30-day Humanitarian/Stay Visa (T Visa / 停留证) at the Exit-Entry Bureau to maintain continuous legal status."
    },
    {
      "stepNumber": "03",
      "title": "Update Work Residence Permit at Exit-Entry Bureau (PSB)",
      "duration": "5 - 7 Business Days",
      "partyResponsible": "Applicant + New Employer HR",
      "description": "Submit your updated Foreigner's Work Permit and application dossier to the local Public Security Bureau to update your sponsoring company on the Work Residence Permit sticker.",
      "requiredDocuments": [
        "New Foreigner's Work Permit Card/Confirmation",
        "Application Form with New Company Stamp",
        "Original Passport"
      ],
      "criticalTips": "You DO NOT need to exit mainland China or apply for a new Z Visa during an in-country transfer as long as permits remain uninterrupted."
    }
  ],
  "officialGuideUrl": "https://chinavisacalc.com/guides/work-permit-transfer-process"
}
```

## Quick Client Configuration (Claude Desktop / Cursor / Windsurf / Hermes)

```json
{
  "mcpServers": {
    "chinavisacalc": {
      "type": "streamable-http",
      "url": "https://chinavisacalc.com/api/mcp"
    }
  }
}
```

Or inspect directly from any Node.js terminal via the pinned official CLI:

```bash
npx -y chinavisacalc-cli@1.0.0 tools
npx -y chinavisacalc-cli@1.0.0 demo
```

## Statutory Compliance & Reference Matrices

### SAFEA Direct Category A 6x Local Average Wage Benchmarks

| City / Economic Region | Monthly Salary Benchmark (6x) | Annual Gross Threshold (RMB) | Non-Degree Legal Impact |
| :--- | :---: | :---: | :--- |
| **Shanghai** | `>= ¥73,100 / mo` | **¥877,200 / yr** | Direct Category A exemption: waives bachelor degree, age ceiling & 2-year experience |
| **Beijing** | `>= ¥71,500 / mo` | **¥858,000 / yr** | Paperless online pre-approval (~5 business days Green Channel) |
| **Shenzhen / Guangzhou** | `>= ¥68,200 / mo` | **¥818,400 / yr** | Eligible for Greater Bay Area 15% Individual Income Tax cap rebate |
| **Hangzhou / Chengdu / Wuhan** | `>= ¥52,000 / mo` | **¥624,000 / yr** | Combines with +4 to +10 regional incentive points under Category B matrix |
| **Third-Tier / Western Cities** | `>= ¥38,000 / mo` | **¥456,000 / yr** | National Key Development Zone & Western Corridor fast-track qualification |

### Statutory Job-Switching Runway (PRC Labor Contract Law Art. 37 & Art. 50)

| Legal Milestone | Statutory Offset | Controlling Chinese Statute & Operational Action |
| :--- | :---: | :--- |
| **Written Resignation Notice** | `Day -30` | Required 30-day formal written notice via traceable email or WeChat (Art. 37) |
| **Employer Release & Cancellation** | `Day +15` | Mandatory 15-day deadline for Release Letter (离职证明) & SAFEA cancellation (Art. 50) |
| **Safe Online Transfer Filing** | `Day +20` | Target submission cutoff on `fuwu.most.gov.cn` before Stay Permit pressure peaks |
| **30-Day Stay Permit Cutoff** | `Day +30` | Hard expiry for Humanitarian T-Visa (停留证); file Labor Arbitration if withheld |

### Municipal Fast-Track Turnarounds & Expat IIT Fringe Rules

| City Hub | Cat A FWP Days | Cat B FWP Days | Regional Policy Highlight |
| :--- | :---: | :---: | :--- |
| **Shanghai** | `3 days` | `10 days` | Single-Window combined FWP + Residence Permit in 7 days; Master's experience waiver |
| **Shenzhen** | `3 days` | `8 days` | Greater Bay Area IIT 15% effective tax cap rebate; Qianhai license recognition |
| **Hangzhou** | `3 days` | `7 days` | Digital economy fast-track & international graduate entrepreneurship residence |
| **Hainan FTP** | `1 day` | `5 days` | **15% IIT tax cap** + Category B **age limit extended to 65** (vs 60 nationwide) |

## Technical Architecture & Editorial Reference

![ChinaVisaCalc Engineering Blueprint](./assets/editorial.png)

## Official Web Tools & Authoritative Guides

- **[ChinaVisaCalc Official Portal — Work Permit Points & Z-Visa Calculator](https://chinavisacalc.com)** — `https://chinavisacalc.com`
- **[China Z-Visa Step-by-Step Application & Document Checklist](https://chinavisacalc.com/z-visa)** — `https://chinavisacalc.com/z-visa`
- **[Foreigner Work Permit Category A/B/C Policy & Processing Guide](https://chinavisacalc.com/work-visa)** — `https://chinavisacalc.com/work-visa`
- **[China Work Visa Legal Workarounds, Apostille & Transfer Guides](https://chinavisacalc.com/guides)** — `https://chinavisacalc.com/guides`
- **[China Work Visa Without a Bachelor Degree: 4 Legal SAFEA Workarounds](https://chinavisacalc.com/guides/work-visa-without-degree)** — `https://chinavisacalc.com/guides/work-visa-without-degree`
- **[How to Reach 60 Points for a Category B China Work Permit](https://chinavisacalc.com/guides/how-to-reach-60-points)** — `https://chinavisacalc.com/guides/how-to-reach-60-points`
- **[China Work Permit Tier A, B, and C Classification Explained](https://chinavisacalc.com/guides/tier-a-b-c-explained)** — `https://chinavisacalc.com/guides/tier-a-b-c-explained`
- **[China Hague Apostille & Document Authentication Country Guide](https://chinavisacalc.com/guides/apostille-authentication-guide)** — `https://chinavisacalc.com/guides/apostille-authentication-guide`
- **[In-China Work Permit Transfer & 30-Day Stay Permit Runway Guide](https://chinavisacalc.com/guides/work-permit-transfer-process)** — `https://chinavisacalc.com/guides/work-permit-transfer-process`
- **[China Foreign Language Teacher Z-Visa & 7-Nation Native Speaker Rule](https://chinavisacalc.com/guides/english-teacher-visa-china)** — `https://chinavisacalc.com/guides/english-teacher-visa-china`

## License

MIT License — maintained by **[ChinaVisaCalc](https://chinavisacalc.com)**.