supercarto

supercarto

mcp-name: io.github.Unselfisheologism/supercarto

原生适配大模型的空间中间件。 将地理空间数据编译为符合 token 预算的拓扑图，让 AI Agent 能够直接推理。

为 Agent 提供地图，无需付出 token 成本。输入一个文件，输出两组数字：examples/synthetic-dense.geojson 的原始大小为 272,993 字节（约 68,000 个 token），在 1024-token 预算下编译后约为 890 个 token——26 个节点（其中 10 个有名称）和 34 条边（街道及通行连接），体积缩小约 99%。 亲自运行：supercarto compile examples/synthetic-dense.geojson --budget 1024。token 数量是根据固定测试文件按字符估算的；太阳和时间戳行会导致每次运行相差几个 token。

npm install supercarto
pip install supercarto      # Python client, talks MCP over stdio

---

提供坐标

这就是完整的产品：

import { SuperCarto } from 'supercarto';

const carto = new SuperCarto();

const result = await carto.maplet({
  lat: 35.6833,
  lon: 139.7620,
  radiusM: 400,
  budget: 1500,
});

console.log(result.yaml);

下面是标题中同一个文件的编译结果（输出已截断； 警告会随地图一同传递，因此只读取地图的 Agent 也能看到警告）：

map:
  center: "37.7749, -122.4194"
  source: geojson
  note: Simplified for reasoning; call expand_feature for exact geometry.
nodes:
  n530: {type: poi, name: Bank 0, tags: [bank]}
  n531: {type: poi, name: Cafe 1, tags: [cafe]}
  n673: {type: transit, name: Station 0, tags: [subway_entrance]}
edges:
  n515->n516: {dist: 80m, dir: east, path: road}
  n516->n517: {dist: 80m, dir: east, path: road}
omitted:
  - {layer: building, count: 259}
  - {layer: poi, count: 141}
  - {layer: road, count: 441}
tools:
  - expand_feature(id)

整个摘录约为 890 个 token，符合 1024-token 预算：每滴水都按图层命名，没有任何内容悄然消失。

---

问题

你希望 Agent 知道事物的位置，以及如何在它们之间通行。有三种选择，都不好：

• 将 GeoJSON 粘贴到提示词中。 每个数据块就要数千个 token。模型难以根据原始坐标进行推理，还会产生幻觉。
• 调用地图 API。 返回的还是同样的 GeoJSON。token 成本没有变化，只是多了一次 HTTP 往返。
• 发明一种紧凑的传输格式，并教模型读取它。 在上下文窗口中使用新语法，会导致坐标幻觉，还会浪费 token 来推断语法。模型并未接受过你的格式训练。

supercarto 认真对待第三种选择，并以唯一可行的方式解决问题：模型永远不会读取传输格式。

  coordinates          live sources             reasoning format
  35.68, 139.76  ──▶  Overpass / PMTiles  ──▶  topological YAML graph
                                           distances in metres,
                                           compass directions,
                                           built for models

传输格式是你拥有的、针对机器优化的规范。推理格式则是标准的流式 YAML，只使用模型读过数十亿次的结构。中间件中的确定性编译器负责转换。

---

Agent 为人服务

人正站在室外。天气和交通状况会影响行程是否成行，因此它们在这里是一级图层，而不是后来附加到路由引擎上的功能。

天气

无需 API 密钥。无需账户。无需付费。

const w = await carto.weatherAt(35.6833, 139.7620, 12);

w.now.summary;          // "heavy rain"
w.now.precipitation;    // "rain" | "snow" | "sleet" | "hail" | "drizzle"
w.now.feelsLikeC;       // what they actually feel

$ supercarto weather --lat 35.6833 --lon 139.762
now  clear night, 23.2C (feels 26.9C), wind 4.3km/h, precip none
  2026-10-01T13:00:00Z  22.7C  none      3.5km/h
  2026-10-01T14:00:00Z  22.1C  none      3.1km/h

MCP 工具返回的是描述性文本，而不是字段，因为模型能可靠地复述“正在下雨，坐公交吧”，却很难可靠地根据十二个数字重新推导出这句话。

当数据源无法访问时，它会为每项读数返回 NaN 并设置 degraded，同时由工具抛出错误。它不会返回零值。如果 Agent 收到 precipitationMm: 0，就会认定天气干燥，让人骑车冲进暴风雨。

交通

const t = await carto.routeWithTraffic({ from, to, mode: 'drive' });

t.freeFlowOnly;   // true when no flow credential is configured
t.worstLevel;     // "severe" - the segment that makes someone late
t.delayS;

