Mapbox MCP Server

chính thức

Mở khóa trí tuệ không gian địa lý thông qua các API của Mapbox như mã hóa địa lý, tìm kiếm POI, chỉ đường, đường đẳng thời và nhiều hơn nữa.

GitHub
347

Tài liệu

Mapbox MCP Server

npm version

Máy chủ Node.js triển khai Model Context Protocol (MCP) cho các API của Mapbox.

Mở Khóa Trí Tuệ Không Gian Địa Lý cho Ứng Dụng AI của Bạn

Mapbox MCP Server biến mọi tác nhân hoặc ứng dụng AI thành một hệ thống có nhận thức về không gian địa lý bằng cách cung cấp quyền truy cập liền mạch vào nền tảng trí tuệ vị trí toàn diện của Mapbox. Với máy chủ này, AI của bạn có thể hiểu và suy luận về các địa điểm, điều hướng thế giới vật lý và truy cập dữ liệu không gian địa lý phong phú bao gồm:

  • Mã hóa địa lý toàn cầu để chuyển đổi địa chỉ và tên địa điểm thành tọa độ và ngược lại
  • Tìm kiếm điểm ưa thích (POI) trên hàng triệu doanh nghiệp, địa danh và địa điểm trên toàn thế giới
  • Định tuyến đa phương thức cho lái xe, đi bộ và đạp xe với giao thông thời gian thực
  • Ma trận thời gian di chuyển để phân tích khả năng tiếp cận và tối ưu hóa hậu cần
  • Tối ưu hóa tuyến đường để tìm thứ tự ghé thăm tối ưu cho nhiều điểm dừng (bài toán người bán hàng)
  • Khớp bản đồ để gắn các dấu vết GPS vào mạng lưới đường bộ nhằm trực quan hóa tuyến đường rõ ràng
  • Tạo đường đẳng thời để trực quan hóa các khu vực có thể đến được trong các ràng buộc thời gian hoặc khoảng cách cụ thể
  • Hình ảnh bản đồ tĩnh để tạo các biểu diễn trực quan về vị trí, tuyến đường và dữ liệu địa lý
  • Tính toán không gian địa lý ngoại tuyến cho khoảng cách, diện tích, phương vị, vùng đệm và phân tích không gian mà không cần gọi API

Cho dù bạn đang xây dựng trợ lý du lịch AI, trình tối ưu hóa hậu cần, hệ thống đề xuất dựa trên vị trí hay bất kỳ ứng dụng nào cần hiểu về "ở đâu", Mapbox MCP Server cung cấp trí tuệ không gian để biến điều đó thành hiện thực. Bạn cũng có thể kích hoạt nó trên các ứng dụng khách phổ biến như Claude Desktop và VS Code. Xem chi tiết bên dưới

Mapbox MCP Server Demo

Cách Sử Dụng

Cần có mã truy cập Mapbox để sử dụng máy chủ MCP này.

Điểm Cuối MCP Được Lưu Trữ

Để truy cập nhanh, bạn có thể sử dụng điểm cuối MCP được lưu trữ của chúng tôi:

Điểm cuối: https://mcp.mapbox.com/mcp

Để biết hướng dẫn thiết lập chi tiết cho các ứng dụng khách khác nhau và cách sử dụng API, hãy xem Hướng dẫn Máy chủ MCP Được Lưu trữ.

Để nhận mã truy cập Mapbox:

  1. Đăng ký tài khoản Mapbox miễn phí tại mapbox.com/signup
  2. Điều hướng đến Trang Tài khoản của bạn
  3. Tạo mã truy cập mới hoặc sử dụng mã truy cập công khai mặc định

Để biết thêm thông tin về mã truy cập Mapbox, hãy xem tài liệu Mapbox về mã truy cập.

Hướng Dẫn Tích Hợp

Để biết hướng dẫn thiết lập chi tiết cho các tích hợp khác nhau, hãy tham khảo các hướng dẫn sau:

Ví Dụ về Lời Nhắc

Hãy thử các lời nhắc này với Claude Desktop hoặc các ứng dụng khách MCP khác sau khi thiết lập:

