voro-mcp

1 align="center">沃罗 MCP 服务器</h1> <p align="center"> 为 Claude、Codex、ChatGPT 等 MCP 客户端提供沃罗语言相关工具。 </p> <p align="center"> <img src="https://img.shields.io/badge/MCP-server-blue" <img src="https://img.shields.io/badge/Python-3+-blue" /> <img src="https://icense-MIT-green" /> <img src="https://img.shields.io/badge/Data-CC--BY--SA--4.0-orange" /> <img src="https://img.shields.io/badge/GiellaLT-GPL--3.0-orange" /> </p> <p align="center"> <img src="gpt-using-mcp-example.gif" alt="ChatGPT 使用沃罗 MCP 服务器" width="100%" /> </p> 一个用于处理沃罗语言的 MCP 服务器：本地词典和语查找、GiellaLT 支持的分析/拼写检查/语法工具，以及 Neurotõlge 翻译。 ## 用该 MCP 服务器为语言模型提供了实用的工具，以便处理沃罗语言。沃罗语是一种资源较少的语言，因此通用语言比广泛支持的语言（如英语或爱沙尼亚语）更容易出错。 通过将模型连接到词典、语料库搜索、形态分析、拼写检查、语法检查、翻译和，该服务器有助于提高模型理解、生成、纠正和翻译沃罗文本的能力。 它可以用于沃罗翻译、检查和改进生成的文本、探索实际用法示例、生成词形、检测未知单词以及支持学习或使用沃罗语言的人员。 ## 安装 ### 快速设置 在 Debian/Ubuntu 上，一条完成整个设置。 ```sh make setup # scripts/run_local_ubuntu.sh; see `make help` for every task ``` 您需要先安装 `make`、Python 和常见的 shell 工具。设置目标安装 HFST/Divvun 系统二进制文件（如果您的系统无法找到 `divvun-gramcheck`，则添加 Apertium 包存储库），下载 SQLite 数据库和预建的 Giella 模型，创建 `.venv` 并安装软件包。使用 `make test` 进行烟雾测试。 `make test` 直接从检出目录运行（无需安装）。需要 SQLite 数据库或 Giella 工具的测试会在这些工具不存在时**跳过并提示**，因此一个空的克隆仍然会报告绿色 - 运行 `make data` 和 `make giella`（或完整的 `make setup`）以实际测试它们。 <details> <summary><strong>手动设置</strong其他平台，或查看各个部分）</summary> <br /> 1. **系统二进制文件** Giella 工具 shell 调用：`hfst-optimized-lookup`st-ospell`、`cg3`、`divvun-checker`。在 Debian/Ubuntu 上，它们来自 Apertium nightly apt 存储库： ```sh curl -fsSL https://apertium.projectjj.com/apt/install-nightly.sh | sudo bash sudo apt-get install -y hfst hfst-ospell cg3 divvun-gramcheck perl gawk bash ``` 2. **软件包**，到虚拟环境（`make install`）： ```sh python3 -m venv .venv . .venv/bin/activate pip install -e . ``` 3. **数据和模型**，从 GitHub 发布版本中获取： ```sh scripts/fetch_data.sh scripts/fetch_giella.sh 4. **验证** 外部工具已解析（打印 JSON 并退出）： ```sh vro-mcp-check ``` </details> <detailssummary><strong>删除本地设置</strong>（撤销 <code>make setup</code>）</summary> <br /> 从最不系统化到最系统化。根据适用情况，从存储库根目录执行相关步骤。 1. **客户端注册** — 从您添加的 MCP 客户端注销服务器： ```sh claude mcp remove vro # Claude Code codex m vro # Codex CLI ``` 2.安装** — 删除虚拟环境： ```sh rm -rf .venv ``` 3. **下载内容** — SQLite 数据库和 Giella 模型（大型；可 data` / `make giella` 重新获取）： ```sh rm -rf data # SQLite 数据库 + data/giella-share 模型 rm -rf .cache/giella-build # 仅当您从源 Giella 时 rm -f .env # 仅当您为部署创建了一个 ``` 要删除代码，请删除您克隆的目录。 4. **A/Divvun apt 存储库** — 仅当 `make setup` 添加了它（当 `divvun-gramcheck` 已经可安装时，它会跳过此操作）。找到它放置的源并删除它： ```sh ls /etc/apt/sources.list.d/ | grep -i apertium sudo rm -f /etc/apt/sources.list.d/apertium*. sudo apt-get update ``` 5. **系统软件包** — 仅删除沃罗特有的二进制文件。保留共享工具（`python3`、`git`、`make`、`perl`、`gawk` 等），因为其他软件可能依赖它们： ```sh sudo apt-get remove hfst-ospell cg3un-gramcheck sudo apt-get autoremove # 可选：删除当前依赖项 ``` </details> ## 工具 | 工具 | 功能 | | --- | --- | | `lookup_word` | 紧凑的词典概念查找en`/`et`/`vro` 语言列表），在术语子字符串回退之前进行精确查找。 | | `find_usage_examples` | 全文语料库搜索，返回片段；`max_snippet_chars` 允许客户端选择片段长度。 | | `word_exists_in_bag` | 快速的单词袋计数检查；`0` 表示不存在。 | | `count_text` | 精简的计数器，返回 `characters`、`words` 和 `estimated_sentences` 以进行草稿约束。 | | `find_unknown_words` | 列表文本中单词形式在中不存在。 | | `find_unrecognized_words`ellaLT 分析器返回为 `+?` 的列表文本单词形式，可选的单词袋预过滤。 | analyze_word` | GiellaLT 形态分析。 | | `generate_forms` | GiellaLT 为一个确切的词干 + 标签分析生成。 | | `spellcheck_vro` | 标记级别的拼写检查，返回 `{ "unknown": [...] }`，并对每个单词进行重复数据删除和最多三个排名建议。默认检查 10 个未知单词；`limit` 可将此数字提高到 50。 | | `grammar_check_vro` | 句子级别的语法检查，返回 `{ "errors": [...] }`，并带有跨度、紧凑代码和每个问题最多三个建议。默认检查 10 个错误；`limit` 可将此数字提高到 50。 | find_estonian_leakage` | 扫描并返回一个精简的、重复数据删除的具有爱沙尼亚语后缀的单词形式列表。 | | `lint_estonian_leakage` | 对特定单词/短语进行深入检查：严重性、消息和提示。 | | `suggest_correction` | 分析器验证的替代更正，对于错误的/未知的形式，限制为三个排名形式；接受 `form` 或 `word`；如果有的话，包括 `seen_in_word_bag`| `translate_vro` | Neurotõlge/TartuNLP 翻译。规范语言代码为 `eng`、`est`、`fin`、`rus`、`hunlav`、`nor`，并接受常见的 2 个字母别名。 | | `check_setup` | 紧凑的设置健康检查：健康的组件为 `true`；故障包括诊断。 | 大多数查找工具接受单个单词或列表进行批处理查询。成功的工具输出故意紧凑，以便 MCP 客户端在内部 ID、调试元数据和出处字段上花费较少的时间。 ## 资源 Markdown 参考文献通过 MCP 公开： - `vro://grammar/noun-cases`：名词/形容词/数词/代词变格。 - `vro://grammar/verb-conjugation`：动词变位、语气、时态、语态。 - `vro://grammar/orthography`：书写系统（字母表、喉塞音 `q`、腭化、高 õ、长度和否定拼写）和沃罗研究所标准语言方向。 - `vro://guide/translator-prompt`：翻译者/后期编辑提示和工作流，用于使用这些工具生成沃罗文本。 ## 配置 数据位于 `data/` 下，并为您获取。`make setup`（或 `make data` + `make giella`）下载所有内容，因此您通常无需配置任何内容。获取脚本尊重 `VRO_DATA_REPO`、`VRO_DATA_TAG` 和 `VRO_GIELLA_TAG`，以指向不同的发布版本。 所有路径默认值均为存储库本地；根据需要使用环境变量覆盖它们。对于 Modal 部署默认值，请复制 `.env.example` 到 `.env`。 <details> <summary><strong>高级配置</strong></summary> <br /> | 变量 | 默认值 | 描述 | | --- | --- | --- | | `VRO_DICTIONARY_DB` | `./data/vro_dictionary.sqlite` | `lookup_word` 和更正建议使用的词典 SQLite 路径。 | | `VRO_CORPUS_DB` | `./data/vro_corpus.sqlite` | `find_usage_examples` 使用的语料库 SQLite 路径。 | | `VRO_WORD_BAG_DB` | `./data/vro_word_bag.sqlite` | `seen/unknown` 单词检查使用的单词袋 SQLite 路径。 | |_NEUROT_BASE_URL` | `https://api.tartun/translation/v2` | Neurotõlge/TartuNLP 翻译 API 基本 URL。指向本地或自行托管的兼容端点，以避免依赖公共服务。 | | `VRO` | `Leo-Martin-Pala/voro-mcp 用于数据集和 Giella 发布版本下载的 Git库。 | | `VRO_DATA_TAG` |-v1` | `scripts/fetch_data.sh` 发布版本补水 `vro-data.tar.xz` 的 GitHub 发布版本 | | `_GIELLA_TAG `giella-v1 `scripts/fetch_giella.sh` 和 Modal 发布水获取的 `giella-share.tar.xz` 的 GitHub 发布版本标签。 | | `MCP_PATH` | `/mcp`； 在 `.env` 中为 Modal 部署生成 | Modal 的秘密托管 HTTP 路径段；本地_stdio 客户端不需要它。DATA_SOURCE` | `release` | Modal数据源：`release`、`local` 或 `none | | `FORCE_DATA` | `0`为 `1` 以覆盖现有的 Modal Volume | | `DATA_DIR` | `./data` |DATA_SOURCE=local` 时使用的本地数据目录。 | | `NEW_SECRET` | `0` | 设置为 `1` 以在部署期间轮换 `M` 并将其保存到 `.env`。 | _SECRET` | `0` | 设置为 `1` 以将 `.env`/environment 中的 `MCP_PATH` 原样推送，并在使用 `make deploy-local-secret` 时失败（如果为空）。 | | `MODAL` | `vro-mcp` | 部署部署脚本使用的 Modal 应用 | | `MODAL_VOLUME_NAME` | `vro-data` | SQLite 数据和 Giella 工件的 Modal Volume 名称。 | | `MODAL_SECRET_NAME` | `vro-mcp-secret` | 存储 `MCP_PATH` 的 Modal 秘密名称。 | </details> ### 翻译后端弹性 `translate_vro` 有意作为 HTTP 客户端，而不是捆绑的翻译默认情况下，它指向公共的 NeurotõlgeuNLP 端点，但您可以将 `VRO_NEUROTOLGE_BASE_URL` 指向兼容的本地或自行托管的后端。请参阅 TartuNLP 的 [`translation-api`](https://github.com/TartuNLP/translation-api) 和 [`translation-worker`](https://github.com/TartuNLP/translation-worker) 存储库以获取其设置说明。 ## 连接客户端 客户端所需要做的就是获取二进制文件的绝对路径。运行 `make local-url` 打印该路径，并为 Claude Code 和 Codex 准备好粘贴配置。 Claude Code： ```sh claude mcp add vro -- /absolute/path/to/vro-mcp-server/.venv/bin/vro-mcp-server ``` Codex： ```sh codex mcp add vro -- /absolute/path/to/vro-mcp-server/.venv/bin/vro-mcp-server ``` 通用 JSON MCP 客户端配置： ```json { "mcpServers": { "vro": { "command":/path/to/vro-mcp-server/.venv/bin/vro-mcp-server", "cwd": "/absolute/path/to/vro-mcp-server" } } } ``` ## 部署 上述本地设置在您的机器上运行服务器。要从任何地方使用它 - 包括 Claude 和 ChatGPT 网页应用 - 而不是部署到 [Modal](https://modal.com)。 ```sh make deploy ``` 这在 Modal 的云中构建服务器，并打印一个类似的托管 HTTPS 端点： ```text https://<workspace>--vro-mcp-serve.modal.run/<secret>/mcp ``` <p align="center <img src="assets/modal-setup-claude-code-example.gif" alt="Modal 设置和 Claude Code" width="100%" /> </p> 将该 URL 粘贴到任何 MCP 客户端（Claude Code、Codex、Claude 网页版、ChatGPT）中，您就可以从任何地方访问这些工具，无需本地安装。服务器按需唤醒，在请求之间空闲时免费。URL 嵌入了一个随机密钥路径作为其密码，因此请将其保密。 有关先决条件、连接每个客户端和完整的部署命令，请参见 [DEPLOY.md](DEPLOY## 许可证 代码为 MIT（`LICENSE`）。SQLite 数据库为 CC-BY-SA-4.0，预建的 GiellaLT 模型为 GPL-3.0。两者都作为单独的发布发，每个资产都自己的许可证和归。请参阅 [.md](NOTICE.md) 以获取范围和源摘要。