# HanyuGuide

Guided Chinese lessons for adult beginners: real conversations with audio, clear grammar notes and practice, plus reviews timed so you remember. Start lesson 1 free.

## 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

- 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`, `mcp:lists:write`, `mcp:lists:manage`, and `mcp:study:write` scopes.
- User MCP: `POST https://hanyuguide.com/mcp/hanyuguide-user` needs a free HanyuGuide account for every tool, the dictionary, pinyin, stroke, and HSK quiz tools included, and exposes learner context and personal lists with `mcp:use`, bulk word saving with `mcp:lists:write`, bulk list management with `mcp:lists:manage`, and saving flashcard answers from `study_session` with `mcp:study:write`. Use bulk tools for multiple words or lists, and obey `Retry-After` on HTTP 429.
- Claude: HanyuGuide is listed in Claude's connector directory at https://claude.ai/directory/connectors/hanyuguide.
- ChatGPT: HanyuGuide is a ChatGPT plugin at https://chatgpt.com/plugins/plugin_asdk_app_6abf66b6999c81918a2059f1810edc7c.
- Setup guide for people: https://hanyuguide.com/ai-connections
- 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.