mcp-docs-server: Instructions file for Codex

AI Agent Instructions for Mapbox MCP Documentation Server

Note: If you're using Claude Code specifically, see CLAUDE.md instead. This file is for general AI coding assistants (Cursor, Continue, Aider, Copilot, etc.).

What This Project Does

This is an MCP (Model Context Protocol) server that gives AI assistants access to Mapbox documentation and reference materials. No Mapbox access token is required for most tools — it is a documentation-only server.

Tech Stack

• Runtime: Node.js 22+
• Language: TypeScript (strict mode)
• Build: tshy (dual ESM/CJS output)
• Testing: Vitest
• Package Manager: npm

Project Structure

src/
├── index.ts                    # MCP server entry point
├── config/toolConfig.ts        # CLI argument parser
├── constants/                  # Static data (API endpoint definitions)
├── resources/                  # MCP resource implementations
│   ├── BaseResource.ts         # Abstract base class
│   ├── resourceRegistry.ts     # Resource registration
│   ├── utils/docParser.ts      # Shared doc parsing utilities
│   └── */                      # Individual resource implementations
├── tools/                      # MCP tool implementations
│   ├── BaseTool.ts             # Abstract base class
│   ├── toolRegistry.ts         # Tool registration
│   └── */                      # Individual tool implementations
└── utils/
    ├── httpPipeline.ts         # HTTP pipeline (User-Agent, caching, retry)
    ├── types.ts                # Shared types
    └── versionUtils.ts

test/                           # Mirrors src/ structure

Critical Patterns

Tool Architecture

• All tools extend BaseTool<InputSchema, OutputSchema> (not MapboxApiBasedTool — that is in a different repo)
• execute(input) receives only the validated input — no accessToken or context parameters
• If a tool needs a Mapbox token, it must be a field in the input schema
• Register tools in src/tools/toolRegistry.ts