# USPS Address Validation and Standardization MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with tools to interact with USPS services, specifically address validation and standardization.

## Features

- **Address Validation**: Validate and standardize US addresses using the official USPS Address Validation API
- **OAuth2 Authentication**: Secure authentication using USPS OAuth2 Client Credentials flow
- **MCP Protocol Compliance**: Standard MCP server implementation for AI model integration
- **Comprehensive Error Handling**: Robust error handling for API timeouts, rate limits, and validation errors
- **TypeScript Support**: Full TypeScript implementation with type safety

## Prerequisites

1. **USPS Business Account**: You need a USPS Business Account to access the APIs. Read the Getting Started at [USPS Developer Portal](https://developers.usps.com/getting-started)
3. **API Credentials**: Obtain Consumer Key and Consumer Secret from your API app

## Setup

### 1. Clone and Install

```bash
git clone https://github.com/bailur/usps-mcp-server.git
cd usps-mcp-server
npm install
```

### 2. Environment Configuration

Copy the example environment file and configure your USPS credentials:

```bash
cp .env.example .env
```

Edit `.env` with your USPS API credentials:

```env
USPS_CLIENT_ID=your_consumer_key_here
USPS_CLIENT_SECRET=your_consumer_secret_here
NODE_ENV=development
```

### 3. Build and Run as stdio

```bash
# Development
npm run dev

# Production build
npm run build
npm start

# Run tests
npm test
```

### 4. Run as an SSE MCP server
```bash

# Production build
npm run start:http

```


## Usage

### As a stdio MCP Server

The server runs as a stdio-based MCP server. Configure your AI client to use this server:

```json
{
  "mcpServers": {
    "usps": {
      "command": "node",
      "args": ["/path/to/usps-mcp-server/dist/index.js"],
      "env": {
        "USPS_CLIENT_ID": "your_key",
        "USPS_CLIENT_SECRET": "your_secret"
      }
    }
  }
}
```

### Usage in Claude as stdio

```json
{
  "mcpServers": {
    "usps": {
      "command": "npx",
      "args": [
        "tsx",
        "/path/to/usps-mcp-server/src/index.ts",
        "--env", "USPS_CLIENT_ID=your_client_id",
        "--env", "USPS_CLIENT_SECRET=your_consumer_secret",
        "--env", "NODE_ENV=prod",
        "--env", "MCP_TRANSPORT=stdio",
        "--env", "USPS_BASE_URL=https://apis.usps.com",
        "--env", "USPS_TEST_BASE_URL=https://apis-tem.usps.com"
      ]
    }
  },
  "globalShortcut": "CommandOrControl+Shift+Space"
}
```

### Usage in VS Code Copilot as SSE

Run the app using SSE
```bash
npm run start:http
```
Configure VS Code mcp.json

```json
{
	"servers": {
		"usps-remote-mcp-server": {
			"url": "http://localhost:3000/mcp",
			"type": "sse"
		}
	},
	"inputs": []
}
```


### Available Tools

#### `validate_address`

Validates and standardizes a US address using USPS services.

**Parameters:**
- `streetAddress` (required): Street address (e.g., "123 Main St")
- `city` (required): City name (e.g., "New York")
- `state` (required): Two-letter state code (e.g., "NY")
- `zipCode` (required): ZIP code (e.g., "12345" or "12345-6789")
- `urbanization` (optional): Urbanization name (Puerto Rico only)

**Example Usage:**
```javascript
{
  "tool": "validate_address",
  "arguments": {
    "streetAddress": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001"
  }
}
```

**Response:**
```json
{
  "success": true,
  "originalAddress": {
    "streetAddress": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001"
  },
  "validatedAddress": {
    "address": {
      "streetAddress": "123 MAIN ST",
      "city": "NEW YORK",
      "state": "NY",
      "ZIPCode": "10001",
      "ZIPPlus4": "1234"
    },
    "additionalInfo": {
      "DPVConfirmation": "Y",
      "business": "N"
    }
  },
  "summary": "Standardized address: 123 MAIN ST, NEW YORK, NY, 10001-1234 (delivery point confirmed)"
}
```

## API Integration

### USPS Authentication

The server automatically handles OAuth2 authentication:

1. Uses Client Credentials flow with your USPS Consumer Key/Secret
2. Caches access tokens and handles automatic refresh
3. Adds Bearer token to all API requests

### Rate Limiting

- USPS APIs have rate limits (default: 60 calls per hour)
- The server implements delays between batch requests
- Consider implementing additional rate limiting for production use

### Testing Environment

For development, set `NODE_ENV=development` to use the USPS Testing Environment for Mailers (TEM):
- Production: `apis.usps.com`
- Testing: `apis-tem.usps.com`

## Error Handling

The server provides comprehensive error handling:

- **Authentication Errors**: Invalid credentials, expired tokens
- **Validation Errors**: Invalid input parameters, malformed addresses
- **API Errors**: USPS service errors, network timeouts
- **Rate Limit Errors**: Automatic retry with exponential backoff

## Development

### Project Structure

```
src/
├── auth/
│   └── oauth-client.ts      # OAuth2 client implementation
├── services/
│   └── address-validation.ts # Address validation service
├── tools/
│   └── validate-address-tool.ts # MCP tool definition
├── types/
│   └── address-types.ts     # TypeScript type definitions
├── server.ts                # Main MCP server
└── index.ts                 # Entry point
```

### Adding New Tools

1. Create service class in `src/services/`
2. Define tool schema in `src/tools/`
3. Register tool in `src/server.ts`
4. Add tests and update documentation

## License

MIT License - see LICENSE file for details

## Support

For USPS API issues:
- [USPS Developer Portal Support](https://emailus.usps.com/s/web-tools-inquiry)
- [USPS API Documentation](https://developers.usps.com/apis)
- [Getting Started with USPS APIs](https://developers.usps.com/getting-started)


For MCP Server issues:
- Create an issue in this repository
- Check the [MCP Specification](https://spec.modelcontextprotocol.io/)