Agentic GIS: 将CARTO工作流程转换为MCP工具

用于展示使用MCP（模型上下文协议）工具和CARTO AI代理分析纽约市2025年交通拥堵法规影响的工作坊材料。

工作坊概述

本实践工作坊演示如何利用CARTO的地理空间工具来分析实际的城市政策影响。参与者将学习如何：

• 创建并部署作为MCP工具的地理空间分析工作流程
• 将CARTO MCP服务器与外部AI代理集成
• 创建提供MCP工具的工作流的CARTO AI代理

使用案例

2025年1月，纽约市推出了一项拥堵定价规定，旨在减少交通拥堵及其对交通事故和空气污染的影响。本工作坊将引导您创建一个分析框架，通过比较三个关键指标来衡量该规定的实际影响：

• 交通量：规定实施前后车辆总数
• 交通事故：碰撞频率和严重程度
• 空气质量：受影响区域的污染测量值

分析将比较规定实施前六个月（2024年6月至12月）与后六个月（2025年1月至6月）的数据，针对纽约市用户定义的任何感兴趣区域。

工作坊结构

1. 引言（5分钟）

• 见到讲师
• 工作坊目标和成果
• 纽约市拥堵规定案例研究概述
• 查看幻灯片！

2. 作为MCP工具的工作流程（25分钟）

学习如何在CARTO中创建地理空间分析工作流程，并将其暴露为可以由任何AI代理使用的MCP工具。

您将构建的内容：

• 扩展分析工作流程：全面异步分析，带状态轮询
• 紧凑分析工作流程：更快同步版本，快速结果
• 区域生成器工作流程：将坐标对转换为WKT区域描述

关键概念：

• 在CARTO中创建工作流程
• 配置工作流程为MCP工具
• 处理异步操作
• 性能优化策略

3. CARTO AI代理（30分钟）

了解CARTO AI代理如何提供基于地图的地理空间分析界面。

您将学到的内容：

• 设置CARTO AI代理
• 提供代理访问MCP工具
• 定义代理逻辑
• 测试和改进代理
• 可视化分析结果

先决条件

• 带有访问工作流程和构建器权限的CARTO账户
• 对地理空间概念的基本理解（坐标、多边形、WKT格式）
• 对AI代理和MCP的熟悉（可选但有益）
• 在您的计算机上安装了AI代理CLI。推荐使用Claude Code或Gemini CLI

开始步骤

第一步：设置您的CARTO环境

1. 登录您的CARTO账户
2. 导航至“工作流程”部分
3. 确保您可以通过CARTO数据仓库访问所需的纽约市数据集：
   • 交通计数数据在carto-demo-data.demo_tables.nyc_traffic_counts。
   • 交通事故/碰撞数据在carto-demo-data.demo_tables.nyc_collisions。
   • 空气质量测量数据在carto-demo-data.demo_tables.nyc_air_quality。

第二步：创建工作流程

通过拖放此存储库中的/workflows文件夹中的文件到您的CARTO账户中的“工作流程”部分来创建您的工作流程。

扩展分析工作流程（异步）

此工作流程执行全面的逐步分析，并异步运行。

关键特性：

• 使用MCP工具async_workflow_job_get_status_v1_0_0和async_workflow_job_get_results_v1_0_0进行异步执行和作业跟踪，以轮询状态并检索结果

区域生成器工作流程

将纬度/经度坐标转换为表示影响区域的WKT多边形字符串。

紧凑分析工作流程（同步）

优化速度的精简版，同步运行以获得更快的结果。

关键特性：

• 优化速度
• 同步执行（立即返回结果）
• 适合交互式演示

第三步：将工作流程暴露为MCP工具

对于每个创建的工作流程：

1. 导航到工作流程设置
2. 选择“作为MCP工具公开”
3. 检查并配置工具元数据：
   • 工具名称：描述性名称（例如，nyc_traffic_analysis_extended_version）
   • 描述：清晰描述工具的功能
   • 参数：定义输入和输出参数
4. 启用为MCP工具

第四步：配置CARTO MCP服务器

为了配置您的MCP客户端，您需要从您的CARTO账户获取以下内容：

• 获取您的MCP服务器URL：在您的CARTO工作区中，转到“开发者”并找到“工作流程API & MCP服务器”
• 创建具有MCP工具授权的API访问令牌：在“开发者”中，转到“凭证”并点击“+ 新建”

更多详细说明，请参阅此文档。

将CARTO MCP服务器添加到您的AI代理配置中以访问这些工具：

通用配置（兼容Claude和Gemini CLI）

{
"mcpServers": {
        "carto-sdsc-demo": {
          "type": "http",
          "url": "https://gcp-us-east1.api.carto.com/mcp/<your_org_id>>",
          "headers": {
            "Authorization": "Bearer<your_api_access_token>"
          }
        }
      }
}

Gemini CLI

$ gemini mcp add carto-mcp-server https://your-carto-instance.com/mcp/<org_id> -t http -H 'Authorization: Bearer <api_access_token>'

