Skip to content

Commit 08c16a0

Browse files
jussi-sajussi-sa
authored
Merge pull request #21 from mapbox/style-helper-streets-v12
Style builder tool
2 parents 4eaf75c + a78fbfc commit 08c16a0

19 files changed

Lines changed: 3842 additions & 384 deletions

‎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/).

‎docs/style-resource-example.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# Mapbox Style Layers Resource Example
2+
3+
This example demonstrates how the Mapbox Style Layers Resource guides LLMs in creating Mapbox styles based on natural language requests.
4+
5+
## How It Works
6+
7+
1. The `MapboxStyleLayersResource` is registered as an MCP resource at `resource://mapbox-style-layers`
8+
2. When an LLM receives a request like "create a style that highlights railways and parks, and changes water to yellow", it can:
9+
- Query the resource to understand available layers
10+
- Get the correct source-layer names, filters, and properties
11+
- Generate proper Mapbox GL style JSON
12+
13+
## Example User Requests
14+
15+
### Request 1: "Highlight railways and parks, make water yellow"
16+
17+
The resource guides the LLM to:
18+
19+
- Use `water` layer (source-layer: "water") with `fill-color: "#ffff00"`
20+
- Use `landuse` layer filtered by `class: "park"` with bright green color
21+
- Use `road` layer filtered by `class: ["major_rail", "minor_rail"]` with red color
22+
23+
### Request 2: "Create a dark mode map with prominent buildings"
24+
25+
The resource guides the LLM to:
26+
27+
- Set `land` background layer to dark color
28+
- Use `building` layer with light color and high opacity
29+
- Adjust text colors for visibility on dark background
30+
31+
### Request 3: "Show only major roads and hide all labels"
32+
33+
The resource guides the LLM to:
34+
35+
- Include only `motorways` and `primary_roads` layers
36+
- Exclude all label layers (`place_labels`, `road_labels`, `poi_labels`)
37+
- Use appropriate filters like `["match", ["get", "class"], ["motorway", "trunk"], true, false]`
38+
39+
## Resource Content Structure
40+
41+
The resource provides:
42+
43+
1. **Quick Reference**: Maps common user requests to specific layers
44+
2. **Layer Categories**: Groups layers by type (water, transportation, labels, etc.)
45+
3. **Detailed Specifications**: For each layer:
46+
- Description
47+
- Source layer name
48+
- Layer type (fill, line, symbol, etc.)
49+
- Common filters
50+
- Paint properties with examples
51+
- Layout properties with examples
52+
- Example user requests
53+
54+
4. **Expression Examples**: Common Mapbox GL expression patterns:
55+
- Zoom-based interpolation
56+
- Feature property matching
57+
- Conditional styling
58+
59+
## Usage in LLM Context
60+
61+
When the LLM needs to create or modify a Mapbox style:
62+
63+
1. It reads the resource to understand available layers
64+
2. Maps user intent to specific layers using the descriptions and examples
65+
3. Generates proper filter expressions using the provided patterns
66+
4. Creates valid paint and layout properties
67+
68+
## Example Generated Style
69+
70+
Based on "highlight railways and parks, yellow water":
71+
72+
```json
73+
{
74+
"version": 8,
75+
"name": "Custom Style",
76+
"sources": {
77+
"composite": {
78+
"type": "vector",
79+
"url": "mapbox://mapbox.mapbox-streets-v8"
80+
}
81+
},
82+
"layers": [
83+
{
84+
"id": "land",
85+
"type": "background",
86+
"paint": {
87+
"background-color": "#f8f4f0"
88+
}
89+
},
90+
{
91+
"id": "water",
92+
"type": "fill",
93+
"source": "composite",
94+
"source-layer": "water",
95+
"paint": {
96+
"fill-color": "#ffff00"
97+
}
98+
},
99+
{
100+
"id": "parks",
101+
"type": "fill",
102+
"source": "composite",
103+
"source-layer": "landuse",
104+
"filter": ["==", ["get", "class"], "park"],
105+
"paint": {
106+
"fill-color": "#00ff00",
107+
"fill-opacity": 0.9
108+
}
109+
},
110+
{
111+
"id": "railways",
112+
"type": "line",
113+
"source": "composite",
114+
"source-layer": "road",
115+
"filter": [
116+
"match",
117+
["get", "class"],
118+
["major_rail", "minor_rail"],
119+
true,
120+
false
121+
],
122+
"paint": {
123+
"line-color": "#ff0000",
124+
"line-width": [
125+
"interpolate",
126+
["exponential", 1.5],
127+
["zoom"],
128+
14,
129+
2,
130+
20,
131+
8
132+
]
133+
}
134+
}
135+
]
136+
}
137+
```
138+
139+
## Benefits
140+
141+
1. **Accuracy**: LLM uses correct source-layer names and properties
142+
2. **Completeness**: All necessary filter expressions are included
143+
3. **Best Practices**: Follows Mapbox GL style specification patterns
144+
4. **Natural Language**: Users can describe what they want without knowing technical details

0 commit comments

Comments
 (0)