mapbox-mcp-devkit-patterns
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMapbox MCP DevKit Patterns
Mapbox MCP DevKit 开发模式
This skill provides patterns for integrating the Mapbox MCP DevKit Server into AI coding workflows to accelerate Mapbox application development.
本技能提供了将Mapbox MCP DevKit Server集成到AI编码工作流的相关模式,可加速Mapbox应用的开发效率。
What is Mapbox MCP DevKit?
什么是Mapbox MCP DevKit?
The Mapbox MCP DevKit Server is a Model Context Protocol (MCP) server that gives AI assistants direct access to Mapbox developer APIs:
- Style management - Create, list, update, delete, preview, validate, compare, and optimize styles
- Token management - Generate and list access tokens with scopes
- Validation - Validate GeoJSON, expressions, styles, and coordinates
- Geographic utilities - Calculate bounding boxes, convert coordinates, query tiles
- Color tools - Check WCAG contrast ratios for accessibility
- Feedback - Access user feedback and reports
- Documentation - Access latest Mapbox docs and references
Key benefit: Build Mapbox applications faster by letting AI handle developer API operations.
Mapbox MCP DevKit Server是一款Model Context Protocol (MCP)服务,可让AI助手直接访问Mapbox开发者API:
- Style management - 样式管理:创建、列举、更新、删除、预览、校验、对比和优化样式
- Token management - 令牌管理:生成和列举带权限范围的访问令牌
- Validation - 校验:校验GeoJSON、表达式、样式和坐标
- Geographic utilities - 地理工具:计算边界框、转换坐标、查询瓦片
- Color tools - 颜色工具:检查WCAG对比度以满足可访问性要求
- Feedback - 反馈:获取用户反馈和报告
- Documentation - 文档:访问最新的Mapbox文档和参考资料
核心优势: 通过让AI处理开发者API操作,更快地构建Mapbox应用。
Setup & Installation
安装与配置
Prerequisites
前置条件
- Mapbox account with access token
- AI coding assistant that supports MCP (Claude Code, Cursor, Windsurf, Cline, etc.)
- 带访问令牌的Mapbox账号
- 支持MCP的AI编码助手(Claude Code、Cursor、Windsurf、Cline等)
Option 1: Hosted Server (Recommended)
选项1:托管服务(推荐)
Easiest setup - Use Mapbox's hosted DevKit MCP server at:
https://mcp-devkit.mapbox.com/mcpNo installation required, just configure your AI assistant.
Authentication: The hosted server supports OAuth, so no token configuration needed! Simply add the server URL:
最简单的配置方式 - 使用Mapbox官方托管的DevKit MCP服务,地址为:
https://mcp-devkit.mapbox.com/mcp无需安装,只需配置你的AI编码助手即可。
身份验证: 托管服务支持OAuth,因此不需要配置令牌!只需添加服务URL即可:
For Claude Desktop
Claude Desktop配置方式
Add to (macOS) or (Windows):
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonjson
{
"mcpServers": {
"mapbox-devkit-mcp": {
"command": "npx",
"args": ["mcp-remote", "https://mcp-devkit.mapbox.com/mcp"]
}
}
}You'll be prompted to authenticate via OAuth on first use.
添加到(macOS)或(Windows):
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonjson
{
"mcpServers": {
"mapbox-devkit-mcp": {
"command": "npx",
"args": ["mcp-remote", "https://mcp-devkit.mapbox.com/mcp"]
}
}
}首次使用时会提示你通过OAuth进行身份验证。
For Claude Code
Claude Code配置方式
Claude Code supports both user-level and project-level MCP configuration:
User-level (applies to all projects) - :
~/.claude.jsonjson
{
"mcpServers": {
"mapbox-devkit": {
"url": "https://mcp-devkit.mapbox.com/mcp"
}
}
}Project-level (specific project, can commit to git) - in repository root:
.mcp.jsonjson
{
"mcpServers": {
"mapbox-devkit": {
"url": "https://mcp-devkit.mapbox.com/mcp"
}
}
}See Claude Code settings documentation for more details on configuration scopes.
Claude Code支持用户级和项目级两种MCP配置:
用户级(对所有项目生效) - :
~/.claude.jsonjson
{
"mcpServers": {
"mapbox-devkit": {
"url": "https://mcp-devkit.mapbox.com/mcp"
}
}
}项目级(仅对指定项目生效,可提交到git) - 仓库根目录下的:
.mcp.jsonjson
{
"mcpServers": {
"mapbox-devkit": {
"url": "https://mcp-devkit.mapbox.com/mcp"
}
}
}更多配置范围的详情可查看Claude Code设置文档。
For Cursor
Cursor配置方式
Create or edit (project-local) or (global):
.cursor/mcp.json~/.cursor/mcp.jsonjson
{
"mcpServers": {
"mapbox-devkit": {
"url": "https://mcp-devkit.mapbox.com/mcp"
}
}
}After saving, restart Cursor. Click "Needs authentication" when prompted and follow the OAuth flow.
创建或编辑(项目级)或(全局):
.cursor/mcp.json~/.cursor/mcp.jsonjson
{
"mcpServers": {
"mapbox-devkit": {
"url": "https://mcp-devkit.mapbox.com/mcp"
}
}
}保存后重启Cursor,出现提示时点击「需要身份验证」,按照OAuth流程完成授权即可。
For VS Code with Copilot
安装了Copilot的VS Code配置方式
Create or edit :
mcp.jsonjson
{
"servers": {
"mapbox-devkit": {
"type": "http",
"url": "https://mcp-devkit.mapbox.com/mcp"
}
}
}After saving, refresh the MCP service in VS Code. Requires GitHub Copilot with MCP support enabled.
创建或编辑:
mcp.jsonjson
{
"servers": {
"mapbox-devkit": {
"type": "http",
"url": "https://mcp-devkit.mapbox.com/mcp"
}
}
}保存后刷新VS Code中的MCP服务,需要开启GitHub Copilot的MCP支持功能。
For Windsurf/Cline
Windsurf/Cline配置方式
Similar configuration using the hosted URL with OAuth support.
使用支持OAuth的托管URL进行类似配置即可。
Option 2: Self-Hosted (Advanced)
选项2:自建托管(高级)
For development, debugging, or customization:
bash
undefined适用于开发、调试或自定义场景:
bash
undefinedClone the DevKit server
克隆DevKit服务仓库
git clone https://github.com/mapbox/mcp-devkit-server.git
cd mcp-devkit-server
git clone https://github.com/mapbox/mcp-devkit-server.git
cd mcp-devkit-server
Install dependencies
安装依赖
npm install
npm install
Build the server
构建服务
npm run build
**Configuration for self-hosted (Claude Desktop):**
```json
{
"mcpServers": {
"MapboxDevKitServer": {
"command": "node",
"args": ["/Users/username/github-projects/mcp-devkit-server/dist/esm/index.js"],
"env": {
"MAPBOX_ACCESS_TOKEN": "some token"
}
}
}
}Replace with your actual path.
/Users/username/github-projects/npm run build
**自建服务的Claude Desktop配置:**
```json
{
"mcpServers": {
"MapboxDevKitServer": {
"command": "node",
"args": ["/Users/username/github-projects/mcp-devkit-server/dist/esm/index.js"],
"env": {
"MAPBOX_ACCESS_TOKEN": "some token"
}
}
}
}将替换为你本地的实际路径。
/Users/username/github-projects/Verify Installation
验证安装
Ask your AI assistant:
"List the available Mapbox DevKit tools"You should see 30+ tools including:
- Style tools: ,
create_style_tool,list_styles_tool,update_style_tool,delete_style_tool, etc.preview_style_tool - Token tools: ,
create_token_toollist_tokens_tool - Validation tools: ,
validate_geojson_tool,validate_style_toolvalidate_expression_tool - Geographic tools: ,
bounding_box_tool,coordinate_conversion_tooltilequery_tool - Documentation:
get_latest_mapbox_docs_tool
向你的AI助手提问:
"列出可用的Mapbox DevKit工具"你应该能看到30+个工具,包括:
- 样式工具: 、
create_style_tool、list_styles_tool、update_style_tool、delete_style_tool等preview_style_tool - 令牌工具: 、
create_token_toollist_tokens_tool - 校验工具: 、
validate_geojson_tool、validate_style_toolvalidate_expression_tool - 地理工具: 、
bounding_box_tool、coordinate_conversion_tooltilequery_tool - 文档工具:
get_latest_mapbox_docs_tool
Core Workflows
核心工作流
1. Style Management
1. 样式管理
Create a style conversationally:
"Create a dark mode Mapbox style with 3D buildings, emphasize parks in green,
and use blue for water. Name it 'app-dark-mode'."The AI will use tool to:
create_style_tool- Generate style JSON following Mapbox Style Spec
- Upload to your Mapbox account
- Return style ID and preview URL
Update existing style:
"Update style mapbox://styles/username/style-id to make roads more prominent
and reduce building opacity to 0.6"Validate style:
"Validate this style JSON: [paste style]"对话式创建样式:
"创建一个深色模式的Mapbox样式,包含3D建筑,公园用绿色突出显示,水体用蓝色,命名为'app-dark-mode'"AI会使用工具完成以下操作:
create_style_tool- 生成符合Mapbox Style Spec的样式JSON
- 上传到你的Mapbox账号
- 返回样式ID和预览URL
更新现有样式:
"更新样式mapbox://styles/username/style-id,让道路更醒目,建筑透明度调整为0.6"校验样式:
"校验这个样式JSON:[粘贴样式内容]"2. Token Management
2. 令牌管理
Create scoped token:
"Create a Mapbox token with these scopes:
- styles:read
- fonts:read
- datasets:read
Restrict it to domains: localhost, example.com"List existing tokens:
"Show me all my Mapbox tokens and their scopes"Use case: Generate tokens for different environments (development, staging, production) with appropriate restrictions.
创建带权限范围的令牌:
"创建一个Mapbox令牌,包含以下权限:
- styles:read
- fonts:read
- datasets:read
限制可访问的域名:localhost, example.com"列举现有令牌:
"展示我所有的Mapbox令牌及其权限范围"使用场景: 为不同环境(开发、预发、生产)生成带有合适权限限制的令牌。
3. Data Validation
3. 数据校验
Validate GeoJSON:
"Validate this GeoJSON and show any errors:
{
\"type\": \"FeatureCollection\",
\"features\": [...]
}"Validate expressions:
"Is this a valid Mapbox expression?
['case', ['<', ['get', 'population'], 1000], 'small', 'large']"Coordinate conversion:
"Convert longitude -122.4194, latitude 37.7749 from WGS84 to Web Mercator"校验GeoJSON:
"校验这个GeoJSON并展示所有错误:
{
\"type\": \"FeatureCollection\",
\"features\": [...]
}"校验表达式:
"这是一个有效的Mapbox表达式吗?
['case', ['<', ['get', 'population'], 1000], 'small', 'large']"坐标转换:
"将经度-122.4194、纬度37.7749从WGS84坐标系转换为Web Mercator坐标系"4. Documentation Access
4. 文档访问
Get style spec info:
"What properties are available for fill layers in Mapbox GL JS?"Check token scopes:
"What token scopes do I need to use the Directions API?"Streets v8 fields:
"What fields are available in the 'road' layer of Streets v8?"获取样式规范信息:
"Mapbox GL JS中的填充层有哪些可用属性?"查询令牌权限范围:
"使用路线规划API需要哪些令牌权限?"查询Streets v8图层字段:
"Streets v8的'road'图层有哪些可用字段?"Design Patterns
设计模式
Pattern 1: Iterative Style Development
模式1:迭代式样式开发
Workflow:
- Describe desired style in natural language
- AI creates initial style via MCP
- View preview URL
- Request adjustments
- AI updates style via MCP
- Repeat until satisfied
Example conversation:
You: "Create a style for a real estate app - emphasize property boundaries,
show parks prominently, muted roads"
AI: [Creates style, returns ID and preview URL]
You: "Make the property boundaries purple and thicker"
AI: [Updates style]
You: "Perfect! Now add POI icons for schools and transit"
AI: [Updates style with symbols]Benefits:
- No manual JSON editing
- Visual feedback via preview URLs
- Rapid iteration
工作流:
- 用自然语言描述期望的样式
- AI通过MCP创建初始样式
- 查看预览URL
- 提出调整需求
- AI通过MCP更新样式
- 重复直到满足需求
对话示例:
你:"为房地产应用创建一个样式,突出显示物业边界,公园展示醒目,道路使用低饱和度颜色"
AI: [创建样式,返回ID和预览URL]
你:"把物业边界改成紫色,增加线条粗细"
AI: [更新样式]
你:「完美!现在添加学校和交通站点的POI图标」
AI: [添加符号更新样式]优势:
- 无需手动编辑JSON
- 通过预览URL获得可视化反馈
- 快速迭代
Pattern 2: Environment-Specific Tokens
模式2:按环境区分令牌
Workflow:
- Define requirements per environment
- AI creates tokens with appropriate scopes/restrictions
- Store securely in environment variables
Example:
You: "Create three tokens:
1. Development - all scopes, localhost only
2. Staging - read-only scopes, staging.example.com
3. Production - minimal scopes, example.com only"
AI: [Creates three tokens with specified configurations]Benefits:
- Least-privilege access
- Domain restrictions prevent token misuse
- Clear separation of concerns
工作流:
- 定义每个环境的权限需求
- AI创建带合适权限/限制的令牌
- 安全存储在环境变量中
示例:
你:"创建三个令牌:
1. 开发环境 - 全权限,仅允许localhost访问
2. 预发环境 - 只读权限,仅允许staging.example.com访问
3. 生产环境 - 最小权限,仅允许example.com访问"
AI: [按照指定配置创建三个令牌]优势:
- 最小权限访问
- 域名限制防止令牌滥用
- 清晰的职责分离
Pattern 3: Validation-First Development
模式3:校验优先开发
Workflow:
- Design data structure
- Validate GeoJSON before using
- Validate expressions before adding to style
- Catch errors early
Example:
You: "I have GeoJSON with restaurant locations. Validate it and check for
any missing required properties"
AI: [Validates, reports any issues]
You: "Now create a style that displays these restaurants with icons sized
by rating. Validate the expression first."
AI: [Validates expression, then creates style]Benefits:
- Catch errors before deployment
- Ensure data integrity
- Faster debugging
工作流:
- 设计数据结构
- 使用前先校验GeoJSON
- 添加到样式前先校验表达式
- 提前发现错误
示例:
你:"我有一份包含餐厅位置的GeoJSON,校验它并检查是否缺少必填属性"
AI: [完成校验,报告所有问题]
你:"现在创建一个样式,用图标展示这些餐厅,图标大小根据评分动态调整,先校验表达式"
AI: [先校验表达式,再创建样式]优势:
- 部署前发现错误
- 保证数据完整性
- 更快的调试效率
Pattern 4: Documentation-Driven Development
模式4:文档驱动开发
Workflow:
- Ask about Mapbox capabilities
- Get authoritative documentation
- Implement with correct patterns
- Validate implementation
Example:
You: "How do I create a choropleth map in Mapbox GL JS?"
AI: [Retrieves docs, provides pattern]
You: "Create a style with that pattern for population density data"
AI: [Creates style following documented pattern]Benefits:
- Always use latest best practices
- No outdated Stack Overflow answers
- Official Mapbox guidance
工作流:
- 询问Mapbox相关能力
- 获取官方权威文档
- 按照正确模式实现
- 校验实现结果
示例:
你:"怎么在Mapbox GL JS中创建分级统计图?"
AI: [检索文档,提供实现模式]
你:"按照这个模式为人口密度数据创建一个样式"
AI: [按照官方文档模式创建样式]优势:
- 始终使用最新最佳实践
- 不会用到Stack Overflow上过时的答案
- 官方Mapbox指导
When to Use MCP DevKit
MCP DevKit适用场景
✅ Use DevKit when:
✅ 适合使用DevKit的场景:
- Creating/modifying styles conversationally
- Generating tokens programmatically
- Validating data during development
- Learning Mapbox APIs through natural language
- Rapid prototyping of map applications
- Automated style generation workflows
- Documentation lookup during coding
- 对话式创建/修改样式
- 程序化生成令牌
- 开发过程中校验数据
- 通过自然语言学习Mapbox API
- 地图应用快速原型开发
- 自动化样式生成工作流
- 编码过程中查询文档
❌ Don't use DevKit for:
❌ 不适合使用DevKit的场景:
- Runtime operations in production apps
- High-frequency style updates (use Mapbox APIs directly)
- Client-side operations (DevKit is development-time only)
- Tile serving or map rendering
- User-facing features requiring low latency
- 生产应用的运行时操作
- 高频样式更新(直接使用Mapbox API)
- 客户端操作(DevKit仅用于开发阶段)
- 瓦片服务或地图渲染
- 需要低延迟的用户面向功能
Integration with Existing Tools
与现有工具集成
With Mapbox Studio
与Mapbox Studio集成
DevKit complements, doesn't replace Studio:
- DevKit: Quick iterations, automated workflows, AI assistance
- Studio: Visual editing, fine-tuning, team collaboration
Pattern: Use DevKit for initial creation, Studio for refinement.
DevKit是对Studio的补充而非替代:
- DevKit: 快速迭代、自动化工作流、AI辅助
- Studio: 可视化编辑、精细调整、团队协作
模式: 用DevKit完成初始创建,用Studio做精细化调整。
With Mapbox APIs
与Mapbox API集成
DevKit wraps Mapbox APIs but doesn't replace them:
- DevKit: Development-time operations via AI
- APIs: Production runtime operations
Pattern: Use DevKit during development, APIs in production code.
DevKit封装了Mapbox API但不会替代它:
- DevKit: 开发阶段通过AI完成操作
- API: 生产环境运行时操作
模式: 开发阶段使用DevKit,生产代码中使用API。
With Version Control
与版本控制集成
Pattern: Save generated styles to git for review and rollback.
You: "Create a new style for the home page map and save the JSON to
styles/home-map.json"
AI: [Creates style, writes JSON to file]
You: [Review, commit to git]模式: 将生成的样式保存到git中用于审核和回滚。
你:"为首页地图创建一个新样式,将JSON保存到styles/home-map.json"
AI: [创建样式,将JSON写入文件]
你: [审核内容,提交到git]Best Practices
最佳实践
Security
安全
- Never commit access tokens - Use environment variables
- Use scoped tokens - Minimal necessary permissions
- Add URL restrictions - Limit to your domains
- Rotate tokens regularly - Generate new tokens periodically
- 永远不要提交访问令牌 - 使用环境变量存储
- 使用带范围的令牌 - 只授予必要的最小权限
- 添加URL限制 - 仅允许你的域名访问
- 定期轮换令牌 - 定期生成新令牌
Style Management
样式管理
- Version your styles - Save JSON to source control
- Use meaningful names - not
prod-light-modestyle-123 - Document decisions - Add comments explaining style choices
- Preview before deploying - Always check preview URL
- 为样式做版本管理 - 将JSON保存到源代码管理中
- 使用有意义的名称 - 用而非
prod-light-modestyle-123 - 记录决策 - 添加注释说明样式选择的原因
- 部署前预览 - 始终检查预览URL
Validation
校验
- Validate early - Check data before creating styles
- Use strict validation - Don't skip validation steps
- Test expressions - Validate before adding to styles
- Verify coordinates - Ensure correct format and bounds
- 尽早校验 - 创建样式前先检查数据
- 使用严格校验 - 不要跳过校验步骤
- 测试表达式 - 添加到样式前先校验
- 验证坐标 - 确保格式和边界正确
Documentation
文档
- Ask specific questions - "What are fill-extrusion properties?"
- Reference versions - Specify GL JS version if relevant
- Cross-reference - Validate AI responses against official docs
- 提出具体问题 - 比如「fill-extrusion有哪些属性?」
- 指定版本 - 如果有需要说明GL JS的版本
- 交叉验证 - 对照官方文档校验AI的回答
Troubleshooting
问题排查
DevKit not appearing in AI assistant
AI助手不显示DevKit
Check:
- MCP server running? Check logs
- Config file in correct location?
- Token environment variable set?
- Path to correct?
index.js
Solution: Restart AI assistant after config changes.
检查项:
- MCP服务是否运行?查看日志
- 配置文件是否在正确位置?
- 令牌环境变量是否设置?
- 的路径是否正确?
index.js
解决方案: 修改配置后重启AI助手。
Style creation fails
样式创建失败
Check:
- Access token has scope
styles:write - Style name is unique
- JSON is valid Mapbox Style Spec
Solution: Use tool first.
validate_style_tool检查项:
- 访问令牌拥有权限
styles:write - 样式名称唯一
- JSON符合Mapbox Style Spec规范
解决方案: 先使用工具校验。
validate_style_toolToken creation fails
令牌创建失败
Check:
- Access token has scope
tokens:write - Requested scopes are valid
- URL restrictions are well-formed
Solution: Check token scope documentation via DevKit.
检查项:
- 访问令牌拥有权限
tokens:write - 请求的权限范围有效
- URL限制格式正确
解决方案: 通过DevKit查询令牌权限文档。
Validation errors
校验错误
Check:
- GeoJSON follows spec (RFC 7946)
- Coordinates are [longitude, latitude] order
- Properties match expected schema
Solution: Ask AI to explain validation errors.
检查项:
- GeoJSON符合RFC 7946规范
- 坐标顺序为[经度, 纬度]
- 属性符合预期的 schema
解决方案: 让AI解释校验错误信息。
Example Workflows
示例工作流
Build a Restaurant Finder
构建餐厅查找应用
You: "I'm building a restaurant finder app. Create:
1. A light, neutral style emphasizing restaurants
2. A token for localhost with minimal scopes
3. Validate this GeoJSON with restaurant locations: [paste]"
AI: [Creates style, token, validates data]
You: "Add filters to show only 4+ star restaurants"
AI: [Updates style with expression]
You: "Generate a preview URL"
AI: [Returns preview]你:"我正在构建一个餐厅查找应用,需要:
1. 一个浅色中性风格的样式,突出显示餐厅
2. 一个供localhost使用的最小权限令牌
3. 校验这份包含餐厅位置的GeoJSON:[粘贴内容]"
AI: [创建样式、生成令牌、完成数据校验]
你:"添加过滤器,仅展示4星以上的餐厅"
AI: [用表达式更新样式]
你:"生成预览URL"
AI: [返回预览地址]Create Multi-Environment Setup
创建多环境配置
You: "Set up styles and tokens for dev, staging, prod:
- Dev: Full access, localhost
- Staging: Read-only, staging.example.com
- Prod: Minimal scopes, example.com
Each environment needs its own style variant."
AI: [Creates 3 styles and 3 tokens with specifications]你:"为开发、预发、生产环境配置样式和令牌:
- 开发环境:全权限,仅localhost可访问
- 预发环境:只读权限,仅staging.example.com可访问
- 生产环境:最小权限,仅example.com可访问
每个环境需要独立的样式版本。"
AI: [按照要求创建3个样式和3个令牌]Validate Third-Party Data
校验第三方数据
You: "I received GeoJSON from a vendor. Validate it, check for:
- Correct coordinate order
- Valid geometry types
- Required properties: name, address, category"
AI: [Validates, reports issues]
You: "Fix the issues and save cleaned data to data/locations.json"
AI: [Fixes, saves file]你:"我从供应商拿到了一份GeoJSON,校验它,检查以下内容:
- 坐标顺序正确
- 几何类型有效
- 包含必填属性:name、address、category"
AI: [完成校验,报告问题]
你:"修复这些问题,将清洗后的数据保存到data/locations.json"
AI: [修复问题,保存文件]Resources
参考资源
When to Use This Skill
何时使用本技能
Invoke this skill when:
- Setting up Mapbox development environment with AI assistance
- Creating or modifying Mapbox styles through AI
- Managing access tokens programmatically
- Validating GeoJSON or expressions during development
- Learning Mapbox APIs with AI guidance
- Automating style generation workflows
- Building Mapbox applications with AI coding assistants
以下场景可调用本技能:
- 借助AI辅助搭建Mapbox开发环境
- 通过AI创建或修改Mapbox样式
- 程序化管理访问令牌
- 开发过程中校验GeoJSON或表达式
- 在AI指导下学习Mapbox API
- 自动化样式生成工作流
- 借助AI编码助手构建Mapbox应用