japan-utils-mcp

MCP-сервер, предоставляющий специфичные для Японии утилиты для ИИ-агентов (Claude, Cursor, Cline, Continue и др.). Предоставьте своему агенту набор инструментов для работы с японскими данными, которые необходимы для любых задач, связанных с Японией, но с которыми обычные LLM не всегда справляются надежно:

• 🗓️ Эра ↔ Западный год — 令和8年 ↔ 2026

• 🔤 Кандзи → Ромадзи Хепберна — 山田太郎 → yamada tarou

• 📮 Поиск почтового индекса — 150-0001 → 東京都 渋谷区 神宮前

• 🎌 Календарь государственных праздников — является ли 2026-05-03 праздником? А как насчет всего 2026 года?

• 🅰️ Преобразование каны — хирагана ↔ катакана ↔ полуширинная катакана

• 📏 Нормализация ширины — полноширинные (全角) ↔ полуширинные (半角) символы для ASCII, цифр, каны

• 👤 Разделение имен — 山田太郎 → фамилия 山田 + имя 太郎 (статистическая модель)

Построено на базе надежных японских библиотек (jpholiday, posuto, pykakasi, jaconv, namedivider-python) и упаковано в инструменты MCP, чтобы любой ИИ-агент мог использовать их без необходимости повторной реализации правил чтения, арифметики эр, данных о почтовых индексах или эвристик разделения имен.

Зачем это нужно

Обычные LLM часто галлюцинируют при работе с японскими данными:

• «Какой год 令和8年?» — часто ошибаются

• «Преобразуй 山田太郎 в ромадзи» — в половине случаев неправильно определяют фамилию

• «Какой адрес у почтового индекса 150-0001?» — выдумывают правдоподобную чепуху

• «Является ли 3 мая японским праздником?» — угадывают

Этот MCP дает им детерминированный ответ.

Инструменты

Все инструменты возвращают структурированный JSON. См. docstrings инструментов в src/japan_utils_mcp/server.py для получения полных схем и примеров.

Установка

Запуск с помощью uvx (без установки — рекомендуется)

uvx japan-utils-mcp

Это всё. uvx (из uv) выполняет установку и запуск за один раз, изолированно от вашего глобального Python.

Из исходного кода

git clone https://github.com/vivek081166/japan-utils-mcp.git
cd japan-utils-mcp
uv sync
uv run japan-utils-mcp

Конфигурация

Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "japan-utils": {
      "command": "uvx",
      "args": ["japan-utils-mcp"]
    }
  }
}

Claude Code

claude mcp add japan-utils -- uvx japan-utils-mcp

Cursor / Cline / Continue

Тот же фрагмент JSON, что и для Claude Desktop, в соответствующих файлах конфигурации MCP.

Примеры

После подключения задавайте агенту вопросы вроде:

Какой год 令和8年? → era_to_western("令和8年") → 2026

Какой адрес у почтового индекса 150-0001? → lookup_postal_code("150-0001") → 東京都 渋谷区 神宮前

Преобразуй 山田太郎 в ромадзи. → kanji_to_romaji("山田太郎") → yamada tarou

Является ли 3 мая 2026 года японским праздником? → is_holiday("2026-05-03") → 憲法記念日 (День памяти конституции)

Перечисли все японские праздники в 2026 году. → list_holidays(2026) → 18 праздников с названиями и датами

Преобразуй ヤマダタロウ в хирагану. → convert_kana("ヤマダタロウ", "hiragana") → やまだたろう

Нормализуй ＡＢＣ１２３ до полуширинных символов. → normalize_width("ＡＢＣ１２３", "to_half") → ABC123

Раздели 長谷川健太 на фамилию и имя. → split_japanese_name("長谷川健太") → 長谷川 / 健太

Ограничения

• Ромадзи личных имен использует наиболее распространенное чтение — имена собственные с необычным чтением будут определены неверно. Это фундаментальное ограничение любого преобразования кандзи в ромадзи без контекста для устранения неоднозначности.

• Набор данных почтовых индексов поставляется через библиотеку posuto, обновляемую ежемесячно на основе данных Japan Post KEN_ALL. Если вам нужны максимально свежие данные, периодически обновляйте posuto.

• Праздники охватывают только государственные праздники (国民の祝日) — не корпоративные или региональные праздники.

• Преобразование эры поддерживает периоды от Мэйдзи (明治) до Рэйва (令和). Более ранние эры не поддерживаются.

Разработка

git clone https://github.com/vivek081166/japan-utils-mcp.git
cd japan-utils-mcp
uv sync
uv run python -c "from japan_utils_mcp.server import era_to_western; print(era_to_western('令和8年'))"

Лицензия

MIT