@mapbox/mcp-server 0.0.2 → 0.1.1-dev.2

package/README.md

@@ -2,6 +2,23 @@
 
 Node.js server implementing Model Context Protocol (MCP) for Mapbox APIs.
 
+## Unlock Geospatial Intelligence for Your AI Applications
+
+The Mapbox MCP Server transforms any AI agent or application into a geospatially-aware system by providing seamless access to Mapbox's comprehensive location intelligence platform. With this server, your AI can understand and reason about places, navigate the physical world, and access rich geospatial data including:
+
+- **Global geocoding** to convert addresses and place names to coordinates and vice versa
+- **Points of interest (POI) search** across millions of businesses, landmarks, and places worldwide
+- **Multi-modal routing** for driving, walking, and cycling with real-time traffic
+- **Travel time matrices** to analyze accessibility and optimize logistics
+- **Isochrone generation** to visualize areas reachable within specific time or distance constraints
+- **Static map images** to create visual representations of locations, routes, and geographic data
+
+Whether you're building an AI travel assistant, logistics optimizer, location-based recommender, or any application that needs to understand "where", the Mapbox MCP Server provides the spatial intelligence to make it possible. You can also enable it on popular clients like Claude Desktop and VS Code. See below for details
+
+![Mapbox MCP Server Demo](./assets/mapbox_mcp_server.gif)
+
+# Usage
+
 **A Mapbox access token is required to use this MCP server.**
 
 To get a Mapbox access token:
@@ -18,7 +35,7 @@ For detailed setup instructions for different integrations, refer to the followi
 
 - [Claude Desktop Setup](./docs/claude-desktop-setup.md) - Instructions for configuring Claude Desktop to work with this MCP server
 - [VS Code Setup](./docs/vscode-setup.md) - Setting up a development environment in Visual Studio Code
-- [SmolaGents Integration](./docs/using-mcp-with-smolagents/README.md) - Example showing how to connect SmolaGents AI agents to Mapbox's tools
+- [Smolagents Integration](./docs/using-mcp-with-smolagents/README.md) - Example showing how to connect Smolagents AI agents to Mapbox's tools
 
 ## Tools
 
@@ -144,6 +161,14 @@ 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.
+
 ---
 
 [License](LICENSE.md)

package/dist/cjs/package.json

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

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CategorySearchTool } from './tools/category-search-tool/CategorySearchTool.js';
+import { DirectionsTool } from './tools/directions-tool/DirectionsTool.js';
+import { ForwardGeocodeTool } from './tools/forward-geocode-tool/ForwardGeocodeTool.js';
+import { IsochroneTool } from './tools/isochrone-tool/IsochroneTool.js';
+import { MatrixTool } from './tools/matrix-tool/MatrixTool.js';
+import { PoiSearchTool } from './tools/poi-search-tool/PoiSearchTool.js';
+import { ReverseGeocodeTool } from './tools/reverse-geocode-tool/ReverseGeocodeTool.js';
+import { StaticMapImageTool } from './tools/static-map-image-tool/StaticMapImageTool.js';
+import { patchGlobalFetch } from './utils/requestUtils.js';
+import { getVersionInfo } from './utils/versionUtils.js';
+// INSERT NEW TOOL IMPORT HERE
+let serverVersionInfo = getVersionInfo();
+patchGlobalFetch(serverVersionInfo);
+// Create an MCP server
+const server = new McpServer({
+    name: serverVersionInfo.name,
+    version: serverVersionInfo.version
+}, {
+    capabilities: {
+        logging: {}
+    }
+});
+// INSERT NEW TOOL REGISTRATION HERE
+new MatrixTool().installTo(server);
+new ReverseGeocodeTool().installTo(server);
+new ForwardGeocodeTool().installTo(server);
+new IsochroneTool().installTo(server);
+new PoiSearchTool().installTo(server);
+new CategorySearchTool().installTo(server);
+new StaticMapImageTool().installTo(server);
+new DirectionsTool().installTo(server);
+// Start receiving messages on stdin and sending messages on stdout
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACV,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,oDAAoD,CAAC;AACxF,OAAO,EAAE,cAAc,EAAE,MAAM,2CAA2C,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,oDAAoD,CAAC;AACxF,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,0CAA0C,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oDAAoD,CAAC;AACxF,OAAO,EAAE,kBAAkB,EAAE,MAAM,qDAAqD,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD,8BAA8B;AAE9B,IAAI,iBAAiB,GAAG,cAAc,EAAE,CAAC;AACzC,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;AAEpC,uBAAuB;AACvB,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B;IACE,IAAI,EAAE,iBAAiB,CAAC,IAAI;IAC5B,OAAO,EAAE,iBAAiB,CAAC,OAAO;CACnC,EACD;IACE,YAAY,EAAE;QACZ,OAAO,EAAE,EAAE;KACZ;CACF,CACF,CAAC;AAEF,oCAAoC;AACpC,IAAI,UAAU,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AACnC,IAAI,kBAAkB,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAC3C,IAAI,kBAAkB,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAC3C,IAAI,aAAa,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AACtC,IAAI,aAAa,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AACtC,IAAI,kBAAkB,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAC3C,IAAI,kBAAkB,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAC3C,IAAI,cAAc,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAEvC,mEAAmE;AACnE,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC"}