交通数据需要凭据，因此只有在设置凭据后，get_traffic 才会出现在工具列表中。没有密钥时，路由流程会报告畅通状态，并注明：

$ supercarto traffic --from 37.7749,-122.4194 --to 37.7849,-122.4194
traffic: unknown (no flow source configured)
free-flow estimate: 244s, ignores congestion
note: set TOMTOM_API_KEY or HERE_API_KEY for live conditions

拥堵路线却估算为畅通，比不给答案更糟，因为人会按 Agent 告知的时间出发。把这种估算说成实时路况，是这个库可能造成的最大危害，因此它不会这么做。

设置 TOMTOM_API_KEY 或 HERE_API_KEY 后，交通数据就会变为实时数据，并报告最拥堵的路段，而非平均路况。

室内楼层

没有其他人发布这类数据。Google 为自己的用户构建室内地图，没有理由把整洁的逐层图结构交给第三方 Agent；Mapbox 没有可比的数据；每个 MCP 包装器返回的都是相同的扁平 GeoJSON。

indoor:
  storeys: 0,1,2
  multi_storey: true
  0: {label: ground, rooms: 12}
    L0n1: {type: corridor}
    L0n2: {type: shop, name: "Blue Bottle"}
    L0n1->L0n2: {dist: 11m}
  v1: {type: lift, levels: [0,1,2], wheelchair: true}
  missing: [1]

电梯会跨楼层合并为一个垂直连接。房间只会连接到同一楼层的走廊——穿过混凝土楼板的边会让人穿过楼层。距离任何走廊超过 40m 的房间会保持未连接状态，因为一条穿过中间墙壁的直线，还不如没有边。未标注的楼层会报告为 missing，而不是凭空编造。

公共交通时刻表

将 SUPERCARTO_GTFS 设置为任意静态 GTFS 数据源（解压后的目录或 .zip），就会出现 get_transit：站点、线路，以及查询日期的运营时段。这是唯一一个能根据实际时刻表回答“能否在 9 点前到达某地”的 Agent 地图工具，并且每种运营方数据异常情况都会通过如实的状态来说明，而不是猜测：

transit:
  center: "36.913, -116.77"
  radius: 3.0km
  feed: sample-feed
  note: Stop distances are straight-line. Schedule from GTFS feed for 2007-01-11 in America/Los_Angeles.
nodes:
  STAGECOACH: {type: stop, name: "Stagecoach Hotel & Casino", tags: [bus], routes: ["30", "40"], first: 06:00, last: 06:58}
  NADAV: {type: stop, name: "North Ave / D Ave N", tags: [bus], routes: ["40"], first: 06:14, last: 06:44}
edges:
  NADAV->DADAN: {dist: 601m, dir: south, path: bus 40}

• 三种服务状态，从不简化成两种。 当天有运营时会显示路线和首末班车。当天没有任何班次时，仍会保留站点，并显示 routes: []——没有公共交通不代表没有站点——备注也会说明这一点。数据源没有运营日历时，会显示整个网络，并说明运营时段未知，而不是把全量数据伪装成当天时刻表。
• 午夜后的时间仍显示为午夜之后。 GTFS 会用超过 24 的小时数（25:10）表示超过运营日午夜的发车时间。显示成 01:10 看起来更直观，却会误导决策，因此会按数据源记录的时间原样显示，并采用数据源自己的时区。
• 边表示结构；时刻表附加到节点。 即使当天没有运营，相邻关系仍会保留，因为 Agent 在站点之间步行时仍需要这些信息。
• 指定 GTFS-Realtime 后即可显示实时延误。 将 SUPERCARTO_GTFS_RT 设置为运营方的 TripUpdates URL，预测信息就会合并到时刻表中：节点线路会增加 live: 属性，例如 bus 16 +300s 或 bus 16 cancelled，备注会说明数据源的新鲜度。遵循规范的优先级规则——明确的站点更新优先于行程级延误；绝对时间预测会根据数据源时区进行转换。最重要的如实说明规则是：没有实时条目的站点表示未知，而不是准点，备注会明确说明。若数据源无法读取（404、超时、格式错误），则会退回到纯时刻表结果，并附上一句说明，绝不会悄无声息地丢弃。
• 显示下一班车，而不只是当天的运营时段。 每个节点的 next: 属性会列出该站点即将发车的班次，按数据源的时间顺序和时钟显示（tram 9 25:10 仍会显示在午夜之后），最多列出三班，并统计隐藏的其余班次（+2 more）。配置实时数据源后，站牌会直接显示预测信息——bus 16 07:05 +300s 或 cancelled——而 live: 列表会省略站牌已显示的内容，避免重复。当当天末班车已经发出时，备注会说明当天运营已结束，避免空白站牌看起来像数据源故障。
• 提供两个坐标之间经过认证的乘车方案。 get_transit_route 会先步行到站点，乘坐一条服务于两端覆盖范围的线路，再步行离站——所有直线步行路段都会明确标注，绝不虚构数据源无法证明的换乘。方案遵循发车站牌的如实原则：根据运营日期进行认证，预测信息会标注到对应班次，已取消的班次会被剔除并在备注中计数；若无法认证任何方案，备注会指出失败的路段。
• 明确信号。 发车时间、时刻表日期和数据源时区都会放在 note 中，让只读取地图的模型也能看到这些信息。