Khám Phá Vị Trí

  • "Tìm các quán cà phê trong khoảng cách đi bộ từ Tòa nhà Empire State"
  • "Tôi muốn đi từ Seattle đến Portland, có Starbucks nào dọc đường không?"
  • "Chỉ cho tôi các trạm xăng dọc tuyến đường từ Boston đến New York"
  • "Có nhà hàng nào gần Quảng trường Thời đại không?"

Điều Hướng & Du Lịch

  • "Nhận chỉ đường lái xe từ LAX đến Hollywood với tình hình giao thông hiện tại"
  • "Mất bao lâu để đi bộ từ Công viên Trung tâm đến Quảng trường Thời đại?"
  • "Tính thời gian di chuyển từ khách sạn của tôi (Four Seasons) đến Sân bay JFK bằng taxi trong giờ cao điểm"

Trực Quan Hóa & Bản Đồ

  • "Tạo một hình ảnh bản đồ hiển thị tuyến đường từ Cầu Cổng Vàng đến Bến Ngư Phủ với các điểm đánh dấu tại cả hai vị trí"
  • "Cho tôi xem chế độ xem vệ tinh của Manhattan với các địa danh chính được đánh dấu"
  • "Tạo bản đồ làm nổi bật tất cả các địa điểm Starbucks trong vòng một dặm từ trung tâm thành phố Seattle"

Phân Tích & Lập Kế Hoạch

  • "Cho tôi xem các khu vực có thể đến được trong vòng 30 phút từ trung tâm thành phố Portland bằng ô tô"
  • "Tính ma trận thời gian di chuyển giữa 3 vị trí khách sạn này (Marriott, Sheraton và Hilton) và trung tâm hội nghị ở Denver"
  • "Tìm tuyến đường tối ưu để tham quan 3 điểm du lịch này (Cầu Cổng Vàng, Cầu thang Âm nhạc và Bến Ngư Phủ) ở San Francisco"
  • "Tối ưu hóa tuyến đường giao hàng cho 8 địa chỉ này: [danh sách địa chỉ]"

GPS & Khớp Tuyến Đường

  • "Làm sạch dấu vết GPS này và hiển thị tuyến đường thực tế trên đường: [danh sách tọa độ với dấu thời gian]"
  • "Gắn chuyến đi xe đạp đã ghi lại này vào mạng lưới đường dành cho xe đạp: [tọa độ GPS]"
  • "Khớp tuyến đường lái xe này với mạng lưới đường bộ và hiển thị mức độ tắc nghẽn giao thông"

Tính Toán Không Gian Địa Lý Ngoại Tuyến

  • "Khoảng cách tính bằng dặm giữa hai tọa độ này là bao nhiêu?"
  • "Tính diện tích của đa giác này bằng kilômét vuông"
  • "Điểm ở 37.7749°B, 122.4194°T có nằm trong đa giác khu vực dịch vụ này không?"
  • "Phương vị từ San Francisco đến New York là gì?"
  • "Tìm điểm giữa giữa London và Paris"
  • "Tạo vùng đệm 5 dặm xung quanh vị trí này"
  • "Tính trọng tâm của ranh giới khu phố này"
  • "Hộp giới hạn cho các tọa độ tuyến đường này là gì?"
  • "Đơn giản hóa đa giác phức tạp này để giảm số lượng điểm"

Mẹo để Có Kết Quả Tốt Hơn

  • Cụ thể về vị trí (sử dụng địa chỉ đầy đủ hoặc tên địa danh)
  • Chỉ định phương thức di chuyển ưa thích của bạn (lái xe, đi bộ, đạp xe)
  • Bao gồm các ràng buộc thời gian khi có liên quan ("trong giờ cao điểm", "lúc 3 giờ chiều")
  • Yêu cầu định dạng đầu ra cụ thể khi cần ("dưới dạng hình ảnh bản đồ", "ở định dạng JSON")

Ví dụ chi tiết: Xem examples/search-along-route.md để biết các ví dụ toàn diện về lời nhắc tìm kiếm dọc tuyến đường với các trường hợp sử dụng khác nhau và hướng dẫn kiểm tra MCP Inspector.

Tài Nguyên

Máy chủ MCP hiển thị dữ liệu tham chiếu tĩnh dưới dạng tài nguyên MCP. Tài nguyên cung cấp quyền truy cập chỉ đọc vào dữ liệu mà ứng dụng khách có thể tham chiếu trực tiếp mà không cần thực hiện lệnh gọi công cụ.

