lookup_postal_code
Resolve a 7-digit Japanese postal code to its prefecture, city, and area, with kanji and kana readings.
Instructions
Look up a Japanese postal code (郵便番号) and return address components.
Args: postal_code: 7-digit JP postal code. Accepts '150-0001', '1500001', '150 0001', or with full-width digits.
Returns: dict with keys: - postal_code: str (normalized 7-digit form) - prefecture: str (都道府県) - city: str (市区町村) - area: str (町域 — neighborhood/area) - prefecture_kana: str (katakana reading of prefecture) - city_kana: str - area_kana: str - found: bool (true if the code resolved)
Examples: lookup_postal_code("150-0001") → { "postal_code": "1500001", "prefecture": "東京都", "city": "渋谷区", "area": "神宮前", ... "found": True, }
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| postal_code | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/japan_utils_mcp/server.py:216-279 (handler)The main handler function for the lookup_postal_code tool. Decorated with @mcp.tool(), it accepts a postal code string, normalizes it to 7 digits, queries the posuto database, and returns address components (prefecture, city, area) along with their kana readings.
@mcp.tool() def lookup_postal_code(postal_code: str) -> dict[str, Any]: """Look up a Japanese postal code (郵便番号) and return address components. Args: postal_code: 7-digit JP postal code. Accepts '150-0001', '1500001', '150 0001', or with full-width digits. Returns: dict with keys: - postal_code: str (normalized 7-digit form) - prefecture: str (都道府県) - city: str (市区町村) - area: str (町域 — neighborhood/area) - prefecture_kana: str (katakana reading of prefecture) - city_kana: str - area_kana: str - found: bool (true if the code resolved) Examples: lookup_postal_code("150-0001") → { "postal_code": "1500001", "prefecture": "東京都", "city": "渋谷区", "area": "神宮前", ... "found": True, } """ digits = re.sub(r"[^0-9]", "", postal_code) digits = digits.translate(str.maketrans("０１２３４５６７８９", "0123456789")) if len(digits) != 7 or not digits.isdigit(): return { "postal_code": postal_code, "found": False, "error": "Postal code must be 7 digits.", } try: entry = posuto.get(digits) except KeyError: return { "postal_code": digits, "found": False, "error": "Postal code not found in dataset.", } except Exception as exc: return { "postal_code": digits, "found": False, "error": f"Lookup failed: {exc}", } return { "postal_code": digits, "prefecture": entry.prefecture, "city": entry.city, "area": entry.neighborhood, "prefecture_kana": entry.prefecture_kana, "city_kana": entry.city_kana, "area_kana": entry.neighborhood_kana, "found": True, } - src/japan_utils_mcp/server.py:216-216 (registration)The tool is registered via the @mcp.tool() decorator on line 216, which is the FastMCP framework's mechanism for registering tools. No separate registration call exists.
@mcp.tool() - src/japan_utils_mcp/server.py:23-24 (helper)The posuto library import used to perform the actual postal code lookup. posuto is a Python library for Japanese postal code data.
import posuto # type: ignore[import-untyped] import pykakasi # type: ignore[import-untyped]