[prompts] Add MCP prompts for multi-step workflows

Implement three high-value prompts that orchestrate multiple tools:

1. create-and-preview-style: Create a map style with automatic token
   management. Checks for existing public tokens, creates one if needed,
   then creates the style and generates a preview link.

2. build-custom-map: Use conversational AI to build themed map styles
   (e.g., "dark cyberpunk", "nature-focused"). Leverages the Style
   Builder tool for AI-powered style generation.

3. analyze-geojson: Complete GeoJSON analysis workflow with validation,
   bounding box calculation, coordinate conversion, and visualization.

Infrastructure:
- BasePrompt abstract class for all prompts
- promptRegistry for centralized prompt management
- Integration with MCP server using Zod schemas
- Full test coverage (37 new tests, all passing)

Documentation updated in README.md and CLAUDE.md with usage examples.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

Author: mattpodwysocki

CLAUDE.md

@@ -18,20 +18,25 @@ The codebase organizes into:
 - `src/index.ts` - Main entry point with .env loading and server initialization
 - `src/config/toolConfig.ts` - Configuration parser for tool filtering and MCP-UI toggles
 - `src/tools/` - MCP tool implementations with `BaseTool` abstract class and registry
+- `src/prompts/` - MCP prompt implementations with `BasePrompt` abstract class and registry
 - `src/resources/` - Static reference data (style specs, token scopes, Streets v8 fields)
 - `src/utils/` - HTTP pipeline, JWT parsing, tracing, and version utilities
 
 ## Key Architectural Patterns
 
 **Tool Architecture:** All tools extend `BaseTool<InputSchema, OutputSchema>`. Tools auto-validate inputs using Zod schemas. Each tool lives in `src/tools/tool-name-tool/` with separate `*.schema.ts` and `*.tool.ts` files.
 
+**Prompt Architecture:** All prompts extend `BasePrompt` abstract class. Prompts orchestrate multi-step workflows, guiding AI assistants through complex tasks with best practices built-in. Each prompt lives in `src/prompts/` with separate files per prompt (e.g., `CreateAndPreviewStylePrompt.ts`). Prompts use kebab-case naming (e.g., `create-and-preview-style`).
+
 **HTTP Pipeline System:** "Never patch global.fetch—use HttpPipeline with dependency injection instead." The `HttpPipeline` class applies policies (User-Agent, retry logic) via a chain-of-responsibility pattern. See `src/utils/httpPipeline.ts:20`.
 
 **Resource System:** Static reference data exposed as MCP resources using URI pattern `resource://mapbox-*`, including style layer specs, Streets v8 field definitions, and token scope documentation.
 
 **Token Management:** Tools receive `MAPBOX_ACCESS_TOKEN` via `extra.authInfo.token` or environment variable. Token scope validation is critical—most tool failures stem from insufficient scopes (see `README.md` for per-tool requirements).
 
-**Tool Registry:** Tools are auto-discovered via `src/tools/index.ts` exports. No manual registration required—just export from index.
+**Tool Registry:** Tools are auto-discovered via `src/tools/toolRegistry.ts` exports. No manual registration required—just export from registry.
+
+**Prompt Registry:** Prompts are registered in `src/prompts/promptRegistry.ts`. To add a new prompt, create the prompt class and add it to the `ALL_PROMPTS` array. The main server automatically registers all prompts with proper Zod schema conversion.
 
 ## Essential Workflows
 

README.md

