# MandarinClips (v3.2.5)

> Authentic Chinese cinema dialogue corpus for Mandarin language learners, educators, and AI agents.

MandarinClips is an immersion-focused Chinese language learning platform, pedagogical API, and Model Context Protocol (MCP) server built from authentic Chinese movies and television series. It provides English-speaking learners, TCSL (Teaching Chinese as a Second Language) educators, and AI agents with a sentence-level cinematic dialogue concordancer to bridge the gap between classroom textbooks and real-world spoken Chinese.

Learners and AI agents can search any Chinese phrase, vocabulary item, or grammar pattern and instantly study how native speakers naturally use it across diverse cinematic contexts with multi-turn dialogue alignments.

## Overview & Verified Scale

* Live Dialogue Clips: 182,404 curated video clips (~3 seconds each, single-sentence focus with 3-turn context)
* Spoken Dialogue Lines: 412,323 verified lines of dialogue
* Primary Interface Language: English (served directly at clean root `/` routes)
* Pedagogical Framework: Schema.org LearningResource, DefinedTerm, and official HSK 3.0 standards
* Technology Stack: Rust 2021 (Axum 0.8, Askama 0.12, sqlx 0.8), PostgreSQL 18 (PGroonga, pgvector HNSW, pg_trgm), moka L1/L2/L3 in-memory concurrent cache

## Model Context Protocol (MCP) & AI Integration

MandarinClips natively supports the open Model Context Protocol (MCP), enabling Claude Desktop, Cursor, and web-based AI agents to query the cinema corpus programmatically:

* Official MCP Registry Namespace: `com.mandarinclips/mcp` (v1.1.0 Verified)
* Streamable HTTP / SSE Endpoint: https://www.mandarinclips.com/mcp/sse
* Available Tools:
  - `search_dialogue_clips`: Search 180,000+ authentic cinema lines by Chinese/Pinyin with 3-turn conversational context (Previous, Target, Next) and English pragmatic subtext.
  - `get_hsk_vocabulary`: Retrieve official HSK 3.0 vocabulary details, definitions, and cinema video examples.
  - `get_grammar_pattern`: Look up Chinese grammar structures, visual slot formulas, and spoken variations.

## Core Capabilities

