Skip to main content
Glama
deenesjakoruzh
dcd887

mc-translator-mcp

by dcd887
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

mc-translator-mcp

MCP-инструмент для перевода модов Minecraft на китайский язык

Автоматически извлекает языковые файлы из jar-файла мода, вызывает 通义千问 для пакетного перевода и создаёт ресурс-пак на китайском языке.

Установка

cd mc-translator-mcp
pip install -e .

Related MCP server: NetEase ModSDK MCP Server

Настройка

Скопируйте .env.example в .env и заполните свой API-ключ 通义千问:

cp .env.example .env
# 编辑 .env，填入 DASHSCOPE_API_KEY

Получить API-ключ: консоль 阿里云百炼

Способы запуска

В качестве MCP-сервера (рекомендуется)

python -m mc_translator_mcp

Настройте MCP-сервер в Trae/Claude Desktop:

{
  "mcpServers": {
    "mc-translator-mcp": {
      "command": "python",
      "args": ["-m", "mc_translator_mcp"]
    }
  }
}

Режим CLI

# 检查 jar 语言文件
python -m mc_translator_mcp check <jar_path>

# 翻译单个 jar
python -m mc_translator_mcp mod <jar_path> [--batch-size 15] [--force-retranslate]

# 批量翻译目录下所有 jar
python -m mc_translator_mcp dir <directory> [--glob "*.jar"] [--batch-size 15]

Примеры использования

Использование MCP-инструментов в диалоге с Trae

Просто скажите Trae:

Помоги перевести этот мод: /path/to/mymod.jar

Trae автоматически вызовет translate_mod или translate_all_mods_in_directory из MCP-инструментов.

Локальный запуск

# 翻译单个模组
python -m mc_translator_mcp mod "C:/Users/kjds/Desktop/mods/myzombie.jar" --batch-size 20

# 批量翻译整个 mods 目录
python -m mc_translator_mcp dir "C:/Users/kjds/Desktop/.minecraft/mods" --glob "*.jar"

Вывод

По умолчанию результат выводится в каталог output/, для каждого мода генерируется отдельный ресурс-пак:

output/
├── mymod-zh-cn/
│   ├── pack.mcmeta
│   └── assets/mymod/lang/zh_cn.json
├── zombie_mod-zh-cn/
│   ├── pack.mcmeta
│   └── assets/zombie_mod/lang/zh_cn.json
└── ...

Для подключения скопируйте папку output/<modid>-zh-cn/ в каталог resourcepacks/ в Minecraft.

Основные модули

Модуль

Назначение

jar_parser.py

Разбирает структуру jar-файла и находит языковые файлы

lang_parser.py

Разбирает языковые файлы форматов .json / .lang

translator.py

Пакетный перевод через 通义千问 + локальный кэш

pack_builder.py

Создаёт ресурс-пак или изменяет jar

mcp_server.py

Точка входа MCP-сервера, предоставляет два инструмента

Тестирование

python -m pytest tests/ -v

Принципы проектирования

  1. Приоритет ресурс-пака: по умолчанию создаётся отдельный ресурс-пак, исходный jar-файл не изменяется.

  2. Интеллектуальный кэш: записи с одинаковым исходным текстом и modid переводятся только один раз, чтобы не тратить токены повторно.

  3. Пропуск существующих переводов: при обнаружении уже существующего zh_cn.json автоматически пропускается, чтобы не перезаписывать перевод сообщества.

  4. Пакетный перевод: не более BATCH_SIZE записей за партию, все результаты возвращаются одним вызовом API.

  5. Совместимость форматов: поддерживаются языковые файлы в форматах .json (современном) и .lang (традиционном).

Available Tools

4 tools
dry_run_modA

预览翻译效果：解析单个模组并抽样翻译一小部分，不写入任何文件。

注意：本工具会调用 AI 翻译 API 并消耗少量 token（最多 limit 条样例）， 只用来快速感受翻译质量，不会生成资源包、不改动原 jar。

Args: jar_path: 模组 jar 文件的绝对路径 limit: 最多预览（抽样翻译）的条目总数（默认 20） batch_size: 每批翻译的词条数（默认 15） Returns: 预览 JSON，含原文-译文对照样例

