py-nameplate

A Python library, MCP server, and REST API for parsing unstructured US contact strings into structured components.

The Problem

You have messy contact data:

Dr. John Smith Jr. 742 Evergreen Terrace
JANE DOE 123 MAIN ST APT 2B BOSTON MA 02101
Smith, Robert "Bob" 456 Oak Ave, Chicago, IL 60601

You need structured data you can actually use.

The Solution

One function that handles it all:

from nameplate import parse

result = parse("Dr. John Smith Jr. 742 Evergreen Terrace, Springfield, IL 62701")

# Name components
result.name.prefix      # "Dr."
result.name.first       # "John"
result.name.last        # "Smith"
result.name.suffix      # "Jr."

# Address components
result.address.street_number  # "742"
result.address.street_name    # "Evergreen"
result.address.street_type    # "Terrace"
result.address.city           # "Springfield"
result.address.state          # "IL"

result.input_type       # "contact"
result.validated        # True (city/state in database)

How It Works

The parse() function uses token-based segmentation to automatically find the boundary between name and address:

Dr. John Smith Jr. 742 Evergreen Terrace
└───── name ─────┘ └────── address ─────┘

Segmentation algorithm:

1. Tokenize input into words
2. Scan for first numeric token that isn't a name suffix (III, 1ST, etc.)
3. Verify remaining tokens contain street indicators (St, Ave, ZIP, state, etc.)
4. Split at that boundary

Address parsing works backwards from the end:

• Extract ZIP code (5 or 9 digits)
• Extract state (2-letter code)
• Extract city (validated against database)
• Extract unit (Apt, Suite, #)
• Remaining tokens are street components

Street-based enhancement fills in missing city/state:

• If address has a street but no city, look up the street in the database
• If street exists in exactly one location, auto-fill city and state
• Common streets like "Main Street" exist in many cities and won't enhance

Installation

pip install py-nameplate

Or with uv:

uv add py-nameplate

Usage

Basic Parsing

from nameplate import parse

# Auto-detects input type
result = parse("123 Main St, Boston, MA 02101")
result.input_type  # "address"

result = parse("Dr. Jane Doe")
result.input_type  # "name"

result = parse("John Smith 123 Main St, Boston, MA 02101")
result.input_type  # "contact"

Enhancement

# Without enhancement - street alone has no city/state
result = parse("100 Dunwoody Club Dr")
result.address.city   # ""
result.address.state  # ""

# With enhancement - city/state auto-filled if street is unique in database
result = parse("100 Dunwoody Club Dr", enhance=True)
result.address.city   # "Atlanta" (auto-filled)
result.address.state  # "GA" (auto-filled)
result.enhanced       # True

Normalization

# Smart title case
result = parse("PATRICK O'BRIEN 123 MAIN ST", normalize=True)
result.name.last       # "O'Brien" (not "O'brien")
result.address.city    # "Boston" (not "BOSTON")

result = parse("RONALD MCDONALD", normalize=True)
result.name.last  # "McDonald" (not "Mcdonald")

Batch Processing

from nameplate import parse_batch

texts = [
    "Dr. John Smith",
    "123 Main St, Boston, MA 02101",
    "Jane Doe 456 Oak Ave, Chicago, IL 60601",
]
result = parse_batch(texts, enhance=True)
result.total           # 3
result.parsed_count    # 3
result.enhanced_count  # number with enhanced data

Supported Formats

Names

Addresses

Contacts

Any combination of name followed by address:

John Smith 123 Main St, Boston, MA 02101
Dr. Jane Doe Jr. PO Box 456, Seattle, WA 98101

MCP Server

Use with Claude Desktop or Claude.ai as an MCP tool.

Local (uvx)

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "nameplate": {
      "command": "uvx",
      "args": ["nameplate"]
    }
  }
}

Hosted

{
  "mcpServers": {
    "nameplate": {
      "type": "url",
      "url": "https://nameplate.mcp.danheskett.com/"
    }
  }
}

Available Tools

Example Prompts

"Parse this: Dr. John Smith 742 Evergreen Terrace, Springfield, IL"

"Parse with enhancement: Jane Doe 100 Dunwoody Club Dr"

"Parse these contacts: John Smith, 123 Main St Boston MA, Jane Doe 456 Oak Ave Chicago IL"

REST API

Use the REST API for direct HTTP access without MCP.

Base URL: https://nameplate.mcp.danheskett.com

Endpoints

Request Format

{
  "text": "Dr. John Smith 123 Main St, Boston, MA 02101",
  "normalize": false,
  "enhance": false
}

For batch requests, use texts (array) instead of text:

{
  "texts": ["John Smith", "123 Main St, Boston, MA 02101"],
  "normalize": true,
  "enhance": true
}

Examples

Basic parse:

curl -X POST https://nameplate.mcp.danheskett.com/api/parse \
  -H "Content-Type: application/json" \
  -d '{"text": "Dr. John Smith 123 Main St, Boston, MA 02101"}'

Parse with enhancement:

curl -X POST https://nameplate.mcp.danheskett.com/api/parse \
  -H "Content-Type: application/json" \
  -d '{"text": "Jane Doe 100 Dunwoody Club Dr", "enhance": true}'

Batch parsing:

curl -X POST https://nameplate.mcp.danheskett.com/api/parse/batch \
  -H "Content-Type: application/json" \
  -d '{"texts": ["John Smith", "123 Main St, Boston, MA 02101"], "normalize": true}'

Health check:

curl https://nameplate.mcp.danheskett.com/health

Python API Reference

parse(text, normalize=False, enhance=False) -> ParseOutput

ParseOutput

NameOutput

AddressOutput

Data Sources

• US Cities: 29,880 city/state combinations from kelvins/US-Cities-Database (MIT)
• Street Names: 500k+ street/location mappings from USGS (ODbL)

Development

git clone https://github.com/dannyheskett/py-nameplate.git
cd py-nameplate
uv sync --extra dev

# Run tests
uv run pytest

# Lint
uv run ruff check src/ tests/
uv run ruff format src/ tests/

Privacy

The hosted MCP server does not store, log, or retain any data. All parsing happens in memory. See the source code to verify.

License

BSD-3-Clause