Mapbox MCP Tools Ios

Mapbox MCPTools

   

iOS Swift包，用于将Mapbox Maps SDK v11函数封装到MCP（模型上下文协议）工具定义中。该库通过提供符合MCP的工具模式和执行处理程序，通过Claude API实现自然语言映射控制。

概述

MapboxMCPTools提供了一个简单的接口，将Mapbox映射功能暴露给Claude等语言模型。该软件包将7个核心地图操作包装为MCP工具，可包含在Claude API请求中，允许人工智能助手通过自然语言控制地图。

这相当于iOS的 安卓Mapbox MCP库.

• Javascript Mapbox MCP工具 JS相当于这个库吗

演示

看看 演示应用程序 以查看MapboxMCPTools与完整的Claude API集成的运行情况。

特性

• ✅ 7个符合MCP标准的工具 用于地图控制
• ✅ 安全型Swift API 具有全面的错误处理功能
• ✅ SwiftUI和UIKit支持
• ✅ 注释层管理 具有自动跟踪功能
• ✅ 协调验证 和输入消毒
• ✅ 零外部依赖 （消费应用提供Mapbox SDK）

需求

• iOS 14.0+
• Mapbox地图SDK v11.0+
• Swift 5.9+
• Xcode 15.0+

安装

Swift包管理器（推荐）

选项1：通过Xcode

1. 在Xcode中打开您的项目
2. 首选 File → 添加包依赖关系
3. 输入存储库URL：

   https://github.com/moritzzzzz/mapbox-mcp-tools-ios.git

1. 选择 “直到下一个主要版本” 随着 1.0.0
2. 点击 “添加包”
3. 选择您的应用程序目标并单击 “添加包” 再次

选项2：通过Package.swift

添加到您的 Package.swift:

dependencies: [
    .package(url: "https://github.com/moritzzzzz/mapbox-mcp-tools-ios.git", from: "1.0.0")
]

然后添加到您的目标：

targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "MapboxMCPTools", package: "mapbox-mcp-tools-ios")
        ]
    )
]

先决条件

您的应用程序必须已经具有 Mapbox地图SDK v11 集成：

dependencies: [
    .package(url: "https://github.com/mapbox/mapbox-maps-ios.git", from: "11.0.0")
]

从获取您的Mapbox访问令牌 Mapbox.com

可用的MCP工具

代币使用和成本

将这7个MCP工具添加到您的Claude API请求使用大约 约1300个代币 根据请求。

成本细分

克劳德十四行诗4.5定价：

• 输入：每100万代币3.00美元
• 产出：每100万代币15.00美元

根据请求：

• MCP工具： ~$0.0039 （1307个代币）
• 用户消息（平均值）： ~$0.0001 （25个代币）
• 克劳德回应（平均值）： ~$0.0015 （100个代币）
• 每回合总计：~0.0055美元 （小于1¢）

使用示例

优化提示

1.使用选择性工具 -仅包括您需要的工具：

// Instead of all 7 tools (~1,300 tokens)
let allTools = mcpTools.getToolsForLLM()

// Use only navigation tools (~400 tokens)
let navTools = [
    MCPToolDefinition.panMapToLocation,
    MCPToolDefinition.setMapStyle
]

2.批量操作 -让Claude在一个请求中执行多个映射操作

3.使用提示缓存 -Claude API的提示缓存（测试版）可以跨请求缓存工具定义

总结

令牌开销很小——你可以 数千个与地图相关的请求，只需几美元，与传统地图API定价相比，这一定价极具成本效益。

用法

1.先决条件

您的iOS应用程序必须具有 Mapbox地图SDK v11 已经集成和a MapView 初始化。

将Mapbox SDK添加到您的应用程序中：

// Add to your app's Package.swift or use SPM in Xcode
.package(url: "https://github.com/mapbox/mapbox-maps-ios.git", from: "11.0.0")

2.基本设置（SwiftUI）