---

预算就是真实预算

大多数面向 Agent 的地图代码只是截断内容，然后寄希望于结果正确。supercarto 将截断视为正确性问题：

• 排序。 有名称的地标会保留；无名路口最先被删减。
• 连通性。 不会删除割点，因此保留下来的网络仍然连通。Agent 能遍历地图却无法连通各处，远不如地图更小但能派上用场。
• 不遗留无法抵达的名称。 如果 Agent 能看到某个地标，却无法规划路线抵达，就会将其移除。否则 Agent 会信心满满地试图走到那里。
• 验证。 emitAndVerify 会重新测量实际输出的 YAML，并反复删减，直到符合限制。报告的预算就是实际交付的预算，而不是估算值。
• 如实记录。 每次删减都会记录在 omitted: 中，并按图层汇总，让模型能区分「不存在」和「未显示」。

---

基准测试

现在已独立存放在自己的仓库中： supercarto-bench。

同一个问题、同一个模型、同一张地图——唯一的变量是上下文窗口中的内容：编译后的图、原始 GeoJSON，或什么都没有。原始运行结果、冻结的测试地图和评分代码都放在那里，因此任何开发竞品地图工具的人都可以运行相同的测试，尝试超越当前分数。

该仓库目前的核心结果：在两个 AI 模型上，精简图为 9/9，原始数据约为 4/9，没有地图则为 0/9。路线问题无法衡量（公开测试路由器给出的答案不可能实现），因此 route 被降级为可行性答复：直线距离、罗盘方向，然后提示「抵达后确认接近路线」。逐向导航需要自行托管并验证路由器；OSRM 可选，不是默认方案。所有这些都明确说明，不作隐瞒。

现在，分数附带专属复现方案（scoreC certificate，从原始答案存档重新推导，不调用模型）、按模型划分的排行榜，以及适配器测试组：竞品工具只需注册一个 { name, prepare } 模块，就能使用相同的任务、模型和通过规则。当前证书结果：所有存档运行合计为 supercarto 38/47 · geojson 15/44 · none 0/47。

• 实时证书 — 所有数字都可根据已提交的存档重新推导，无需调用模型。
• 实时排行榜 — 按模型和测试组划分，包含你可以自行运行的免费模型。

此仓库保留的是快速令牌成本检查：

npx supercarto bench <file.geojson>

---

数据源

来源	状态	用途
Overpass	默认	开发。每次调用需 15-40 秒，且有速率限制。
PMTiles / Protomaps	SUPERCARTO_PMTILES	**生产环境。**通过对象存储发起范围请求，耗时仅几毫秒，且没有速率限制。
OSRM	默认	提供逐向导航，支持步行／骑行／驾车。
Open-Meteo	默认	天气。无需密钥。
TomTom / HERE	需要密钥	实时交通状况。
Terrarium tiles	默认	海拔和坡度。无需密钥。
GTFS feeds	SUPERCARTO_GTFS	公交站、线路和时刻表。可使用任意静态数据源，无需密钥。实时延误通过 SUPERCARTO_GTFS_RT 指定的 GTFS-Realtime TripUpdates URL 合并。

export SUPERCARTO_PMTILES=https://your-bucket/planet.pmtiles

在生产规模下，PMTiles 是理想选择。它已包含读取器——无需 pmtiles 依赖，也不需要 mapbox-gl，没有任何传递依赖包。

所有数据都由一个工厂从环境中读取，因此 CLI 和 MCP 服务对数据来源的认知不会产生分歧。它们曾经出现过分歧，但没有任何提示。

SUPERCARTO_PMTILES      PMTiles archive URL; primary source when set
OVERPASS_ENDPOINT       your own Overpass instance
TERRARIUM_ENDPOINT      elevation tile template
TOMTOM_API_KEY          enables get_traffic
HERE_API_KEY            enables get_traffic
SUPERCARTO_NO_TERRAIN   disable elevation
SUPERCARTO_NO_WEATHER   disable weather
SUPERCARTO_GTFS         path to a GTFS feed (dir or .zip); enables get_transit
SUPERCARTO_GTFS_RT      TripUpdates URL; adds live delay lines to get_transit

