内容
# map-mcp
驱动和感知一个**现有的、实时的 MapLibre GL 地图**，通过 AI 代理（通过 MCP）或人类
CLI — 查询渲染的要素，读取视口，单击并读取弹出窗口，导航，切换
层。代理和 CLI 对**同一张地图**进行操作，具备相同的功能。
它**不**生成地图。其他地理 MCP 服务器（gis-mcp，Mapbox，CARTO）创建地图或
调用 GIS 操作；map-mcp 直接与**已经在屏幕上的地图**进行交互。可以将其视为
[MapGrab](https://github.com/maxlapides/mapgrab) 的代理原生对应版本：相同的实时地图
访问，但通过 MCP 进行对话，而不是作为测试代码编写。
> **状态：** v1，仅支持 MapLibre GL。需要合作（您的应用程序添加一行钩子代码）。
> 无需合作的路径和其他地图库是未来的工作。
* [LangChain 代理](examples/langchain_agent.py) 找到最具人口的可见城市并
导航到它 — 通过 map-mcp 感知和驱动实时地图。
## 安装
```
uvx map-mcp --help # 或：pip install map-mcp
```
## 快速入门
1. **启动桥接器 + MCP 服务器。** 它打印一个 WebSocket URL 和一个会话令牌。
```
map-mcp serve
```
2. **将钩子添加到您的 MapLibre 页面**（`map` 是您现有的 `maplibregl.Map`）：
```html
<script src="map-mcp-hook.js"></script>
<script>
mapMcp.register(map, { url: "ws://127.0.0.1:8765", token: "粘贴令牌" });
</script>
```
3. **将您的代理指向 MCP 服务器**（默认情况下为 stdio；`--transport http` 用于 HTTP/SSE）。
或从终端亲自驱动它：
```
map-mcp call get_viewport
map-mcp call query_rendered_features --params '{"point":[12.5,41.9]}'
```
在 [`examples/sample_app/`](examples/sample_app/) 中有一个可运行的示例应用程序。
## 示例：LangChain 代理
[`examples/langchain_agent.py`](examples/langchain_agent.py) 是一个真正的代理 —
一个 langgraph ReAct 代理，适用于任何具有工具能力的模型 — 通过 map-mcp 的操作
驱动实时地图（它就是上面 GIF 的制作方式）。给它 map-mcp 工具和一个任务，它就会
感知和导航地图：
```
export OPENROUTER_API_KEY=sk-or-...
uvx playwright install chromium # 一次性，用于实时浏览器
uv run --extra demo python examples/langchain_agent.py
```
它默认使用 OpenRouter 模型（设置 `OPENROUTER_MODEL` 以更改）。代理的工具是
薄薄的一层封装在 MCP 服务器公开的相同 `CoreOps` 之上 — 因此代理可以做的任何事情，
CLI 也可以做到。
## 工具（操作界面）
代理的 MCP 工具和 CLI 的 `call` 操作是完全相同的集合：
| 操作 | 说明 |
|---|---|
| `get_viewport` | 中心点 `[lng,lat]`，缩放级别，方位角，俯仰角，边界 |
| `query_rendered_features` | 当前渲染的要素（可选在某个点或某个边界框内） |
| `get_features_at` | 在 `[lng,lat]` 点渲染的要素 |
| `click_at` | 在某个点触发地图的点击事件（运行您的弹出窗口处理程序），返回要素 + 弹出窗口 |
| `read_popup` | 任何打开的弹出窗口的文本 |
| `set_view` | 中心点 + 缩放级别（和方位角/俯仰角），或适应边界框 |
| `list_layers` | 样式的层 + 可见性 |
| `set_layer_visibility` | 显示/隐藏层 |
| `screenshot` | 当前地图的 PNG 数据 URL* |
感知返回**结构化的要素属性**（GeoJSON 形状）— 代理根据属性进行推理，而不是像素。
`screenshot` 是可选的。
\* 需要使用 `preserveDrawingBuffer: true` 创建地图（参见 [`hook/snippet.md`](hook/snippet.md)）。
## 工作原理
钩子代码连接到 `map-mcp` 进程运行的本地 WebSocket。MCP 工具和
CLI 是薄薄的一层封装在共享的核心操作层上，因此任一者可以执行的任何操作，另一者也可以执行。
**安全模型（仅限本地）。** 桥接器仅绑定到 `127.0.0.1`，因此您的机器以外的任何内容
都无法访问它。浏览器不对 WebSocket 连接应用同源策略，因此**每会话令牌**是
安全边界：只有呈现它的页面才能驱动您的地图。将令牌视为秘密 — 示例中的便捷
`?token=` 模式通过浏览器历史记录和服务器日志泄漏它，因此对于任何敏感内容，请
将令牌粘贴到页面中，而不是 URL 中。强化源白名单是未来的工作。
## 范围（v1）
- **包含：** MapLibre GL；上述操作；stdio + HTTP/SSE；具有同等功能的 CLI。
- **排除：** 生成地图；托管服务；非地图可视化；其他地图库
（Leaflet/deck.gl）和无需合作（Playwright）路径是未来的工作。
## 许可证
MIT
