Usps MCP Server

USPS地址验证和标准化MCP服务器

一种模型上下文协议（MCP）服务器，为AI助手提供与USPS服务交互的工具，特别是解决验证和标准化问题。

特性

• 地址验证：使用官方USPS地址验证API验证和标准化美国地址
• OAuth2身份验证：使用USPS OAuth2客户端凭据流进行安全身份验证
• MCP协议合规性：用于AI模型集成的标准MCP服务器实现
• 全面的错误处理：针对API超时、速率限制和验证错误的稳健错误处理
• TypeScript支持：具有类型安全的完整TypeScript实现

先决条件

1. USPS商业账户：您需要一个USPS商业帐户才能访问API。阅读入门指南 USPS开发者门户
2. API证书：从API应用程序获取消费者密钥和消费者秘密

设置

1.克隆和安装

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

2.环境配置

复制示例环境文件并配置您的USPS凭据：

cp .env.example .env

编辑 .env 使用您的USPS API证书：

USPS_CLIENT_ID=your_consumer_key_here
USPS_CLIENT_SECRET=your_consumer_secret_here
NODE_ENV=development

3.构建并作为stdio运行

# Development
npm run dev

# Production build
npm run build
npm start

# Run tests
npm test

4.作为SSE MCP服务器运行

# Production build
npm run start:http

用法

作为stdio MCP服务器

该服务器作为基于stdio的MCP服务器运行。配置您的AI客户端以使用此服务器：

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

在Claude中用作stdio

{
  "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"
}

在VS代码副本中用作SSE

使用SSE运行应用程序

npm run start:http

配置VS代码mcp.json

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

可用工具

validate_address

使用USPS服务验证和标准化美国地址。

参数：

• streetAddress （必填）：街道地址（例如“主街123号”）
• city （必填）：城市名称（例如“纽约”）
• state （必填）：两个字母的州代码（例如“NY”）
• zipCode （必填）：邮政编码（例如“12345”或“12345-6789”）
• urbanization （可选）：城市化名称（仅限波多黎各）

示例用法：

{
  "tool": "validate_address",
  "arguments": {
    "streetAddress": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001"
  }
}

答复：

{
  "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集成

USPS认证

服务器自动处理OAuth2身份验证：

1. 将客户端凭据流与您的USPS消费者密钥/秘密一起使用
2. 缓存访问令牌并处理自动刷新
3. 向所有API请求添加承载令牌

速率限制

• USPS API有速率限制（默认值：每小时60次调用）
• 服务器实现了批处理请求之间的延迟
• 考虑对生产使用实施额外的速率限制

测试环境

对于开发，set NODE_ENV=development 使用USPS邮件测试环境（TEM）：

• 生产： apis.usps.com
• 测试： apis-tem.usps.com

错误处理

服务器提供全面的错误处理：

• 身份验证错误：凭据无效，令牌过期
• 验证错误：输入参数无效，地址格式错误
• API错误：USPS服务错误、网络超时
• 速率限制错误：使用指数回退自动重试

发展

项目结构

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

添加新工具

1. 在中创建服务类 src/services/
2. 在中定义工具架构 src/tools/
3. 在中注册工具 src/server.ts
4. 添加测试并更新文档

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

对于USPS API问题：

• USPS开发人员门户支持
• 美国邮政API文件
• USPS API入门

对于MCP服务器问题：

• 在此存储库中创建问题
• 检查 MCP规范