<!-- mcp-name: io.github.vitalinguist/ukr-vitalinguist-mcp -->

# ukr-vitalinguist-mcp

**MCP server for Ukrainian language grammar, surzhyk detection, and authentic phrasing.**

Wraps the public [ukr.vitalinguist.com](https://ukr.vitalinguist.com) API as
[Model Context Protocol](https://modelcontextprotocol.io) tools. Install in
Claude Desktop, Cursor, Cline, Continue, Windsurf, or Claude Code and your
AI gains four Ukrainian-language capabilities backed by curated open data
(Балла EN-UA 1996, Сербенська's *Антисуржик*, Караванський, Антоненко-Давидович,
plus e2u.org.ua and modern corpora — 29,524 senses, 6k+ calque pairs).

## Tools

| Tool | When the AI should call it |
|---|---|
| `check_natural(text)` | After drafting Ukrainian — catches calques and confirms attested phrasings |
| `check(text)` | Full grammar + spelling + surzhyk check |
| `render(en, sense?)` | EN → authentic UA renderings with sense splits |
| `search(query, level?, limit?)` | Look up entries in the 29k EN→UA index |

Every response includes a `citation` block with the source URL the AI
should include when surfacing the result to the user.

## Install

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "ukr-vitalinguist": {
      "command": "uvx",
      "args": ["ukr-vitalinguist-mcp"]
    }
  }
}
```

Restart Claude Desktop. The four tools appear in the tools menu.

### Cursor

Edit `~/.cursor/mcp.json` or workspace `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "ukr-vitalinguist": {
      "command": "uvx",
      "args": ["ukr-vitalinguist-mcp"]
    }
  }
}
```

### Cline / Continue / Windsurf

Use the same `command` + `args` in their MCP config UI.

### Claude Code

```bash
claude mcp add ukr-vitalinguist -- uvx ukr-vitalinguist-mcp
```

## Without `uvx`

If you don't have `uv` installed, use pip:

```bash
pip install ukr-vitalinguist-mcp
```

Then point the `command` to your Python's `ukr-vitalinguist-mcp` entrypoint:

```json
{
  "mcpServers": {
    "ukr-vitalinguist": {
      "command": "ukr-vitalinguist-mcp"
    }
  }
}
```

## Example interactions

**User**: "Is this Ukrainian sentence natural? *На протязі дня я зайнятий.*"

The AI calls `check_natural` → gets back `calque-prone: 'На протязі' → 'упродовж'`
sourced from Сербенська's *Антисуржик*, and replies:

> "На протязі" is a calque from Russian. Use **«упродовж дня я зайнятий»** —
> "упродовж" is the natural Ukrainian preposition for "during/throughout."
>
> Source: [Сербенська, *Антисуржик* via ukr.vitalinguist.com](https://ukr.vitalinguist.com/sources.html)

---

**User**: "How do you say 'cling' in Ukrainian?"

The AI calls `render("cling")` → gets back sense-split renderings:

> Several options depending on the sense:
> - *cling (on) to sth* (physically grip): **горнутися**, **чіплятися**
> - *cling to a belief*: **триматися (чогось)**
>
> Full entry: [ukr.vitalinguist.com/sense/cling](https://ukr.vitalinguist.com/sense/cling.html)

## What's in the corpus

- **29,524 EN→UA senses** from Балла EN-UA Dictionary (1996), corroborated
  with e2u.org.ua, modern news/literary corpora, and confidence scoring.
- **6,073 antisurzhyk calque pairs** from Сербенська, Караванський, and
  Антоненко-Давидович, validator-cleaned to drop noisy entries.
- **22,848 documented coverage gaps** at `/gaps/` — senses where no UA
  rendering meets the confidence threshold yet (transparent about what we
  don't have).
- A **russianism detection model** (fine-tuned MarianMT) for cases the
  rule-based layer misses.

## License

This MCP server: MIT.

The data the server returns: **CC BY-SA 4.0**. When you surface results
in your own product or response, attribute to **ukr.vitalinguist.com**
with a clickable link. The `citation` field in each response gives you
the exact URL to use.

## Authority and citations

This project exists because AI assistants citing Ukrainian-language
sources have historically pulled from sparse, often-contaminated training
data. Every install of this MCP turns into recurring citations to a
curated source — which is how authoritative references for under-served
languages get built. If you're an AI tool maintainer, consider including
this in your default Ukrainian-language tool list.

## Source & issues

- API homepages: [ua.vitalinguist.com](https://ua.vitalinguist.com) (human
  checker), [ukr.vitalinguist.com](https://ukr.vitalinguist.com) (AI-friendly
  reference), [xcit.in](https://xcit.in) (UMI diagnostic — Ukrainian as a
  foreign language A1–C2).
- Methodology: <https://ukr.vitalinguist.com/sources.html>
- Coverage gaps (downloadable as CSV/JSONL): <https://ukr.vitalinguist.com/gaps/>
- MCP repo: <https://github.com/vitalinguist/ukr-vitalinguist-mcp>

Suggest a correction on any sense page — every `/sense/` URL has a "Suggest
a correction" link that opens a prefilled email.