mcp-docs-server: Instructions file for Claude Code

Mapbox MCP Documentation Server

An MCP server providing AI assistants with access to Mapbox documentation and reference materials. No Mapbox access token required for most tools.

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 (--enable-tools, --disable-tools)
├── constants/                  # Static data (API endpoint definitions, etc.)
├── resources/                  # MCP resource implementations
│   ├── BaseResource.ts         # Abstract base class for resources
│   ├── resourceRegistry.ts     # Resource registration
│   ├── utils/docParser.ts      # Shared doc parsing utilities
│   └── */                      # Individual resource implementations
├── tools/                      # MCP tool implementations
│   ├── BaseTool.ts             # Abstract base class for tools
│   ├── toolRegistry.ts         # Tool registration
│   └── */                      # Individual tool implementations
└── utils/
    ├── httpPipeline.ts         # HTTP pipeline with User-Agent, caching, retry
    ├── types.ts                # Shared types (HttpRequest, etc.)
    └── versionUtils.ts         # Version info

test/                           # Mirrors src/ structure

Key Patterns

Tool Architecture

All tools extend BaseTool<InputSchema, OutputSchema>:

export class MyTool extends BaseTool<
  typeof MyInputSchema,
  typeof MyOutputSchema
> {
  readonly name = 'my_tool';
  readonly description = '...';
  readonly annotations = { title: 'My Tool', readOnlyHint: true, ... };

  constructor({ httpRequest }: { httpRequest: HttpRequest }) {
    super({ inputSchema: MyInputSchema, outputSchema: MyOutputSchema });
    this.httpRequest = httpRequest;
  }

  protected async execute(
    input: z.infer<typeof MyInputSchema>
  ): Promise<CallToolResult> {
    // no accessToken param — docs tools don't need one
  }
}