Tài Nguyên Có Sẵn

Tài Nguyên Danh Mục Mapbox

Mẫu URI: mapbox://categories hoặc mapbox://categories/{language}

Truy cập danh sách đầy đủ các ID danh mục có sẵn để sử dụng với công cụ tìm kiếm danh mục. Danh mục có thể được sử dụng để lọc kết quả tìm kiếm theo loại (ví dụ: "restaurant", "hotel", "gas_station").

Ví dụ:

  • mapbox://categories - Danh sách danh mục mặc định (tiếng Anh)
  • mapbox://categories/ja - Tên danh mục tiếng Nhật
  • mapbox://categories/es - Tên danh mục tiếng Tây Ban Nha

Truy Cập Tài Nguyên:

  • Ứng dụng khách có hỗ trợ tài nguyên MCP gốc: Sử dụng phương thức giao thức MCP resources/read
  • Ứng dụng khách không hỗ trợ tài nguyên: Sử dụng resource_reader_tool với URI tài nguyên

Xem Trước Bản Đồ Phong Phú (Ứng Dụng MCP)

static_map_image_tool cung cấp bảng xem trước bản đồ tương tác trong các ứng dụng khách tương thích, ngoài hình ảnh base64 mà tất cả ứng dụng khách đều nhận được.

Máy chủ này triển khai giao thức Ứng dụng MCP (@modelcontextprotocol/ext-apps), hiển thị bảng ứng dụng HTML khép kín trực tiếp bên trong cuộc trò chuyện. Các ứng dụng khách được hỗ trợ hiển thị bản đồ tương tác với nút chuyển đổi Toàn màn hình:

  • Claude Desktop ✅
  • VS Code với GitHub Copilot ✅
  • Claude Code ✅
  • Goose ✅

Tất cả ứng dụng khách đều nhận được hình ảnh bản đồ được mã hóa base64 bất kể hỗ trợ giao thức — xem trước tương tác là một cải tiến lũy tiến trên phản hồi hình ảnh tiêu chuẩn.

Kế Thừa: MCP-UI

Máy chủ này cũng giữ lại hỗ trợ cho MCP-UI (@mcp-ui/server), một đặc tả mở trước đó cho xem trước iframe nhúng. Ứng dụng MCP là giao thức được khuyến nghị; hỗ trợ MCP-UI được giữ lại để tương thích ngược.

MCP-UI được bật theo mặc định. Để tắt nó, truyền --disable-mcp-ui làm cờ dòng lệnh hoặc đặt ENABLE_MCP_UI=false. Xem tài liệu MCP-UI để biết chi tiết.

CLIENT_NEEDS_RESOURCE_FALLBACK

Công Cụ Dự Phòng Tài Nguyên (Tùy Chọn cho Ứng Dụng Khách Không Tuân Thủ)

Tài nguyên là một tính năng MCP cốt lõi được hầu hết các ứng dụng khách hỗ trợ (Claude Desktop, VS Code, MCP Inspector, v.v.). Tuy nhiên, một số ứng dụng khách (như smolagents) hoàn toàn không hỗ trợ tài nguyên. Đối với những ứng dụng khách này, máy chủ có thể cung cấp "công cụ dự phòng tài nguyên" cung cấp cùng nội dung với tài nguyên nhưng thông qua lệnh gọi công cụ.

