mstar-addressvalidation-mcp-tool

An MCP server that uses Google Maps Platform APIs to:

• hard-check whether an address passes validation rules
• retrieve nearby business information for a single address in one Google Places API call

Install

npm install -g mstar-addressvalidation-mcp-tool

Requirements

• Node.js 18+
• GOOGMAP_KEY environment variable

Start

cd /Users/hlh/Products/mstar-addressvalidation-mcp-tool
export GOOGMAP_KEY="your_google_api_key"
npm start

Or run the published CLI directly:

export GOOGMAP_KEY="your_google_api_key"
npx -y mstar-addressvalidation-mcp-tool --stdio

Or with npx:

export GOOGMAP_KEY="your_google_api_key"
npx -y mstar-addressvalidation-mcp-tool --stdio

Local Test

cd /Users/hlh/Products/mstar-addressvalidation-mcp-tool
export GOOGMAP_KEY="your_google_api_key"
npm run test:address -- --address="P ROUAIX 2324 B CP.75790 OMEGA PERSEO ESTRELLAS DEL SUR 031C.P.75790 TEHUACAN,PUE." --regionCode=MX

If you omit --address, the script uses the sample Mexico address by default.

Nearby businesses:

cd /Users/hlh/Products/mstar-addressvalidation-mcp-tool
export GOOGMAP_KEY="your_google_api_key"
npm run test:nearby-businesses -- --address="P ROUAIX 2324 B CP.75790 OMEGA PERSEO ESTRELLAS DEL SUR 031C.P.75790 TEHUACAN,PUE."

MCP Tool

Tool name: validate_address_exists

Description:

• Validate a customer full address string directly with Google Address Validation API.

Input rules:

• Pass only one field: address.
• The input must be the full customer address string only.
• Do not include customer name or non-address fields.

Return rules:

• return true with confidence PASS when verdict.possibleNextAction is ACCEPT or VERIFY
• and either verdict.validationGranularity or verdict.geocodeGranularity is PREMISE or SUB_PREMISE
• return true with confidence SOFT_PASS when verdict.possibleNextAction is ACCEPT, VERIFY, or CONFIRM
• and either verdict.validationGranularity or verdict.geocodeGranularity is PREMISE_PROXIMITY or ROUTE
• soft-pass results should be tagged as 门牌级近似匹配 and/or 街道级匹配
• if primary validation fails, run a second-stage Places Text Search fallback using the raw address text
• when the result is locatable, return googleMapsUrl so callers can open the mapped address or nearby/street-level location in Google Maps
• return true with confidence FALLBACK_PASS only when the fallback finds a locatable place with strong text and/or postal-code overlap with the input
• otherwise return false

Input:

{
  "address": "P ROUAIX 2324 B CP.75790 OMEGA PERSEO ESTRELLAS DEL SUR 031C.P.75790 TEHUACAN,PUE.",
  "exists": true,
  "source": "ADDRESS_VALIDATION",
  "confidence": "PASS",
  "reason": "Validation passed the hard rules for possibleNextAction and address granularity.",
  "normalizedAddress": "P ROUAIX 2324 B, ESTRELLAS DEL SUR, 75790 Tehuacán, Pue., México",
  "googleMapsUrl": "https://www.google.com/maps/search/?api=1&query=P+ROUAIX+2324+B%2C+ESTRELLAS+DEL+SUR%2C+75790+Tehuac%C3%A1n%2C+Pue.%2C+M%C3%A9xico&query_place_id=ChIJexample"
}

Tool name: get_nearby_businesses_by_address

Description:

• Retrieve nearby business information for one address using Google Places Text Search.
• This tool makes exactly one Google Maps API call per request.
• This tool returns raw nearby business data only. It does not return a consumption-level judgement.

Input rules:

• Pass only one field: address.
• Use the map-call address string only.
• Do not pass customer name or other non-address fields.

Return shape:

• address: the input address
• query: the Google Places text query used internally
• count: the number of returned businesses
• businesses: raw nearby business results

Example output:

{
  "address": "P ROUAIX 2324 B CP.75790 OMEGA PERSEO ESTRELLAS DEL SUR 031C.P.75790 TEHUACAN,PUE.",
  "query": "negocios cerca de P ROUAIX 2324 B CP.75790 OMEGA PERSEO ESTRELLAS DEL SUR 031C.P.75790 TEHUACAN,PUE.",
  "count": 2,
  "businesses": [
    {
      "name": "Bodega Aurrera",
      "formattedAddress": "Tehuacan, Puebla, Mexico",
      "primaryType": "supermarket",
      "types": ["supermarket", "store", "food"],
      "rating": 4.1,
      "userRatingCount": 1200,
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "businessStatus": "OPERATIONAL",
      "location": {
        "latitude": 18.45,
        "longitude": -97.39
      },
      "googleMapsUri": "https://maps.google.com/?cid=123"
    }
  ]
}

Example MCP Client Config

{
  "mcpServers": {
    "google-address-validation": {
      "command": "npx",
      "args": ["-y", "mstar-addressvalidation-mcp-tool", "--stdio"],
      "env": {
        "GOOGMAP_KEY": "your_google_api_key"
      }
    }
  }
}

Notes

• The tool returns an object with:
  • address: the input address
  • exists: the final boolean validation result
  • source: ADDRESS_VALIDATION or PLACES_TEXT_SEARCH
  • confidence: PASS, SOFT_PASS, FALLBACK_PASS, or HARD_FAIL
  • reason: human-readable explanation of the result
• The nearby-business tool is intended as a reference-only enrichment signal.
• If your downstream agent does not receive enough nearby business data, it should treat the conclusion as unavailable instead of guessing.

Publish

npm login
npm publish --access public