Skip to main content

py-nameplate

CI Python 3.12+ License

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

Format Example
Simple John Smith
With prefix Dr. Jane Doe, Lt. Col. John Smith
With suffix John Smith Jr., Jane Doe PhD
Last, First Smith, John
With nickname Robert "Bob" Smith
Name particles Ludwig van Beethoven, Juan de la Vega
Roman numerals Henry Ford III

Addresses

Format Example
Standard 123 Main St, Boston, MA 02101
With unit 456 Oak Ave Apt 2B, Chicago, IL 60601
PO Box PO Box 789, Miami, FL 33101
Directional 100 N Main St, Denver, CO 80202
ZIP+4 123 Main St, Boston, MA 02101-1234

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

Tool Description
parse Parse any input with auto-detection and optional enhancement
parse_batch Batch parse multiple inputs

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

Endpoint Method Description
/api/parse POST Parse a single input
/api/parse/batch POST Parse multiple inputs
/health GET Health check

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

Parameter Type Description
text str Input string to parse
normalize bool Apply smart title case
enhance bool Fill in missing data from database

ParseOutput

Field Type Description
input_type str "name", "address", or "contact"
name NameOutput Parsed name components
address AddressOutput Parsed address components
parsed bool True if parsing succeeded
validated bool True if city/state found in database
enhanced bool True if data was enhanced
enhanced_fields list[str] Fields that were enhanced
errors list[str] Any parsing errors

NameOutput

Field Type Description
prefix str Dr., Mr., Mrs., Rev., etc.
first str First/given name
middle str Middle name(s)
last str Last/family name
suffix str Jr., Sr., III, PhD, etc.
nickname str Nickname if present

AddressOutput

Field Type Description
street_number str House/building number
street_name str Street name
street_type str St, Ave, Blvd, etc.
street_direction str N, S, E, W, etc.
unit_type str Apt, Suite, Unit, etc.
unit_number str Unit/apartment number
city str City name
state str Two-letter state code
zip_code str 5 or 9 digit ZIP

Data Sources

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

Metadata

Release files for py-nameplate 1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for py-nameplate 1.0
File Size Uploaded Provenance Actions
py_nameplate-1.0.tar.gz 38.4 MB Without provenance Details for py_nameplate-1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for py-nameplate 1.0
File Interpreter ABI Platform Actions
py_nameplate-1.0-py3-none-any.whl Python 3 none any Details for py_nameplate-1.0-py3-none-any.whl

Total release size: 76.8 MB

Release files / py_nameplate-1.0.tar.gz

Download URL py_nameplate-1.0.tar.gz
Size 38.4 MB
Tags Source
SHA-256 checksum
How to use checksums
5d43f3371d261d26c61b67ec8fbdb6501b81f1b4d87117b62eb1de06ad69b181
BLAKE2b-256 checksum
How to use checksums
bd2355d02058d4e2064547705c010789cf3933d8f5ea3297b99db556a0657461
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / py_nameplate-1.0-py3-none-any.whl

Download URL py_nameplate-1.0-py3-none-any.whl
Size 38.4 MB
Tags Python 3
SHA-256 checksum
How to use checksums
5e1f5269b214f0774845cfa98eb1bf984cbdaad629cab55ec23c7d10571781dd
BLAKE2b-256 checksum
How to use checksums
549d07bb65962d5c253b1a2060895ee858dbbcb2984ed49806d63be4e8db52b7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for py-nameplate 1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page