NameRequiredDescriptionDefault
limitNo
jar_pathYes
batch_sizeNo

Output Schema

NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior4/5

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

With no annotations, the description must carry the behavioral burden and largely does: it discloses that no files are written, that the AI translation API is called and tokens are consumed (bounded by limit), that no resource pack is generated, and that the source jar is untouched. It omits auth requirements, rate limits, and failure behavior, but the mutation-and-cost profile is unusually well covered.

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?

Front-loaded with the no-write guarantee in bold, followed by cost warning and args/returns blocks. The structure is easy to scan; the cost warning is slightly verbose and the 'Returns' note partly duplicates the output schema.

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?

For a 3-parameter tool with an output schema, the description covers the essential unknowns: side effects (none on disk), cost (token spend), and parameter meaning. Return-value detail is minimal, which is acceptable given the output schema exists.

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

Parameters4/5

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

Schema description coverage is 0%, so the description is the only source of parameter meaning, and it documents all three: jar_path as an absolute path, limit as the max sampled entries (default 20), and batch_size as entries per batch (default 15). This compensates well for the empty schema descriptions, though the relationship between limit and batch_size could be spelled out.

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?

States a specific verb and resource ('解析单个模组并抽样翻译') plus the scope constraint of not writing files, which lets an agent distinguish it from translate_mod. However it never explicitly contrasts itself with the closest sibling, preview_mod, whose name suggests overlapping purpose.

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?

Gives clear usage context: '只用来快速感受翻译质量' (only for quickly sensing translation quality) and warns about token consumption. It does not, however, name the alternative tool to use when the agent actually wants a full translation or a written output.

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

preview_modA

（零成本）预览单个模组的汉化范围：列出每个语言文件、条目数与预估 token。

只做 jar 扫描与文本解析，不调用任何 AI 翻译 API、不消耗 token、不写任何文件， 用于在真正翻译前评估工作量与费用。

Args: jar_path: 模组 jar 文件的绝对路径 Returns: 预览摘要 JSON（含每个 modid 的格式、条目数、是否已有 zh_cn、社区估算 token）

NameRequiredDescriptionDefault
jar_pathYes

Output Schema

NameRequiredDescription
resultYes

TDQS

A4.3/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 the full burden; it declares read-only scanning, no AI API calls, no token consumption, and no file writes. It also states the return content is a preview summary JSON, giving a strong safety and behavior profile.

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?

Front-loaded with the key purpose and scope, then supporting details and Args/Returns. Slight redundancy between '零成本' and '不消耗 token' keeps it from being maximally tight.

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 an output schema exists, the description need not detail return values, and it still summarizes them. It covers the single input, safety behavior, and usage context, leaving no major gaps for an agent to call it correctly.

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

Parameters4/5

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

The schema has one parameter with 0% description coverage, but the description defines jar_path as the absolute path to a mod jar file. This compensates adequately, though no further path constraints are given.

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?

States a specific verb and resource: preview a single mod's localization scope, listing language files, entry counts, and estimated tokens. It is clear but does not explicitly name or differentiate itself from siblings such as dry_run_mod, so sibling differentiation remains implicit.

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?

Provides a clear context: use before actual translation to assess workload and cost. It also states what it does not do (no AI API, no token use, no file writes), but it does not explicitly say when to choose it over dry_run_mod or translate_mod.

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

translate_all_mods_in_directoryB

批量翻译目录下所有模组 jar 包。

Args: directory: 包含模组 jar 的目录路径 glob_pattern: jar 文件匹配模式（默认 *.jar） batch_size: 每批翻译的词条数 force_retranslate: 强制重新翻译 Returns: 批量翻译汇总

NameRequiredDescriptionDefault
directoryYes
batch_sizeNo
glob_patternNo*.jar
force_retranslateNo

Output Schema

NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full disclosure burden, yet it says nothing about side effects: whether jars are modified in place, whether existing translations are backed up, whether the translation backend imposes rate limits, or whether the operation is reversible. Only the force_retranslate flag hints at overwrite behavior.

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 purpose sentence is front-loaded and the Args list is terse with no filler. The trailing Returns line is minimal, which is acceptable since an output schema exists, though it adds little.

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

