查询约定

https://api.vesselmcp.com 给程序，https://mcp.vesselmcp.com 给 Agent，提供同一套只读查询：按 IMO 取船舶身份，或按 IMO 取最近靠港。两者独立鉴权、独立限流，互不接受对方的 key。域名职责见 域名。

主站 vesselmcp.com 是本地留存快照，不走这两条程序化接口。程序化结果可能与公开页面上的记录日期和字段范围不同。

只按 IMO

层	身份	靠港
REST	GET /v1/vessels/{imo}	GET /v1/vessels/{imo}/recent-ports
MCP	vesselmcp_get_vessel	vesselmcp_get_recent_ports

• IMO 必须是七位数字，通过 checksum，且不能是 0000000。
• 没有船名搜索、分页、旧聚合入口或别名。
• 身份成功不包含靠港字段；靠港成功不包含身份可选字段。
• 需要两边时必须各调用一次。两次都计入该服务的 IP 与 key ID 限额；缓存命中不免额度。

Checksum：前六位依次乘以 7、6、5、4、3、2，乘积之和模 10 等于第七位。

身份

成功对象只允许 imo，以及可选的 name、flag、vesselType、callsign、mmsi。成功必须带 fetchedAt。

REST 外包 { "data": { "vessel": ... } }。真实未找到时 REST 返回 404 VESSEL_NOT_FOUND，MCP 工具返回 isError 文本 Vessel not found.。其他身份失败是查询失败，不是「未找到」。

靠港

成功结果恰好三个字段：imo、recentPorts、fetchedAt。最多 10 条，可重复同一港口，不保证完整历史。有效空数组 [] 仍是成功，且必须带 fetchedAt。

港口查询失败（例如超时、不可用、数据不合格或繁忙）都是查询失败：REST 返回 502 BACKEND_UNAVAILABLE，MCP 返回通用 isError。不能当成空数组或「船舶不存在」。已知 IMO 可直接查靠港，不必先查身份。

每条靠港：

字段	规则
id	必需，1–64 位 ASCII 字母、数字、下划线或连字符
portName	必需，1–120 个 UTF-16 code unit，首尾无空格，无控制字符
portId	可选，同 id
unlocode	可选，两位大写字母加三位大写字母或数字
coordinates	可选，[经度, 纬度]，经度 [-180,180]，纬度 [-90,90]
arrival / departure	可选，UTC YYYY-MM-DDTHH:mm:ss.sssZ；两者都有时离港不早于抵港
minutesOfStay	可选，有限非负数字
status	可选，仅 arrived、departed、inPort

按 id 去重，不按港口名去重，没有排序或分页参数。

fetchedAt

表示这一次身份或靠港成功采集完成的时间，不是港口事件时间，也不承诺实时。格式必须恰好 24 字符 YYYY-MM-DDTHH:mm:ss.sssZ。身份与靠港互不借用时间。缓存命中保留原时间。

鉴权

服务	Bearer 格式
REST	vmcp_api_v1_<key-id>_<secret>
MCP	vmcp_mcp_v1_<key-id>_<secret>

从主站首页填写邮箱并选择 API 或 MCP。独立的 app.vesselmcp.com 服务发送 30 分钟内有效的验证链接；打开并确认邮箱后，所选服务的 key 将通过邮件发送，有效期为 90 天（UTC）。每个服务都会拒绝为另一服务签发的 key。原始 secret 不会出现在限流计数里。

两次申请请至少间隔一小时。每个邮箱、每项服务最多一个未过期 key，有效期内不替换、不重发。密钥邮件只尝试发送一次；如果发放已开始但投递结果无法确认，90 天有效期结束前不能自动再发一个 key。未收到邮件可联系支持，请勿附上密钥或验证链接。文档站不发放 key；申请功能是否可用取决于独立服务是否启用。