MCP Translation Text

Instructions

Implementation Reference

• src/translation_server.py:562-611 (handler)

  The main tool handler function for 'translate_text', decorated with @mcp.tool(). Handles input validation via Annotated types (schema), normalizes language codes, calls Niutrans API via helper, and formats the response.
  @mcp.tool() def translate_text( text: Annotated[str, Field(description="待翻译的原文文本，可以是任意长度的字符串。")], source: Annotated[str, Field(description='源语言代码或常见别名（例如 "zh"、"中文"、"chinese"）。')], target: Annotated[str, Field(description='目标语言代码或常见别名（例如 "en"、"英文"、"english"）。')], ) -> Dict[str, Any]: """使用小牛翻译 API 将文本从 source 语种翻译到 target 语种。 支持 450+ 种语言代码，并可自动处理常见别名。返回结构包含译文和 API 原始响应。 Args: text (str): 待翻译的原文文本，可以是任意长度的字符串。 source (str): 源语言代码或常见别名（例如 "zh"、"中文"、"chinese"）。 target (str): 目标语言代码或常见别名（例如 "en"、"英文"、"english"）。 Returns: Dict[str, Any]: 包含以下字段的字典： - source: 标准化后的源语言代码 - target: 标准化后的目标语言代码 - original_text: 原文 - translated_text: 译文 - raw: 小牛翻译 API 的原始响应数据 """ api_key = os.getenv("NIUTRANS_API_KEY") if not api_key: raise RuntimeError("缺少环境变量 NIUTRANS_API_KEY") source_code = _ensure_language_code("source", source) target_code = _ensure_language_code("target", target) payload: Dict[str, Any] = { "apikey": api_key, "from": source_code, "to": target_code, "src_text": text, } data = _call_niutrans(payload) translated = data.get("tgt_text") or data.get("target_text") if translated is None: raise RuntimeError(f"小牛翻译接口未返回译文: {data}") return { "source": source_code, "target": target_code, "original_text": text, "translated_text": translated, "raw": data, }
• src/translation_server.py:508-530 (helper)

  Helper function that makes the HTTP POST request to the Niutrans API, handles errors, and returns the parsed JSON response.
  def _call_niutrans(payload: Dict[str, Any]) -> Dict[str, Any]: api_url = os.getenv("NIUTRANS_API_URL", DEFAULT_NIUTRANS_API_URL) try: response = requests.post(api_url, data=payload, timeout=10) except requests.RequestException as exc: raise RuntimeError(f"调用小牛翻译接口失败: {exc}") from exc if response.status_code != 200: raise RuntimeError( f"小牛翻译接口返回非 200 状态码 {response.status_code}: {response.text}" ) try: data: Dict[str, Any] = response.json() except ValueError as exc: raise RuntimeError("小牛翻译接口返回非 JSON 内容") from exc error_code = data.get("error_code") or data.get("errorCode") if error_code not in (None, "0", 0): message = data.get("error_msg") or data.get("errorMessage") or "Unknown error" raise RuntimeError(f"小牛翻译接口报错 {error_code}: {message}") return data
• src/translation_server.py:533-559 (helper)

  Helper function to normalize and validate language codes for source and target, using aliases, synonyms, and fuzzy matching.
  def _ensure_language_code(label: str, value: str) -> str: if not value: raise RuntimeError(f"缺少 {label} 语言代码") raw = value.strip() if raw in LANGUAGE_CODES: return raw normalized = _normalize_alias(raw) if normalized in LANGUAGE_CODES: return normalized alias_code = LANGUAGE_SYNONYMS.get(normalized) or LANGUAGE_SYNONYMS.get( normalized.replace(" ", "") ) if alias_code: return alias_code normalized_lower = raw.lower() for code in LANGUAGE_CODES: if code.lower() == normalized_lower: return code raise RuntimeError( f"不支持的 {label} 语言代码: {value}。请参考 language-catalog 资源提供的列表后重新选择。" )