Completeness3/5

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

With an output schema present, return values need no explanation, and all four parameters are covered. What is missing is the mutation profile of a batch file-processing tool with no annotations: overwrite/backup behavior and any safety or ordering caveats an agent should know before running it.

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

Parameters4/5

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

Schema description coverage is 0% (titles only), so the description must compensate, and it does define all four parameters meaningfully: directory path, glob matching pattern, entries per batch, and force-retranslate. It does not explain the acceptable values or performance implications of batch_size, but coverage of the semantics is solid.

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 states a specific verb+resource: batch-translating all mod jars under a directory. The scope word ('all mods in a directory' / 目录下所有) implicitly distinguishes it from the singular translate_mod sibling. It stops short of naming the siblings, so it is clear but not fully differentiated.

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

Usage Guidelines2/5

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

No guidance on when to use this versus preview_mod, dry_run_mod, or translate_mod. The batch scope is implied by the name and purpose line, but there is no explicit condition, prerequisite, or exclusion telling an agent which tool to pick.

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

translate_modA

翻译单个 Minecraft 模组 jar 包，生成中文资源包。

Args: jar_path: 模组 jar 文件的绝对路径（如 C:...\mymod-1.2.0.jar） batch_size: 每批翻译的词条数（默认 15，越大越快但单次请求更长） force_retranslate: 强制重新翻译（忽略缓存，慎用） Returns: 翻译结果摘要（包含每个模组的输出路径）

NameRequiredDescriptionDefault
jar_pathYes
batch_sizeNo
force_retranslateNo

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

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

With no annotations present, the description carries the full burden. It does disclose useful behavior: force_retranslate ignores the cache ('慎用' = use with caution) and batch_size trades speed against request length. It omits permissions, network/API dependency, and whether the original jar is modified.

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?

Purpose is front-loaded in the first sentence, followed by a compact Args/Returns block. Every line carries information; no padding.

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

Completeness3/5

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

An output schema exists, so the Returns note is redundant but harmless. However, for a tool with no annotations that presumably performs network translation and file output, the description never states prerequisites, failure modes, or side effects on disk, leaving notable behavioral gaps.

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 description coverage is 0%, so the description is the only source of parameter meaning, and it delivers for all three: jar_path is an absolute path with an example format, batch_size gives the default and its speed/latency tradeoff, and force_retranslate explains the cache-bypass consequence and cautions against it.

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?

Names a specific verb and resource ('translate a single Minecraft mod jar, generate a Chinese resource pack'), so the agent knows exactly what the tool produces. It does not, however, distinguish itself from its siblings (preview_mod, dry_run_mod) which likely operate on the same kind of input.

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

Usage Guidelines2/5

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

No statement of when to use this tool versus preview_mod, dry_run_mod, or translate_all_mods_in_directory. An agent must infer that a single-jar translate is distinct from a dry-run or batch translate without any explicit routing guidance.

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. 4 tool updatesv0.1.0
    • First observeddry_run_mod
    • First observedpreview_mod
    • First observedtranslate_all_mods_in_directory
    • First observedtranslate_mod
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 4 tools

Disambiguation4/5

preview_mod and dry_run_mod both preview a single mod, but one is a zero-cost scope review and the other samples actual AI translations, so the cost/AI distinction prevents most confusion. translate_mod and translate_all_mods_in_directory are clearly distinguished by single vs batch scope.

Naming Consistency4/5

All tool names use snake_case and follow an action_mod pattern, which is mostly consistent. The only minor deviation is dry_run_mod, which uses a compound action phrase rather than a simple verb_noun, and translate_all_mods_in_directory is noticeably longer than the others.

Tool Count5/5

Four tools are well-scoped for a Minecraft mod translation workflow: preview scope, preview quality, translate one, and translate many. No tool feels redundant, and the count matches the domain without being thin or bloated.

Completeness4/5

The surface covers the core translation lifecycle from cost estimation and sampled preview through single-mod and batch translation. Minor gaps remain around explicit output/language configuration or result validation, but agents can work around these.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers