# HanyuGuide

Learning Chinese starts easy, then review piles up. HanyuGuide manages new words and reviews together so progress stays smooth. Affordable yearly and lifetime plans.

## Summary

- HanyuGuide helps learners build Mandarin fluency with pinyin input, recall-heavy review, and spaced repetition.
- Public content includes learning tools, vocabulary lists, grammar explainers, blog posts, and a searchable dictionary.
- Personal study queues, dashboards, and billing flows require authentication. Most study actions also require an active subscription.

## Public URLs

- Home: https://hanyuguide.com
- Tools: https://hanyuguide.com/tools
- Vocabulary: https://hanyuguide.com/vocabulary
- Dictionary: https://hanyuguide.com/dictionary
- Grammar: https://hanyuguide.com/grammar
- Blog: https://hanyuguide.com/blog
- Pricing: https://hanyuguide.com/pricing
- Sitemap: https://hanyuguide.com/sitemap.xml
- API catalog: https://hanyuguide.com/.well-known/api-catalog
- ARD AI catalog: https://hanyuguide.com/.well-known/ai-catalog.json
- MCP manifest: https://hanyuguide.com/.well-known/mcp
- MCP server card: https://hanyuguide.com/.well-known/mcp/server-card.json
- OAuth authorization server metadata: https://hanyuguide.com/.well-known/oauth-authorization-server
- OAuth protected resource metadata: https://hanyuguide.com/.well-known/oauth-protected-resource
- Agent Skills: https://hanyuguide.com/.well-known/agent-skills/index.json
- LLM summary: https://hanyuguide.com/llms.txt

## Public API

- OpenAPI: `GET https://hanyuguide.com/api/agent/v1/openapi.json` describes the public API in OpenAPI 3.1 JSON.
- Dictionary search: `GET https://hanyuguide.com/api/agent/v1/dictionary/search?query=你好&script=traditional` returns public dictionary search results in JSON and supports `script=simplified|traditional`.
- Dictionary entry: `GET https://hanyuguide.com/api/agent/v1/dictionary/entries/%E4%BD%A0%E5%A5%BD?script=traditional` returns a full entry payload while keeping the canonical identifier simplified.
- Pinyin conversion: `POST https://hanyuguide.com/api/agent/v1/pinyin/convert` with JSON like `{"text":"中国人abc，你好！"}` returns the original `text`, a compiled `pinyin` string, and ordered `segments`.
- Pinyin values are returned exactly as stored in the database, using tone marks when present.

## MCP

- Public MCP: `POST https://hanyuguide.com/mcp/hanyuguide` exposes read-only dictionary search, dictionary entry, pinyin conversion, and character stroke metadata tools.
- OAuth discovery: `GET https://hanyuguide.com/.well-known/oauth-authorization-server` advertises Passport OAuth endpoints and `GET https://hanyuguide.com/.well-known/oauth-protected-resource` advertises the `mcp:use` protected resource scope.
- WebMCP-capable browsers receive `dictionary_search`, `dictionary_entry`, and `pinyin_convert` tools on page load.

## Notes for agents

- Localized public pages are available under locale-prefixed paths such as `/hi/...`.
- Pricing and trial presentation can vary by region.
- Do not assume authenticated study or billing endpoints are public.
- Public dictionary HTML pages also expose simplified/traditional display switching. Logged-in users can save that preference in settings, and accounts created from a traditional dictionary page default to traditional display.
- For machine integration, prefer the OpenAPI description and the versioned `/api/agent/v1/...` endpoints over the older UI-oriented web routes.