# Smarty MCP

> Smarty validates, autocompletes, and extracts global street addresses instantly for your AI client. It handles messy raw text—whether it's a customer note or an email—and cleans it into perfectly formatted postal data. You get delivery point validation (DPV) status and coordinates for both US and international locations without writing any code.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** address-validation, geocoding, data-sanitization, postal-verification, location-intelligence

## Description

Smarty hooks up your AI client so it can deal with junk address data. It doesn't matter if you're reading a messy customer note or an old email—this server cleans that raw text and formats the physical locations into structured, usable postal data. You get Delivery Point Validation (DPV) status and precise coordinates for both U.S. addresses and international spots without ever writing a single line of code yourself.

When you use this toolset, your agent handles complex geospatial calls through natural language prompts. It bypasses the headache of setting up custom API scripts or manually testing data in some sandbox environment.

### How You Use It

You'll group related functions together. The server first checks connection status using `get_account_info`, letting your agent confirm current usage limits and service health before it starts working.

For full address validation, you have two paths. If the location is in the U.S., use `validate_us_address`. This function takes a specific street address and tells you its DPV status while returning exact coordinates for pinpointing it on a map. For anything outside the U.S.—like Canada or Europe—you'll run `validate_intl_address`. It confirms if that full international address is real by querying global postal databases and gives you precise geocoding data.

If your client only has partial info, don't sweat it. When a user provides just a fragment of an address, like a street name or apartment number, you use autocomplete tools to guess the rest. For U.S. addresses, `autocomplete_us_address` suggests three likely full completions based on what was typed. For international suggestions, run `autocomplete_intl_address` when your user gives you only a piece of an address in another country.

When you're not validating or guessing, but pulling data from existing text, use `extract_addresses`. You feed this tool any chunk of unformatted writing—it could be meeting notes, a long email chain, or a document copy—and it pulls out every identifiable physical address into an easy-to-read list. To confirm general postal zones, run `verify_zip_code`. This takes a simple five-digit ZIP code and confirms its existence while returning the associated city and state limits.

When you put it all together, your agent can check account status first with `get_account_info`, then use `extract_addresses` to pull out multiple locations from an email body. After that, it might run `verify_zip_code` on a specific zip code found in the text. If the extracted address is international, you validate it immediately using `validate_intl_address`. If it's U.S.-based, you check its deliverability with `validate_us_address`, or if you only have partial info for either country, you let the appropriate autocomplete function—`autocomplete_us_address` or `autocomplete_intl_address`—handle the rest.

## Tools

### autocomplete_intl_address
Predicts and suggests full international street addresses when given a partial input string.

### autocomplete_us_address
Provides three suggested completions for US addresses based on partial inputs like street numbers or abbreviations.

### extract_addresses
Reads any chunk of raw text (emails, documents) and pulls out all identifiable physical addresses into a list.

### get_account_info
Retrieves basic account details for the Smarty service to confirm connection status or usage limits.

### validate_intl_address
Confirms if a full international street address is real and geocodes it using required country and line data.

### validate_us_address
Checks a US street address for DPV status, returning coordinates and confirming deliverability.

### verify_zip_code
Takes a 5-digit postal code and returns the associated state and city limits to confirm the zone.

## Prompt Examples

**Prompt:** 
```
Validate this US address: 1 Santa Claus Ln, North Pole, AK 99705.
```

**Response:** 
```
I've validated the inputted address using the Smarty API.
**Normalized Result**: 1 Santa Claus Ln, North Pole, AK 99705-9901
**DPV Match**: Yes (Y) - Valid deliverable address
**County**: Fairbanks North Star
**Coordinates**: Latitude 64.75, Longitude -147.34
```

**Prompt:** 
```
Can you extract any known addresses from this raw text string: "I live out near the big oak tree at 1600 Amphitheatre Pkwy, Mountain View, CA 94043, come visit soon!"
```

**Response:** 
```
I extracted the following geographic location using the text parsing API:

**Address 1**:
- **Cleaned Line**: 1600 Amphitheatre Pkwy, Mountain View, CA 94043
- **ZIP**: 94043
- **Verification**: Confirmed deliverable (Google Headquarters).
```

**Prompt:** 
```
Provide a markdown list of US autocomplete suggestions when a user types "3311 w 300 s s".
```

**Response:** 
```
Based on the incomplete input `3311 w 300 s s`, the Smarty API returned these 3 most likely completions:

1. **3311 W 300 S**, Salt Lake City, UT 84104
2. **3311 W 300 S**, Syracuse, IN 46567
3. **3311 W 300 S**, Swayzee, IN 46986

Would you like me to run a full DPV validation on the Salt Lake City result?
```

## Capabilities

### Validate US Addresses
The agent checks a specific US street address, returning the Delivery Point Validation (DPV) status and precise coordinates.

### Validate International Addresses
The agent confirms if an international street address is valid by querying global postal databases and geocoding its location.

