Skip to content

Commit a78fbfc

Browse files
jussi-sajussi-sa
committed
doc
1 parent e7bb2f4 commit a78fbfc

2 files changed

Lines changed: 245 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,10 @@ The `MAPBOX_ACCESS_TOKEN` environment variable is required. **Each tool requires
118118

119119
Complete set of tools for managing Mapbox styles via the Styles API:
120120

121+
**Style Builder Tool** - Create and modify Mapbox styles programmatically through conversational prompts
122+
123+
📖 **[See the Style Builder documentation for detailed usage and examples →](./docs/STYLE_BUILDER.md)**
124+
121125
**ListStylesTool** - List all styles for a Mapbox account
122126

123127
- Input: `limit` (optional - max number of styles), `start` (optional - pagination token)

‎docs/STYLE_BUILDER.md‎

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
# Mapbox Style Builder Tool
2+
3+
## Overview
4+
5+
The Style Builder tool is a powerful utility for creating and modifying Mapbox styles programmatically. It provides a conversational interface to build complex map styles with various customizations for layers, labels, boundaries, roads, POIs, and more.
6+
7+
## Important Limitations
8+
9+
⚠️ **Resource Access Limitation**: Style resources (sprites, glyphs, and other assets) cannot currently be accessed through clients like Claude Desktop. This is a known limitation when using the tool through MCP (Model Context Protocol) interfaces.
10+
11+
## Getting Started
12+
13+
To start building a style, you can initiate the conversation with prompts like:
14+
15+
- "Can you help me building a style, what customizations can I make?"
16+
- "Create a new Mapbox style with specific features"
17+
- "Modify my existing style to add/remove layers"
18+
19+
The tool can be used for both **creating new styles** and **modifying existing styles**.
20+
21+
## Example Style Creation Prompts
22+
23+
### 1. Comprehensive Style with All Labels
24+
25+
**Prompt**: "Create a style with all possible labels enabled, make every label have a different look so that they can be distinguished. Include also all boundaries (countries, provinces). And all roads with different colors and opacities. POIs with icons."
26+
27+
This creates a maximally detailed style where:
28+
29+
- Every label type has distinct visual properties
30+
- All administrative boundaries are visible
31+
- Roads are color-coded by type
32+
- POIs display with appropriate icons
33+
34+
### 2. Selective Administrative and Road Display
35+
36+
**Prompt**: "Create a style with only administrative boundaries having admin_level 0 or 1, and roads with class motorway and oneway true"
37+
38+
This creates a minimalist style focusing on:
39+
40+
- Country and state/province boundaries only
41+
- Motorways that are one-way streets
42+
- Clean, uncluttered appearance
43+
44+
### 3. Zoom-Based Road Visibility
45+
46+
**Prompt**: "Create a style with minor roads only visible above zoom 14, service roads only above zoom 16, with zoom-based width increase"
47+
48+
This creates a progressive detail style where:
49+
50+
- Road visibility depends on zoom level
51+
- Road widths increase smoothly with zoom
52+
- Performance optimized for different zoom ranges
53+
54+
### 4. Comprehensive POI Filtering
55+
56+
**Prompt**: "Create a style with only POIs showing maki icons for restaurants, cafes, and bars, each in different colors"
57+
58+
This creates a food & beverage focused style with:
59+
60+
- Selective POI display
61+
- Color-coded categories
62+
- Clear maki icon representation
63+
64+
### 5. Complex Boundary Rules
65+
66+
**Prompt**: "Create a style with international boundaries (admin_level 0) that are not maritime and not disputed in solid black, disputed ones in red dashed"
67+
68+
This creates a politically-aware style with:
69+
70+
- Different styling for disputed boundaries
71+
- Maritime boundary filtering
72+
- Visual hierarchy for boundary types
73+
74+
## Common Customizations
75+
76+
The Style Builder supports extensive customizations including:
77+
78+
### Layers
79+
80+
- Add/remove specific layer types
81+
- Modify layer ordering
82+
- Apply filters and conditions
83+
84+
### Labels
85+
86+
- Control text size, font, and color
87+
- Set visibility by zoom level
88+
- Adjust label density and overlap behavior
89+
90+
### Roads
91+
92+
- Customize by road class (motorway, trunk, primary, secondary, etc.)
93+
- Apply different styles for bridges and tunnels
94+
- Control casing and width properties
95+
96+
### Boundaries
97+
98+
- Filter by administrative level
99+
- Style disputed boundaries differently
100+
- Control maritime boundary display
101+
102+
### POIs (Points of Interest)
103+
104+
- Filter by category or specific types
105+
- Customize icons and colors
106+
- Control density and zoom-based visibility
107+
108+
### Buildings
109+
110+
- 3D extrusion settings
111+
- Color by height or type
112+
- Opacity and visibility controls
113+
114+
### Terrain and Hillshading
115+
116+
- Add terrain layers
117+
- Adjust hillshade intensity
118+
- Control exaggeration factors
119+
120+
## Advanced Features
121+
122+
### Working with Existing Styles
123+
124+
The tool can modify existing Mapbox styles:
125+
126+
- Import a style by ID or URL
127+
- Make targeted modifications
128+
- Preserve existing customizations while adding new features
129+
130+
### Performance Optimization
131+
132+
The builder can optimize styles for:
133+
134+
- Mobile devices (reduced layer count)
135+
- High-density displays
136+
- Specific zoom ranges
137+
138+
### Theme Variations
139+
140+
Create multiple versions of a style:
141+
142+
- Light and dark modes
143+
- Seasonal variations
144+
- Brand-specific color schemes
145+
146+
## Best Practices
147+
148+
1. **Start Simple**: Begin with basic requirements and iteratively add complexity
149+
2. **Test at Multiple Zooms**: Ensure your style works well across zoom levels
150+
3. **Consider Performance**: More layers and complex filters can impact rendering speed
151+
4. **Use Consistent Naming**: When creating custom layers, use clear, descriptive IDs
152+
5. **Document Your Choices**: Keep notes on why certain styling decisions were made
153+
154+
## Troubleshooting
155+
156+
### Common Issues
157+
158+
1. **Resources Not Loading**: Remember that sprite and glyph resources may not be accessible in Claude Desktop
159+
2. **Layer Conflicts**: Check layer ordering if elements appear hidden
160+
3. **Performance Issues**: Reduce layer count or simplify filters for better performance
161+
4. **Zoom Range Problems**: Verify minzoom and maxzoom settings on layers
162+
163+
### Getting Help
164+
165+
When encountering issues, provide:
166+
167+
- The style configuration you're trying to achieve
168+
- Any error messages received
169+
- The platform/client you're using
170+
171+
## Technical Details
172+
173+
The Style Builder tool:
174+
175+
- Generates Mapbox GL JS compatible style specifications
176+
- Follows the Mapbox Style Specification v8
177+
- Supports all standard Mapbox layer types
178+
- Can output styles for use in Mapbox GL JS, native SDKs, and Mapbox Studio
179+
180+
## Limitations and Considerations
181+
182+
- Some advanced Studio-only features may not be available
183+
- Custom data sources need to be added separately
184+
- Sprite and font resources must be hosted and accessible
185+
- Complex expressions may need manual refinement
186+
187+
## Integration with Other Tools
188+
189+
Once you've built or modified a style using the Style Builder:
190+
191+
### Creating a New Style
192+
193+
Use the **CreateStyleTool** to save your generated style to your Mapbox account:
194+
195+
- The tool will create a new style with your specifications
196+
- Returns a style ID that you can use for further modifications
197+
198+
### Updating an Existing Style
199+
200+
Use the **UpdateStyleTool** to apply modifications to an existing style:
201+
202+
- Provide the style ID or name of the style you want to update (if the name uniquely identifies it)
203+
- The tool will update the style with your new specifications
204+
205+
### Previewing Your Style
206+
207+
Use the **PreviewStyleTool** to generate a preview URL:
208+
209+
- Instantly view your style in a browser
210+
- Test different zoom levels and locations
211+
- Share the preview link with team members
212+
213+
**Example workflow for new style:**
214+
215+
1. "Build a style with only roads and labels"
216+
2. "Now create this style in my account" → Uses CreateStyleTool
217+
3. "Generate a preview link for this style" → Uses PreviewStyleTool
218+
219+
**Example workflow for modifying existing style:**
220+
221+
1. "Modify my 'Winter Theme' style to add POIs with restaurant icons"
222+
2. "Update the style in my account" → Uses UpdateStyleTool (finds style by name)
223+
3. "Generate a preview link for this style" → Uses PreviewStyleTool
224+
225+
**Alternative with style ID:**
226+
227+
1. "Modify style clxyz123... to add building extrusions"
228+
2. "Update the style in my account" → Uses UpdateStyleTool (uses style ID)
229+
3. "Generate a preview link for this style" → Uses PreviewStyleTool
230+
231+
## Next Steps
232+
233+
After creating or modifying your style:
234+
235+
1. Test in your target environment using the preview URL
236+
2. Use the style in your applications with the style ID
237+
3. Optimize for your specific use case
238+
4. Consider creating variations for different contexts
239+
5. Your styles are also viewable and editable in Mapbox Studio if needed
240+
241+
For more information on Mapbox styles, refer to the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/).

0 commit comments

Comments
 (0)