整个都市区的数据源会完整加载到内存中。从 0.6.1 版起，加载采用 列式存储——stop_times 直接存入每个行程的数组，不创建行对象——因此 Translink SEQ 那么大的数据源（35 MB zip）也能放进 Node 的默认堆内存， 而且答案与 0.6.1 之前的构建逐字节一致。已在该规模下实时验证：时刻表、出发信息板和 750 多条实时预测可合并在同一答案中，无需设置任何 NODE_OPTIONS。更大的数据源会按照其膨胀后的实际大小占用内存；运行时请为这类任务设置 NODE_OPTIONS=--max-old-space-size=4096。

---

Agent 集成

Claude Desktop（一键安装）

每个版本都会附带 supercarto-X.Y.Z.mcpb——一个 MCPB bundle： 从最新版本下载， 用 Claude Desktop 打开，即可一键安装地图工具。 安装时可选择配置：用于提高天气查询限额的 Open-Meteo 密钥，以及用于交通工具的本地 GTFS 数据源路径（以及运营方的 TripUpdates URL）。唯一要求是 Node ≥ 18；bundle 内含服务端，而它没有任何 npm 依赖，因此大小只有半兆字节。

MCP

{
  "mcpServers": {
    "supercarto": { "command": "npx", "args": ["supercarto", "mcp"] }
  }
}

提供七种工具：get_maplet、route、search_places、expand_feature、 get_daylight、get_terrain、get_weather；有密钥时还提供 get_traffic， 配置了 GTFS 数据源时还提供 get_transit 和 get_transit_route。每个 maplet 都会列出该部署能够响应的确切工具，因此 Agent 不会调用无法使用的工具。get_daylight 始终可用：太阳位置可通过计算得出，无需数据源或凭据。

maplet 如何描述地点

除了拓扑和距离，节点还可以携带决定一次出行是否值得的事实：

n3: {type: poi, name: Blue Bottle, tags: [cafe], hours: 07:00-18:00, brand: Blue Bottle}
n4: {type: poi, name: Central Rx, tags: [pharmacy], hours: 09:00-17:00}
map:
  sun: up, elevation: 43.4deg, twilight: day, azimuth: 22deg, sunrise: "..."

上面两家商店在当地时间 12:00 时都营业。同样的两家店在 04:00 时显示 hours: closed，因为它们的营业时间已知，而且当时关门了。没有记录营业时间的长椅则完全不输出 hours 字段。

hours 会根据某个时刻计算，并使用地图所在的时区，而非服务端的时区。它有三种状态，而非两种：时间范围、closed，或因无人记录而缺省。缺省状态刻意不等于 closed——二者会导向截然相反的建议：前者表示可以去看看，后者表示应去别处。

twilight 的值为 day、civil、nautical 或 night，而非布尔值， 因为这几种状态会导向不同的决策：民用暮光时适合步行，航海暮光时则不宜步行。在夏季和冬季的北极圈以北，地图会报告 polar: day 或 polar: night，而不会凭空编造日出时间。

传入 compile.utcOffsetMinutes 和 compile.now，即可将二者固定到已知地点和时刻，测试中也是这样做的。

Python

import asyncio
from supercarto import SuperCarto

async def main():
    async with SuperCarto() as carto:
        m = await carto.maplet(lat=35.6833, lon=139.7620, radius_m=400, budget=1500)
        print(m.yaml)
        w = await carto.weather(lat=35.6833, lon=139.7620)

asyncio.run(main())

零运行时依赖。它通过标准输入/输出与 Node 服务通信并传输 JSON-RPC，而不是导入 SDK；这是因为 mcp 包会引入 httpx 和 pydantic，而已经依赖其中一个的 Agent 框架不应再引入另一份副本。

HTTP

curl 'localhost:8787/maplet?lat=35.6833&lon=139.762&radiusM=400&budget=1500&format=yaml'

托管模式（已部署）

编译路径兼容 Workers（基于 fetch 的数据源，不使用 Node 内置模块），cloud/worker/ 会将其打包为 Cloudflare Worker：提供与上方本地 HTTP API 相同的 /maplet、/scr、天气、日照和地形功能，并对每个 IP 限流，且在每个地图响应中注明 ODbL 归属。此模式有意仅提供部分功能——不提供交通运输和交通流量，因为 Worker 没有用于 GTFS 数据源的文件系统，且托管模式不提供流量数据提供商的密钥；GET / 会明确说明这一点。请参阅 cloud/worker/README.md。

