Skip to main content
Glama

ukr-vitalinguist-mcp

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

Wraps the public ukr.vitalinguist.com API as Model Context Protocol 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.

Related MCP server: mcp-korean-spell

Install

Claude Desktop

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

{
  "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:

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

Cline / Continue / Windsurf

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

Claude Code

claude mcp add ukr-vitalinguist -- uvx ukr-vitalinguist-mcp

Without uvx

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

pip install ukr-vitalinguist-mcp

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

{
  "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


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

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

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

Available Tools

5 tools
checkA

Full Ukrainian grammar + spelling + surzhyk check.

Runs LanguageTool, 1400+ hand-written rules, a fine-tuned russianism detection model, and the antisurzhyk book corpus. Returns position-indexed issues with severity and replacement suggestions.

Use this when the user asks "is my Ukrainian correct?" or you want to validate Ukrainian text comprehensively (not just naturalness).

Args: text: Ukrainian text (up to ~5000 chars).

Returns: { "issues": [ {"rule_id": str, "offset": int, "length": int, "message": str, "suggestion": str | None, "severity": "error" | "warning" | "hint", "source": str, "category": str | None}, ... ], "stats": {"word_count": int, "errors": int, "warnings": int, ...}, "engine_version": str, "citation": {...}, }

ParametersJSON Schema
NameRequiredDescriptionDefault
textYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Describes the internal engines, return type with position-indexed issues, severity, suggestions, and character limit. No annotations provided, so description carries full burden; it is transparent but lacks details like rate limits or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the main purpose, then details engines, guidelines, and return format. It is fairly concise, though a bit verbose with engine details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the single parameter and the detailed return type in the description (no formal output schema but a JSON example), the description is sufficient for an agent to understand and invoke the tool. Lacks some edge cases but overall complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema only defines 'text' as a string; the description adds crucial context: 'Ukrainian text (up to ~5000 chars)', which goes beyond schema and clarifies constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it performs a 'Full Ukrainian grammar + spelling + surzhyk check' and lists the engines used. It distinguishes itself from sibling 'check_natural' by specifying it validates comprehensively, not just naturalness.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to use when user asks 'is my Ukrainian correct?' or wants comprehensive validation, and contrasts with 'not just naturalness', providing clear guidance vs. alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

check_naturalA

Check Ukrainian text for calque-prone phrases and naturalness.

Returns spans flagged as: • calque-prone — phrase appears in the antisurzhyk book corpus (Сербенська, Караванський, Антоненко-Давидович) as something to avoid; prefer gives the recommended alternative. • natural — phrase is attested as a high/medium-confidence rendering in the 29k-sense corpus.

Use this AFTER drafting Ukrainian text, BEFORE returning it to the user. Rewrite calque-prone spans before delivering your response.

Args: text: Ukrainian text (2 chars min).

Returns: { "input": str, "spans": [ {"span": str, "start": int, "end": int, "verdict": "calque-prone" | "natural", "prefer": str | None, # for calque-prone "for_en": str | None, # for natural "source": str | None, "source_url": str}, ... ], "summary": {"calque_prone": int, "natural": int, "score": float}, "citation": {...}, }

ParametersJSON Schema
NameRequiredDescriptionDefault
textYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It explains return format with verdicts and their meanings (calque-prone vs natural), sources, and fields. However, it does not explicitly state it is read-only or non-destructive, though implied by analysis nature.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear purpose, usage instruction, and structured return format using bullet points. No superfluous sentences; each sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With output schema described in detail and one input parameter fully explained, the description is complete for the tool's complexity. Sibling tools are not compared, but usage guidance is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has zero description coverage; description adds 'Ukrainian text (2 chars min)' which specifies language constraint and minimum length, adding significant meaning beyond type string.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool checks Ukrainian text for calque-prone phrases and naturalness, with specific verb 'Check' and resource 'Ukrainian text'. Distinct from siblings like 'check' which is more general, and 'render', 'search', 'substantiate' which serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use this AFTER drafting Ukrainian text, BEFORE returning it to the user' and instructs to rewrite calque-prone spans before delivery. This provides clear when-to-use and action guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

renderA

Get authentic Ukrainian renderings for an English word or sense.

Returns multiple natural UA renderings sourced from Балла EN-UA Dictionary (1996), e2u.org.ua, and modern corpora. When the English word is polysemous, each sense is returned with its own renderings.

Use this for translation or vocabulary tasks where you want idiomatic Ukrainian (not a calque or AI-guessed translation).

Args: en: English word (lemma or surface). sense: Optional sense filter (substring match on sense description).

Returns: { "en_key": str, "senses": [ {"sense": str, "explanation": str, "level": str, "renderings": [{"phrase": str, "confidence": str, "n_sources": int, ...}, ...], "permalink": str}, ... ], "citation": {...}, }

ParametersJSON Schema
NameRequiredDescriptionDefault
enYes
senseNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses that renderings come from multiple sources, handles polysemy by returning per-sense results, and includes the full output schema. No behavioral contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear purpose, usage context, source attribution, and output format. Every section adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema (described in detail), the description covers all necessary context: input parameters, output structure, data sources, and when to use. Nothing is missing for effective tool selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% (no parameter descriptions in schema), but the description includes an 'Args' section explaining 'en' (English word) and 'sense' (optional filter). This adds full meaning beyond the schema property titles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get authentic Ukrainian renderings for an English word or sense.' It uses a specific verb ('Get') and resource ('Ukrainian renderings'), and the context of translation/vocabulary tasks distinguishes it from sibling tools like search or substantiate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance: 'Use this for translation or vocabulary tasks where you want idiomatic Ukrainian (not a calque or AI-guessed translation).' It does not explicitly list when not to use or compare to siblings, but the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

substantiateA

Get the citation chain for a Ukrainian phrase.

Returns independent attestations from configured primary sources — Балла 1996 (with page numbers), e2u.org.ua, r2u.org.ua (which hosts Karavansky's RU-UA dictionaries cleanly), Сербенська's Антисуржик, Антоненко-Давидович's Як ми говоримо, uk.wiktionary, slovnyk.ua, and more.

Use this when:

  • You need to back up a claim about Ukrainian usage with cited evidence

  • You're explaining why a particular word/phrase is correct or preferable, and want to point to authoritative sources

  • You want to find historical attestation (pre-Soviet UA, etc.)

Args: phrase: Any Ukrainian phrase (single word or multi-word). sources: Optional comma-separated source IDs to limit the query (e.g., "e2u,r2u" or "balla,wiktionary"). Default: all.

Returns: { "phrase": str, "confidence": "high" | "medium" | "tentative" | "missing" | "rejected", "attestation_count": int, "attestations": [ {"source_id": str, "kind": str, "ref": str, "url": str | None, "verbatim": str | None, "context": str | None, "confidence": float}, ... ], "canonical": str, # the citable API URL for this lookup "citation": {...}, }

ParametersJSON Schema
NameRequiredDescriptionDefault
phraseYes
sourcesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses that the tool returns independent attestations from several primary sources and details the output structure. However, it lacks explicit statements about side effects (e.g., read-only nature), authentication requirements, or rate limits. The behavior is adequately described but could be more transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear purpose statement, a bulleted usage section, and formal Args/Returns sections. It is concise, front-loaded, and every sentence adds value. No extraneous text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema is richly defined in the description, and the tool has only two parameters, the description covers purpose, usage, parameters, and output comprehensively. It does not mention error handling or edge cases like unrecognized phrases, but the confidence field mitigates this. Overall very complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, but the description fully compensates by explaining 'phrase' (any Ukrainian phrase) and 'sources' (optional comma-separated source IDs, default all). This adds meaning beyond the schema, making it clear how to use each parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get the citation chain for a Ukrainian phrase', which is a specific verb+resource. It lists the sources involved, making the purpose immediately understandable. However, it does not explicitly differentiate from sibling tools like check, search, or render, though the uniqueness is implied.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes a bullet list under 'Use this when:' with three explicit use cases (backing up claims, explaining correctness, finding historical attestations). This provides clear guidance on when to invoke the tool, but it does not include when not to use it or mention alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.2.0
    • First observedcheck
    • First observedcheck_natural
    • First observedrender
    • First observedsearch
    • First observedsubstantiate

TDQS

A4.3/5.0

Scored across 5 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: check for grammar/spelling, check_natural for naturalness/calques, render for English-to-Ukrainian translations, search for sense index lookup, and substantiate for citation chains. No overlap or ambiguity.

Naming Consistency3/5

Tool names mix styles: check and check_natural use underscores, while render, search, and substantiate are single verbs without underscores. The pattern is not uniform, but names are still descriptive and readable.

Tool Count5/5

With 5 tools, the server is well-scoped for its purpose of Ukrainian language checking and translation support. Each tool addresses a core need without unnecessary bloat.

Completeness4/5

The tool set covers grammar/spelling checking, naturalness assessment, English-to-Ukrainian rendering, sense search, and citation substantiation. A minor gap is the lack of Ukrainian-to-English rendering, but the server's focus on English-assisted Ukrainian use makes it reasonably complete.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers