mcp-docs-server CLAUDE.md

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
  }
}