@mapbox/mcp-server 0.2.4 → 0.4.0

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,14 +206,6 @@ npx plop create-tool
 # provide tool name without suffix (e.g. Search)
 ```
 
-## Environment Variables
-
-### VERBOSE_ERRORS
-
-Set `VERBOSE_ERRORS=true` to get detailed error messages from the MCP server. This is useful for debugging issues when integrating with MCP clients.
-
-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.
-
 ## Data Usage & Privacy
 
 ### What data is sent to Mapbox APIs

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":"AAAA,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,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,38 @@
+#!/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: {}
+    }
+});
+// 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;KACV;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,4 +1,5 @@
-import { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp';
+import { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import { z, ZodTypeAny } from 'zod';
 export declare const OutputSchema: z.ZodObject<{
     content: z.ZodArray<z.ZodUnion<[z.ZodObject<{
@@ -50,8 +51,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 +66,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,EACL,SAAS,EACT,cAAc,EACf,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AACnF,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAEpC,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":";;;AAKA,6BAAoC;AAEvB,QAAA,YAAY,GAAG,OAAC,CAAC,MAAM,CAAC;IACnC,OAAO,EAAE,OAAC,CAAC,KAAK,CACd,OAAC,CAAC,KAAK,CAAC;QACN,OAAC,CAAC,MAAM,CAAC;YACP,IAAI,EAAE,OAAC,CAAC,OAAO,CAAC,MAAM,CAAC;YACvB,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;SACjB,CAAC;QACF,OAAC,CAAC,MAAM,CAAC;YACP,IAAI,EAAE,OAAC,CAAC,OAAO,CAAC,OAAO,CAAC;YACxB,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;YAChB,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE;SACrB,CAAC;KACH,CAAC,CACH;IACD,OAAO,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;CACpC,CAAC,CAAC;AAEH,MAAsB,kBAAkB;IAI7B,WAAW,CAAc;IACxB,MAAM,GAAqB,IAAI,CAAC;IAE1C,MAAM,KAAK,iBAAiB;QAC1B,OAAO,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;IACzC,CAAC;IAED,MAAM,KAAK,iBAAiB;QAC1B,OAAO,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,yBAAyB,CAAC;IACtE,CAAC;IAED,YAAY,MAAoC;QAC9C,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;IACxC,CAAC;IAED;;;;;OAKG;IACK,gBAAgB,CAAC,KAAa;QACpC,0EAA0E;QAC1E,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QAErC,qCAAqC;QACrC,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAChD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CACP,QAAiB,EACjB,KAAqC;QAErC,IAAI,CAAC;YACH,8DAA8D;YAC9D,6EAA6E;YAC7E,6EAA6E;YAC7E,qGAAqG;YACrG,MAAM,SAAS,GAAG,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC;YACzC,MAAM,WAAW,GAAG,SAAS,IAAI,kBAAkB,CAAC,iBAAiB,CAAC;YACtE,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CACb,0FAA0F,CAC3F,CAAC;YACJ,CAAC;YAED,qDAAqD;YACrD,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,WAAW,CAAC,EAAE,CAAC;gBACxC,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;YAC7D,CAAC;YAED,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAC/C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;YAEtD,8DAA8D;YAC9D,IACE,MAAM;gBACN,OAAO,MAAM,KAAK,QAAQ;gBAC1B,CAAC,MAAM,CAAC,IAAI,KAAK,OAAO,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,EACnD,CAAC;gBACD,OAAO;oBACL,OAAO,EAAE,CAAC,MAAM,CAAC;oBACjB,OAAO,EAAE,KAAK;iBACf,CAAC;YACJ,CAAC;YAED,2BAA2B;YAC3B,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;gBACzD,OAAO,EAAE,KAAK;aACf,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,YAAY,GAChB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAEzD,IAAI,CAAC,GAAG,CACN,OAAO,EACP,GAAG,IAAI,CAAC,IAAI,6BAA6B,YAAY,EAAE,CACxD,CAAC;YAEF,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,YAAY;qBACnB;iBACF;gBACD,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;IACH,CAAC;IAUD;;OAEG;IACH,SAAS,CAAC,MAAiB;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,OAAO,MAAM,CAAC,IAAI,CAChB,IAAI,CAAC,IAAI,EACT,IAAI,CAAC,WAAW,EACf,IAAI,CAAC,WAA2C,CAAC,KAAK,EACvD,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CACvC,CAAC;IACJ,CAAC;IAED;;OAEG;IACO,GAAG,CACX,KAA6C,EAC7C,IAAS;QAET,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;CACF;AApID,gDAoIC"}

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,SACiU;gBAExT,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 = 'Get the complete list of supported search categories from Mapbox Search API. 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,yUAAyU,CAAC;IAE5U,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"}