内容
# voikko-mcp
[](LICENSE)
芬兰语语言验证MCP服务器，由 [libvoikko](https://voikko.puimula.org/) 提供支持。为任何兼容MCP的客户端（OpenWebUI、OpenCode、Claude Desktop、Cursor等）提供拼写检查、语法检查、形态分析、换行和分词等工具。
## 功能特点
- **拼写检查** — 验证单个单词是否符合libvoikko的芬兰语词典
- **语法检查** — 检测大写、词序和协议错误
- **形态分析** — 检查词根、格、数、所有格后缀
- **换行** — 基于音节的单词拆分，用于换行和发音
- **分词** — 将芬兰语文本拆分为单词、空格和标点符号
- **可流式HTTP传输** — 作为Web服务器运行，无需本地进程管理
## 先决条件
- [Docker](https://docs.docker.com/get-docker/) 和 Docker Compose
## 快速开始
```bash
docker compose up --build
```
服务器在 `http://localhost:8000` 启动，提供可流式HTTP传输（端点为 `/mcp`）。
## 工具列表
| 工具 | 参数 | 返回值 |
|------|------------|---------|
| `check_spelling` | `word: str` | `{word, correct, suggestions}` |
| `suggest_spelling` | `word: str` | `list[str]` — 建议的纠正 |
| `check_grammar` | `text: str` | `list[{start, length, snippet, description, suggestions}]` |
| `verify_text` | `text: str` | `{text, is_correct, spelling_errors, grammar_errors}` |
| `analyze_word` | `word: str` | `list[{BASEFORM, CLASS, SIJAMUOTO, ...}]` |
| `hyphenate_word` | `word: str` | `{word, hyphenated}` |
| `tokenize_text` | `text: str` | `list[{token_type, token_text, position}]` |
所有工具都包含错误处理，并在失败时返回空值或默认值。
## 客户端配置
### OpenWebUI
**设置 > MCP服务器 > 添加**:
- **名称**: `voikko-mcp`
- **传输**: 可流式HTTP
- **URL**: `http://localhost:8000/mcp`
### OpenCode
添加到 `opencode.json`:
```json
{
"mcp": {
"voikko-mcp": {
"type": "remote",
"url": "http://localhost:8000/mcp"
}
}
}
```
### Claude Desktop
添加到 `claude_desktop_config.json`:
```json
{
"mcpServers": {
"voikko-mcp": {
"type": "streamableHttp",
"url": "http://localhost:8000/mcp"
}
}
}
```
### Cursor
添加一个MCP服务器条目，使用可流式HTTP传输指向 `http://localhost:8000/mcp`。
## 架构
```
客户端（OpenWebUI / OpenCode / Claude） ──POST /mcp──▶ uvicorn ──▶ FastMCP ──▶ libvoikko
◀──可流式HTTP（JSON-RPC）──
```
- **Python 3.11**，使用官方MCP Python SDK中的 **FastMCP**
- **libvoikko** C++ 库，通过其Python绑定用于所有语言操作
- **可流式HTTP传输**，通过uvicorn绑定 `0.0.0.0:8000`
- 基于 `python:3.11-slim` 的Docker镜像，包含 `libvoikko-dev` 和 `voikko-fi`
## 致谢
- [libvoikko](https://voikko.puimula.org/) — 由Voikko项目提供的芬兰语处理库
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) — 由Anthropic提供的模型上下文协议实现
- [FastMCP](https://github.com/jlowin/fastmcp) — 高级MCP服务器框架
- 芬兰语形态词典 ([voikko-fi](https://github.com/voikko/corevoikko)) 由Voikko社区维护
## 许可证
GNU通用公共许可证第3版或更高版本 — 参见 [LICENSE](LICENSE) 了解详情。
