mcp-server: Instructions file for Claude Code

Mapbox MCP Server

An MCP (Model Context Protocol) server that provides AI agents with geospatial intelligence capabilities through Mapbox APIs. This enables AI applications to understand locations, navigate the physical world, and access rich spatial data including geocoding, search, routing, travel time analysis, and map visualization.

Tech Stack

• Runtime: Node.js 22+ LTS
• Language: TypeScript (strict mode)
• Testing: Vitest
• Package Manager: npm

Project Structure

src/
├── index.ts                    # Main MCP server entry point
├── config/toolConfig.ts        # Tool configuration parser
├── tools/                      # MCP tool implementations
│   ├── MapboxApiBasedTool.ts   # Base class for Mapbox API tools
│   ├── toolRegistry.ts         # Tool registration system
│   └── */Tool.ts               # Individual tool implementations
├── resources/                  # MCP resources (static data)
│   ├── MapboxApiBasedResource.ts
│   └── resourceRegistry.ts
└── utils/
    ├── httpPipeline.ts         # HTTP policy pipeline system
    ├── tracing.ts              # OpenTelemetry instrumentation
    └── versionUtils.ts         # Version info utilities

test/                           # Mirrors src/ structure

Key Patterns

Tool Architecture

• All Mapbox API tools extend MapboxApiBasedTool (src/tools/MapboxApiBasedTool.ts:16)
• Tools receive httpRequest via dependency injection (src/tools/toolRegistry.ts:22-29)
• Register new tools in ALL_TOOLS array (src/tools/toolRegistry.ts:18)

HTTP Pipeline System

• Never patch global.fetch - use HttpPipeline with dependency injection instead
• Pipeline applies policies (User-Agent, Retry, etc.) to all HTTP requests (src/utils/httpPipeline.ts:21)
• Default pipeline exported as httpRequest (src/utils/httpPipeline.ts)

Resource System

• Static reference data exposed as MCP resources (src/resources/)
• Resources use URI pattern: mapbox://resource-name
• Example: category list at mapbox://categories or mapbox://categories/{language}