已部署至 https://supercarto-compile.jeffrinjames99.workers.dev。`/maplet` 和 /scr 的数据源链：首先尝试实时 Overpass，然后使用托管的 OpenStreetMap 底图 PMTiles 星球数据构建版本——所有已知的公共 Overpass 实例都会拒绝共享的 Cloudflare 出口 IP 段（HTTP 521），因此托管地图块实际上由回退数据源提供。该归档在 z10 左右以上的细节较为粗略，且部署会限制请求获取的地图块和要素数量，以确保星球数据地图块处于 Worker CPU 预算范围内；截断情况会作为警告写入文档，如果由回退数据源提供，source: 行会显示 protomaps。天气、日照和限流功能正常运行；地形会如实返回 503（Terrarium 地图块采用 PNG 编码，内置的零依赖解码器仅读取原始 Terrarium 缓冲区）；由于 GET / 中所列原因，不提供交通运输和交通流量。GET /healthz 仅探测 Overpass，因此该端点返回 503 表示 Overpass 链路不可达，并不代表 PMTiles 回退数据源已停止运行。

---

CLI

supercarto fetch --lat 35.6833 --lon 139.762 --radiusM 400 --budget 1500 --metrics
supercarto weather --lat 35.6833 --lon 139.762 --hours 12
supercarto traffic --from 37.7749,-122.4194 --to 37.7849,-122.4194
supercarto transit --feed city-gtfs.zip --lat 36.913 --lon -116.77 --radiusM 3000
supercarto route --from 37.7749,-122.4194 --to 37.7849,-122.4194 --mode walk
supercarto mcp
supercarto serve --port 8787
supercarto compile city.geojson --budget 1024 --metrics
supercarto encode city.geojson --out city.scr
supercarto decode city.scr
supercarto bench city.geojson

fetch 图层除原始 OSM 标签外，还接受 road 和 poi；其他值都会被拒绝，而不是静默返回空结果。如果请求会返回有名称的地点，却不包含街道，则会明确报错，而不是生成误导性的地图——仅需 POI 地图时，请传入 --layers poi。警告会写入地图输出，而不只是输出到 stderr，因此 Agent 也能看到。

---

准确性

通过中高纬度地区的 haversine 真值验证距离：

• 旧金山（37.77°N）误差为 0.11%
• 奥斯陆（59.91°N）误差为 0.11%

这需要正确处理 Web Mercator 比例校正：Mercator 距离在两个轴上都比地面距离大 1/cos(latitude)；如果符号弄错，中纬度地区会产生 26% 的误差，并且误差会向两极不断累积。对于非正方形边界框，使用平均各向同性比例也不正确，因此比例会按轴分别应用。

基准测试任务集特意覆盖从北纬 64°到南纬 33°的范围。仅在北纬 37°进行基准测试只能测出一种情况，会掩盖向两极延伸时出现的所有符号错误。

---

状态

461 项测试全部通过：328 项单元测试（包括 GTFS transit 层的 42 项、protobuf wire 和 TripUpdates schema 的 14 项、实时叠加层连接的 5 项，以及 PNG 高程解码器的 7 项）、针对实时数据源的 121 项测试，以及 12 项 MCP 端到端测试。 输出与 Python 移植版逐字节一致——每次推送都会运行一致性引擎。已通过实时 OpenStreetMap、实时 Open-Meteo，以及由 Python 驱动的实时 MCP 服务验证。

已实现：SCR 编解码器（文本和二进制、增量几何、环组、三种热度编码、省略、路线、引用），带逐轴比例校正的 Web Mercator、Visvalingam-Whyatt 简化、带 OSM 分类的 GeoJSON 导入、带路口焊接和地标附加的拓扑编译、带连通性保障的令牌预算、YAML 输出、带垂直通行结构的室内楼层图、地点密度热力图、实时 Overpass、内置 MVT 解码器的 PMTiles、路由降级为可行性判断（默认使用直线距离和方向；对于已验证的引擎，可选择启用 OSRM 转向导航——公开演示路由器会返回不可能的距离）、无需密钥的天气功能，数据降级时拒绝编造读数、提供真实自由流量回退方案的交通功能、地形高程和坡度、具有三种真实服务状态的 GTFS 班次、将 GTFS-Realtime 行程更新关联到这些班次，并采用未知即非准点的语义、基于 stdio 的 MCP、HTTP API、CLI、Python 客户端，以及使用 OSRM 真实值的任务级基准测试。

尚未实现：提供样式交付的托管矢量切片，以及超出质心范围的完整室内房间几何。

---

许可证

Apache-2.0