Công Cụ Dự Phòng:

  • resource_reader_tool - Dự phòng chung để đọc bất kỳ tài nguyên nào theo URI
  • category_list_tool - Cung cấp quyền truy cập vào danh sách danh mục (mapbox://categories)

Theo mặc định, các công cụ này KHÔNG được bao gồm (giả định ứng dụng khách của bạn hỗ trợ tài nguyên). Nếu ứng dụng khách của bạn không hỗ trợ tài nguyên, hãy bật các công cụ dự phòng:

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

Khi nào nên đặt điều này:

  • ✅ Đặt thành true nếu sử dụng smolagents hoặc các ứng dụng khách khác không hỗ trợ tài nguyên
  • ❌ Để trống (mặc định) nếu sử dụng Claude Desktop, VS Code, MCP Inspector hoặc bất kỳ ứng dụng khách nào có khả năng tài nguyên
  • ❌ Để trống nếu không chắc chắn (hầu hết các ứng dụng khách đều hỗ trợ tài nguyên)

Công Cụ

Công Cụ Tiện Ích

Công Cụ Đọc Tài Nguyên

Cung cấp quyền truy cập vào tài nguyên MCP cho các ứng dụng khách không hỗ trợ API tài nguyên MCP gốc. Sử dụng công cụ này để đọc các tài nguyên như danh sách danh mục.

Tham Số:

  • uri: URI tài nguyên cần đọc (ví dụ: mapbox://categories, mapbox://categories/ja)

Ví Dụ Sử Dụng:

  • Đọc danh mục mặc định: {"uri": "mapbox://categories"}
  • Đọc danh mục tiếng Nhật: {"uri": "mapbox://categories/ja"}

Lưu ý: Nếu ứng dụng khách MCP của bạn hỗ trợ tài nguyên gốc, hãy ưu tiên sử dụng trực tiếp API tài nguyên để có hiệu suất tốt hơn.

Công Cụ Không Gian Địa Lý Ngoại Tuyến

Các công cụ này thực hiện tính toán không gian địa lý hoàn toàn ngoại tuyến mà không yêu cầu gọi API Mapbox. Chúng sử dụng Turf.js để tính toán địa lý chính xác và hoạt động ở mọi nơi, ngay cả khi không có kết nối internet.

Công Cụ Khoảng Cách

Tính khoảng cách giữa hai tọa độ địa lý bằng công thức Haversine.

Tính Năng:

  • Hỗ trợ nhiều đơn vị: kilômét, dặm, mét, feet, hải lý
  • Tính toán khoảng cách đường tròn lớn chính xác
  • Không yêu cầu gọi API

Ví Dụ Sử Dụng: "Khoảng cách giữa San Francisco (37.7749°B, 122.4194°T) và New York (40.7128°B, 74.0060°T) là bao nhiêu?"

Công Cụ Điểm Trong Đa Giác

Kiểm tra xem một điểm có nằm trong đa giác hoặc đa đa giác hay không.

Tính Năng:

  • Hoạt động với các đa giác phức tạp bao gồm cả lỗ hổng
  • Hỗ trợ đa đa giác
  • Hữu ích cho việc kiểm tra hàng rào địa lý và khu vực dịch vụ

Ví Dụ Sử Dụng: "Địa chỉ giao hàng này có nằm trong khu vực dịch vụ của chúng tôi không?"

Công Cụ Phương Vị

Tính hướng la bàn (phương vị) từ tọa độ này đến tọa độ khác.

Tính Năng:

  • Trả về phương vị theo độ (0-360°)
  • Cung cấp hướng chính (B, ĐB, Đ, ĐN, N, TN, T, TB)
  • Hữu ích cho điều hướng và truy vấn hướng

Ví Dụ Sử Dụng: "Tôi nên đi theo hướng nào để từ đây đến sân bay?"

Công Cụ Điểm Giữa

Tìm điểm giữa địa lý giữa hai tọa độ dọc theo đường tròn lớn.

Tính Năng:

  • Tính toán điểm giữa thực sự trên bề mặt cong của Trái Đất
  • Hữu ích cho đề xuất điểm gặp gỡ
  • Xử lý chính xác các tính toán khoảng cách xa

Ví Dụ Sử Dụng: "Điểm giữa San Francisco và New York là gì?"

Công Cụ Trọng Tâm

Tính trung tâm hình học (trọng tâm) của đa giác hoặc đa đa giác.

Tính Năng:

  • Hoạt động với các hình dạng phức tạp
  • Trả về trung bình cộng của tất cả các điểm
  • Hữu ích cho việc đặt nhãn hoặc điểm đánh dấu

Ví Dụ Sử Dụng: "Tôi nên đặt điểm đánh dấu cho ranh giới khu phố này ở đâu?"

Công Cụ Diện Tích

Tính diện tích của một đa giác.

Tính Năng:

  • Hỗ trợ nhiều đơn vị: mét vuông, kilômét vuông, mẫu Anh, hécta, dặm vuông, feet vuông
  • Tính toán diện tích chính xác trên bề mặt Trái Đất
  • Hoạt động với các đa giác có kích thước bất kỳ

Ví Dụ Sử Dụng: "Diện tích của công viên này tính bằng mẫu Anh là bao nhiêu?"

Công Cụ Hộp Giới Hạn

Tính hộp giới hạn tối thiểu (bbox) chứa một hình học.

Tính Năng:

  • Hoạt động với điểm, đường, đa giác và đa đa giác
  • Trả về [minLongitude, minLatitude, maxLongitude, maxLatitude]
  • Hữu ích cho tính toán khung nhìn và lập chỉ mục không gian

Ví Dụ Sử Dụng: "Hộp giới hạn cho tuyến đường này là gì?"

Công Cụ Vùng Đệm

Tạo vùng đệm (đa giác) xung quanh một điểm, đường hoặc đa giác.

Tính Năng:

  • Hỗ trợ nhiều đơn vị khoảng cách
  • Tạo vùng đệm tròn xung quanh các điểm
  • Hữu ích cho phân tích lân cận và tạo vùng ảnh hưởng

Ví Dụ Sử Dụng: "Cho tôi xem vùng đệm 5km xung quanh vị trí này"

Công Cụ Đơn Giản Hóa

Giảm số lượng đỉnh trong một đường hoặc đa giác bằng thuật toán Douglas-Peucker.

Tính Năng:

  • Dung sai có thể cấu hình cho mức độ chi tiết
  • Bảo toàn hình dạng tổng thể trong khi giảm độ phức tạp
  • Hữu ích để giảm kích thước tệp và cải thiện hiệu suất kết xuất
  • Tùy chọn duy trì cấu trúc liên kết (ngăn tự giao cắt)

Ví Dụ Sử Dụng: "Đơn giản hóa ranh giới phức tạp này để giảm số lượng điểm"

Công Cụ API Mapbox

Công Cụ Danh Sách Danh Mục (Đã Lỗi Thời)

⚠️ Đã lỗi thời: Sử dụng resource_reader_tool với URI mapbox://categories thay thế, hoặc truy cập trực tiếp tài nguyên mapbox://categories nếu ứng dụng khách của bạn hỗ trợ tài nguyên MCP.

Công cụ này được duy trì để tương thích ngược với các ứng dụng khách không hỗ trợ tài nguyên MCP hoặc resource_reader_tool.

Công Cụ Ma Trận

Tính toán thời gian và khoảng cách di chuyển giữa nhiều điểm bằng Mapbox Matrix API. Các tính năng bao gồm:

  • Tính toán định tuyến một-nhiều, nhiều-một hoặc nhiều-nhiều hiệu quả
  • Hỗ trợ các hồ sơ di chuyển khác nhau (lái xe-có giao thông, lái xe, đi bộ, đạp xe)
  • Chỉ định thời gian khởi hành cho các tính toán có nhận thức về giao thông
  • Tóm tắt tuyến đường với các chỉ số khoảng cách và thời lượng
  • Kiểm soát cách tiếp cận (lề đường/không hạn chế) và phạm vi phương vị khởi hành được phép

Công cụ hình ảnh tĩnh

Tạo hình ảnh bản đồ tĩnh bằng Mapbox static image API. Các tính năng bao gồm:

  • Kiểu bản đồ tùy chỉnh (đường phố, ngoài trời, vệ tinh, v.v.)
  • Kích thước hình ảnh và mức thu phóng có thể điều chỉnh
  • Hỗ trợ nhiều điểm đánh dấu với màu sắc và nhãn tùy chỉnh
  • Tùy chọn lớp phủ bao gồm đa tuyến và đa giác
  • Tự động điều chỉnh vừa với tọa độ được chỉ định

Công cụ tìm kiếm danh mục

Thực hiện tìm kiếm danh mục bằng Mapbox Search Box category search API. Các tính năng bao gồm:

  • Tìm kiếm điểm ưa thích theo danh mục (nhà hàng, khách sạn, trạm xăng, v.v.)
  • Lọc theo khoảng cách địa lý
  • Giới hạn kết quả có thể tùy chỉnh
  • Siêu dữ liệu phong phú cho mỗi kết quả
  • Hỗ trợ nhiều ngôn ngữ

Công cụ mã hóa địa lý ngược

Thực hiện mã hóa địa lý ngược bằng Mapbox geocoding V6 API. Các tính năng bao gồm:

  • Chuyển đổi tọa độ địa lý thành địa chỉ mà con người có thể đọc được
  • Mức độ chi tiết có thể tùy chỉnh (đường phố, khu phố, thành phố, v.v.)
  • Lọc kết quả theo loại (địa chỉ, poi, khu phố, v.v.)
  • Hỗ trợ nhiều ngôn ngữ
  • Thông tin ngữ cảnh vị trí phong phú

Công cụ chỉ đường

Tìm nạp chỉ đường định tuyến bằng Mapbox Directions API. Các tính năng bao gồm:

  • Hỗ trợ các hồ sơ định tuyến khác nhau: lái xe (với giao thông trực tiếp hoặc điển hình), đi bộ và đạp xe
  • Tuyến đường từ nhiều điểm tham chiếu (2-25 cặp tọa độ)
  • Tùy chọn tuyến đường thay thế
  • Chú thích tuyến đường (khoảng cách, thời lượng, tốc độ, tắc nghẽn)
  • Tùy chọn lập lịch:
    • Thời gian khởi hành trong tương lai (depart_at) cho hồ sơ lái xe và lái xe-có giao thông
    • Thời gian đến mong muốn (arrive_by) chỉ cho hồ sơ lái xe
  • Tối ưu hóa cụ thể theo hồ sơ:
    • Lái xe: ràng buộc kích thước phương tiện (chiều cao, chiều rộng, trọng lượng)
  • Tùy chọn loại trừ cho định tuyến:
    • Loại trừ phổ biến: tuyến phà, trạm thu phí chỉ thu tiền mặt
    • Loại trừ cụ thể cho lái xe: trạm thu phí, đường cao tốc, đường không trải nhựa, đường hầm, biên giới quốc gia, biên giới tiểu bang
    • Loại trừ điểm tùy chỉnh (tối đa 50 điểm địa lý cần tránh)
  • Định dạng đầu ra hình học GeoJSON

Công cụ đường đẳng thời

Tính toán các khu vực có thể đến được trong một khoảng thời gian xác định từ một vị trí bằng Mapbox Isochrone API. Các tính năng bao gồm:

  • Hỗ trợ các hồ sơ di chuyển khác nhau (lái xe, đi bộ, đạp xe)
  • Thời gian hoặc khoảng cách di chuyển có thể tùy chỉnh
  • Tạo nhiều đường đồng mức (ví dụ: phạm vi 15, 30, 45 phút)
  • Chỉ định thời gian khởi hành hoặc đến tùy chọn
  • Tùy chỉnh màu sắc để trực quan hóa

Công cụ tìm kiếm và mã hóa địa lý

Sử dụng điểm cuối Mapbox Search Box Text Search API để hỗ trợ tìm kiếm và mã hóa địa lý POI, địa chỉ, địa điểm và bất kỳ loại nào khác được API đó hỗ trợ. Công cụ này hợp nhất chức năng trước đây được cung cấp bởi ForwardGeocodeTool và PoiSearchTool (từ các phiên bản trước của máy chủ MCP này) thành một công cụ duy nhất.

Công cụ khớp bản đồ

Gắn các dấu vết GPS vào mạng lưới đường bộ bằng Mapbox Map Matching API. Các tính năng bao gồm:

  • Chuyển đổi dấu vết GPS nhiễu thành các tuyến đường sạch trên mạng lưới đường bộ
  • Hỗ trợ các hồ sơ di chuyển khác nhau (lái xe, lái xe-có giao thông, đi bộ, đạp xe)
  • Xử lý tối đa 100 cặp tọa độ mỗi yêu cầu
  • Dấu thời gian tùy chọn để cải thiện độ chính xác dựa trên tốc độ
  • Bán kính gắn có thể cấu hình cho các mức chất lượng GPS khác nhau
  • Chú thích tuyến đường (giới hạn tốc độ, khoảng cách, thời lượng, tắc nghẽn giao thông)
  • Nhiều định dạng đầu ra hình học (GeoJSON, polyline)

Ví Dụ Sử Dụng: "Làm sạch dấu vết GPS này và gắn nó vào đường: [tọa độ với dấu thời gian]"

Công cụ tối ưu hóa

Tìm tuyến đường tối ưu qua nhiều vị trí bằng Mapbox Optimization API. Các tính năng bao gồm:

  • Giải bài toán người bán hàng (TSP) cho 2-12 vị trí
  • Hỗ trợ các hồ sơ di chuyển khác nhau (lái xe, lái xe-có giao thông, đi bộ, đạp xe)
  • Cấu hình điểm bắt đầu và kết thúc linh hoạt
  • Tối ưu hóa chuyến đi khứ hồi hoặc một chiều
  • Hướng dẫn điều hướng từng chặng (tùy chọn)
  • Chú thích tuyến đường (khoảng cách, thời lượng, tốc độ)
  • Nhiều định dạng đầu ra hình học (GeoJSON, polyline)

Ví Dụ Sử Dụng: "Tìm tuyến đường tối ưu để ghé thăm 5 điểm dừng này: [danh sách địa chỉ hoặc tọa độ]"

Lưu ý: API V2 với các tính năng nâng cao (cửa sổ thời gian, ràng buộc dung lượng, nhiều phương tiện) có sẵn nhưng yêu cầu quyền truy cập beta. Việc triển khai V2 được bao gồm trong cơ sở mã nhưng không được đăng ký theo mặc định.

Phát Triển

Kiểm tra máy chủ

Sử dụng Node.js

# Run the built image
npm run inspect:build

Sử dụng Docker

# Build the Docker image
docker build -t mapbox-mcp-server .

# Run and inspect the server
npx @modelcontextprotocol/inspector docker run -i --rm --env MAPBOX_ACCESS_TOKEN="YOUR_TOKEN" mapbox-mcp-server

Tạo công cụ mới

npx plop create-tool
# provide tool name without suffix (e.g. Search)

Phát Hành Phiên Bản Mới

# 1. Bump version in package.json
npm version <new-version> --no-git-tag-version

# 2. Sync version to manifest.json and server.json
npm run sync-manifest

# 3. Prepare CHANGELOG (replaces "Unreleased" with version and date)
npm run changelog:prepare-release <new-version>

# 4. Update package-lock.json
npm install

# 5. Review changes, then commit and tag
git add package.json package-lock.json manifest.json server.json CHANGELOG.md
git commit -m "Release v<new-version>"
git tag v<new-version>
git push && git push --tags

Quan trọng: Quy trình làm việc của nhà xuất bản xác thực rằng các phiên bản package.json và server.json khớp với phiên bản phát hành. Bỏ qua việc tăng phiên bản hoặc đồng bộ hóa tệp kê khai sẽ gây ra lỗi xuất bản.

Theo Dõi OpenTelemetry

Máy chủ MCP này bao gồm theo dõi OpenTelemetry toàn diện để quan sát trong sản xuất:

Demo Nhanh

# 1. Copy the example configuration
cp .env.example .env

# 2. Edit .env to add your MAPBOX_ACCESS_TOKEN and configure tracing

# 3. Start Jaeger for local development
npm run tracing:jaeger:start

# 4. Run the server (it will automatically use .env configuration)
npm run inspect:build

# 5. View traces at http://localhost:16686

# 6. Stop Jaeger when done
npm run tracing:jaeger:stop

Lưu ý: Máy chủ tự động tải cấu hình từ tệp .env của bạn khi khởi động. Tệp .env.example bao gồm các ví dụ cấu hình cho nhiều nền tảng quan sát.

Nền Tảng Quan Sát Được Hỗ Trợ

Ví dụ cấu hình được bao gồm trong .env.example cho:

Nhà Cung Cấp Đám Mây:

  • ☁️ AWS X-Ray
  • ☁️ Azure Monitor (Application Insights)
  • ☁️ Google Cloud Trace

Nền Tảng SaaS:

  • 📊 Datadog
  • 📊 New Relic
  • 📊 Honeycomb
  • 📊 Bất kỳ backend tương thích OTLP nào

Cấu Hình Sản Xuất

Xem docs/tracing.md để biết hướng dẫn thiết lập đầy đủ bao gồm:

  • 🔧 Hướng dẫn cấu hình cụ thể cho nền tảng
  • 📊 Thiết lập xác thực và điểm cuối
  • 🎯 Thuộc tính và ngữ cảnh theo dõi tùy chỉnh
  • 🚀 Tối ưu hóa hiệu suất (chi phí tối thiểu)
  • 🔍 Khắc phục sự cố và gỡ lỗi

Tính Năng Theo Dõi:

  • ✅ Theo dõi tải cấu hình (tải tệp .env)
  • ✅ Theo dõi thực thi công cụ tự động
  • ✅ Đo lường yêu cầu HTTP với ID tương quan CloudFront
  • ✅ Trình xuất có thể cấu hình (console, OTLP)
  • ✅ Có ý thức bảo mật (bảo vệ dữ liệu, xác thực JWT)
  • ✅ Sẵn sàng cho sản xuất (<1% chi phí CPU)

Đóng Góp

Chúng tôi hoan nghênh các đóng góp cho Mapbox MCP Server! Vui lòng đọc CONTRIBUTING.md trước khi gửi pull request.

Tiêu chuẩn và hướng dẫn đầy đủ:

Bắt Đầu Nhanh cho Người Đóng Góp

  1. Fork kho lưu trữ và sao chép fork của bạn
  2. Cài đặt phụ thuộc: npm install
  3. Thực hiện thay đổi của bạn theo tiêu chuẩn mã hóa của chúng tôi
  4. Chạy kiểm thử và linting: npm test && npm run lint
  5. Thêm kiểm thử cho bất kỳ chức năng mới nào
  6. Gửi pull request với mô tả rõ ràng

Tất cả đóng góp phải vượt qua kiểm tra CI và quy trình xem xét mã của chúng tôi. Xem docs/engineering_standards.md để biết yêu cầu chi tiết.

Sử Dụng Dữ Liệu & Quyền Riêng Tư

Dữ liệu nào được gửi đến API Mapbox

Khi bạn sử dụng các công cụ máy chủ MCP, dữ liệu sau được gửi trực tiếp từ môi trường của bạn đến API Mapbox:

  • Công cụ mã hóa địa lý: Văn bản địa chỉ/vị trí, tọa độ, bộ lọc quốc gia/khu vực
  • Công cụ tìm kiếm: Truy vấn tìm kiếm, tọa độ vị trí cho khoảng cách gần, bộ lọc danh mục
  • Công cụ chỉ đường: Tọa độ bắt đầu/kết thúc, điểm tham chiếu, tùy chọn định tuyến, ràng buộc phương tiện
  • Công cụ ma trận: Nhiều cặp tọa độ, hồ sơ di chuyển, thời gian khởi hành
  • Công cụ bản đồ tĩnh: Tọa độ, mức thu phóng, tùy chọn kiểu dáng, thông tin điểm đánh dấu
  • Công cụ đường đẳng thời: Tọa độ gốc, tham số thời gian/khoảng cách, hồ sơ di chuyển

Quyền riêng tư của bạn

  • Thực thi cục bộ: Tất cả các lệnh gọi API được thực hiện trực tiếp từ môi trường của bạn đến API Mapbox
  • Bảo mật mã truy cập: Mã truy cập API Mapbox của bạn vẫn ở trên máy cục bộ và không bao giờ được truyền đến hoặc lưu trữ bởi máy chủ MCP này
  • Không lưu trữ dữ liệu: Máy chủ MCP này không lưu trữ, ghi nhật ký hoặc thu thập bất kỳ dữ liệu hoặc yêu cầu API nào của bạn
  • Giao tiếp trực tiếp: Không có máy chủ trung gian nào giữa bạn và API Mapbox

Sử dụng dữ liệu của bên thứ ba

  • Chính sách quyền riêng tư của Mapbox điều chỉnh dữ liệu được gửi đến API của họ: https://www.mapbox.com/legal/privacy/
  • Sử dụng API: Điều khoản API Mapbox tiêu chuẩn áp dụng cho tất cả các yêu cầu được thực hiện thông qua các công cụ này
  • Lưu giữ dữ liệu: Tham khảo tài liệu của Mapbox để biết chính sách lưu giữ dữ liệu của họ

Hỗ Trợ & Liên Hệ

Đối với Sự Cố Máy Chủ MCP

Đối với Câu Hỏi về API Mapbox

Cam Kết Bảo Trì

Máy chủ MCP này được bảo trì chính thức bởi Mapbox, Inc. Chúng tôi cung cấp:

  • Cập nhật thường xuyên cho các tính năng API Mapbox mới
  • Sửa lỗi và cập nhật bảo mật
  • Tương thích với các phiên bản giao thức MCP mới nhất
  • Hỗ trợ cộng đồng thông qua GitHub issues

Giấy Phép MIT