GeoLibre 无界面制图指南:用 .geolibre.json 项目文件与 MCP 工具链生成可分享的交互式地图【免费下载链接】GeoLibreA lightweight, cloud-native GIS platform for visualizing, exploring, and analyzing geospatial data. It runs in the web browser, on the desktop, on mobile, and inside Jupyter notebooks.项目地址: https://gitcode.com/GitHub_Trending/ge/GeoLibreGeoLibre 把做一张图收敛为写一个文件:.geolibre.json项目文件同时是桌面应用、浏览器应用和 Jupyter 组件的唯一数据面,Agent 无需驱动任何 UI,只要按固定工作流生成该文件(或由其导出的独立 HTML),就能得到三端一致渲染的交互式地图。本文基于仓库内的 Agent 技能文档 SKILL.md 及其四份参考资料,结合geolibre-mcp服务器与geolibrePython 包的真实源码,完整讲解入口选择、MCP 工作区沙箱、六步制图工作流、常见失败规则与验证方法,读完即可在 Agent 会话、脚本或 Notebook 中稳定产出可双击打开的地图交付物。核心理念:项目文件就是全部的 Agent 表面GeoLibre 是一个云原生 GIS 平台,同一份可移植项目文件驱动三种宿主:Tauri 桌面应用、浏览器应用,以及 Jupyter 组件。一个项目里保存了:相机状态(center / zoom / bearing / pitch);底图(basemap);有序图层列表(自底向上绘制);每图层的样式;地图控件(图例 legend、色条 colorbar、擦除对比 swipe)。任何宿主打开任何项目,渲染结果一致。因此不需要驱动 UI 就能做出 GeoLibre 地图——写对项目文件,它在桌面应用、托管 Web 查看器(web.geolibre.app)和 Notebook 单元格里是同一张图。技能文档明确给出这一判断:该文件是全部的 Agent 表面(the whole agent surface)。这一点在源码层面可以得到印证。MCP 服务器模块的 模块 docstring 写道:每个工具都读取一个.geolibre.json文件、通过geolibre.authoring施加一次修改、再写回磁盘,盘上的项目就是唯一状态(the project on disk is the only state)——服务器本身不需要浏览器、不需要运行中的应用、不需要打包的 Web 构建产物,它的产物就是用户可以打开的项目文件或从项目导出的独立 HTML 页面。选择入口:先判断场景,再决定用什么写项目SKILL 文档的第一张决策表值得原样继承。同一个目标(一张图)有六种写法,选错入口是低效的根源:场景使用原因聊天或 Agent 会话,无浏览器、无 Notebookgeolibre-mcp(MCP 服务器)专为该场景设计,写真实的项目文件和独立 HTML,从这里开始MCP 不可用 / 脚本 / 批量生成geolibrePython 包geolibre.Map无头构建同样的项目;m.save_project()/m.to_html()Jupyter 或 Colab NotebookgeolibrePython 包同一套 API,但完整应用渲染在单元格里,状态双向同步什么都没装,只需要一个文件手写 JSONschema 小且宽容,见 references/project-json.md自己控制的网页里已运行着一个 GeoLibre 实例geolibre/embed URL 参数对一个运行中的实例做实时控制,见 references/catalog.md用户在应用内部想要聊天面板应用内置的AI Assistant不是你该管的——它通过应用自身的 store 操作,编辑可撤销要修改 GeoLibre 本身仓库,而不是本技能见 CLAUDE.md两条边界要记牢:MCP 服务器只负责写项目,不驱动实时地图——不存在平移我屏幕上那张图这类工具,那是 embed API 或 Python 组件的职责;而应用内置 AI Assistant 与外部 Agent 是两回事,前者通过应用 store 工作,编辑天然可撤销。MCP 服务器安装与--root工作区沙箱安装与注册pip install geolibre[mcp] claude mcp add geolibre -- geolibre-mcp --root ~/maps其他 MCP 客户端采用常见的mcpServers形状(command: geolibre-mcp,args: [--root, /path/to/maps])。如果客户端PATH里找不到geolibre-mcp控制台脚本,直接用解释器启动:/path/to/venv/bin/python -m geolibre.mcp。--root可重复传入,环境变量GEOLIBRE_MCP_ROOTS等价。每一次工具调用中的每个路径都被限制在这些根目录之内——根外的路径会被拒绝,逃逸出的符号链接同样被拒绝。技能文档特别提醒:把根指向一个为地图准备的目录,而不是家目录。从源码看沙箱是怎么实现的沙箱逻辑集中在 workspace.py,值得展开三个细节:白名单解析。Workspace类(见 L34-L65)构造时把每个根做expanduser()resolve(),根不存在、不是目录、或配置为空都会在启动时报错——启动时失败,好过之后每次调用都被拒、原因客户端还看不见。相对路径统一按第一个根解析,所以客户端可以只说maps/city.geolibre.json而无需知道宿主机布局。写后缀白名单。服务器只允许写两种后缀(见 L24-L27):项目文件.json/.geolibre.json,导出文件.html/.htm。裸.json之外的任何东西都会被拒,防止一个错误路径覆盖源码或点文件。传输方式可选。入口函数main()支持--transport参数,取值stdio(默认,桌面客户端拉起的模式)、streamable-http、sse(见 L1237-L1242)。此外,工作区级规则还包括:读单个项目文件上限256 MB;已存在的文件不带overwriteTrue绝不替换;远程拉取拒绝任何解析到私有、回环或链路本地地址的主机,且在每一个重定向跳上都检查——这是保护运行服务器那台机器自己的 SSRF 防线,不要试图绕过。create_project的防误删保护overwriteTrue的语义是替换那里面的项目,不是替换那里面的任何东西。服务器用两个键mapView和basemapStyleUrl(PROJECT_MARKERS,见 L82-L101)识别这是一个 GeoLibre 项目:即使传了overwriteTrue,指向一个不认识的 JSON(比如根目录里恰好有一个package.json)也会被拒绝。create_project 的实现 还保证初始zoom与后续set_view一样被夹到 [0, 24] 区间。六步制图工作流技能文档把工作流压缩为六步,大多数地图用其中四步。1.create_project——永远第一步给它一个以.geolibre.json结尾的path、一个name,以及(如果知道的话)center([lng, lat])与zoom(经验值:0 世界,~4 国家,~10 都会区,~14 城市)。2. 加图层——一次add_*_layer对应一个数据集,自底向上按数据是什么选工具,而不是按你想看到什么选。references/mcp-tools.md 的选型表:你手里有工具备注GeoJSON URL / 文件 / 字面量add_geojson_layer内联进项目,自包含;唯一能被classify_layer做分级的类型;上限 50 MB大的远程 FlatGeobuf / GeoParquet / GeoJSONadd_vector_layer就地读取,不拷贝;项目文件里没有属性表Cloud Optimized GeoTIFF (COG)add_raster_layerbands、colormap、rescaleXYZ 栅格瓦片模板({z}/{x}/{y}.png)add_tile_layerOSM 这类底图走这里,不是set_basemapPMTiles 归档或矢量瓦片服务add_tiles_layerkindpmtiles(配tile_type)或kindvector-tilesWMS 或 WMTS 端点add_ogc_layerservicewms或wmtsOGC 3D Tiles 场景add_3d_tiles_layeraltitude_offset落地;Cesium Ion 场景用ion_asset_id替代urlCesium Ion 资产(场景或影像)add_cesium_ion_layer仅 3D 球:配合set_renderer/primaryRenderer: cesium;影像用kindimageryCZML 动态场景(轨道、轨迹、运动模型)add_czml_layer仅 3D 球;url指向.czml文档,或data内联包数组;球体跟随文档clock原生 KML/KMZ(带文档样式)add_cesium_kml_layer仅 3D 球;url、内联 XML 或 KMZ data URL;共享时把本地图标打包进 KMZShapefile / GeoPackage / KML / CSV先转换用 GeoPandas 读出后把 GeoJSON 传给add_geojson_layer,或用 Python API 的Map.add_shp/Map.add_gpkg/Map.add_kml/Map.add_csv图层自底向上绘制;每个add_*都接受可选index(绘制顺序位置),省略则置顶。关键参数细节(来自工具签名说明):add_geojson_layer(data...)接受http(s)URL、工作区内文件路径、或字面 GeoJSON 对象;数据在edit上下文内加载,即目标文件先通过全部检查(沙箱、后缀、是否真是项目)之后,才付出 50 MB 的读取/抓取成本(见 L421-L434)。add_raster_layer:bands是1 基索引([1]单波段,[1, 2, 3]RGB);rescale是每波段一对[min, max]([[0, 3000]])。COG URL 必须公开可读且启用 CORS——浏览器直接抓瓦片。add_ogc_layer:servicewms时layers必填;version默认1.1.1,与服务器宣告不符时显式传入;WMTS 的endpoint是完整瓦片 URL 模板;bounds是[west, south, east, north],服务图层没有几何可供推导范围,不给它缩放到图层就没有去处(从能力文档读:WMS 用EX_GeographicBoundingBox,WMTS 用ows:WGS84BoundingBox)。样式键冲突会被显式报错:每个 builder 都把未识别键收进**style,但样式键若撞上了图层 builder 自己的参数名,_build_layer会抛出指名道姓的ValueError(见 L104-L159),而不是静默改变行为。3.set_view取景centerzoom,或bbox适配一个区域。注意bbox只是近似值,原因见下文规则清单。4. 定样式style_layer合并(merge)样式键而不整体替换;classify_layer基于数值列生成分级统计(choropleth)样式。5. 装饰add_legend、add_colorbar、add_swipe(前后对比,__basemap__指底图)。6.export_html交付产出一个自包含单页,接收者无需安装任何东西。只要用户想要能看或能转发的东西,就应当以export_html收尾:一个裸的.geolibre.json是需要 GeoLibre 才能打开的文件,HTML 才是双击就能打开的地图。只有当用户明确要项目文件、或之后还要继续编辑时,才停在项目文件这一步。export_html的源码实现(L1163-L1210)直接调用render_project_html(),返回写入路径、来源项目与字节数;页面内嵌托管的 GeoLibre 查看器并注入项目,凭据在导出时被剥离。完整示例:一张 choropleth 从头到尾create_project(pathcounties.geolibre.json, namePopulation by county, center[-98.5, 39.8], zoom4, basemappositron) add_geojson_layer(path..., nameCounties, datahttps://example.com/counties.geojson) list_layer_properties(path..., layerCounties) # 找真实列名 classify_layer(path..., layerCounties, columnpop_2020, class_count5, colormapblues, schemequantile) add_legend(path..., titlePopulation, legend_dict{Low: #eff6ff, High: #1e3a8a}) export_html(path..., out_pathcounties.html, titlePopulation by county)工具签名速查项目生命周期:create_project(path, nameUntitled Project, centerNone, zoomNone, basemapNone, overwriteFalse) describe_project(path) list_catalog()加图层(完整签名见 references/mcp-tools.md):add_geojson_layer(path, name, data, styleNone, indexNone) add_vector_layer(path, name, url, render_modegeojson, data_formatNone, source_layerNone, styleNone, indexNone) add_raster_layer(path, name, url, bandsNone, colormapNone, rescaleNone, styleNone, indexNone) add_tile_layer(path, name, url, tile_size256, attributionNone, indexNone) add_ogc_layer(path, name, service, endpoint, layersNone, styles, image_formatimage/png, transparentTrue, tile_size256, version1.1.1, boundsNone, indexNone) add_tiles_layer(path, name, url, kindpmtiles, tile_typevector, source_layersNone, styleNone, indexNone) add_3d_tiles_layer(path, name, urlNone, ion_asset_idNone, altitude_offset0, indexNone) add_cesium_ion_layer(path, name, asset_id, kind3d-tiles, altitude_offset0, indexNone) add_czml_layer(path, name, urlNone, dataNone, indexNone) add_cesium_kml_layer(path, name, urlNone, dataNone, indexNone)编辑:update_layer(path, layer, nameNone, visibleNone, opacityNone, indexNone) remove_layer(path, layer) style_layer(path, layer, style) set_layer_popup(path, layer, fieldsNone, clickNone, titleNone, title_expressionNone, body_expressionNone, show_feature_idNone, tooltipNone, mergeFalse) classify_layer(path, layer, column, class_count5, colormapviridis, schemeequal-interval) list_layer_properties(path, layer)取景与装饰:set_renderer(path, renderer, pane_idNone) set_map_layout(path, rows, cols, view_kindsNone, sync_viewTrue) set_view(path, centerNone, zoomNone, bearingNone, pitchNone, bboxNone) set_basemap(path, basemap) add_legend(path, titleNone, legend_dictNone, labelsNone, colorsNone, builtinNone, positionbottom-left, shapesquare) add_colorbar(path, colormapviridis, vmin0.0, vmax1.0, label, units, colorsNone, orientationvertical, positionbottom-right) add_swipe(path, left_layers, right_layers, orientationvertical, position50, control_positiontop-right)常用约定:layer参数处处接受图层id 或显示名;style_layer常用键为fillColor、fillOpacity、strokeColor、strokeWidth、circleRadius、minZoom、maxZoom,栅格另有rasterBrightnessMin/rasterBrightnessMax/rasterSaturation/rasterContrast/rasterHueRotate,颜色是 CSS 字符串;classify_layer把class_count夹到 2–12,scheme取equal-interval(值域均分)或quantile(每级要素数相等);set_view的zoom夹到 0–24;set_basemap接受命名底图或 MapLibre 样式 JSON URL,但 XYZ 栅格底图(OpenStreetMap、Esri 影像)不是底图样式,应add_tile_layer加在index0;add_legend三种给法(legend_dict/labelscolors/builtin预设名如nlcd、esa_worldcover)三选一;add_colorbar要求vmin vmax。真正会咬人的十条规则这是 SKILL 文档中最有实战价值的部分,逐条继承并补充依据:命名底图、色带、图例预设前先调list_catalog。猜名字是最常见的失败原因。list_catalog 实现返回底图名到 URL 的映射、色带名、内置图例预设以及当前工作区根;服务器才是权威。色条控件不渲染list_catalog列出的全部色带。图层符号学(classify_layer)认全部名字,但地图上的色条由 maplibre-gl-components 绘制,其命名色带表区分大小写,且不含blues、greens、oranges、reds、purples、greys、rdylgn、rdylbu、rdbu——这些会静默地按 viridis 画出来。色条必须与这类图层匹配时,改传显式停靠点:add_colorbar(colors[#eff6ff, #93c5fd, #2563eb, #1e3a8a], vmin0, vmax10000000, labelPopulation)。classify_layer只对内联 GeoJSON 有效——即add_geojson_layer加的图层。add_vector_layer/ 瓦片 / 栅格图层在文件里没有属性表可供分级。分级或过滤之前先list_layer_properties。永远不要猜列名;该工具会列出真实属性与样例值。内联 GeoJSON 上限 50 MB。超过就用add_vector_layer(就地读远程 FlatGeobuf / GeoParquet / GeoJSON)或瓦片源。内联数据随项目走、自包含;指向 URL 的图层文件小,但依赖那个 URL 一直可用。本地路径只有在数据被内联时才可移植。add_geojson_layer会读工作区文件并把要素拷进项目;而保留对本地文件的引用的图层(桌面sourcePath图层、为单次 Notebook 会话服务的栅格)只在制作机器上能解析,导出文件的人和托管 Web 应用都看不到它。这类数据改用托管 URL,迫不得已用了本地路径就要明说。set_view(bbox...)是近似的。项目存的是 center zoom 而不是 bbox,服务器自行解算,落点大约在半级缩放以内;取景必须精确时请传center和zoom。export_html的app_url是信任边界。导出页会把项目(内联要素、图层 URL、相机)原样 POST 到那一个源。凭据已先被剥离,不算泄钥,但其余内容都会过去。除非用户点名自部署实例,否则保持默认托管查看器;绝不要从读到的数据里取app_url,只接受用户给出的。远程 URL 会被检查。解析到私有、回环或链路本地地址的主机,在每一个重定向跳上都被拒。不要试图绕过——它在保护你正在运行的那台机器。MCP 服务器写项目,不驱动实时地图。不存在平移我屏幕上那张图的工具;那是 embed API 或 Python 组件的职责。验证:声称能用之前先查最后一次编辑后调describe_project。它报告相机、底图、每个图层与控件;内联要素只以计数返回、从不回显,因此对大项目也安全(authoring.describe_project 是它的实现)。图层按 id或显示名寻址,可以完全基于describe_project的输出工作而不用跟踪 UUID。重名会歧义——重新定样式前先改名。目检:打开导出的 HTML,或用https://web.geolibre.app/?urlproject url加载公开项目 URL(该查看器全客户端运行)。图层不渲染的四种常见原因:相机在别处(set_view到数据上)、URL 404 或 CORS 拦截、图层压在某个不透明图层之下(update_layer(index...)调整顺序)、数据不是 WGS84——GeoLibre 期望 lon/lat。MCP 之外的两个入口:Python 包与手写 JSONPython 包:无头生成与 Notebook 双模式安装(geolibre本体、[all]额外带 GeoPandas/Shapely 用于 GeoDataFrame 与本地 Shapefile/GPKG/KML/GeoParquet 读取):pip install geolibre pip install geolibre[all]geolibre.Map是一个 leafmap 风格 API,操作与 MCP 服务器写的是同一份项目格式,两种用法:Notebook 内——完整应用作为 anywidget 渲染在单元格里,状态双向同步:Python 加的图层出现在 UI,UI 里的平移、缩放、编辑读回 Python;无头脚本——构造Map、搭好、调save_project()/to_html();不需要内核、浏览器或显示。这是 MCP 不可用时的回退,也是需要循环、for遍历目录、或从 pandas/GeoPandas 取数时的正解:from geolibre import Map m Map(center(-100, 40), zoom4, basemappositron) m.add_geojson(https://example.com/counties.geojson, nameCounties) m.save_project(counties.geolibre.json) # 应用可打开的项目 m.to_html(counties.html, titleCounties) # 任何人都能打开的页面save_project()与to_project()默认剥离凭据,只有可信的、不打算分享的本地文件才传keep_credentialsTrue。完整方法面(加数据的add_*全家、无预计算符号学add_choropleth/add_marker/add_heatmap、popup/tooltip、内存 xarray 栅格、相机与图层操作、Map 控件、仅 Notebook 可用的实时交互如fly_to/identify/to_image、往返的to_project/load_project)见 references/python-api.md;其中load_project会校验必填顶层键(version、name、mapView)并对坏项目抛ValueError而非静默失败,因此它兼作手写项目的验证器。手写.geolibre.json:MCP 和 Python 包都不可用时references/project-json.md 的核心结论:必填字段只有三个:version、name、mapView。其余全部有默认值:加载时basemapStyleUrl回落到应用默认、layers回落[]、styles回落{}、图层上未设的样式键各回落自身默认。手写项目因此可以很小——不要去复刻应用写出的约 60 个样式键,那些是被序列化出来的默认值。越界值被夹取、未知或坏值回落到默认,所以手编不会把应用弄到不可用,但可能静默忽略你的意图——用describe_project、geolibre.Map.load_project()或打开文件确认结果。一个最小合法项目:{ version: 0.1.0, name: Cities, mapView: { center: [-100, 40], zoom: 4, bearing: 0, pitch: 0 }, basemapStyleUrl: https://tiles.openfreemap.org/styles/positron, basemapVisible: true, basemapOpacity: 1, layers: [ { id: 8f1c0f6a-1f26-4a1e-9a5f-2b1d3c4e5f60, name: Cities, type: geojson, source: { type: geojson }, visible: true, opacity: 1, style: { circleRadius: 6, fillColor: #ef4444 }, geojson: { type: FeatureCollection, features: [ { type: Feature, geometry: { type: Point, coordinates: [-122.4, 37.8] }, properties: { name: San Francisco } } ] } } ], styles: {}, metadata: {} }id项目内唯一(UUID 是惯例);图层按数组顺序绘制,第一个在底部。坐标是 WGS84 lon/lat,center是[lng, lat]而非[lat, lng]——地图落在西非外海说明这对数写反了;落在南极或地图之外通常是投影坐标没重投影。发布前:剥离凭据(任何离开工作区的文件都应过redactCredentials(project),Share、HTML 导出、embed 快照和Map.save_project()已默认如此)、确认 URL 可达且 CORS 开启(浏览器直抓,curl 能通不代表应用里能通)、本地sourcePath图层不会跟人走。验证:from geolibre import Map; Map().load_project(my.geolibre.json)(坏项目抛ValueError);或 TypeScript 侧geolibre/core的parseProject/serializeProject/createEmptyProject/redactCredentials。目录速查:底图、色带与嵌入参数references/catalog.md 汇总了三份免往返名单(list_catalog仍是权威):命名底图(set_basemap/Map.set_basemap可接受,也可传完整 MapLibre 样式 JSON URL):名称观感liberty默认。全细节 OpenStreetMap 制图bright更浅、更高对比度的通用样式positron灰调——choropleth 或任何数据图层之下的正确选择dark深底,适合亮色数据与夜间页面fiord低饱和蓝灰色带(classify_layer、add_colorbar、Map.add_choropleth、add_raster_layer(colormap...)接受):viridis、plasma、inferno、magma、cividis、turbo、spectral、blues、greens、oranges、reds、purples、terrain、rdylgn、rdylbu、rdbu、coolwarm、jet、greys、gray。经验法则:低到高的量用顺序色(blues、viridis);只有存在有意义中点(零、均值)时才用发散色(rdbu、coolwarm、spectral);高程用terrain;定量分析避开jet——它会发明数据中不存在的边界。分级方案方面,equal-interval适合近似均匀分布,quantile适合人口、收入这类偏斜分布(但各级宽度不等,图例必须标出断点)。图例预设(add_legend(builtin...)):nlcd(NLCD 土地利用,20 类官方色表)、esa_worldcover(ESA WorldCover,11 类);esa、worldcover、esa_world_cover、nlcd_land_cover为可用别名。嵌入与 URL 参数(托管查看器全客户端运行,参数可自由组合,例如?urlprojectmaponlythemedark是干净的嵌入):参数示例效果url?urlhttps://.../project.geolibre.json从公开 URL 加载项目data?datahttps://.../places.geojson直接加载公开 GeoJSON/GeoParquet/PMTiles/COGstyle?stylehttps://.../sample.style.json给data图层应用样式layout?layoutviewerviewer(只读 chrome)或compact(仅图标)maponly?maponly只有地图——无工具条、面板、状态栏toolbar/panels?toolbarnonepanelscollapsed逐项裁剪 chrometheme?themedark强制配色主题locale/lang?langzh设置 UI 语言注意url与data是浏览器去抓取的,目标必须公开或同源——带登录态的 URL 在托管查看器里加载不了,因为 Cookie 不会跨源发送。对运行中实例做程序化控制,用发布到 npm 的类型化 iframe 客户端geolibre/embed。调用失败时怎么办references/mcp-tools.md 的排错表:错误处理路径在工作区根之外写到某个根内,或请用户用--root增加一个文件已存在传overwriteTrue——但仅当替换确实是用户想要的未知底图 / 色带 / 图例预设调list_catalog,用真实名字找不到图层describe_project看当前名字与 idnot a GeoLibre project目标是别的 JSON,换个路径classify_layer报没有属性数据该图层不是内联 GeoJSON 图层,用add_geojson_layer重新加参考资料索引以下文件位于仓库skills/geolibre/目录下,按需阅读:references/mcp-tools.md——每个 MCP 工具的参数说明,以及按文件扩展名或服务类型选add_*_layer工具的选型表;references/python-api.md——Notebook 与无头项目生成场景下的geolibre.Map用法,含 MCP 服务器做不到的循环;references/project-json.md——.geolibre.jsonschema、最小合法项目与图层对象,供手写或修复项目;references/catalog.md——底图、色带、图例预设、图层类型、支持格式与 embed/URL 参数面。源码层面,工具的实现分散在 mcp/server.py(工具定义与服务器入口)、mcp/workspace.py(路径沙箱)、authoring.py(Map与 MCP 工具共同委托的无组件项目操作模块,可单独import geolibre.authoring使用)以及 project.py(图层 builder 与空项目构造)。官方文档站另有 MCP、Python 与项目格式三篇上游文档,参考资料不够用时可对照查阅;仓库侧的 docs/mcp.md 与 docs/python.md 也提供对应说明。【免费下载链接】GeoLibreA lightweight, cloud-native GIS platform for visualizing, exploring, and analyzing geospatial data. It runs in the web browser, on the desktop, on mobile, and inside Jupyter notebooks.项目地址: https://gitcode.com/GitHub_Trending/ge/GeoLibre创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