package/dist/tools/MapboxApiBasedTool.d.ts

@@ -0,0 +1,75 @@
+import { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp';
+import { z, ZodTypeAny } 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, {
+        type: "text";
+        text: string;
+    }, {
+        type: "text";
+        text: string;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"image">;
+        data: z.ZodString;
+        mimeType: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "image";
+        data: string;
+        mimeType: string;
+    }, {
+        type: "image";
+        data: string;
+        mimeType: string;
+    }>]>, "many">;
+    is_error: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    content: ({
+        type: "text";
+        text: string;
+    } | {
+        type: "image";
+        data: string;
+        mimeType: string;
+    })[];
+    is_error: boolean;
+}, {
+    content: ({
+        type: "text";
+        text: string;
+    } | {
+        type: "image";
+        data: string;
+        mimeType: string;
+    })[];
+    is_error?: boolean | undefined;
+}>;
+export declare abstract class MapboxApiBasedTool<InputSchema extends ZodTypeAny> {
+    abstract readonly name: string;
+    abstract readonly description: string;
+    readonly inputSchema: InputSchema;
+    protected server: McpServer | null;
+    static readonly MAPBOX_ACCESS_TOKEN: string | undefined;
+    static readonly MAPBOX_API_ENDPOINT: string;
+    constructor(params: {
+        inputSchema: InputSchema;
+    });
+    /**
+     * Validates and runs the tool logic.
+     */
+    run(rawInput: unknown): Promise<z.infer<typeof OutputSchema>>;
+    /**
+     * Tool logic to be implemented by subclasses.
+     */
+    protected abstract execute(_input: z.infer<InputSchema>): Promise<any>;
+    /**
+     * Installs the tool to the given MCP server.
+     */
+    installTo(server: McpServer): RegisteredTool;
+    /**
+     * Helper method to send logging messages
+     */
+    protected log(level: 'debug' | 'info' | 'warning' | 'error', data: any): void;
+}
+//# sourceMappingURL=MapboxApiBasedTool.d.ts.map