import SwiftUI
import MapboxMaps
import MapboxMCPTools

struct ContentView: View {
    @State private var mcpTools: MapboxMCPTools?

    var body: some View {
        Map()
            .ignoresSafeArea()
            .onMapLoaded { mapViewProxy in
                // Initialize MCP Tools when map loads
                if let mapView = mapViewProxy.mapView {
                    mcpTools = MapboxMCPTools(mapView: mapView)

                    // Get tool definitions for Claude API
                    let tools = mcpTools?.getToolsForLLM()
                    sendToolsToClaudeAPI(tools: tools)
                }
            }
    }

    func sendToolsToClaudeAPI(tools: [MCPToolDefinition]?) {
        // Implement your Claude API integration here
    }
}

3.基本设置（UIKit）

import UIKit
import MapboxMaps
import MapboxMCPTools

class MapViewController: UIViewController {
    var mapView: MapView!
    var mcpTools: MapboxMCPTools!

    override func viewDidLoad() {
        super.viewDidLoad()

        // Initialize Mapbox MapView
        let cameraOptions = CameraOptions(
            center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
            zoom: 12
        )

        mapView = MapView(
            frame: view.bounds,
            mapInitOptions: MapInitOptions(
                cameraOptions: cameraOptions,
                styleURI: .streets
            )
        )
        view.addSubview(mapView)

        // Initialize MCP Tools
        mcpTools = MapboxMCPTools(mapView: mapView)

        // Get tool definitions for Claude API
        let tools = mcpTools.getToolsForLLM()
        print("Available tools: \(tools.count)")
    }
}

4.获取工具定义

// Get as Swift array
let tools: [MCPToolDefinition] = mcpTools.getToolsForLLM()

// Get as JSON string for API requests
if let toolsJSON = try? mcpTools.getToolsJSON() {
    print(toolsJSON)
}

5.执行工具

当Claude响应工具调用时，使用 executeTool 方法：

func handleClaudeResponse(toolName: String, parameters: [String: Any]) {
    let result = mcpTools.executeTool(name: toolName, params: parameters)

    switch result {
    case .success(let data):
        print("✅ Success: \(data)")
        // Update UI or send result back to Claude

    case .error(let message):
        print("❌ Error: \(message)")
        // Handle error in UI
    }
}

工具示例

将地图平移到位置

let result = mcpTools.executeTool(
    name: "pan_map_to_location",
    params: [
        "latitude": 40.7128,
        "longitude": -74.0060,
        "zoom": 14.0,
        "animated": true
    ]
)

添加点（标记）

let result = mcpTools.executeTool(
    name: "add_points_to_map",
    params: [
        "points": [
            ["latitude": 40.7128, "longitude": -74.0060, "title": "New York"],
            ["latitude": 34.0522, "longitude": -118.2437, "title": "Los Angeles"]
        ],
        "layerId": "cities",
        "iconColor": "#FF0000",
        "iconSize": 1.5
    ]
)

添加路线

let result = mcpTools.executeTool(
    name: "add_route_to_map",
    params: [
        "coordinates": [
            [-74.0060, 40.7128],  // [longitude, latitude]
            [-118.2437, 34.0522]
        ],
        "layerId": "route1",
        "lineColor": "#0000FF",
        "lineWidth": 5.0
    ]
)

增加多边形

let result = mcpTools.executeTool(
    name: "add_polygon_to_map",
    params: [
        "coordinates": [
            [-74.0, 40.7],
            [-73.9, 40.7],
            [-73.9, 40.8],
            [-74.0, 40.8],
            [-74.0, 40.7]  // Close the polygon
        ],
        "layerId": "area1",
        "fillColor": "#00FF00",
        "fillOpacity": 0.3,
        "strokeColor": "#006600",
        "strokeWidth": 2.0
    ]
)

设置地图样式

let result = mcpTools.executeTool(
    name: "set_map_style",
    params: ["style": "satellite"]
)

