@mapbox/mcp-server 0.2.4 → 0.4.1

package/LICENSE.md

@@ -1,13 +1,21 @@
-BSD 3-Clause License
+MIT License
 
-Copyright (c) 2025, Mapbox, Inc. All rights reserved.
+Copyright (c) 2025 Mapbox, Inc.
 
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+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:
 
-Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
-Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+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

@@ -23,6 +23,14 @@ Whether you're building an AI travel assistant, logistics optimizer, location-ba
 
 **A Mapbox access token is required to use this MCP server.**
 
+## Hosted MCP Endpoint
+
+For quick access, you can use our hosted MCP endpoint:
+
+**Endpoint**: https://mcp.mapbox.com/mcp
+
+For detailed setup instructions for different clients and API usage, see the [Hosted MCP Server Guide](./docs/hosted-mcp-guide.md).
+
 To get a Mapbox access token:
 
 1. Sign up for a free Mapbox account at [mapbox.com/signup](https://www.mapbox.com/signup/)
@@ -178,7 +186,7 @@ Computes areas that are reachable within a specified amount of times from a loca
 npm run build
 
 # Inspect
-npx @modelcontextprotocol/inspector node dist/index.js
+npx @modelcontextprotocol/inspector node dist/esm/index.js
 ```
 
 ### Using Docker
@@ -198,13 +206,23 @@ npx plop create-tool
 # provide tool name without suffix (e.g. Search)
 ```
 
-## Environment Variables
+## Contributing
+
+We welcome contributions to the Mapbox MCP Server! Please review our standards and guidelines before contributing:
+
+- **[Engineering Standards (CLAUDE.md)](./CLAUDE.md)** - Code quality, testing, documentation, and collaboration standards for all contributors
+- **[AI Agent Instructions (AGENTS.md)](./AGENTS.md)** - Comprehensive guide for AI agents working with this codebase
+- **[GitHub Copilot Guidelines](./.github/copilot-instructions.md)** - Best practices for using GitHub Copilot responsibly in this project
 
-### VERBOSE_ERRORS
+### Quick Start for Contributors
 
-Set `VERBOSE_ERRORS=true` to get detailed error messages from the MCP server. This is useful for debugging issues when integrating with MCP clients.
+1. Fork the repository and clone your fork
+2. Follow the development setup in our [Engineering Standards](./CLAUDE.md#getting-started)
+3. Make your changes following our coding standards
+4. Add tests for any new functionality
+5. Submit a pull request with a clear description
 
-By default, the server returns generic error messages. With verbose errors enabled, you'll receive the actual error details, which can help diagnose API connection issues, invalid parameters, or other problems.
+All contributions must pass our CI checks and code review process. See [CLAUDE.md](./CLAUDE.md) for detailed requirements.
 
 ## Data Usage & Privacy
 
@@ -256,4 +274,4 @@ This MCP server is officially maintained by Mapbox, Inc. We provide:
 
 ---
 
-[BSD 3-Clause License](LICENSE.md)
+[MIT License](LICENSE.md)

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

@@ -0,0 +1,8 @@
+import type { 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":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D,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,CAqBhB"}

package/dist/commonjs/config/toolConfig.js

@@ -0,0 +1,40 @@
+"use strict";
+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 early since enabledTools takes precedence
+        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":";;AAOA,0DAqBC;AAED,kCAwBC;AA/CD,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,mDAAmD;QACnD,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"}

package/dist/commonjs/index.d.ts

@@ -0,0 +1,2 @@
+import 'dotenv/config';
+//# sourceMappingURL=index.d.ts.map

package/dist/{index.d.ts.map → commonjs/index.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,eAAe,CAAC"}

package/dist/commonjs/index.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const toolConfig_js_1 = require("./config/toolConfig.js");
+const toolRegistry_js_1 = require("./tools/toolRegistry.js");
+const versionUtils_js_1 = require("./utils/versionUtils.js");
+require("dotenv/config");
+const versionInfo = (0, versionUtils_js_1.getVersionInfo)();
+// Parse configuration from command-line arguments
+const config = (0, toolConfig_js_1.parseToolConfigFromArgs)();
+// Get and filter tools based on configuration
+const allTools = (0, toolRegistry_js_1.getAllTools)();
+const enabledTools = (0, toolConfig_js_1.filterTools)(allTools, config);
+// Create an MCP server
+const server = new mcp_js_1.McpServer({
+    name: versionInfo.name,
+    version: versionInfo.version
+}, {
+    capabilities: {
+        tools: {},
+        logging: {}
+    }
+});
+// Register enabled tools to the server
+enabledTools.forEach((tool) => {
+    tool.installTo(server);
+});
+async function main() {
+    // Start receiving messages on stdin and sending messages on stdout
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error('Fatal error starting MCP server:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/commonjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;AAAA,oEAAoE;AACpE,wEAAiF;AACjF,0DAA8E;AAC9E,6DAAsD;AACtD,6DAAyD;AACzD,yBAAuB;AAEvB,MAAM,WAAW,GAAG,IAAA,gCAAc,GAAE,CAAC;AAErC,kDAAkD;AAClD,MAAM,MAAM,GAAG,IAAA,uCAAuB,GAAE,CAAC;AAEzC,8CAA8C;AAC9C,MAAM,QAAQ,GAAG,IAAA,6BAAW,GAAE,CAAC;AAC/B,MAAM,YAAY,GAAG,IAAA,2BAAW,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AAEnD,uBAAuB;AACvB,MAAM,MAAM,GAAG,IAAI,kBAAS,CAC1B;IACE,IAAI,EAAE,WAAW,CAAC,IAAI;IACtB,OAAO,EAAE,WAAW,CAAC,OAAO;CAC7B,EACD;IACE,YAAY,EAAE;QACZ,KAAK,EAAE,EAAE;QACT,OAAO,EAAE,EAAE;KACZ;CACF,CACF,CAAC;AAEF,uCAAuC;AACvC,YAAY,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;IAC5B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AACzB,CAAC,CAAC,CAAC;AAEH,KAAK,UAAU,IAAI;IACjB,mEAAmE;IACnE,MAAM,SAAS,GAAG,IAAI,+BAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,kCAAkC,EAAE,KAAK,CAAC,CAAC;IACzD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/{cjs → commonjs}/package.json

@@ -1,3 +1,3 @@
 {
   "type": "commonjs"
-}
+}

package/dist/{tools → commonjs/tools}/MapboxApiBasedTool.d.ts

@@ -1,10 +1,12 @@
-import { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp';
-import { z, ZodTypeAny } from 'zod';
+import type { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import type { ZodTypeAny } from 'zod';
+import { z } from 'zod';
 export declare const OutputSchema: z.ZodObject<{
     content: z.ZodArray<z.ZodUnion<[z.ZodObject<{
         type: z.ZodLiteral<"text">;
         text: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
+    }, "strip", ZodTypeAny, {
         type: "text";
         text: string;
     }, {
@@ -14,7 +16,7 @@ export declare const OutputSchema: z.ZodObject<{
         type: z.ZodLiteral<"image">;
         data: z.ZodString;
         mimeType: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
+    }, "strip", ZodTypeAny, {
         type: "image";
         data: string;
         mimeType: string;
@@ -24,7 +26,7 @@ export declare const OutputSchema: z.ZodObject<{
         mimeType: string;
     }>]>, "many">;
     isError: z.ZodDefault<z.ZodBoolean>;
-}, "strip", z.ZodTypeAny, {
+}, "strip", ZodTypeAny, {
     content: ({
         type: "text";
         text: string;
@@ -50,8 +52,8 @@ export declare abstract class MapboxApiBasedTool<InputSchema extends ZodTypeAny>
     abstract readonly description: string;
     readonly inputSchema: InputSchema;
     protected server: McpServer | null;
-    static readonly MAPBOX_ACCESS_TOKEN: string | undefined;
-    static readonly MAPBOX_API_ENDPOINT: string;
+    static get mapboxAccessToken(): string | undefined;
+    static get mapboxApiEndpoint(): string;
     constructor(params: {
         inputSchema: InputSchema;
     });
@@ -65,11 +67,11 @@ export declare abstract class MapboxApiBasedTool<InputSchema extends ZodTypeAny>
     /**
      * Validates and runs the tool logic.
      */
-    run(rawInput: unknown): Promise<z.infer<typeof OutputSchema>>;
+    run(rawInput: unknown, extra?: RequestHandlerExtra<any, any>): Promise<z.infer<typeof OutputSchema>>;
     /**
      * Tool logic to be implemented by subclasses.
      */
-    protected abstract execute(_input: z.infer<InputSchema>): Promise<any>;
+    protected abstract execute(_input: z.infer<InputSchema>, accessToken: string): Promise<any>;
     /**
      * Installs the tool to the given MCP server.
      */

package/dist/commonjs/tools/MapboxApiBasedTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MapboxApiBasedTool.d.ts","sourceRoot":"","sources":["../../../src/tools/MapboxApiBasedTool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EACf,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AACxF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAevB,CAAC;AAEH,8BAAsB,kBAAkB,CAAC,WAAW,SAAS,UAAU;IACrE,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAEtC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAQ;IAE1C,MAAM,KAAK,iBAAiB,uBAE3B;IAED,MAAM,KAAK,iBAAiB,WAE3B;gBAEW,MAAM,EAAE;QAAE,WAAW,EAAE,WAAW,CAAA;KAAE;IAIhD;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IASxB;;OAEG;IACG,GAAG,CACP,QAAQ,EAAE,OAAO,EACjB,KAAK,CAAC,EAAE,mBAAmB,CAAC,GAAG,EAAE,GAAG,CAAC,GACpC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;IA4DxC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,CACxB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,EAC5B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,GAAG,CAAC;IAEf;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,cAAc;IAU5C;;OAEG;IACH,SAAS,CAAC,GAAG,CACX,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,EAC7C,IAAI,EAAE,GAAG,GACR,IAAI;CAKR"}

package/dist/commonjs/tools/MapboxApiBasedTool.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MapboxApiBasedTool = exports.OutputSchema = void 0;
+const zod_1 = require("zod");
+exports.OutputSchema = zod_1.z.object({
+    content: zod_1.z.array(zod_1.z.union([
+        zod_1.z.object({
+            type: zod_1.z.literal('text'),
+            text: zod_1.z.string()
+        }),
+        zod_1.z.object({
+            type: zod_1.z.literal('image'),
+            data: zod_1.z.string(),
+            mimeType: zod_1.z.string()
+        })
+    ])),
+    isError: zod_1.z.boolean().default(false)
+});
+class MapboxApiBasedTool {
+    inputSchema;
+    server = null;
+    static get mapboxAccessToken() {
+        return process.env.MAPBOX_ACCESS_TOKEN;
+    }
+    static get mapboxApiEndpoint() {
+        return process.env.MAPBOX_API_ENDPOINT || 'https://api.mapbox.com/';
+    }
+    constructor(params) {
+        this.inputSchema = params.inputSchema;
+    }
+    /**
+     * Validates if a string has the format of a JWT token (header.payload.signature)
+     * Docs: https://docs.mapbox.com/api/accounts/tokens/#token-format
+     * @param token The token string to validate
+     * @returns boolean indicating if the token has valid JWT format
+     */
+    isValidJwtFormat(token) {
+        // JWT consists of three parts separated by dots: header.payload.signature
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return false;
+        // Check that all parts are non-empty
+        return parts.every((part) => part.length > 0);
+    }
+    /**
+     * Validates and runs the tool logic.
+     */
+    async run(rawInput, extra) {
+        try {
+            // First check if token is provided via authentication context
+            // Check both standard token field and accessToken in extra for compatibility
+            // In the streamableHttp, the authInfo is injected into extra from `req.auth`
+            // https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/server/streamableHttp.ts#L405
+            const authToken = extra?.authInfo?.token;
+            const accessToken = authToken || MapboxApiBasedTool.mapboxAccessToken;
+            if (!accessToken) {
+                throw new Error('No access token available. Please provide via Bearer auth or MAPBOX_ACCESS_TOKEN env var');
+            }
+            // Validate that the token has the correct JWT format
+            if (!this.isValidJwtFormat(accessToken)) {
+                throw new Error('Access token is not in valid JWT format');
+            }
+            const input = this.inputSchema.parse(rawInput);
+            const result = await this.execute(input, accessToken);
+            // Check if result is already a content object (image or text)
+            if (result &&
+                typeof result === 'object' &&
+                (result.type === 'image' || result.type === 'text')) {
+                return {
+                    content: [result],
+                    isError: false
+                };
+            }
+            // Otherwise return as text
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result) }],
+                isError: false
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.log('error', `${this.name}: Error during execution: ${errorMessage}`);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: errorMessage
+                    }
+                ],
+                isError: true
+            };
+        }
+    }
+    /**
+     * Installs the tool to the given MCP server.
+     */
+    installTo(server) {
+        this.server = server;
+        return server.tool(this.name, this.description, this.inputSchema.shape, (args, extra) => this.run(args, extra));
+    }
+    /**
+     * Helper method to send logging messages
+     */
+    log(level, data) {
+        if (this.server) {
+            this.server.server.sendLoggingMessage({ level, data });
+        }
+    }
+}
+exports.MapboxApiBasedTool = MapboxApiBasedTool;
+//# sourceMappingURL=MapboxApiBasedTool.js.map

package/dist/commonjs/tools/MapboxApiBasedTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MapboxApiBasedTool.js","sourceRoot":"","sources":["../../../src/tools/MapboxApiBasedTool.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/tools/category-list-tool/CategoryListTool.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { MapboxApiBasedTool } from '../MapboxApiBasedTool.js';
+declare const CategoryListInputSchema: z.ZodObject<{
+    language: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    offset: number;
+    language?: string | undefined;
+    limit?: number | undefined;
+}, {
+    language?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+}>;
+type CategoryListInput = z.infer<typeof CategoryListInputSchema>;
+/**
+ * Tool for retrieving the list of supported categories from Mapbox Search API
+ */
+export declare class CategoryListTool extends MapboxApiBasedTool<typeof CategoryListInputSchema> {
+    private fetchImpl;
+    name: string;
+    description: string;
+    constructor(fetchImpl?: typeof fetch);
+    protected execute(input: CategoryListInput, accessToken: string): Promise<any>;
+}
+export {};
+//# sourceMappingURL=CategoryListTool.d.ts.map

package/dist/commonjs/tools/category-list-tool/CategoryListTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CategoryListTool.d.ts","sourceRoot":"","sources":["../../../../src/tools/category-list-tool/CategoryListTool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAG9D,QAAA,MAAM,uBAAuB;;;;;;;;;;;;EAqB3B,CAAC;AAEH,KAAK,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAajE;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,kBAAkB,CACtD,OAAO,uBAAuB,CAC/B;IAKa,OAAO,CAAC,SAAS;IAJ7B,IAAI,SAAwB;IAC5B,WAAW,SAC+X;gBAEtX,SAAS,GAAE,OAAO,KAAmB;cAIzC,OAAO,CACrB,KAAK,EAAE,iBAAiB,EACxB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,GAAG,CAAC;CA2ChB"}

package/dist/commonjs/tools/category-list-tool/CategoryListTool.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CategoryListTool = void 0;
+const zod_1 = require("zod");
+const MapboxApiBasedTool_js_1 = require("../MapboxApiBasedTool.js");
+const fetchRequest_js_1 = require("../../utils/fetchRequest.js");
+const CategoryListInputSchema = zod_1.z.object({
+    language: zod_1.z
+        .string()
+        .optional()
+        .describe('ISO language code for the response (e.g., "en", "es", "fr", "de", "ja"). If not provided, English (en) will be used as the default.'),
+    limit: zod_1.z
+        .number()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe('Number of categories to return (1-100). WARNING: Only use this parameter if you need to optimize token usage. If using pagination, please make multiple calls to retrieve all categories before proceeding with other tasks. If not specified, returns all categories.'),
+    offset: zod_1.z
+        .number()
+        .min(0)
+        .optional()
+        .default(0)
+        .describe('Number of categories to skip for pagination. Default is 0.')
+});
+/**
+ * Tool for retrieving the list of supported categories from Mapbox Search API
+ */
+class CategoryListTool extends MapboxApiBasedTool_js_1.MapboxApiBasedTool {
+    fetchImpl;
+    name = 'category_list_tool';
+    description = 'Tool for retrieving the list of supported categories from Mapbox Search API. Use this when another function requires a list of categories. Returns all available category IDs by default. Only use pagination (limit/offset) if token usage optimization is required. If using pagination, make multiple calls to retrieve ALL categories before proceeding with other tasks to ensure complete data.';
+    constructor(fetchImpl = fetchRequest_js_1.fetchClient) {
+        super({ inputSchema: CategoryListInputSchema });
+        this.fetchImpl = fetchImpl;
+    }
+    async execute(input, accessToken) {
+        const url = new URL('https://api.mapbox.com/search/searchbox/v1/list/category');
+        url.searchParams.set('access_token', accessToken);
+        if (input.language) {
+            url.searchParams.set('language', input.language);
+        }
+        const response = await this.fetchImpl(url.toString(), {
+            method: 'GET',
+            headers: {
+                'User-Agent': `@mapbox/mcp-server/${process.env.npm_package_version || 'dev'}`
+            }
+        });
+        if (!response.ok) {
+            throw new Error(`Mapbox API request failed: ${response.status} ${response.statusText}`);
+        }
+        const data = (await response.json());
+        // Apply pagination - if no limit specified, return all
+        const startIndex = input.offset || 0;
+        let endIndex = data.listItems.length;
+        if (input.limit) {
+            endIndex = Math.min(startIndex + input.limit, data.listItems.length);
+        }
+        // Return simple object with listItems array
+        const categoryIds = data.listItems
+            .slice(startIndex, endIndex)
+            .map((item) => item.canonical_id);
+        return {
+            listItems: categoryIds
+        };
+    }
+}
+exports.CategoryListTool = CategoryListTool;
+//# sourceMappingURL=CategoryListTool.js.map

package/dist/commonjs/tools/category-list-tool/CategoryListTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CategoryListTool.js","sourceRoot":"","sources":["../../../../src/tools/category-list-tool/CategoryListTool.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,oEAA8D;AAC9D,iEAA0D;AAE1D,MAAM,uBAAuB,GAAG,OAAC,CAAC,MAAM,CAAC;IACvC,QAAQ,EAAE,OAAC;SACR,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,qIAAqI,CACtI;IACH,KAAK,EAAE,OAAC;SACL,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,GAAG,CAAC;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,wQAAwQ,CACzQ;IACH,MAAM,EAAE,OAAC;SACN,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,EAAE;SACV,OAAO,CAAC,CAAC,CAAC;SACV,QAAQ,CAAC,4DAA4D,CAAC;CAC1E,CAAC,CAAC;AAeH;;GAEG;AACH,MAAa,gBAAiB,SAAQ,0CAErC;IAKqB;IAJpB,IAAI,GAAG,oBAAoB,CAAC;IAC5B,WAAW,GACT,uYAAuY,CAAC;IAE1Y,YAAoB,YAA0B,6BAAW;QACvD,KAAK,CAAC,EAAE,WAAW,EAAE,uBAAuB,EAAE,CAAC,CAAC;QAD9B,cAAS,GAAT,SAAS,CAA4B;IAEzD,CAAC;IAES,KAAK,CAAC,OAAO,CACrB,KAAwB,EACxB,WAAmB;QAEnB,MAAM,GAAG,GAAG,IAAI,GAAG,CACjB,0DAA0D,CAC3D,CAAC;QAEF,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;QAElD,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACnB,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;QACnD,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE;YACpD,MAAM,EAAE,KAAK;YACb,OAAO,EAAE;gBACP,YAAY,EAAE,sBAAsB,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,KAAK,EAAE;aAC/E;SACF,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CACb,8BAA8B,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CACvE,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAyB,CAAC;QAE7D,uDAAuD;QACvD,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;QACrC,IAAI,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;QAErC,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAChB,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,GAAG,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACvE,CAAC;QAED,4CAA4C;QAC5C,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS;aAC/B,KAAK,CAAC,UAAU,EAAE,QAAQ,CAAC;aAC3B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAEpC,OAAO;YACL,SAAS,EAAE,WAAW;SACvB,CAAC;IACJ,CAAC;CACF;AAzDD,4CAyDC"}

package/dist/{tools → commonjs/tools}/category-search-tool/CategorySearchTool.d.ts

@@ -37,10 +37,9 @@ declare const CategorySearchInputSchema: z.ZodObject<{
     poi_category_exclusions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     format: z.ZodDefault<z.ZodOptional<z.ZodEnum<["json_string", "formatted_text"]>>>;
 }, "strip", z.ZodTypeAny, {
-    category: string;
     limit: number;
+    category: string;
     format: "json_string" | "formatted_text";
-    country?: string[] | undefined;
     language?: string | undefined;
     proximity?: {
         longitude: number;
@@ -55,10 +54,10 @@ declare const CategorySearchInputSchema: z.ZodObject<{
         maxLongitude: number;
         maxLatitude: number;
     } | undefined;
+    country?: string[] | undefined;
     poi_category_exclusions?: string[] | undefined;
 }, {
     category: string;
-    country?: string[] | undefined;
     language?: string | undefined;
     limit?: number | undefined;
     proximity?: string | {
@@ -71,15 +70,17 @@ declare const CategorySearchInputSchema: z.ZodObject<{
         maxLongitude: number;
         maxLatitude: number;
     } | undefined;
+    country?: string[] | undefined;
     poi_category_exclusions?: string[] | undefined;
     format?: "json_string" | "formatted_text" | undefined;
 }>;
 export declare class CategorySearchTool extends MapboxApiBasedTool<typeof CategorySearchInputSchema> {
+    private fetch;
     name: string;
     description: string;
-    constructor();
+    constructor(fetch?: typeof globalThis.fetch);
     private formatGeoJsonToText;
-    protected execute(input: z.infer<typeof CategorySearchInputSchema>): Promise<{
+    protected execute(input: z.infer<typeof CategorySearchInputSchema>, accessToken: string): Promise<{
         type: 'text';
         text: string;
     }>;

package/dist/commonjs/tools/category-search-tool/CategorySearchTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CategorySearchTool.d.ts","sourceRoot":"","sources":["../../../../src/tools/category-search-tool/CategorySearchTool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAG9D,QAAA,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8F7B,CAAC;AAEH,qBAAa,kBAAmB,SAAQ,kBAAkB,CACxD,OAAO,yBAAyB,CACjC;IAKa,OAAO,CAAC,KAAK;IAJzB,IAAI,SAA0B;IAC9B,WAAW,SACoX;gBAE3W,KAAK,GAAE,OAAO,UAAU,CAAC,KAAmB;IAIhE,OAAO,CAAC,mBAAmB;cAsDX,OAAO,CACrB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,EAChD,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAmE3C"}