Claude Code

$ claude mcp add carto-mcp-server https://your-carto-instance.com/mcp/<org_id> -t http -H 'Authorization: B
Bearer <api_access_token>'

第五步：使用外部AI代理测试

一旦配置并连接了CARTO MCP服务器，尝试向您的AI代理提问，如：

• “曼哈顿百老汇和东休斯顿街周围的拥堵规定效果如何？”
• “分析2025年1月规定实施后时代广场附近的交通变化”
• “比较金融区在规定实施前后的空气质量”

第六步：设置CARTO AI代理

现在您已经使用外部AI代理测试了MCP工具，让我们创建一个CARTO AI代理，以实现集成的地图体验。

1. 在您的组织中启用CARTO AI

第一步是在您的组织中启用CARTO AI。为此，请导航至设置 > CARTO AI并启用它。

2. 创建一个地图来托管您的代理

1. 转到您CARTO工作区中的“AI代理”部分
   • 这里您可以查看您CARTO组织中可用的所有AI代理
2. 点击“创建AI代理”
3. 选择“+ 新地图”（因为我们还没有现有的地图来覆盖这个用例）

3. 添加数据源并准备图层

在您的地图中，提供标题分析纽约市拥堵定价计划的影响，并添加位于CARTO数据仓库 > 示例数据 > 示例表中的以下纽约市数据源：

• 碰撞：纽约市交通事故数据
• 空气质量：纽约市空气质量测量数据
• 拥堵：纽约市交通量数据
• 纽约市拥堵区：纽约市拥堵定价区边界

根据需要样式化图层（例如，通过carto_point_density样式化碰撞，以便更好地可视化）

4. 创建并配置您的AI代理

a) 导航到地图中的“AI代理”标签

b) 点击“创建代理”，出现代理配置对话框，您可以在此处配置您的AI代理。

c) 提供描述您的代理功能的用例：

分析纽约市拥堵定价规定的影响（2025年1月5日启动）。比较规定实施前（2024年6月至12月）与后（2025年1月至6月）的交通量、事故和空气质量。量化这三个指标的变化，并创建一个数据驱动的故事，展示规定的空间效应。

d) 选择正确的模型

• 导航到“模型”部分
• CARTO默认使用CARTO管理模型，但您也可以在CARTO AI设置中配置自己的模型。
• 在我们的案例中，我们将选择gemini-2.5-pro

e) 添加我们在前面步骤中创建的MCP工具

您的代理默认拥有核心工具的访问权限。现在添加您在步骤2-3中创建的自定义工作流程作为MCP工具：

• 在代理配置中点击“添加工具”
• 搜索组织中可用的MCP工具
• 添加这些工具：
  • create_area_from_coordinates
  • nyc_traffic_analysis_compact
• 检查每个工具的元数据（描述、输入参数、输出定义）

f) 提供指令

定义代理的分析工作流程和行为：

• 导航到“指令”部分
• 从agent/instructions.md复制内容
• 粘贴到代理配置中

指令定义了通信风格、不同输入场景下的分析工作流程、如何呈现结果以及处理缺失数据的方法。

g) 完成后，点击“创建代理”

5. 测试您的代理

现在您可以在编辑模式下开始测试您的代理，在预览和发布地图之前。尝试查询，如：

• “我画出的区域内的交通影响是什么？”
• “显示当前地图视图的拥堵影响”
• “时代广场的交通模式发生了什么变化？”
• “分析帝国大厦周围的交通变化”

参见agent/test-prompts.md以获取更多测试查询

6. 最终确定并分享

打开AI代理配置来自定义介绍消息和对话起始提示，帮助用户开始使用您的代理。

添加介绍消息和对话起始提示：

自定义问候消息并提供建议提示，以指导用户。这有助于他们了解代理可以做什么，并提供简单的起点。

参见agent/intro-message.md以获取示例介绍消息和对话起始提示

为查看者启用：

转到地图设置并为查看者启用地图上的AI代理，以便他们可以与代理互动。

预览和分享：

在预览模式下测试，以查看最终用户体验。

一旦您对代理的工作方式感到满意，就可以分享地图：

• 特定用户：与个别团队成员共享
• 您的组织：让组织中的每个人都可以访问
• 公众：使地图公开可访问

您的CARTO AI代理现在已准备好使用！

在这个例子中，我们询问了“帝国大厦周围的交通情况”。可以看到代理的分析结果以及所考虑的兴趣区域，显示为地图上的新AI生成图层。

额外资源

• CARTO工作流程作为MCP工具文档
• 模型上下文协议（MCP）规范
• CARTO AI代理指南

支持

对于问题或问题：

• 在工作坊期间：向讲师提问
• 工作坊之后：联系CARTO支持：support@carto.com

致谢

工作坊由CARTO产品管理团队的Ana Manzanares和Ernesto Martínez开发。

数据来源：纽约市开放数据，[其他来源]