simscout

simscout

simscout 是一个小型本地桥接工具，连接到 esimoa 托管的 MCP 服务。该服务收录旅行 eSIM 套餐：选择目的地，说明行程时长 和所需流量，目录便会返回符合条件的套餐、以 KRW 计价的 价格，以及每个套餐在 esimoa.com 上的页面链接，用户可在 该页面购买。

该桥接工具不维护自己的目录。它会在本地提供上游服务的 工具列表，内容与从实时端点捕获的内容完全一致，并将每次 工具调用转发给上游，原样返回结果。捕获的全部功能都只用于 读取——搜索、获取单个套餐、比较候选套餐列表和列出目的地—— 其中没有结账或支付工具。

工具

• search_esims — 搜索指定目的地的目录。 所有筛选条件均为可选：country（ISO 代码或任意语言 的名称，例如 JP 或 Japan）、days（行程天数）、 data_gb / max_data_gb、unlimited、 countries（多国行程，最多 8 个国家）、data_type （daily 或 total）、local_number、network （local 或 roaming）、multi_country、 min_price_krw / max_price_krw、provider、 hotspot、five_g、sort（recommended、price、 data、price_per_gb 或 validity）、limit（1-10， 默认值为 5）和 lang。每个结果都包含一个 id 和套餐页面 url。
• get_esim — 获取一个套餐的完整详情。必填： id（来自 search_esims）。可选：lang。
• compare_esims — 并排比较两到五个套餐： 价格、流量、有效期、每 GB 价格、覆盖范围、网络、 热点和本地电话号码，以及在最低价格、流量最多、有效期最长 和每 GB 价格最低这几项中的优胜套餐。必填：ids。 可选：lang。
• list_countries — 列出所有有套餐出售的目的地，以及每个 国家或地区的套餐数量和最低价格。可选：query（名称或 ISO 筛选条件）和 lang。
• search — 使用 ChatGPT 深度研究所用的搜索/获取格式进行 全文搜索，例如“Japan 7 days unlimited”。必填：query。 返回供 fetch 使用的 ID。如果可以填写筛选条件，请优先使用 search_esims。
• fetch — 根据 search 返回的 ID，将一个套餐作为文档 返回。必填：id。对于通过 search_esims 找到的套餐， 请改用 get_esim。

配置

• ESIMOA_MCP_URL（可选）— 覆盖上游端点。默认值为 https://api.esimoa.com/mcp。（此覆盖机制是本次重建自行 标注的内容。）
• ESIMOA_API_KEY（可选）— 设置后，每个上游请求都会携带 X-API-Key: <key> 标头（合作伙伴密钥会将合作伙伴的联盟代码 添加到购买链接中）。未设置时，不会发送密钥标头，上游会返回 普通链接。绝不会发送 Authorization 标头。（此转发机制 也是本次重建自行标注的内容；原始功能表面是在不带密钥的情况 下捕获的。）

转发机制

首次调用工具时，客户端会与上游建立可流式传输的 HTTP 会话： 发送 JSON-RPC initialize 请求（protocolVersion 为 2025-03-26，clientInfo 名称为 simscout），然后发送 notifications/initialized 通知，再发送携带调用方原样参数的 tools/call 请求。当上游在 initialize 响应中返回 Mcp-Session-Id 标头时，该值会随此会话的每个后续请求发送， 并在进程运行期间重复使用。响应可能是普通 JSON，也可能是 服务器发送事件；两种格式都会读取。

上游的成功结果会原样传递，包括上游设置的任何 isError 标记。 失败情况——JSON-RPC 错误、非 2xx 状态、无法读取的响应，或 无法完成的请求——会作为 isError 结果返回，文本以 simscout error: 开头（此错误呈现方式是本次重建自行标注的 内容）。

命令行界面

每个工具也可以作为子命令调用，并接受一个 JSON 参数字符串 （不需要参数的工具可省略）：

npx @reneturcios/simscout search_esims '{"country":"JP","days":7,"sort":"price"}'
npx @reneturcios/simscout get_esim '{"id":"plan-9"}'
npx @reneturcios/simscout compare_esims '{"ids":["plan-9","plan-11"]}'
npx @reneturcios/simscout list_countries '{"query":"Japan"}'
npx @reneturcios/simscout --version

退出代码：成功时为 0，结果为 isError 时为 1，用法错误时 为 2。

MCP 服务

npx -y @reneturcios/simscout mcp

MCP 客户端配置：

{
  "mcpServers": {
    "simscout": {
      "command": "npx",
      "args": ["-y", "@reneturcios/simscout", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/simscout
docker run --rm ghcr.io/cloudcorprecords/simscout --version

容器的默认命令是 mcp，因此第一种形式是 stdio MCP 服务；其他任何参数都会照常传递给 CLI。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全针对存根 JSON-RPC 上游运行，不会进行实时网络调用。

许可证

MIT — 参见 LICENSE。