Naver Dictionary MCP Server

一个基于 FastMCP 2.0 的 Streamable HTTP MCP 服务器,用于查询 Naver 辞典(韩中、韩英)。

✨ 功能特性

• 🔍 多语言辞典: 韩中/韩英辞典查询，返回释义、发音、例句
• ⚡ 高性能: 异步架构 + 连接池 + 智能缓存（TTL + LRU）
• 📦 统一查询: 仅暴露 search_words 工具，单查/批查共用（最多 30 词）
• 🚦 限流保护: 令牌桶算法，全局共享上游限流（默认 60 请求/分钟）
• 🛡️ 健壮性: 输入验证 + 分类错误处理 + 自动重试
• 🐳 Docker 就绪: 多架构镜像（amd64/arm64），~110MB
• ✅ 高质量: 90% 测试覆盖率 + MyPy 严格类型检查 + Ruff 代码规范

🚀 快速开始

Docker 部署（推荐）

# 拉取并运行最新镜像
docker pull chouann/naverdictmcp:latest
docker run -d -p 8000:8000 --name naverdictmcp chouann/naverdictmcp:latest

# 或使用 Docker Compose
docker-compose up -d

本地开发

# 克隆并安装
git clone <repository-url>
cd naverdictMCP
uv sync

# 启动服务器
python src/server.py

服务器将在 http://localhost:8000 启动。

📖 使用示例

统一查询（单词）

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_words",
      "arguments": {
        "words": ["안녕하세요"],
        "dict_type": "ko-zh"
      }
    }
  }'

统一查询（批量）

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search_words",
      "arguments": {
        "words": ["안녕하세요", "감사합니다", "학교"],
        "dict_type": "ko-zh"
      }
    }
  }'

⚙️ 配置

环境变量

创建 .env 文件自定义配置（开发模式自动加载，生产环境建议通过容器环境变量注入）：

# 服务器配置
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
LOG_LEVEL=INFO

# 性能配置
HTTP_TIMEOUT=30.0
REQUESTS_PER_MINUTE=60
CACHE_TTL=3600
CACHE_MAX_SIZE=1000

🐳 Docker 部署

本项目 Docker 镜像采用多阶段构建，并包含运行时最小化与安全配置（Docker 优化）。

方式一：Docker Hub 镜像（推荐）

# 拉取最新版本
docker pull chouann/naverdictmcp:latest
docker run -d -p 8000:8000 --name naverdictmcp chouann/naverdictmcp:latest

# 或使用指定版本（生产环境推荐）
docker pull chouann/naverdictmcp:v1.0.0
docker run -d -p 8000:8000 --name naverdictmcp chouann/naverdictmcp:v1.0.0

镜像仓库： Docker Hub - chouann/naverdictmcp

方式二：Docker Compose

# 启动服务
docker-compose up -d

# 更新镜像并重启
docker-compose pull && docker-compose up -d

# 停止服务
docker-compose down

创建 .env 文件自定义配置：

SERVER_PORT=8000
LOG_LEVEL=INFO
HTTP_TIMEOUT=30.0
REQUESTS_PER_MINUTE=60

方式三：本地构建

# 构建并运行
docker build -t naver-dict-mcp .
docker run -d -p 8000:8000 --name naver-dict-mcp naver-dict-mcp:latest

# 或使用 Makefile
make docker-build
make docker-run

🔧 API 参考

search_words

统一查询单词（单查和批查共用）。

参数:

• words (array[string], 必需): 要查询的单词列表（1..30，每项最长 100 字符）
• dict_type (string, 可选): 辞典类型 "ko-zh"（默认）或 "ko-en"

返回: JSON 字符串，包含释义、发音、例句等

示例:

{
  "name": "search_words",
  "arguments": {
    "words": ["안녕하세요"],
    "dict_type": "ko-zh"
  }
}

🛠️ 开发

安装开发依赖

uv sync
pre-commit install

运行测试

# 运行所有测试
pytest

# 测试覆盖率
pytest --cov=src --cov-report=html

# 性能测试
pytest tests/test_performance.py -m performance

代码质量检查

# 格式化
ruff format src/ tests/

# Lint
ruff check src/ tests/

# 类型检查
mypy src/

# 或使用 Makefile
make format
make lint
make type-check

🔧 故障排除

错误类型

常见问题

SERVER_PORT=9000 python src/server.py

REQUESTS_PER_MINUTE=100

LOG_LEVEL=DEBUG

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

开发者: 基于 FastMCP 2.0 构建

相关链接:

• FastMCP 文档
• Naver 辞典
• Docker Hub 镜像