japan-utils-mcp

Servidor MCP que expone utilidades específicas de Japón a agentes de IA (Claude, Cursor, Cline, Continue, etc.). Proporciona a tu agente el pequeño conjunto de funciones específicas de Japón que toda tarea relacionada con el país necesita, pero que ningún LLM genérico maneja de forma fiable:

• 🗓️ Era ↔ Año occidental — 令和8年 ↔ 2026

• 🔤 Kanji → Romaji Hepburn — 山田太郎 → yamada tarou

• 📮 Búsqueda de código postal — 150-0001 → 東京都 渋谷区 神宮前

• 🎌 Calendario de días festivos nacionales — ¿es 2026-05-03 festivo? ¿y todo el año 2026?

• 🅰️ Conversión de kana — hiragana ↔ katakana ↔ katakana de ancho medio

• 📏 Normalización de ancho — ancho completo (全角) ↔ ancho medio (半角) para ASCII, dígitos y kana

• 👤 División de nombres — 山田太郎 → apellido 山田 + nombre 太郎 (modelo estadístico)

Construido sobre bibliotecas japonesas bien mantenidas (jpholiday, posuto, pykakasi, jaconv, namedivider-python), envueltas como herramientas MCP para que cualquier agente de IA pueda llamarlas sin tener que reimplementar reglas de lectura, aritmética de eras, datos postales o heurísticas de división de nombres.

Por qué existe esto

Los LLM genéricos alucinan con datos específicos de Japón:

• "¿Qué año es 令和8年?" — a menudo incorrecto

• "Convierte 山田太郎 a romaji" — se equivoca con el apellido la mitad de las veces

• "¿Cuál es la dirección del código postal 150-0001?" — inventa tonterías que parecen plausibles

• "¿Es el 3 de mayo un día festivo en Japón?" — adivina

Este MCP les proporciona una respuesta determinista.

Herramientas

Todas las herramientas devuelven JSON estructurado. Consulta las cadenas de documentación de las herramientas en src/japan_utils_mcp/server.py para ver esquemas completos y ejemplos.

Instalación

Ejecutar con uvx (sin instalación — recomendado)

uvx japan-utils-mcp

Eso es todo. uvx (de uv) gestiona la instalación y la ejecución de una sola vez, aislado de tu Python global.

Desde el código fuente

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

Configuración

Claude Desktop

Añádelo a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %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

El mismo fragmento JSON que en Claude Desktop, en sus respectivos archivos de configuración MCP.

Ejemplos

Una vez conectado, pide a tu agente cosas como:

¿Qué año es 令和8年? → era_to_western("令和8年") → 2026

¿Cuál es la dirección del código postal 150-0001? → lookup_postal_code("150-0001") → 東京都 渋谷区 神宮前

Convierte 山田太郎 a romaji. → kanji_to_romaji("山田太郎") → yamada tarou

¿Es el 3 de mayo de 2026 un día festivo en Japón? → is_holiday("2026-05-03") → 憲法記念日 (Día de la Constitución)

Lista todos los días festivos japoneses en 2026. → list_holidays(2026) → 18 días festivos con nombres y fechas

Convierte ヤマダタロウ a hiragana. → convert_kana("ヤマダタロウ", "hiragana") → やまだたろう

Normaliza ＡＢＣ１２３ a ancho medio. → normalize_width("ＡＢＣ１２３", "to_half") → ABC123

Divide 長谷川健太 en apellido y nombre. → split_japanese_name("長谷川健太") → 長谷川 / 健太

Advertencias

• El romaji de nombres personales utiliza la lectura más común; los nombres propios con lecturas inusuales serán incorrectos. Esta es una limitación fundamental de cualquier conversión de kanji a romaji sin contexto de desambiguación.

• El conjunto de datos de códigos postales se distribuye a través de la biblioteca posuto, actualizada mensualmente con el KEN_ALL de Japan Post. Si necesitas datos ultra actualizados, refresca posuto periódicamente.

• Los días festivos cubren solo los días festivos nacionales (国民の祝日), no las festividades regionales o específicas de empresas.

• La conversión de eras admite desde Meiji (明治) hasta Reiwa (令和). No se admiten eras anteriores.

Desarrollo

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年'))"

Licencia

MIT