# hsk-mcp

A remote Model Context Protocol (MCP) server that gives AI assistants structured access to the complete HSK Chinese vocabulary dataset. It exposes 13 tools and 8 resources covering word lookup, trans…

## Quick Start

```bash
# Connect this server (installs CLI if needed)
npx -y @smithery/cli@latest mcp add kuibin-dev/hsk-mcp

# Browse available tools
npx -y @smithery/cli@latest tool list kuibin-dev/hsk-mcp

# Get full schema for a tool
npx -y @smithery/cli@latest tool get kuibin-dev/hsk-mcp hsk_lookup

# Call a tool
npx -y @smithery/cli@latest tool call kuibin-dev/hsk-mcp hsk_lookup '{}'
```

## Direct MCP Connection

Endpoint: `https://hsk-mcp--kuibin-dev.run.tools`

## Tools (13)

- `hsk_lookup` — Look up a Chinese word by simplified characters, traditional characters, or pinyin. Returns all pronunciation forms wit…
- `hsk_frequency` — Get the frequency ranking and usage statistics for a Chinese word. Returns the word's rank among HSK vocabulary (1 = mo…
- `hsk_convert_script` — Convert a Chinese word to all 5 transcription systems: pinyin (tone marks), numeric (tone numbers), Wade-Giles, Bopomof…
- `hsk_classifier` — Find the measure word (classifier / 量词) for a Chinese noun. Returns all classifiers associated with the word. Empty lis…
- `hsk_convert_characters` — Convert a Chinese word between simplified and traditional characters. Accepts either script and returns both with pinyi…
- `hsk_search_meaning` — Search for HSK words by English meaning using full-text search. Each result includes simplified characters, pinyin, all…
- `hsk_words_by_radical` — Find all HSK words sharing a given radical (部首). Each word includes simplified/traditional characters, pinyin, part of …
- `hsk_polyphones` — List Chinese characters with multiple pronunciations (多音字) in HSK vocabulary. Each result includes all pronunciation fo…
- `hsk_homophones` — Find HSK words sharing the same pinyin pronunciation (homophones). Useful for drilling tone-pair distinctions. Each res…
- `hsk_build_study_set` — Build a study set of HSK words for a given level, ordered by frequency (most common first). Each word includes simplifi…
- `hsk_suggest_next` — Suggest the next words to learn at a given HSK level, excluding words already known. Each word includes simplified/trad…
- `hsk_compare` — Compare 2-5 Chinese words side by side. Each word shows simplified/traditional characters, pinyin, part of speech, freq…
- `hsk_diff` — Compare two HSK levels to see vocabulary overlap and differences. Shows words exclusive to each level and words shared …

```bash
# Get full input/output schema for a tool
npx -y @smithery/cli@latest tool get kuibin-dev/hsk-mcp <tool-name>
```

## Resources

- `hsk://meta` — Server metadata: dataset version, tool count, and vocabulary statistics.
- `hsk://level/1` — HSK 3.0 level 1 vocabulary list (brief format, ordered by frequency).
- `hsk://level/2` — HSK 3.0 level 2 vocabulary list (brief format, ordered by frequency).
- `hsk://level/3` — HSK 3.0 level 3 vocabulary list (brief format, ordered by frequency).
- `hsk://level/4` — HSK 3.0 level 4 vocabulary list (brief format, ordered by frequency).
- `hsk://level/5` — HSK 3.0 level 5 vocabulary list (brief format, ordered by frequency).
- `hsk://level/6` — HSK 3.0 level 6 vocabulary list (brief format, ordered by frequency).
- `hsk://level/7` — HSK 3.0 level 7 vocabulary list (brief format, ordered by frequency).

## Prompts (2)

- `hsk-study-session` (level) — Start a guided HSK study session. Builds a study set for your level, lets you exclude words you already know, and prese…
- `hsk-word-deep-dive` (word) — Get comprehensive details about a Chinese word: all transcription systems, frequency rank, part of speech, classifiers,…