package/dist/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,sCAAsC,CAAC;AAC9C,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,CAAC,QAAQ,CAAC,mBAAmB,qBAAmC;IACtE,MAAM,CAAC,QAAQ,CAAC,mBAAmB,SAC4B;gBAEnD,MAAM,EAAE;QAAE,WAAW,EAAE,WAAW,CAAA;KAAE;IAIhD;;OAEG;IACG,GAAG,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;IA2CnE;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC;IAEtE;;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/tools/MapboxApiBasedTool.js

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+export const OutputSchema = z.object({
+    content: z.array(z.union([
+        z.object({
+            type: z.literal('text'),
+            text: z.string()
+        }),
+        z.object({
+            type: z.literal('image'),
+            data: z.string(),
+            mimeType: z.string()
+        })
+    ])),
+    is_error: z.boolean().default(false)
+});
+export class MapboxApiBasedTool {
+    inputSchema;
+    server = null;
+    static MAPBOX_ACCESS_TOKEN = process.env.MAPBOX_ACCESS_TOKEN;
+    static MAPBOX_API_ENDPOINT = process.env.MAPBOX_API_ENDPOINT || 'https://api.mapbox.com/';
+    constructor(params) {
+        this.inputSchema = params.inputSchema;
+    }
+    /**
+     * Validates and runs the tool logic.
+     */
+    async run(rawInput) {
+        try {
+            if (!MapboxApiBasedTool.MAPBOX_ACCESS_TOKEN) {
+                throw new Error('MAPBOX_ACCESS_TOKEN is not set');
+            }
+            const input = this.inputSchema.parse(rawInput);
+            const result = await this.execute(input);
+            // 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],
+                    is_error: false
+                };
+            }
+            // Otherwise return as text
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result) }],
+                is_error: false
+            };
+        }
+        catch (error) {
+            this.log('error', `${this.name}: Error during execution: ${error instanceof Error ? error.message : String(error)}`);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Internal error has occurred.'
+                    }
+                ],
+                is_error: true
+            };
+        }
+    }
+    /**
+     * Installs the tool to the given MCP server.
+     */
+    installTo(server) {
+        this.server = server;
+        return server.tool(this.name, this.description, this.inputSchema.shape, this.run.bind(this));
+    }
+    /**
+     * Helper method to send logging messages
+     */
+    log(level, data) {
+        if (this.server) {
+            this.server.server.sendLoggingMessage({ level, data });
+        }
+    }
+}
+//# sourceMappingURL=MapboxApiBasedTool.js.map

package/dist/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/tools/category-search-tool/CategorySearchTool.d.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { MapboxApiBasedTool } from '../MapboxApiBasedTool.js';
+declare const CategorySearchInputSchema: z.ZodObject<{
+    category: z.ZodString;
+    language: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    proximity: z.ZodOptional<z.ZodUnion<[z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, z.ZodEffects<z.ZodString, [number, number] | "ip", string>]>>;
+    bbox: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    country: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    poi_category_exclusions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    category: string;
+    limit: number;
+    country?: string[] | undefined;
+    language?: string | undefined;
+    proximity?: [number, number] | "ip" | undefined;
+    bbox?: [number, number, number, number] | undefined;
+    poi_category_exclusions?: string[] | undefined;
+}, {
+    category: string;
+    country?: string[] | undefined;
+    language?: string | undefined;
+    limit?: number | undefined;
+    proximity?: string | [number, number] | undefined;
+    bbox?: [number, number, number, number] | undefined;
+    poi_category_exclusions?: string[] | undefined;
+}>;
+export declare class CategorySearchTool extends MapboxApiBasedTool<typeof CategorySearchInputSchema> {
+    name: string;
+    description: string;
+    constructor();
+    private formatGeoJsonToText;
+    protected execute(input: z.infer<typeof CategorySearchInputSchema>): Promise<{
+        type: 'text';
+        text: string;
+    }>;
+}
+export {};
+//# sourceMappingURL=CategorySearchTool.d.ts.map

package/dist/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;AAwe9D,QAAA,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;EAsE7B,CAAC;AAEH,qBAAa,kBAAmB,SAAQ,kBAAkB,CACxD,OAAO,yBAAyB,CACjC;IACC,IAAI,SAAwB;IAC5B,WAAW,SACwU;;IAMnV,OAAO,CAAC,mBAAmB;cAsDX,OAAO,CACrB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,GAC/C,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAgE3C"}