diff --git a/README.md b/README.md index a5ff1e5..94c4885 100644 --- a/README.md +++ b/README.md @@ -4,18 +4,37 @@ A Model Context Protocol (MCP) server that provides AI assistants with direct ac ![Mapbox MCP DevKit Server Demo](./assets/mcp_server_devkit.gif) -## Integration with Developer Tools +## Table of Contents + +- [Quick Start](#quick-start) + - [Integration with Developer Tools](#integration-with-developer-tools) + - [DXT Package Distribution](#dxt-package-distribution) + - [Getting Your Mapbox Access Token](#getting-your-mapbox-access-token) +- [Tools](#tools) + - [Documentation Tools](#documentation-tools) + - [Style Management Tools](#style-management-tools) + - [Token Management Tools](#token-management-tools) + - [Local Processing Tools](#local-processing-tools) +- [Development](#development) + - [Testing](#testing) + - [Inspecting Server](#inspecting-server) + - [Creating New Tools](#creating-new-tools) + - [Environment Variables](#environment-variables) + +## Quick Start + +### Integration with Developer Tools Get started by integrating with your preferred AI development environment: - [Claude Code Integration](./docs/claude-code-integration.md) - Command-line development with Claude - [Claude Desktop Integration](./docs/claude-desktop-integration.md) - Desktop application integration -## DXT Package Distribution +### DXT Package Distribution This MCP server can be packaged as a DXT (Desktop Extension) file for easy distribution and installation. DXT is a standardized format for distributing local MCP servers, similar to browser extensions. -### Creating the DXT Package +#### Creating the DXT Package To create a DXT package: @@ -39,7 +58,7 @@ The DXT package includes: - User configuration schema for the Mapbox access token - Automatic environment variable setup -## Getting Your Mapbox Access Token +### Getting Your Mapbox Access Token **A Mapbox access token is required to use this MCP server.** @@ -59,9 +78,24 @@ The `MAPBOX_ACCESS_TOKEN` environment variable is required. **Each tool requires ## Tools -### Mapbox API tools +### Documentation Tools -#### Style Management Tools +**get_latest_mapbox_docs_tool** - Access the latest official Mapbox documentation directly from the source. This tool fetches comprehensive, up-to-date information about all Mapbox APIs, SDKs, and developer resources from docs.mapbox.com/llms.txt. + + +**Example prompts:** + +- "What are the latest Mapbox APIs available for developers?" +- "Show me all current Mapbox services and SDKs" +- "I need up-to-date Mapbox documentation for my project" +- "What mapping solutions does Mapbox offer for my tech stack?" +- "Give me an overview of Mapbox's navigation and routing capabilities" +- "Compare Mapbox web SDKs versus mobile SDKs" +- "What's new in the Mapbox ecosystem?" + +📖 **[See more examples and interactive demo →](./docs/mapbox-docs-tool-demo.md)** + +### Style Management Tools Complete set of tools for managing Mapbox styles via the Styles API: @@ -115,7 +149,7 @@ Complete set of tools for managing Mapbox styles via the Styles API: - "Please generate a preview link for this style" - "Can you change the background to snow style?" -#### Token Management Tools +### Token Management Tools #### create-token @@ -189,7 +223,7 @@ List Mapbox access tokens for the authenticated user with optional filtering and - "List the 5 most recently modified tokens" - "Show all public tokens in my account" -### Local processing tools +### Local Processing Tools #### GeoJSON Preview tool (Beta) @@ -315,11 +349,11 @@ An array of four numbers representing the bounding box: `[minX, minY, maxX, maxY - "Calculate the bounding box of this GeoJSON file" (then upload a .geojson file) - "What's the bounding box for the coordinates in the uploaded parks.geojson file?" -# Development +## Development -## Testing +### Testing -### Tool Snapshot Tests +#### Tool Snapshot Tests The project includes snapshot tests to ensure tool integrity and prevent accidental additions or removals of tools. These tests automatically discover all tools and create a snapshot of their metadata. @@ -360,9 +394,9 @@ npm test -- --updateSnapshot **Important**: Only update snapshots when you have intentionally added, removed, or modified tools. Unexpected snapshot failures indicate accidental changes to the tool structure. -## Inspecting server +### Inspecting Server -### Using Node.js +#### Using Node.js ```sh # Build @@ -372,7 +406,7 @@ npm run build npx @modelcontextprotocol/inspector node dist/index.js ``` -### Using Docker +#### Using Docker ```sh # Build the Docker image @@ -382,7 +416,7 @@ docker build -t mapbox-mcp-devkit . npx @modelcontextprotocol/inspector docker run -i --rm --env MAPBOX_ACCESS_TOKEN="YOUR_TOKEN" mapbox-mcp-devkit ``` -## Create new tool +### Creating New Tools ```sh npx plop create-tool @@ -432,9 +466,9 @@ src/tools/your-tool-name-tool/ - Consistent with existing tools in the project - Enhanced TypeScript type safety -## Environment Variables +### Environment Variables -### VERBOSE_ERRORS +#### 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. diff --git a/docs/mapbox-docs-tool-demo.md b/docs/mapbox-docs-tool-demo.md new file mode 100644 index 0000000..2543ee2 --- /dev/null +++ b/docs/mapbox-docs-tool-demo.md @@ -0,0 +1,223 @@ +# Mapbox Documentation Tool Demo + +This demo showcases the `get_latest_mapbox_docs_tool` and provides example prompts that will trigger the AI assistant to use this tool instead of web search. + +> **⚠️ Important Note**: Different MCP clients (Claude Desktop, Claude Code, etc.) and different LLM models may exhibit varying behavior when selecting tools. The examples below are demonstrations of intended behavior and may not work identically across all environments. Tool selection depends on the specific AI model's training, the MCP client implementation, and system prompts used. + +## 🎯 Tool Overview + +The `get_latest_mapbox_docs_tool` automatically fetches the latest official Mapbox documentation from `docs.mapbox.com/llms.txt`. This ensures AI assistants always have access to current, authoritative information about Mapbox APIs and services. + +## 📝 Demo Prompts + +Try these prompts with your AI assistant to see the tool in action: + +### 1. Basic Documentation Queries + +``` +What are the latest Mapbox APIs available for developers? I want to make sure I'm using the most current information. +``` + +``` +I need the most up-to-date official Mapbox documentation. Can you provide a complete overview? +``` + +``` +Please show me all current Mapbox services and APIs using the latest documentation. +``` + +### 2. Development Planning (More Direct Approach) + +``` +Can you get the latest official Mapbox documentation and help me understand what developer tools are available? +``` + +``` +I need current information from Mapbox documentation about their complete developer platform. +``` + +``` +Please use the most recent Mapbox documentation to show me all mapping solutions they offer. +``` + +### 3. Learning & Research + +``` +Using the latest Mapbox documentation, give me a comprehensive overview of their current product ecosystem. +``` + +``` +I need up-to-date official information about Mapbox's navigation and routing capabilities. +``` + +``` +Please check the current Mapbox documentation and explain the differences between their web and mobile SDKs. +``` + +``` +I'm new to Mapbox. Can you get the latest official documentation and give me an overview of their resources? +``` + +### 4. Architecture Decisions + +``` +Can you check the latest Mapbox documentation and tell me what APIs are available for real estate applications with maps and search? +``` + +``` +I need current Mapbox documentation about mapping, geocoding, and routing options. What's available? +``` + +``` +Using the latest official Mapbox documentation, compare their web versus mobile solutions. +``` + +``` +Please get the most recent Mapbox documentation and show me services relevant for logistics platforms. +``` + +### 5. Latest Information Requests + +``` +What's new in the Mapbox ecosystem? Please use the latest official documentation to show me all current offerings. +``` + +``` +Can you get the most recent Mapbox documentation and tell me about any recent additions to their APIs? +``` + +``` +I need the current state of Mapbox developer tools - please check their latest documentation. +``` + +``` +I last used Mapbox 2 years ago. Can you get the latest documentation and show me what has changed? +``` + +## 🎪 Interactive Demo Session + +### More Effective Examples (Based on Real Testing): + +**Try these prompts that are more likely to trigger the documentation tool:** + +**Example 1:** + +``` +What are the latest Mapbox APIs available for developers? I want to make sure I'm using the most current information. +``` + +**Example 2:** + +``` +I need the most up-to-date Mapbox documentation for my project. Can you show me all current services available? +``` + +**Example 3:** + +``` +Please use the latest official Mapbox documentation to tell me about their navigation capabilities. +``` + +### Less Effective Examples: + +❌ **"I'm planning a food delivery app with real-time tracking and route optimization. What current Mapbox services would be relevant?"** + +- _Problem_: Too project-specific, may trigger general knowledge response + +❌ **"What Mapbox APIs should I use for my app?"** + +- _Problem_: Too general, may trigger web search + +❌ **"How do I implement Mapbox in React?"** + +- _Problem_: Implementation-focused, may trigger general coding help + +### Why Some Examples Work Better: + +✅ **Direct documentation requests**: "latest Mapbox documentation", "current APIs available" +✅ **Emphasis on currency**: "most current information", "up-to-date" +✅ **Official source requests**: "official Mapbox documentation", "latest official information" + +> **📝 Real-World Note**: Based on testing, prompts that explicitly request documentation or emphasize getting the latest official information have higher success rates for triggering the documentation tool. + +## 🔍 What Makes These Prompts Effective + +These prompts work because they: + +- ✅ **Emphasize currency**: Use words like "latest", "current", "up-to-date" +- ✅ **Request completeness**: Ask for "all", "comprehensive", "complete overview" +- ✅ **Imply official sources**: Request "current offerings", "official documentation" +- ✅ **Suggest comparison needs**: Multiple options require comprehensive data +- ✅ **Focus on accuracy**: "make sure I'm using correct information" + +## 🚀 Benefits Demonstration + +### Before (using web search): + +- May get outdated information +- Fragmented results from multiple sources +- Potential inaccuracies from third-party sites +- Missing new APIs or changes + +### After (using get_latest_mapbox_docs_tool): + +- ✅ Always current official information +- ✅ Complete ecosystem overview +- ✅ Authoritative source (directly from Mapbox) +- ✅ Includes latest APIs and features + +## 🎛 Advanced Usage + +### Complex Project Planning + +``` +Can you get the latest Mapbox documentation and help me architect a geospatial solution with mapping, search, routing, and analytics? I need to know what services are currently available. +``` + +### Competitive Analysis + +``` +I'm evaluating Mapbox versus other platforms. Please use the most current official Mapbox documentation to show me all their capabilities for my analysis. +``` + +### Migration Planning + +``` +We're migrating from another platform. Can you check the latest Mapbox documentation and show me all services that could replace our current functionality? +``` + +## 💡 Pro Tips + +1. **Use temporal keywords**: "latest", "current", "up-to-date", "recent" +2. **Request comprehensiveness**: "all", "complete", "entire", "full" +3. **Emphasize accuracy**: "official", "authoritative", "correct" +4. **Avoid specific tool names**: Let the AI choose the right tool naturally +5. **Context matters**: Mention your project needs to get relevant filtering + +### 🔧 **Troubleshooting Tool Selection** + +If the AI is not using the documentation tool: + +- **Be more explicit**: "I need official Mapbox documentation" or "Please use the latest source" +- **Emphasize currency**: "Make sure you have the most current information" +- **Request authority**: "I want authoritative information directly from Mapbox" +- **Try rephrasing**: Different models respond to different prompt styles +- **Check your MCP setup**: Ensure the tool is properly registered and available + +### 🌐 **Environment Considerations** + +**Claude Desktop vs Claude Code**: Different interfaces may have varying tool selection behaviors. + +**Model Versions**: Newer models may be better at tool selection than older ones. + +**System Prompts**: Some MCP clients may have system prompts that influence tool selection preferences. + +--- + +## 📋 **Disclaimer** + +_This demo file provides **examples and suggestions** for using the Mapbox Documentation Tool. The prompts are crafted to **ideally** trigger correct tool selection, but actual behavior **will vary** across different MCP clients, AI models, and system configurations._ + +_**Results may vary**: Tool selection depends on many factors including model training, client implementation, and system prompts. These examples show **intended behavior** rather than guaranteed outcomes._ + +_Use these examples as **starting points** and adjust your prompts based on your specific environment and the AI assistant's responses._ diff --git a/package-lock.json b/package-lock.json index 85dc55a..191f4cd 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@mapbox/mcp-devkit-server", - "version": "0.3.1", + "version": "0.3.2", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@mapbox/mcp-devkit-server", - "version": "0.3.1", + "version": "0.3.2", "license": "BSD-3-Clause", "dependencies": { "@modelcontextprotocol/sdk": "^1.12.1", diff --git a/package.json b/package.json index 33d26b2..a4bc837 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@mapbox/mcp-devkit-server", - "version": "0.3.1", + "version": "0.3.2", "description": "Mapbox MCP devkit server", "main": "dist/index.js", "module": "dist/index-esm.js", diff --git a/src/tools/__snapshots__/tool-naming-convention.test.ts.snap b/src/tools/__snapshots__/tool-naming-convention.test.ts.snap index b606c85..204a4e5 100644 --- a/src/tools/__snapshots__/tool-naming-convention.test.ts.snap +++ b/src/tools/__snapshots__/tool-naming-convention.test.ts.snap @@ -37,6 +37,11 @@ exports[`Tool Naming Convention should maintain consistent tool list (snapshot t "description": "Generate a geojson.io URL to visualize GeoJSON data. Returns only the URL link.", "toolName": "geojson_preview_tool", }, + { + "className": "GetMapboxDocSourceTool", + "description": "Get the latest official Mapbox documentation, APIs, SDKs, and developer resources directly from Mapbox. Always up-to-date, comprehensive coverage of all current Mapbox services including mapping, navigation, search, geocoding, and mobile SDKs. Use this for accurate, official Mapbox information instead of web search.", + "toolName": "get_latest_mapbox_docs_tool", + }, { "className": "ListStylesTool", "description": "List styles for a Mapbox account. Use limit parameter to avoid large responses (recommended: limit=5-10). Use start parameter for pagination.", diff --git a/src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.schema.ts b/src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.schema.ts new file mode 100644 index 0000000..ccc29ef --- /dev/null +++ b/src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.schema.ts @@ -0,0 +1,5 @@ +import { z } from 'zod'; + +export const GetMapboxDocSourceSchema = z.object({}); + +export type GetMapboxDocSourceInput = z.infer; diff --git a/src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.test.ts b/src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.test.ts new file mode 100644 index 0000000..d857e42 --- /dev/null +++ b/src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.test.ts @@ -0,0 +1,121 @@ +import { GetMapboxDocSourceTool } from './GetMapboxDocSourceTool.js'; + +// Mock fetch for testing +global.fetch = jest.fn(); + +describe('GetMapboxDocSourceTool', () => { + let tool: GetMapboxDocSourceTool; + const mockFetch = global.fetch as jest.MockedFunction; + + beforeEach(() => { + tool = new GetMapboxDocSourceTool(); + mockFetch.mockClear(); + }); + + it('should have correct name and description', () => { + expect(tool.name).toBe('get_latest_mapbox_docs_tool'); + expect(tool.description).toContain( + 'Get the latest official Mapbox documentation' + ); + expect(tool.description).toContain('Always up-to-date'); + expect(tool.description).toContain('instead of web search'); + }); + + it('should successfully fetch documentation content', async () => { + const mockContent = `# Mapbox Documentation + +This is the Mapbox developer documentation for LLMs. + +## Web SDKs +- Mapbox GL JS for interactive maps +- Mobile SDKs for iOS and Android + +## APIs +- Geocoding API for address search +- Directions API for routing`; + + mockFetch.mockResolvedValueOnce({ + ok: true, + status: 200, + text: () => Promise.resolve(mockContent) + } as Response); + + const result = await tool.run({}); + + expect(mockFetch).toHaveBeenCalledWith('https://docs.mapbox.com/llms.txt'); + expect(result.content).toHaveLength(1); + expect(result.content[0].type).toBe('text'); + + if (result.content[0].type === 'text') { + expect(result.content[0].text).toBe(mockContent); + } + expect(result.isError).toBe(false); + }); + + it('should handle HTTP errors', async () => { + mockFetch.mockResolvedValueOnce({ + ok: false, + status: 404 + } as Response); + + const result = await tool.run({}); + + expect(result.isError).toBe(true); + expect(result.content[0].type).toBe('text'); + + if (result.content[0].type === 'text') { + expect(result.content[0].text).toContain( + 'Failed to fetch Mapbox documentation' + ); + expect(result.content[0].text).toContain('HTTP error! status: 404'); + } + }); + + it('should handle network errors', async () => { + mockFetch.mockRejectedValueOnce(new Error('Network error')); + + const result = await tool.run({}); + + expect(result.isError).toBe(true); + expect(result.content[0].type).toBe('text'); + + if (result.content[0].type === 'text') { + expect(result.content[0].text).toContain( + 'Failed to fetch Mapbox documentation' + ); + expect(result.content[0].text).toContain('Network error'); + } + }); + + it('should handle unknown errors', async () => { + mockFetch.mockRejectedValueOnce('Unknown error'); + + const result = await tool.run({}); + + expect(result.isError).toBe(true); + expect(result.content[0].type).toBe('text'); + + if (result.content[0].type === 'text') { + expect(result.content[0].text).toContain( + 'Failed to fetch Mapbox documentation' + ); + expect(result.content[0].text).toContain('Unknown error occurred'); + } + }); + + it('should work with empty input object', async () => { + const mockContent = 'Test documentation content'; + + mockFetch.mockResolvedValueOnce({ + ok: true, + status: 200, + text: () => Promise.resolve(mockContent) + } as Response); + + const result = await tool.run({}); + + expect(result.isError).toBe(false); + expect(result.content).toHaveLength(1); + expect(result.content[0].type).toBe('text'); + }); +}); diff --git a/src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.ts b/src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.ts new file mode 100644 index 0000000..3474146 --- /dev/null +++ b/src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.ts @@ -0,0 +1,40 @@ +import { BaseTool } from '../BaseTool.js'; +import { + GetMapboxDocSourceSchema, + GetMapboxDocSourceInput +} from './GetMapboxDocSourceTool.schema.js'; + +export class GetMapboxDocSourceTool extends BaseTool< + typeof GetMapboxDocSourceSchema +> { + name = 'get_latest_mapbox_docs_tool'; + description = + 'Get the latest official Mapbox documentation, APIs, SDKs, and developer resources directly from Mapbox. Always up-to-date, comprehensive coverage of all current Mapbox services including mapping, navigation, search, geocoding, and mobile SDKs. Use this for accurate, official Mapbox information instead of web search.'; + + constructor() { + super({ inputSchema: GetMapboxDocSourceSchema }); + } + + protected async execute( + _input: GetMapboxDocSourceInput + ): Promise<{ type: 'text'; text: string }> { + try { + const response = await fetch('https://docs.mapbox.com/llms.txt'); + + if (!response.ok) { + throw new Error(`HTTP error! status: ${response.status}`); + } + + const content = await response.text(); + + return { + type: 'text', + text: content + }; + } catch (error) { + const errorMessage = + error instanceof Error ? error.message : 'Unknown error occurred'; + throw new Error(`Failed to fetch Mapbox documentation: ${errorMessage}`); + } + } +} diff --git a/src/tools/toolRegistry.ts b/src/tools/toolRegistry.ts index ce481e4..8c8ee2d 100644 --- a/src/tools/toolRegistry.ts +++ b/src/tools/toolRegistry.ts @@ -5,6 +5,7 @@ import { CreateStyleTool } from './create-style-tool/CreateStyleTool.js'; import { CreateTokenTool } from './create-token-tool/CreateTokenTool.js'; import { DeleteStyleTool } from './delete-style-tool/DeleteStyleTool.js'; import { GeojsonPreviewTool } from './geojson-preview-tool/GeojsonPreviewTool.js'; +import { GetMapboxDocSourceTool } from './get-mapbox-doc-source-tool/GetMapboxDocSourceTool.js'; import { ListStylesTool } from './list-styles-tool/ListStylesTool.js'; import { ListTokensTool } from './list-tokens-tool/ListTokensTool.js'; import { PreviewStyleTool } from './preview-style-tool/PreviewStyleTool.js'; @@ -29,6 +30,7 @@ export const ALL_TOOLS = [ new BoundingBoxTool(), new CountryBoundingBoxTool(), new CoordinateConversionTool(), + new GetMapboxDocSourceTool(), new StyleComparisonTool(), new TilequeryTool() ] as const;