contact-verification-mcp

一个包装了 Melissa 的 Global Address、Global Email 和 Global Phone 验证 API 的 MCP 服务器。它是为配合 SD Times / Melissa 开发者文章《为验证 API 构建一个 MCP 服务器》而构建的。

这是什么

智能体可以在对联系数据采取行动之前调用三个工具来检查其真实性，外加一个批量工具和每次会话的调用预算，防止智能体循环调用导致账单失控：

• verify_postal_address

• verify_email

• verify_phone

• verify_batch

关于工具描述背后的设计选择、三态（已确认 / 部分确认 / 未确认）结果，以及为什么刻意不暴露电话线路类型，请参阅 src/melissaClient.ts。

Related MCP server: email-verify

设置

npm install
cp .env.example .env
# edit .env and set MELISSA_LICENSE_KEY to your own key
npm run build
npm start

该服务器通过 stdio 使用 MCP 协议进行通信，因此它应由 MCP 客户端（Claude Code、Claude Desktop 或任何其他兼容 MCP 的主机）启动，而不是为交互式使用而独立运行。

测试

npm test          # runs entirely against recorded fixtures, no network calls, no key required
npm run typecheck  # type-checks src/ and tests/ together

tests/fixtures/ 中的测试带有一个 _source 字段：REAL 表示从 Melissa 发布的 OpenAPI 示例中逐字复制（github.com/MelissaData/MelissaCloudAPI-OpenAPI-Specifications）；SYNTHETIC 表示是因为 Melissa 的公开规范中没有该形状的真实示例（主要是失败用例）而构造出来的，用于测试覆盖。不要将合成夹具的具体结果码当作已经真实账户验证过的。

运行真实测试

MELISSA_LICENSE_KEY=your-real-key npm run test:live

这会真实调用 Melissa 的 API 并消耗 API 额度。它永远不会作为 npm test 或 CI 的一部分运行。不要把真实密钥放在任何已提交的文件中；只能在运行时将其设置为环境变量。

结果代码来源

本代码库中引用的每个 Melissa 结果代码（AV24、ES01、ES07、ES08、ES21、PS01、PS20、PS22）都已通过 grep 搜索 Melissa 自己发布的 OpenAPI 规范示例确认，而不是猜测或旧文章草稿相关。具体如下：

• AV24 是 Melissa 的 Global Address 规范示例中出现的唯一 AV 前缀代码。没有针对独立的“已确认到子场所”层级的已确认代码，因此该客户端不宣称这一层级。

• Global Email 的规范示例只显示 ES 前缀代码。该规范中从不出现任何 EE 前缀代码。

• Global Phone 的线路类型检测（mobile/landline/VoIP）在文档中仅限 Premium 模式且仅限美国/加拿大，因此此处不作为通用能力提供。

如果你的账户真实响应包含上述以外的代码，那说明该客户端需要更新，而不是新代码以错。

尚未完成的工作

• 用于多实例部署的 Redis 缓存（目前仅支持进程内 LRU，见 src/cache.ts）。

• 对启用了 Premium 模式的账户提供线路类型检测，置于功能开关之后。

• 在 Melissa 自身规范中的 US/UK/DE 示例之外，对 Global Address 进行更广泛的国家/地区覆盖测试。