@@ -15,6 +15,7 @@ https://github.com/user-attachments/assets/8b1b8ef2-9fba-4951-bc9a-beaed4f6aff6
     - [Hosted MCP Endpoint](#hosted-mcp-endpoint)
     - [Getting Your Mapbox Access Token](#getting-your-mapbox-access-token)
   - [Tools](#tools)
+  - [Prompts](#prompts)
     - [Documentation Tools](#documentation-tools)
     - [Reference Tools](#reference-tools)
     - [Style Management Tools](#style-management-tools)
@@ -453,6 +454,98 @@ An array of four numbers representing the bounding box: `[minX, minY, maxX, maxY
 - "Calculate the bounding box of this GeoJSON file" (then upload a .geojson file)
 - "What's the bounding box for the coordinates in the uploaded parks.geojson file?"
 
+## Prompts
+
+MCP Prompts are pre-built workflow templates that guide AI assistants through multi-step tasks. They orchestrate multiple tools in the correct sequence, providing best practices and error handling built-in.
+
+**Available Prompts:**
+
+### create-and-preview-style
+
+Create a new Mapbox map style and generate a shareable preview link with automatic token management.
+
+**Arguments:**
+
+- `style_name` (required): Name for the new map style
+- `style_description` (optional): Description of the style theme or purpose
+- `base_style` (optional): Base style to start from (e.g., "streets-v12", "dark-v11")
+- `preview_location` (optional): Location to center the preview map
+- `preview_zoom` (optional): Zoom level for the preview (0-22, default: 12)
+
+**What it does:**
+
+1. Checks for an existing public token with `styles:read` scope
+2. Creates a new public token if needed
+3. Creates the map style
+4. Generates a preview link
+
+**Example usage:**
+
+```
+Use prompt: create-and-preview-style
+Arguments:
+  style_name: "My Custom Map"
+  style_description: "A dark-themed map for nighttime navigation"
+  base_style: "dark-v11"
+  preview_location: "San Francisco"
+  preview_zoom: "13"
+```
+
+### build-custom-map
+
+Use conversational AI to build a custom styled map based on a theme description.
+
+**Arguments:**
+
+- `theme` (required): Theme description (e.g., "dark cyberpunk", "nature-focused", "minimal monochrome")
+- `emphasis` (optional): Features to emphasize (e.g., "parks and green spaces", "transit lines")
+- `preview_location` (optional): Location to center the preview map
+- `preview_zoom` (optional): Zoom level for the preview (0-22, default: 12)
+
+**What it does:**
+
+1. Uses the Style Builder tool to create a themed style based on your description
+2. Creates the style in your Mapbox account
+3. Generates a preview link
+
+**Example usage:**
+
+```
+Use prompt: build-custom-map
+Arguments:
+  theme: "retro 80s neon"
+  emphasis: "nightlife and entertainment venues"
+  preview_location: "Tokyo"
+  preview_zoom: "14"
+```
+
+### analyze-geojson
+
+Analyze and visualize GeoJSON data with automatic validation and bounding box calculation.
+
+**Arguments:**
+
+- `geojson_data` (required): GeoJSON object or string to analyze
+- `show_bounds` (optional): Calculate and display bounding box (true/false, default: true)
+- `convert_coordinates` (optional): Provide Web Mercator conversion examples (true/false, default: false)
+
+**What it does:**
+
+1. Validates GeoJSON format
+2. Calculates bounding box (if requested)
+3. Provides coordinate conversion examples (if requested)
+4. Generates an interactive visualization link
+
+**Example usage:**
+
+```
+Use prompt: analyze-geojson
+Arguments:
+  geojson_data: {"type":"FeatureCollection","features":[...]}
+  show_bounds: "true"
+  convert_coordinates: "false"
+```
+
 ## Resources
 
 This server exposes static reference documentation as MCP Resources. While these are primarily accessed through the `get_reference_tool`, MCP clients that fully support the resources protocol can access them directly.

src/index.ts

@@ -11,9 +11,11 @@ import { SpanStatusCode } from '@opentelemetry/api';
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
 import { parseToolConfigFromArgs, filterTools } from './config/toolConfig.js';
 import { getAllTools } from './tools/toolRegistry.js';
 import { getAllResources } from './resources/resourceRegistry.js';
+import { getAllPrompts } from './prompts/promptRegistry.js';
 import { getVersionInfo } from './utils/versionUtils.js';
 import {
   initializeTracing,
@@ -64,7 +66,8 @@ const server = new McpServer(
   {
     capabilities: {
       tools: {},
-      resources: {}
+      resources: {},
+      prompts: {}
     }
   }
 );
@@ -80,6 +83,37 @@ resources.forEach((resource) => {
   resource.installTo(server);
 });
 
+// Register prompts to the server
+const prompts = getAllPrompts();
+prompts.forEach((prompt) => {
+  const argsSchema: Record<string, z.ZodString | z.ZodOptional<z.ZodString>> =
+    {};
+
+  // Convert prompt arguments to Zod schema format
+  prompt.arguments.forEach((arg) => {
+    const zodString = z.string().describe(arg.description);
+    argsSchema[arg.name] = arg.required ? zodString : zodString.optional();
+  });
+
+  server.registerPrompt(
+    prompt.name,
+    {
+      description: prompt.description,
+      argsSchema: argsSchema
+    },
+    async (args) => {
+      // Filter out undefined values from optional arguments
+      const filteredArgs: Record<string, string> = {};
+      for (const [key, value] of Object.entries(args || {})) {
+        if (value !== undefined) {
+          filteredArgs[key] = value;
+        }
+      }
+      return prompt.execute(filteredArgs);
+    }
+  );
+});
+
 async function main() {
   // Send MCP logging messages about .env loading
   if (envLoadError) {

src/prompts/AnalyzeGeojsonPrompt.ts

@@ -0,0 +1,139 @@
+// Copyright (c) Mapbox, Inc.
+// Licensed under the MIT License.
+
+import type { PromptMessage } from '@modelcontextprotocol/sdk/types.js';
+import { BasePrompt, type PromptArgument } from './BasePrompt.js';
+
+/**
+ * Prompt for analyzing and visualizing GeoJSON data
+ *
+ * This prompt orchestrates multiple tools to:
+ * 1. Validate GeoJSON format
+ * 2. Calculate bounding box
+ * 3. Generate visualization link
+ * 4. Provide analysis summary
+ */
+export class AnalyzeGeojsonPrompt extends BasePrompt {
+  readonly name = 'analyze-geojson';
+  readonly description =
+    'Analyze and visualize GeoJSON data. Validates format, calculates bounding box, and generates an interactive map visualization.';
+
+  readonly arguments: ReadonlyArray<PromptArgument> = [
+    {
+      name: 'geojson_data',
+      description:
+        'GeoJSON object or string to analyze (Point, LineString, Polygon, Feature, FeatureCollection, etc.)',
+      required: true
+    },
+    {
+      name: 'show_bounds',
+      description:
+        'Whether to calculate and display the bounding box (true/false, default: true)',
+      required: false
+    },
+    {
+      name: 'convert_coordinates',
+      description:
+        'Whether to provide coordinate conversion examples for Web Mercator (true/false, default: false)',
+      required: false
+    }
+  ];
+
+  getMessages(args: Record<string, string>): PromptMessage[] {
+    const geojsonData = args['geojson_data'];
+    const showBounds = args['show_bounds'] !== 'false'; // Default to true
+    const convertCoordinates = args['convert_coordinates'] === 'true'; // Default to false
+
+    let instructionText = `Analyze the provided GeoJSON data and generate an interactive visualization.
+
+**GeoJSON Data:**
+\`\`\`json
+${geojsonData}
+\`\`\`
+
+Follow these steps to analyze and visualize the data:
+
+1. **Parse and validate the GeoJSON**
+   - Parse the GeoJSON data (it may be provided as a string or object)
+   - Verify it's valid GeoJSON with proper structure
+   - Identify the geometry type (Point, LineString, Polygon, Feature, FeatureCollection, etc.)
+   - Count the number of features if it's a FeatureCollection`;
+
+    if (showBounds) {
+      instructionText += `
+
+2. **Calculate bounding box**
+   - Use the bounding_box_tool to calculate the geographic extent
+   - The tool will return [minX, minY, maxX, maxY] (west, south, east, north)
+   - Present the bounds in a clear format:
+     * Western edge (minX): [longitude]
+     * Eastern edge (maxX): [longitude]
+     * Southern edge (minY): [latitude]
+     * Northern edge (maxY): [latitude]
+   - Calculate and display the width and height in degrees`;
+    }
+
+    if (convertCoordinates) {
+      instructionText += `
+
+3. **Provide coordinate conversion examples**
+   - Use the coordinate_conversion_tool to show Web Mercator equivalents
+   - Convert a sample point from the GeoJSON from EPSG:4326 to EPSG:3857
+   - Explain when Web Mercator coordinates might be useful (web mapping, tilesets)`;
+    }
+
+    const nextStep =
+      showBounds && convertCoordinates
+        ? '4'
+        : showBounds || convertCoordinates
+          ? '3'
+          : '2';
+
+    instructionText += `
+
+${nextStep}. **Generate visualization**
+   - Use the geojson_preview_tool to create an interactive map
+   - This will generate a geojson.io URL where the data can be viewed and edited
+   - The visualization will show:
+     * The geometry rendered on a map
+     * Feature properties in a side panel
+     * Interactive editing capabilities
+
+${parseInt(nextStep) + 1}. **Provide analysis summary**
+   Present a comprehensive summary including:
+   - **Geometry type**: [Point/LineString/Polygon/etc.]
+   - **Feature count**: [number of features]
+   - **Coordinate system**: WGS84 (EPSG:4326)`;
+
+    if (showBounds) {
+      instructionText += `\n   - **Geographic extent**: [bounding box summary]`;
+    }
+
+    instructionText += `\n   - **Visualization link**: [geojson.io URL - clickable]
+   - **Properties**: [list any feature properties found]
+   - **Data quality notes**: [any issues or observations]
+
+**Analysis guidelines:**
+- Check for common issues: invalid coordinates, missing required fields, topology errors
+- Note if coordinates are in the correct order (longitude, latitude)
+- Identify if the data uses right-hand rule for polygon winding
+- Suggest improvements if the GeoJSON could be optimized
+- For large datasets, note that the preview URL may be long
+
+**Important notes:**
+- GeoJSON coordinates must be [longitude, latitude], not [latitude, longitude]
+- Valid longitude range: -180 to 180
+- Valid latitude range: -90 to 90
+- The preview tool works best with small to medium-sized datasets`;
+
+    return [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: instructionText
+        }
+      }
+    ];
+  }
+}