Skip to main content
Glama
deenesjakoruzh
dcd887

mc-translator-mcp

by dcd887
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

mc-translator-mcp

Minecraft mod Chinese-translation MCP tool

Automatically extracts language files from mod jars, calls 通义千问 for batch translation, and generates Chinese resource packs.

Installation

cd mc-translator-mcp
pip install -e .

Related MCP server: NetEase ModSDK MCP Server

Configuration

Copy .env.example to .env and fill in your 通义千问 API Key:

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

API Key application: 阿里云百炼控制台

How to start

As an MCP server (recommended)

python -m mc_translator_mcp

Configure the MCP server in Trae/Claude Desktop:

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

CLI mode

# 检查 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]

Usage examples

Using the MCP tools in Trae conversations

Tell Trae directly:

"Help me translate this mod: /path/to/mymod.jar"

Trae will automatically call translate_mod or translate_all_mods_in_directory from the MCP tools.

Running locally

# 翻译单个模组
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

Outputs to the output/ directory by default, and generates an independent resource pack for each mod:

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
└── ...

To load it: copy the output/<modid>-zh-cn/ folder into Minecraft's resourcepacks/ directory.

Core modules

Module

Function

jar_parser.py

Parses the jar structure and discovers language files

lang_parser.py

Parses language files in .json / .lang format

translator.py

Batch translation with 通义千问 + local cache

pack_builder.py

Generates a resource pack or rewrites the jar

mcp_server.py

MCP server entry point, exposes two tools

Testing

python -m pytest tests/ -v

Design highlights

  1. Resource pack first: Generates an independent resource pack by default without modifying the original jar file.

  2. Smart caching: Entries with the same source text + modid are only translated once, avoiding duplicate token usage.

  3. Skip existing Chinese translations: Automatically skips when an existing zh_cn.json is detected, avoiding overwriting community translations.

  4. Batch translation: Translates up to BATCH_SIZE entries per batch, with a single API call returning all results.

  5. Format compatibility: Supports both .json (modern) and .lang (legacy) language file formats.

Available Tools

4 tools
dry_run_modA

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

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

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

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
jar_pathYes
batch_sizeNo

Output Schema

ParametersJSON 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）

ParametersJSON Schema
NameRequiredDescriptionDefault
jar_pathYes

Output Schema

ParametersJSON 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: 批量翻译汇总

ParametersJSON Schema
NameRequiredDescriptionDefault
directoryYes
batch_sizeNo
glob_patternNo*.jar
force_retranslateNo

Output Schema

ParametersJSON 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: 翻译结果摘要（包含每个模组的输出路径）

ParametersJSON Schema
NameRequiredDescriptionDefault
jar_pathYes
batch_sizeNo
force_retranslateNo

Output Schema

ParametersJSON 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

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers