@mapbox/mcp-docs-server 0.1.0-dev

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mapbox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,196 @@
+# Mapbox MCP Documentation Server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives AI assistants instant access to Mapbox documentation and reference materials — **no Mapbox access token required**.
+
+## Quick Start
+
+### Hosted (no install required)
+
+Connect directly to the hosted endpoint — nothing to install or maintain:
+
+**Claude Code / Claude Desktop / Cursor / VS Code**
+
+```json
+{
+  "mcpServers": {
+    "mapbox-docs": {
+      "url": "https://mcp-docs.mapbox.com/mcp"
+    }
+  }
+}
+```
+
+---
+
+### npx (runs locally, no install)
+
+**Claude Code** — run `claude mcp add`:
+
+```bash
+claude mcp add mapbox-docs -- npx -y @mapbox/mcp-docs-server
+```
+
+**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "mapbox-docs": {
+      "command": "npx",
+      "args": ["-y", "@mapbox/mcp-docs-server"]
+    }
+  }
+}
+```
+
+**Cursor / VS Code** — add the same `mcpServers` block to your editor's MCP settings file.
+
+---
+
+### Docker
+
+**Build the image:**
+
+```bash
+docker build -t mapbox/mcp-docs-server .
+```
+
+**Or pull from the registry:**
+
+```bash
+docker pull mapbox/mcp-docs-server
+```
+
+**Claude Desktop / Cursor / VS Code** — configure your MCP client to run the container:
+
+```json
+{
+  "mcpServers": {
+    "mapbox-docs": {
+      "command": "docker",
+      "args": ["run", "--rm", "-i", "mapbox/mcp-docs-server"]
+    }
+  }
+}
+```
+
+---
+
+### Local (from source)
+
+```bash
+git clone https://github.com/mapbox/mcp-docs-server.git
+cd mcp-docs-server
+npm install
+npm run build
+```
+
+**Claude Desktop / Cursor / VS Code:**
+
+```json
+{
+  "mcpServers": {
+    "mapbox-docs": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-docs-server/dist/esm/index.js"]
+    }
+  }
+}
+```
+
+## Tools
+
+### Documentation Tools
+
+**`get_latest_mapbox_docs_tool`** — Fetches the full Mapbox documentation index from `docs.mapbox.com/llms.txt`. Returns up-to-date, comprehensive coverage of all Mapbox services, APIs, SDKs, and guides in a single LLM-optimized format.
+
+Example prompts:
+
+- "What Mapbox APIs are available?"
+- "How do I add a custom layer to a Mapbox style?"
+- "What's the latest Mapbox GL JS version?"
+
+**`search_mapbox_docs_tool`** _(coming soon)_ — AI-powered search of Mapbox documentation. Returns ranked, relevant sections for a specific query instead of the full corpus. Supports filtering by category (apis, sdks, guides, examples).
+
+**`explore_mapbox_api_tool`** _(coming soon)_ — Structured, queryable information about Mapbox REST API endpoints. Lists available APIs, operations, required parameters, authentication scopes, and rate limits without making any API calls.
+
+**`validate_api_request_tool`** _(coming soon)_ — Validates a Mapbox API request before sending it. Checks required parameters, types, enum values, and token scopes.
+
+**`test_api_request_tool`** _(coming soon)_ — Makes real HTTP calls to Mapbox APIs and returns actual responses, with optional code generation in curl, JavaScript, and Python. Requires a Mapbox access token as input.
+
+**`get_contextual_docs_tool`** _(coming soon)_ — Retrieves documentation relevant to a specific code context, error message, or technology.
+
+### Reference Tools
+
+**`get_reference_tool`** — Serves static Mapbox reference documentation directly as tool output (useful for clients that don't support MCP resources). Covers style layers, Streets v8 fields, token scopes, and layer type mappings.
+
+## Resources
+
+MCP resources expose reference data that AI assistants can read on demand:
+
+| Resource URI                                      | Contents                                                            |
+| ------------------------------------------------- | ------------------------------------------------------------------- |
+| `resource://mapbox-documentation`                 | Full Mapbox docs from `docs.mapbox.com/llms.txt`                    |
+| `resource://mapbox-api-reference` _(coming soon)_ | REST API reference docs only                                        |
+| `resource://mapbox-sdk-docs` _(coming soon)_      | SDK and client library docs only                                    |
+| `resource://mapbox-guides` _(coming soon)_        | Tutorials, how-tos, and guides only                                 |
+| `resource://mapbox-examples` _(coming soon)_      | Code examples and playgrounds only                                  |
+| `resource://mapbox-reference` _(coming soon)_     | Tilesets, data products, and reference materials                    |
+| `resource://mapbox-style-layers`                  | Style layer reference (paint/layout properties for all layer types) |
+| `resource://mapbox-streets-v8-fields`             | Mapbox Streets v8 tileset field reference                           |
+| `resource://mapbox-token-scopes`                  | All available Mapbox token scopes with descriptions                 |
+| `resource://mapbox-layer-type-mapping`            | Mapping of Mapbox layer types to their properties                   |
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 22
+- npm
+
+### Setup
+
+```bash
+git clone https://github.com/mapbox/mcp-docs-server.git
+cd mcp-docs-server
+npm install
+```
+
+### Commands
+
+```bash
+npm run build          # Compile TypeScript (ESM + CJS)
+npm test               # Run test suite (vitest)
+npm run lint           # ESLint
+npm run format         # Prettier check
+npm run format:fix     # Prettier auto-fix
+npm run inspect:build  # Launch MCP Inspector against built server
+npm run inspect:dev    # Launch MCP Inspector against source (tsx)
+```
+
+### Architecture
+
+The server is a TypeScript MCP server using `@modelcontextprotocol/sdk` with a dual ESM/CJS build via `tshy`.
+
+- **Tools** extend `BaseTool<InputSchema, OutputSchema>` in `src/tools/`
+- **Resources** extend `BaseResource` in `src/resources/`
+- No Mapbox access token required for documentation tools
+- HTTP requests use a shared `httpPipeline` with 1-hour caching
+
+### Creating a New Tool
+
+1. Create a directory `src/tools/my-tool/`
+2. Add `MyTool.input.schema.ts` (Zod schema), `MyTool.output.schema.ts`, and `MyTool.ts` (extends `BaseTool`)
+3. Register in `src/tools/toolRegistry.ts`
+4. Add tests in `test/tools/my-tool/`
+
+## Contributing
+
+Please read [CONTRIBUTING.md](./CONTRIBUTING.md) and [VISION.md](./VISION.md) before submitting a pull request. Contributors using AI coding assistants should also review:
+
+- [CLAUDE.md](./CLAUDE.md) — for Claude Code
+- [AGENTS.md](./AGENTS.md) — for other AI coding assistants (Cursor, Copilot, Aider, etc.)
+
+## License
+
+MIT — see [LICENSE](./LICENSE)

package/dist/commonjs/config/toolConfig.d.ts

@@ -0,0 +1,8 @@
+import { ToolInstance } from '../tools/toolRegistry.js';
+export interface ToolConfig {
+    enabledTools?: string[];
+    disabledTools?: string[];
+}
+export declare function parseToolConfigFromArgs(): ToolConfig;
+export declare function filterTools(tools: readonly ToolInstance[], config: ToolConfig): ToolInstance[];
+//# sourceMappingURL=toolConfig.d.ts.map

package/dist/commonjs/config/toolConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolConfig.d.ts","sourceRoot":"","sources":["../../../src/config/toolConfig.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD,MAAM,WAAW,UAAU;IACzB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,wBAAgB,uBAAuB,IAAI,UAAU,CAqBpD;AAED,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,MAAM,EAAE,UAAU,GACjB,YAAY,EAAE,CAoBhB"}

package/dist/commonjs/config/toolConfig.js

@@ -0,0 +1,41 @@
+"use strict";
+// Copyright (c) Mapbox, Inc.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseToolConfigFromArgs = parseToolConfigFromArgs;
+exports.filterTools = filterTools;
+function parseToolConfigFromArgs() {
+    const args = process.argv.slice(2);
+    const config = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--enable-tools') {
+            const value = args[++i];
+            if (value) {
+                config.enabledTools = value.split(',').map((t) => t.trim());
+            }
+        }
+        else if (arg === '--disable-tools') {
+            const value = args[++i];
+            if (value) {
+                config.disabledTools = value.split(',').map((t) => t.trim());
+            }
+        }
+    }
+    return config;
+}
+function filterTools(tools, config) {
+    let filteredTools = [...tools];
+    // If enabledTools is specified, only those tools should be enabled
+    // This takes precedence over disabledTools
+    if (config.enabledTools !== undefined) {
+        filteredTools = filteredTools.filter((tool) => config.enabledTools.includes(tool.name));
+        return filteredTools;
+    }
+    // Apply disabledTools filter only if enabledTools is not specified
+    if (config.disabledTools && config.disabledTools.length > 0) {
+        filteredTools = filteredTools.filter((tool) => !config.disabledTools.includes(tool.name));
+    }
+    return filteredTools;
+}
+//# sourceMappingURL=toolConfig.js.map

package/dist/commonjs/config/toolConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolConfig.js","sourceRoot":"","sources":["../../../src/config/toolConfig.ts"],"names":[],"mappings":";AAAA,6BAA6B;AAC7B,kCAAkC;;AASlC,0DAqBC;AAED,kCAuBC;AA9CD,SAAgB,uBAAuB;IACrC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,MAAM,GAAe,EAAE,CAAC;IAE9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAEpB,IAAI,GAAG,KAAK,gBAAgB,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;YACxB,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,CAAC,YAAY,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YAC9D,CAAC;QACH,CAAC;aAAM,IAAI,GAAG,KAAK,iBAAiB,EAAE,CAAC;YACrC,MAAM,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;YACxB,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,CAAC,aAAa,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAgB,WAAW,CACzB,KAA8B,EAC9B,MAAkB;IAElB,IAAI,aAAa,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IAE/B,mEAAmE;IACnE,2CAA2C;IAC3C,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACtC,aAAa,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAC5C,MAAM,CAAC,YAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CACzC,CAAC;QACF,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,mEAAmE;IACnE,IAAI,MAAM,CAAC,aAAa,IAAI,MAAM,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5D,aAAa,GAAG,aAAa,CAAC,MAAM,CAClC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,aAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CACrD,CAAC;IACJ,CAAC;IAED,OAAO,aAAa,CAAC;AACvB,CAAC"}