### Extract from Raw Text
The tool scans unstructured text (emails, notes) and pulls out every physical address it finds.

### Predict Address Suggestions (US)
The agent takes a partial US street name or location fragment and suggests the three most likely full completions.

### Verify Postal Zones
The tool accepts a 5-digit ZIP code, confirming its existence and returning associated municipal boundaries (city/state).

## Use Cases

### Cleaning Web Form Submissions
A user submits a lead form with mixed fields: name, email, and an address that has typos. The agent runs `extract_addresses` first to isolate the messy text, then uses `validate_us_address` on the result. It returns a clean, confirmed deliverable line, ready for CRM entry.

### Processing Bulk Customer Notes
A data team needs to process thousands of unstructured service notes containing addresses from different countries. The agent runs `extract_addresses` on the entire batch and then cycles through `validate_intl_address` for every result, building a clean database record.

### Autocomplete During Chat Support
A customer is talking to support via chat, providing an incomplete address like '3311 w 300 s s'. The agent prompts `autocomplete_us_address` with the fragment and shows three suggested completions, letting the user pick the correct location immediately.

### Validating Shipping Labels
The logistics team has a list of addresses that need to be verified for shipment. They use `validate_us_address` against each entry and then run `verify_zip_code` on the resulting postal code to confirm local municipal limits.

## Benefits

- The agent handles dirty data. Instead of manually cleaning spreadsheets, you just give the AI a blob of raw notes; it runs `extract_addresses` and pulls out only valid locations.
- You get instant delivery confirmation for US addresses. Running `validate_us_address` gives you the DPV status and coordinates right in your chat interface, confirming if it’s actually deliverable.
- Global coverage means less work for international teams. Use `validate_intl_address` to confirm foreign postal data—it doesn't care where the address is on earth.
- No more guessing partial inputs. If a user types '3311 W 300 S', you run `autocomplete_us_address`, and it gives three highly probable completions, letting you guide them to the right result.
- The process is simple: First, use `verify_zip_code` on the postal code; second, pass that data into a full validation tool. You build confidence in your input before proceeding.

## How It Works

The bottom line is: your AI agent does the API calling for you; you just talk to it in natural language.

1. Subscribe to the server and provide your Smarty Auth ID and Auth Token.
2. Connect an MCP-compatible client (like Cursor or Claude).
3. Prompt your agent directly: 'Validate this address:' The agent executes the necessary tool call, and you get the structured validation result back.

## Frequently Asked Questions

**How do I use Smarty MCP Server to check a US address?**
Use the `validate_us_address` tool. You give your agent the full US street address and it returns the Delivery Point Validation (DPV) status, coordinates, and confirmation that the address is deliverable.

**Can Smarty MCP Server pull addresses from emails?**
Yes, use `extract_addresses`. You feed your agent any raw text—like a pasted email body—and it intelligently isolates every physical location found in that noise.

**Do I need to manually validate the ZIP code before running validation?**
No, but you can use `verify_zip_code` first. It’s a good step for confidence; it confirms the 5-digit postal zone and returns associated city/state limits before you run full validation.

**How do I autocomplete an international address with Smarty?**
Call the `autocomplete_intl_address` tool. You provide a partial street name or location, and it suggests multiple valid completions based on global data sets.

**How do I connect my AI client using the `get_account_info` tool?**
You must first subscribe to the server and provide your Smarty Auth ID and Token. Your agent sends this information to execute `get_account_info`, which confirms your connection status and basic account details.

**What should happen if `validate_us_address` encounters an invalid address format?**
The tool will return a validation failure status, detailing why the input failed. You get specific error codes alongside the DPV match status, telling you exactly what needs fixing.

**Can `extract_addresses` process very large blocks of raw text?**
Yes, it processes complex and lengthy strings effectively by parsing them for physical addresses. You can feed your agent a large document dump or log file; the tool isolates valid postal locations within that context.

**How does Smarty handle rate limits when I use multiple validation tools?**
The server adheres to standard API usage rates, so repeated calls won't overload it. If you hit a limit, your AI client will receive an appropriate HTTP error code, telling you exactly when to retry the request.

**Can the AI find an address hidden inside a block of text automatically?**
Yes! You can paste an entire email string or customer support note into your prompt and ask the AI: 'Extract any addresses mentioned in this text.' The agent triggers the `extract_addresses` engine to return the geolocated and sanitized address format purely.

**How accurate is the address verification?**
Smarty ensures the address is validated against official sources like the USPS using DPV (Delivery Point Validation) for US requests, guaranteeing a package can actually be delivered to the mapped coordinate. Your AI agent returns this rigorous underlying metadata.

**Can I use the agent to fix my dataset dynamically without coding?**
Yes. If you have 20 poorly formatted customer addresses, you can simply paste them in the prompt, asking your AI to 'Run each of these through Smarty and return a markdown table of the normalized addresses.' The agent handles the iteration loop for you via the tools.