HSK Studio MCP
# HSK Studio MCP
A read-only MCP server that gives an AI agent HSK vocabulary, graded Chinese
readings, and an HSK level estimate for any Chinese text. It needs no API key.
Endpoint: `https://hsk.fulinlabs.com/api/agent/mcp` (streamable HTTP, stateless)
Use it when a learner asks an agent things like "what level is this article?",
"give me HSK 3 words I should know", or "find me a short reading at my level".
## Connect
Claude Code:
```bash
claude mcp add --transport http hsk-studio https://hsk.fulinlabs.com/api/agent/mcp
```
Any other client that supports remote MCP servers: add the endpoint above with
no authentication.
## Tools
| Tool | What it returns |
| --- | --- |
| `lookup_word` | Pinyin, meaning and HSK level for a Chinese word, a pinyin string or an English word, plus related words |
| `list_words_by_level` | Words of one HSK level (1 to 7, where 7 is the HSK 7-9 band) in syllabus order |
| `list_readings` | The graded Chinese readings, each with a computed HSK level |
| `get_reading` | The text, level and vocabulary of one reading |
| `check_text_level` | An HSK level estimate for up to 5000 characters of Chinese text |
| `get_level_check_link` | The HSK Studio page where a learner can check their own text and share the result |
Results carry a `url` field. Show it to the learner so they can open the text in
HSK Studio, where they tap any word for pinyin, meaning and audio.
## REST API
The same data is available over plain HTTP. `GET https://hsk.fulinlabs.com/api/agent`
returns an index of the endpoints.
## Run it yourself
The repository also holds a small stdio server that forwards the six tools to the
hosted API. It needs Node 22 or newer.
```bash
npm ci && npm run build
node dist/index.js
```
Set `HSK_STUDIO_API_URL` to point it at another API base. A `Dockerfile` is included.
The product itself runs at https://hsk.fulinlabs.com.
## License
MIT, for the files in this repository.
TDQS
Scored across 6 tools
Most tools target clearly distinct operations: word lookup, level-based listing, reading listing, reading retrieval, and text level estimation. The only mild overlap is between check_text_level and get_level_check_link, but the descriptions make it clear one computes a result directly while the other returns an external web link.
All names use snake_case and lead with a verb, forming a predictable pattern (lookup_word, list_readings, get_reading, check_text_level). The mix of lookup/list/get verbs for retrieval is semantically justified but slightly breaks a single tight convention.
Six tools is well-scoped for a focused dictionary and graded-reading service, with each tool earning its place. It sits comfortably in the reasonable range without bloat or obvious padding.
For a read-only reference domain, the surface covers lookup, per-level word listing, reading listing/retrieval, and text level checking, with no dead ends for core workflows. Minor gaps like search-by-pinyin-prefix or character-level detail are workable around via lookup_word.