// Available styles: streets, satellite, satellite-streets, dark, light, outdoors, standard

清除图层

// Clear specific layers
let result = mcpTools.executeTool(
    name: "clear_map_layers",
    params: ["layerIds": ["cities", "route1"]]
)

// Clear all layers
let result = mcpTools.executeTool(
    name: "clear_map_layers",
    params: ["layerIds": []]
)

获取地图状态

let result = mcpTools.executeTool(
    name: "get_map_state",
    params: [:]
)

// Returns camera position, style, and active layers

与Claude API集成

与Claude API集成的示例（使用Anthropic SDK）：

import Anthropic

func sendMapToolsToClaudeAPI() async {
    let client = Anthropic(apiKey: "your-api-key")

    // Get MCP tool definitions
    let tools = mcpTools.getToolsForLLM()

    // Convert to Claude API format
    let claudeTools = tools.map { tool in
        Tool(
            name: tool.name,
            description: tool.description,
            inputSchema: tool.inputSchema
        )
    }

    // Send request with tools
    let response = try await client.messages.create(
        model: "claude-3-5-sonnet-20241022",
        maxTokens: 1024,
        messages: [
            Message(role: .user, content: "Show me New York City on the map")
        ],
        tools: claudeTools
    )

    // Handle tool use response
    if let toolUse = response.content.first?.toolUse {
        let result = mcpTools.executeTool(
            name: toolUse.name,
            params: toolUse.input
        )

        // Send result back to Claude if needed
        print(result)
    }
}

建筑

┌─────────────────────────┐
│   Your iOS App          │
│  (SwiftUI or UIKit)     │
└───────────┬─────────────┘
            │
            │ MapView reference
            ▼
┌─────────────────────────┐
│  MapboxMCPTools         │
│  (Facade)               │
├─────────────────────────┤
│ • getToolsForLLM()      │
│ • executeTool()         │
└───────────┬─────────────┘
            │
            │ Dispatch to tools
            ▼
┌─────────────────────────┐
│  Individual Tools       │
│  • PanMapTool           │
│  • AddPointsTool        │
│  • AddRouteTool         │
│  • ... etc              │
└───────────┬─────────────┘
            │
            │ Mapbox SDK calls
            ▼
┌─────────────────────────┐
│  Mapbox Maps SDK v11    │
│  (MapView)              │
└─────────────────────────┘

错误处理

所有工具返回a ToolResult 枚举：

public enum ToolResult {
    case success(data: [String: Any])
    case error(message: String)
}

常见错误场景：

• 坐标无效（超出范围）
• 缩放级别无效（不是0-22）
• 缺少必要参数
• 颜色格式无效（非十六进制）
• MapView已取消分配
• 多边形/路线的坐标不足

最佳实践

1. 始终在地图加载后进行初始化：在创建之前，确保MapView已完全初始化 MapboxMCPTools
2. 使用唯一的图层ID：每个注释层都需要一个唯一的标识符
3. 验证Claude的回答：执行前检查工具名称和参数
4. 优雅地处理错误：当工具执行失败时，向用户显示错误消息
5. 轨道层清理：使用 clear_map_layers 在不再需要时删除注释
6. 坐标格式：对路线和多边形使用\[经度、纬度\]顺序（GeoJSON标准）

局限性

• 点注释的图标图像必须包含在消费应用程序的捆绑包中
• 不支持自定义MapView子类
• 线程安全：所有操作都在主线程上运行（Mapbox SDK要求）
• 样式更改可能会重置自定义层（Mapbox SDK行为）

许可证

MIT许可证

贡献

欢迎投稿！请随时提交拉取请求。

相关项目

• 安卓Mapbox MCP工具 -Android相当于此库
• Javascript Mapbox MCP工具 -JS相当于这个库

支持

对于问题和疑问：

• 在GitHub上提交问题
• 检查Mapbox文档：https://docs.mapbox.com/ios/maps/
• MCP规范：https://spec.modelcontextprotocol.io/

致谢