Metadata-Version: 2.4
Name: cymraeg-mcp
Version: 0.1.0
Summary: Welsh proofing/validation MCP server — deterministic spelling (hunspell cy_GB) and mutation (treiglad) checking, 100% offline
Project-URL: Homepage, https://github.com/dwain-barnes/cymraeg-mcp
Project-URL: HuggingFace, https://huggingface.co/EryriLabs
Author: Dwain Barnes (EryriLabs)
License: MIT
License-File: LICENSE
Keywords: cymraeg,mcp,mutations,spellcheck,treiglad,welsh
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: spylls>=0.1.7
Description-Content-Type: text/markdown

# cymraeg-mcp

**Gweinydd MCP prawfddarllen Cymraeg / Welsh proofing & validation MCP server**

![cymraeg-mcp yn dal gwallau treiglo / catching mutation errors](assets/demo.gif)

[English below](#english)

---

## Cymraeg

Haen ddilysu **benderfynadwy** ar gyfer testun Cymraeg: gwirio sillafu (hunspell `cy_GB`) a gwirio treigladau (peiriant rheolau lleol). **100% lleol — dim APIau allanol, dim allweddi API, dim lawrlwytho wrth redeg, yn gweithio'n gyfan gwbl all-lein.**

**Nid pecyn cymorth Cymraeg cyffredinol mo hwn.** Mae LLMau eisoes yn ysgrifennu Cymraeg dda — y broblem yw nad oes modd *gwarantu* cywirdeb allbwn tebygolaethol. Yr egwyddor yma yw: **"Claude sy'n drafftio, hwn sy'n dilysu."** Wedi'i anelu at unrhyw un sy'n cyhoeddi cynnwys dwyieithog dan Safonau'r Gymraeg — cynghorau, GIG Cymru, cyrff cyhoeddus — sydd angen gramadeg gwarantedig-gywir.

### Offer

| Offeryn | Mewnbwn | Allbwn |
|---|---|---|
| `cymraeg_check_spelling` | testun Cymraeg | camsillafiadau + awgrymiadau (hunspell cy_GB Prifysgol Bangor) |
| `cymraeg_check_mutations` | testun Cymraeg | gwallau treiglo (meddal / trwynol / llaes) gyda chywiriadau, hyder, a'r rheol yn ddwyieithog |
| `cymraeg_explain_mutation` | gair + cyd-destun | pa dreiglad sy'n berthnasol a pham, ynghyd â thabl treiglo llawn y gair |
| `cymraeg_proof_text` | testun Cymraeg | adroddiad cyfun: sillafu + treigladau mewn un pas |

### Gosod

Gweler y cyfarwyddiadau gosod yn yr adran Saesneg isod — mae'r gorchmynion yn union yr un fath.

### Cyfrannu

Mae'r rheolau treiglo yn [data/mutation_rules.yaml](data/mutation_rules.yaml) — ychwanegwch sbardunau, enwau benywaidd, neu eithriadau yno a chyflwynwch PR. Rhedwch `uv run pytest` cyn cyflwyno.

---

## English

A **deterministic validation layer** for Welsh text: spellchecking (hunspell `cy_GB`) and mutation checking (a local rules engine). **100% local — no external APIs, no API keys, no first-run downloads, fully offline.**

**This is NOT a general Welsh toolkit.** LLMs already write good Welsh — the problem is that probabilistic output can't be *guaranteed* correct. The positioning here is: **"Claude drafts it, this verifies it."** Target users: anyone publishing bilingual content under the Welsh Language Standards (councils, NHS Wales, public bodies) who need guaranteed-correct grammar rather than probabilistic LLM output.

**Novelty:** as of July 2026, no other Welsh-language MCP server exists.

### Tools

| Tool | Input | Output |
|---|---|---|
| `cymraeg_check_spelling` | Welsh text | misspellings + up to 5 suggestions each (Bangor University hunspell cy_GB, 72k+ entries, bundled) |
| `cymraeg_check_mutations` | Welsh text | mutation errors (treiglad meddal / trwynol / llaes) with corrections, confidence levels, and the rule cited bilingually |
| `cymraeg_explain_mutation` | word + context | which mutation applies and why, whether the word is radical or mutated, and the word's full mutation table |
| `cymraeg_proof_text` | Welsh text | combined report: spelling + mutation issues in one pass |

All tools are read-only, idempotent, and fully offline.

### What the mutation engine covers

- **Soft mutation (treiglad meddal):** after the prepositions am, ar, at, dan, tan, dros, drwy/trwy, gan, heb, hyd, i, o, wrth; after dy, dau, dwy, neu, mor, rhy, pur, go, dyma, dyna, dacw, pa; feminine singular nouns after y/yr/'r/un (using an extensible noun list); with the ll/rh exceptions applied.
- **Nasal mutation (treiglad trwynol):** after fy; yn/ym/yng locative with **form agreement** (flags "yn Nghaerdydd" → "yng Nghaerdydd", "ym Bangor" → "ym Mangor"); blynedd/blwydd after numerals (pum mlynedd).
- **Aspirate mutation (treiglad llaes):** after â, gyda, tua, tri, chwe, a (and), ei (her), na.
- **Ambiguity handled honestly:** "ei" (his/her) is disambiguated by an echoing pronoun where present ("ei tad hi" → "ei thad hi"); "a" offers both the aspirate (conjunction) and soft (relative pronoun) readings; genuinely ambiguous cases are reported at low confidence and hidden by default.

The engine is tuned for **precision over recall**: it only flags what it can justify from an explicit trigger rule plus a dictionary check, and every finding carries a confidence level. A clean result does not guarantee every mutation is correct — see limitations.

### Install

Requires Python 3.11+. With [uv](https://docs.astral.sh/uv/) (preferred):

```bash
git clone https://github.com/dwain-barnes/cymraeg-mcp
cd cymraeg-mcp
uv sync
```

Or with pip:

```bash
pip install .
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cymraeg": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/cymraeg-mcp", "cymraeg-mcp"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add cymraeg -- uv run --directory /path/to/cymraeg-mcp cymraeg-mcp
```

### Example

> **Input:** `cymraeg_proof_text("Dw i eisiau mynd i Caerdydd gyda fy cath.")`
>
> **Output:** 2 mutation issues — `Caerdydd` → `Gaerdydd` (soft mutation after the preposition 'i'), `cath` → `nghath` (nasal mutation after 'fy').

### Limitations (read this)

- **A clean report is not a proof of correctness.** The engine deliberately stays silent where Welsh is genuinely ambiguous without deeper parsing — e.g. unmutated words after predicative/locative "yn", gender of nouns not in its list, mutation after inflected verbs (object soft mutation), and wrong-mutation-type cases like "gyda dad".
- The feminine-noun rule only covers nouns listed in `data/mutation_rules.yaml` (extensible by PR).
- The dictionary includes correctly mutated forms, so the spellchecker will not flag a mutation error as a misspelling — that's the mutation checker's job.
- hunspell `cy_GB` is comprehensive (72k+ stems plus affix rules) but no dictionary is complete; rare proper nouns may be reported as unknown.

### Licensing

- **Code:** MIT © Dwain Barnes (EryriLabs).
- **Bundled dictionary** (`data/dictionaries/cy_GB.*`): © Bangor University (Prifysgol Bangor) and Troi, licensed under the **LGPL v3 or later** — see [data/dictionaries/LICENCE](data/dictionaries/LICENCE). It is redistributed unmodified with its licence and attribution intact, as permitted by the LGPL.
- No data leaves your machine; there is no telemetry and no network access.

### Contributing

Mutation rules live in [data/mutation_rules.yaml](data/mutation_rules.yaml) — triggers, feminine nouns, exceptions and never-mutate words are all data, not code. Add a rule, add a test case to `tests/test_mutations.py`, and run:

```bash
uv run pytest
uv run ruff check src tests
```

### Credits

Built by **Dwain Barnes / EryriLabs** — [HuggingFace](https://huggingface.co/EryriLabs). Dictionary by [Uned Technolegau Iaith, Prifysgol Bangor](https://github.com/techiaith/hunspell-cy).
