vietnam-address-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Vietnamese administrative addresses after the 2025 reform: 34 provinces and 3,321 wards/communes, with no district level.
Use these tools instead of guessing: ward names, merges and splits are easy to get wrong from memory.
Always read confidence and notes. "split_default" means the old ward was divided between several new wards and the returned one is only a heuristic default; show alternatives to the user.
A status of "ambiguous" means the input matches several units; ask the user (usually for the district) rather than choosing.
Data: current names/codes from https://github.com/thanglequoc/vietnamese-provinces-database @ 8b78ba5; old→new mapping from https://github.com/tranngocminhhieu/vietnamadminunits @ 7fac8c4 (both MIT).
Data reflects Resolution 388/NQ-UBTVQH16 (effective 2026-09-20); every result carries dataVersion. Boundary changes after that date are not included.
For many addresses (a list or spreadsheet column) use normalize_addresses instead of calling normalize_address repeatedly.
Not covered: street-level data, coordinates, new→old conversion, wards merged before 2025 that are missing from the 2025-07 legacy list.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| normalize_addressA | Takes a free-text, comma-separated Vietnamese address in either the OLD format (ward, district, province - before 1 July 2025) or the NEW format (ward, province) and returns it in the current 2-level structure (34 provinces, no districts), keeping the street part. Handles missing diacritics, abbreviations (P., Q., TP.HCM) and a street glued to the ward. Chuẩn hóa địa chỉ / đổi địa chỉ cũ sang địa chỉ mới sau sáp nhập tỉnh, bỏ cấp huyện. Returns status ok | ambiguous | not_found, a confidence level, alternatives for divided wards, and suggestions for typos. |
| normalize_addressesA | Batch version of normalize_address for up to 200 addresses (for example a column of a customer or order spreadsheet). Returns one result per input in the same order plus a summary of how many are ok, ambiguous, not_found or divided-ward defaults. Review ambiguous and not_found items with the user instead of guessing. Chuẩn hóa hàng loạt địa chỉ cũ sang địa chỉ mới. |
| convert_legacy_addressA | Converts a pre-July-2025 administrative address given as separate fields to the new 2-level structure. Prefer this over normalize_address when the parts are already split (e.g. database columns). Đổi xã/phường/huyện/tỉnh cũ sang đơn vị hành chính mới. If the old ward was divided between several new wards, the result has confidence "split_default" and lists every alternative. Omitting the district works when the ward name is unique in the province; otherwise the result is "ambiguous". |
| search_unitsA | Searches administrative units by name, ignoring diacritics and tolerating small typos. scope "current" (default) searches the 34 provinces and 3,321 wards in force today and returns official codes. scope "legacy" searches pre-2025 provinces, districts and wards and returns where each one maps to now. Tra cứu tỉnh/thành, phường/xã theo tên, kèm mã đơn vị hành chính. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 4 tools
Each tool has a stated input shape: batch array (normalize_addresses), free-text string (normalize_address), pre-split fields (convert_legacy_address), and name lookup (search_units). The only overlap is between normalize_address and convert_legacy_address, which both produce the same normalized output, but descriptions explicitly say to prefer the latter when fields are already split.
All four names are snake_case with a clear verb_noun structure (normalize_address, convert_legacy_address, search_units), and the batch variant follows a predictable plural convention (normalize_addresses). No mixed styles or vague verbs.
Four tools is lean but each covers a distinct entry mode (single free-text, batch, structured fields, lookup) with no filler. Nothing suggests a missing variant at this scope.
The surface covers old-format normalization, new-format passthrough, batch processing, structured conversion, and search in both current and legacy scopes, plus ambiguity/suggestion handling. Minor gaps remain: no batch variant for convert_legacy_address and no reverse (new-to-old) mapping, though most agents can work around these.