* Multi-Modal Contextual Tracks: Simultaneous display of Simplified Chinese characters, standardized Pinyin with tone marks, natural English translations, and native video turn sequences.
* Bilingual Full-Text Search: Powered by PostgreSQL PGroonga and pg_trgm GIN indexes, supporting Simplified Chinese characters (e.g., 算了, 应该的) and untoned lowercase Pinyin (e.g., "suan le ba", "ni hao").
* HSK 3.0 Proficiency Indexing: Graded across all official HSK 3.0 bands (Levels 1 through 7-9) with curated featured clip acceleration.
* 10-Dimensional Pragmatic Context: Controlled scene taxonomies (workplace, dining, social, family, conflict, etc.), native English pragmatic subtext (speaker's actual intent vs. literal wording), communicative speech styles, and registers.
* Non-Linear Semantic Knowledge Graph: Directed graph relations connecting similar expressions, contrastive retorts, and pragmatic alternatives.
* Instant Audio Shadowing & Looping: Zero-latency browser-based native playback designed for pronunciation and rhythm training.

## Core Content Hubs (Canonical Clean Routes)

All active content is served directly under root-level canonical routes without `/en/` prefixes:

* Homepage & Discovery: https://www.mandarinclips.com/
* HSK 3.0 Vocabulary Atlas: https://www.mandarinclips.com/hsk
* HSK 3.0 Anki Decks (All Levels): https://www.mandarinclips.com/hsk/anki-decks
* Conversational Expressions: https://www.mandarinclips.com/expressions
* Sentence Blueprints (Grammar): https://www.mandarinclips.com/grammar
* Pragmatic Communicative Scenes: https://www.mandarinclips.com/scenes
* TV Shows & Movies Directory: https://www.mandarinclips.com/shows
* Unified Cinema Corpus Search: https://www.mandarinclips.com/search
* Educational Insights & Blog: https://www.mandarinclips.com/blog/
* Academic Access for Professors: https://www.mandarinclips.com/educators
* Chinese to Pinyin Converter: https://www.mandarinclips.com/tools/pinyin-converter
* HSK Level Checker: https://www.mandarinclips.com/tools/hsk-level-checker
* HSK Vocabulary Coverage Checker: https://www.mandarinclips.com/tools/hsk-vocab-checker
* Text Analyzer Hub: https://www.mandarinclips.com/tools/text-analyzer
* Learning Resources Directory: https://www.mandarinclips.com/resources
* Pricing & Plans (Pro Membership): https://www.mandarinclips.com/pricing

## Mobile RESTful API (`/api/v1/*`)

MandarinClips exposes a pure, 100% structured JSON RESTful API for mobile applications (Flutter) and third-party integrations:

* `GET /api/v1/homepage`: Complete homepage bundle with curated clips and exploration paths.
* `GET /api/v1/search`: Hybrid full-text and Pinyin search with multi-dimensional filtering.
* `GET /api/v1/clips/{id}`: Full semantic dossier for a dialogue clip including 3-turn context and relations.
* `GET /api/v1/hsk/{level}`: Paginated vocabulary list for HSK 3.0 levels 1 to 7.
* `GET /api/v1/words/{slug}`: Word definition and authentic cinema dialogue examples.
* `POST /api/v1/tools/pinyin`: In-memory Pinyin conversion (marks, numbers, none).
* `POST /api/v1/tools/hsk-level-check`: Sentence difficulty and HSK band estimation.
* `POST /api/v1/tools/hsk-vocab-check`: Vocabulary coverage breakdown and unlisted word extraction.
* `GET /api/v1/auth/me`: Current authenticated user profile and subscription tier.
* Authentication: Supports `Authorization: Bearer <session_token>` header or `better-auth.session_token` Cookie. Unauthenticated requests to `/api/v1/*` strictly receive HTTP 401 JSON.

## URL & Canonical Conventions

Individual clip, word, and grammar dossiers follow strict SEO/GEO friendly slug patterns:

* Clip Dossier: https://www.mandarinclips.com/clip/{clip_id}
  Example: https://www.mandarinclips.com/clip/1a6bc231-wei-mian-tai-qing-le-ba-1373000
* HSK Word Dossier: https://www.mandarinclips.com/word/{slug}
  Example: https://www.mandarinclips.com/word/ai-1
* Grammar Blueprint: https://www.mandarinclips.com/grammar/{slug}
  Example: https://www.mandarinclips.com/grammar/hai-shi-ba
* Pragmatic Scene Hub: https://www.mandarinclips.com/scenes/{scene_code}
  Example: https://www.mandarinclips.com/scenes/polite-refusal

All historical multilingual paths (such as `/zh/*`, `/de/*`, `/es/*`, `/fr/*`, `/ja/*`, `/ko/*`, and legacy `/en/*`) are single-hop HTTP 301 permanently redirected to the clean canonical root URLs, consolidating all external backlinks and domain authority into the canonical English interface.

## Target Audience

* English-speaking self-learners bridging textbook theory into authentic spoken fluency.
* TCSL / CSL (Teaching Chinese as a Second Language) educators and university professors creating lesson plans and sourcing authentic example sentences.
* Advanced HSK students mastering nuanced modal particles, colloquial hedging, and cultural subtexts.
* NLP researchers, lexicographers, and AI agent builders requiring verified Chinese cinema dialogue alignments.

## Platform & Policies

* Website: https://www.mandarinclips.com
* Creator Mission: "Learn Chinese from real conversations instead of textbook sentences."
* Account & API Key Management: https://www.mandarinclips.com/account
* Fair Use & DMCA Notice: https://www.mandarinclips.com/fair-use
* Privacy Policy: https://www.mandarinclips.com/privacy
* Terms of Service: https://www.mandarinclips.com/terms