terrainprofile

terrainprofile

terrainprofile 是一个小型本地桥接服务，用于连接托管的 Geospatial System 位置剖面 MCP 服务，该服务从全球和区域 DEM （数字高程模型）数据集中读取高程数据。提供纬度、 经度和数据集 ID，即可查询该点的高程、周边小窗口内的高程和坡度统计数据、 范围箱线图、组合地形图，或该位置的 3D 透视地表图。

该桥接服务本身不存储任何地形数据。它会在本地提供上游服务的工具列表， 内容与从在线端点捕获的内容完全一致，并将每次工具调用转发至上游，原样返回结果。 捕获的接口仅提供只读地形数据：其中没有写入、购买或账户相关工具。

工具

• list_datasets — 列出服务器上所有可用的高程 数据集。不接受参数；先调用此工具以获取 dataset_id。
• LP_Get_Elevation — 获取单个坐标点的高程，单位为米。必需参数：lat、lon、dataset_id。 所有套餐均可使用，包括 Free。
• LP_Get_Elevation_Batch — 单次调用获取最多 100 个点的高程。必需参数：queries，即包含 lat、lon 和 dataset_id 的对象列表。 所有套餐均可使用，包括 Free。
• LP_Get_Elevation_Stats — 获取以坐标为中心的 3×3、5×5 和 7×7 像素窗口内的高程统计数据 （最小值、平均值、最大值）。必需参数：lat、lon、 dataset_id。需要 Pro 或 Enterprise 密钥。
• LP_Get_Slope_Stats — 获取相同窗口尺寸内的地形坡度统计数据 （最小值、平均值、最大值），单位为度，并经过 WGS-84 校正。必需参数：lat、lon、 dataset_id。需要 Pro 密钥。
• LP_Get_Elevation_Chart — 返回高程范围箱线图的 URL，图中展示 三种窗口尺寸下的最小值、平均值和最大值。必需参数： lat、lon、dataset_id。可选参数：fmt （默认为 "png"，也可以是 "svg" 或 "pdf"）。 需要 Pro 密钥。
• LP_Get_Slope_Chart — 返回地形坡度范围箱线图。必需参数：lat、lon、dataset_id。 可选参数：fmt（默认为 "png"）。需要 Pro 密钥。
• LP_Get_Terrain_Map — 组合地形图：卫星影像加平滑并带有标注的等高线、 水流方向箭头和位置标记，所有内容均采用 EPSG:3857。必需参数：lat、lon、dataset_id。 可选参数：offset（半窗口像素数，默认为 20）、 n_arrows（水流箭头网格密度，默认为 11）， 以及 fmt（默认为 "png"）。需要 Pro 密钥。
• LP_Get_Terrain_3D — 3D 透视地形表面图，按高程着色，并用红色图钉标记 查询位置。必需参数：lat、lon、dataset_id。可选参数：offset（默认为 20）、 elev_angle（相机仰角，默认为 45）、 azim_angle（相机方位角，默认为 135），以及 fmt（默认为 "png"，也可以是 "html"）。 需要 Pro 密钥。

坐标采用 WGS-84 十进制度数。

配置

• GEOSPATIAL_MCP_URL（可选）— 覆盖 上游端点。默认为 https://api.geospatialsystem.com/mcp。（此覆盖 钩子是本次重建自行添加并标注的内容。）
• GEOSPATIAL_API_KEY（可选）— 设置后，每个 上游请求都会携带 Authorization: Bearer <key> 请求头，使用调用者自己的 Geospatial System 密钥。原始服务器的注册记录声明需要 Authorization 密钥请求头；Bearer 方案以及从此环境变量进行的转发均为 标注的重建内容，因为原始接口是在未提供密钥的情况下捕获的。未设置此变量时， 不会发送密钥请求头。

转发机制

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

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

CLI

每个工具也都是一个子命令，接收一个 JSON 参数 字符串：

npx @reneturcios/terrainprofile list_datasets
npx @reneturcios/terrainprofile LP_Get_Elevation '{"lat":37.7749,"lon":-122.4194,"dataset_id":"<id from list_datasets>"}'
npx @reneturcios/terrainprofile LP_Get_Elevation_Batch '{"queries":[{"lat":37.7749,"lon":-122.4194,"dataset_id":"<id>"}]}'
npx @reneturcios/terrainprofile LP_Get_Terrain_3D '{"lat":37.7749,"lon":-122.4194,"dataset_id":"<id>","fmt":"html"}'
npx @reneturcios/terrainprofile --version

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

MCP 服务

npx -y @reneturcios/terrainprofile mcp

MCP 客户端配置：

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

Docker

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

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

开发

npm install
npm run build
npm test
npm run dev

测试套件完全基于桩化的 JSON-RPC 上游运行，不会进行实时网络调用。

许可证

MIT — 参见 LICENSE。