# ainu-mcp

> A Model Context Protocol (MCP) server for the Ainu language. One endpoint
> exposes corpus search + word frequencies, multi-dictionary lookup, grammar
> references, morpheme/lexeme decomposition, script conversion, the textual-
> sources catalogue, and read/write access to the Itak-uoeroskip glossary.

Endpoint (Streamable HTTP): https://mcp.aynu.org/mcp
Transport: MCP over Streamable HTTP (legacy SSE at /sse)
Auth: OAuth 2.1 — "Sign in with GitHub". Unauthenticated requests get 401 with
  WWW-Authenticate pointing at the OAuth metadata, which MCP clients follow.
Health: GET /health (no auth) → JSON {status: ok|degraded|error}; 200 when the
  Turso reference store is reachable and seeded, 503 otherwise.

## Access
- Any authenticated GitHub user: read/reference tools.
- Members of the "aynumosir" GitHub org: also glossary write + maintenance tools.

## Connect
- Claude Code:   claude mcp add --transport http ainu https://mcp.aynu.org/mcp
- Claude Desktop / ChatGPT: add a custom connector with URL https://mcp.aynu.org/mcp
A browser GitHub sign-in happens once; the token is stored and reused.

## Tools
- corpus_search(query, lang=ain|jpn|any, dialect?, author?, limit?) — search ~195k aligned Ainu/Japanese sentences
- corpus_stats() — total sentences + dialect distribution
- corpus_word_frequency(word) — corpus frequency of a word: count, rank, stopword flag, totals (affix clitics normalized)
- corpus_frequency_list(limit?, offset?, include_stopwords?, min_count?) — ranked token frequency list (drop stopwords with include_stopwords=false)
- corpus_stopwords() — Ainu stopword list (from aynumosir/ainu-stopwords)
- dictionary_list() — list dictionaries with entry counts
- dictionary_lookup(word, dicts?, fields?, limit?) — substring lookup across any field of 80+ dictionaries
- dictionary_reverse_lookup(aynu, dicts?, limit?) — Ainu form -> Japanese/English glosses (exact then substring)
- grammar_list(kind?) — list grammar books/articles
- grammar_search(query, include_transcribed?, limit?) — filename/title/author + transcribed-fulltext search
- morpheme_decompose(word, mode=nested|flat|first) — decompose an Ainu word into morphemes (mdb.aynu.org); known lemmas resolve directly, unknown forms fall back to greedy-longest segmentation
- morpheme_search(query, limit?) — search the morpheme inventory (mdb.aynu.org) by lemma, allomorph, or gloss; returns category, glosses, frequency, verified flag
- lexeme_search(query, limit?) — search the lexeme bank (語彙素層, mdb.aynu.org) by lemma, kana, or gloss; returns POS, glosses, dialects, linked morpheme ids
- sources_search(query?, category?, type?, region?, language?, limit?) — search the textual-sources catalogue (db.aynu.org)
- source_get(slug) — full detail for one source (bibliographic record + persons/places/institutions/links/relations/tags)
- convert_script(text, from_script, to_script) — convert between latn/kana/cyrl
- detect_script(text) — detect latn/kana/cyrl
- script_all(text) — all three script renditions
- entry_research(word, ...) — composed: scripts + glossary + dictionaries + corpus for one word
- glossary_list_categories() — glossary sheet tabs with metadata
- glossary_list_entries(category, limit?, offset?) — page through a category
- glossary_get_entry(category, row) — one entry (+ row_hash for safe edits)
- glossary_search(query, fields?, category?, limit?) — substring search the glossary
- glossary_untranslated(category?, langs?, limit?) — rows missing target-language columns
- glossary_add_entry(category, fields)            [aynumosir members]
- glossary_update_entry(category, row, fields, expected_row_hash?)  [aynumosir members]
- glossary_audit()                                 [aynumosir members]
- glossary_missing_high_frequency(top_n?, min_count?)  [aynumosir members]
- glossary_refresh_site_cache(dry_run?)            [aynumosir members]
- source_add(title, type, category, …)             [aynumosir members]
- source_update(slug, …)                           [aynumosir members]

## Related
- itak.aynu.org — the Itak-uoeroskip glossary this server edits
- Part of the aynu.org family of Ainu-language tools