From 0ba8923f5e72e2bfbaa2656f0c81ffb285ac7901 Mon Sep 17 00:00:00 2001
From: Mofei Zhu <13761509829@163.com>
Date: Fri, 5 Sep 2025 11:21:16 +0300
Subject: [PATCH 1/7] add doc tool

---
 .../tool-naming-convention.test.ts.snap       |   5 +
 .../GetMapboxDocSourceTool.schema.ts          |   5 +
 .../GetMapboxDocSourceTool.test.ts            | 117 ++++++++++++++++++
 .../GetMapboxDocSourceTool.ts                 |  40 ++++++
 src/tools/toolRegistry.ts                     |   2 +
 5 files changed, 169 insertions(+)
 create mode 100644 src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.schema.ts
 create mode 100644 src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.test.ts
 create mode 100644 src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.ts

diff --git a/src/tools/__snapshots__/tool-naming-convention.test.ts.snap b/src/tools/__snapshots__/tool-naming-convention.test.ts.snap
index b606c85..a6c1d9d 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": "Fetch and return Mapbox documentation source collection content from llms.txt",
+    "toolName": "get_mapbox_doc_source_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<typeof GetMapboxDocSourceSchema>;
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..20b3033
--- /dev/null
+++ b/src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.test.ts
@@ -0,0 +1,117 @@
+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<typeof fetch>;
+
+  beforeEach(() => {
+    tool = new GetMapboxDocSourceTool();
+    mockFetch.mockClear();
+  });
+
+  it('should have correct name and description', () => {
+    expect(tool.name).toBe('get_mapbox_doc_source_tool');
+    expect(tool.description).toContain('Fetch and return Mapbox documentation');
+  });
+
+  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..77d7c21
--- /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_mapbox_doc_source_tool';
+  description =
+    'Fetch and return Mapbox documentation source collection content from llms.txt';
+
+  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;

From 483ebb09d4599e3229adf42c0b2824da024a85d7 Mon Sep 17 00:00:00 2001
From: Mofei Zhu <13761509829@163.com>
Date: Fri, 5 Sep 2025 11:39:38 +0300
Subject: [PATCH 2/7] add doc

---
 README.md                                     |  26 +++
 docs/mapbox-docs-tool-demo.md                 | 171 ++++++++++++++++++
 .../tool-naming-convention.test.ts.snap       |   4 +-
 .../GetMapboxDocSourceTool.test.ts            |   8 +-
 .../GetMapboxDocSourceTool.ts                 |   4 +-
 5 files changed, 207 insertions(+), 6 deletions(-)
 create mode 100644 docs/mapbox-docs-tool-demo.md

diff --git a/README.md b/README.md
index a5ff1e5..8dcf324 100644
--- a/README.md
+++ b/README.md
@@ -189,6 +189,32 @@ 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"
 
+#### 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.
+
+**Parameters:** None required
+
+**Example:**
+
+```json
+{}
+```
+
+**Returns:** Complete Mapbox documentation including all current APIs, SDKs, tools, and developer resources. Always up-to-date and more reliable than web search results.
+
+**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)**
+
 ### Local processing tools
 
 #### GeoJSON Preview tool (Beta)
diff --git a/docs/mapbox-docs-tool-demo.md b/docs/mapbox-docs-tool-demo.md
new file mode 100644
index 0000000..24fe940
--- /dev/null
+++ b/docs/mapbox-docs-tool-demo.md
@@ -0,0 +1,171 @@
+# 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.
+
+## 🎯 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.
+```
+
+```
+Show me all current Mapbox services and SDKs available for developers.
+```
+
+```
+I need the most up-to-date Mapbox documentation for my project planning.
+```
+
+### 2. Development Planning
+
+```
+I'm building a location-based mobile application. What Mapbox tools and APIs should I consider for my tech stack?
+```
+
+```
+Help me understand the complete Mapbox developer platform - what options do I have?
+```
+
+```
+What mapping solutions does Mapbox offer? I need to choose the right approach for my web application.
+```
+
+### 3. Learning & Research
+
+```
+Give me a comprehensive overview of Mapbox's current product ecosystem.
+```
+
+```
+What are Mapbox's navigation and routing capabilities? Please provide current details.
+```
+
+```
+Explain the differences between Mapbox web SDKs and mobile SDKs.
+```
+
+```
+I'm new to Mapbox development. Can you give me an overview of their documentation and resources?
+```
+
+### 4. Architecture Decisions
+
+```
+For a real estate application with interactive maps and address search, what Mapbox APIs would be most relevant?
+```
+
+```
+I need to implement mapping, geocoding, and turn-by-turn routing. What are my Mapbox options?
+```
+
+```
+Compare Mapbox solutions for web applications versus mobile app implementations.
+```
+
+```
+I'm building a logistics platform. What Mapbox services should I evaluate?
+```
+
+### 5. Latest Information Requests
+
+```
+What's new in the Mapbox ecosystem? I want to make sure I'm aware of all current offerings.
+```
+
+```
+Are there any recent additions to Mapbox's API collection that I should know about?
+```
+
+```
+Give me a current state overview of Mapbox developer tools and services.
+```
+
+```
+I last used Mapbox 2 years ago. What has changed and what new services are available?
+```
+
+## 🎪 Interactive Demo Session
+
+Try this complete conversation flow:
+
+**You:** "I'm planning a food delivery app with real-time tracking and route optimization. What current Mapbox services would be relevant?"
+
+**Expected AI behavior:**
+
+1. The AI should use `get_latest_mapbox_docs_tool`
+2. Provide specific recommendations based on current Mapbox offerings
+3. Include relevant APIs like Navigation SDK, Directions API, etc.
+
+**Follow-up:** "Can you give me more details about the Navigation SDK options?"
+
+**Expected AI behavior:**
+
+1. Reference the already-fetched documentation
+2. Provide specific details about iOS/Android Navigation SDKs
+3. Include links to relevant documentation
+
+## 🔍 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
+
+```
+I need to architect a complete geospatial solution with mapping, search, routing, and analytics. Based on the latest Mapbox offerings, what would be the optimal combination of services?
+```
+
+### Competitive Analysis
+
+```
+I'm evaluating Mapbox versus other mapping platforms. What are all the current Mapbox capabilities I should consider in my analysis?
+```
+
+### Migration Planning
+
+```
+We're currently using [other platform]. What are all the Mapbox 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
+
+---
+
+_This demo file is designed to help developers and AI assistants make the most of the Mapbox Documentation Tool. The prompts are crafted to naturally trigger the correct tool selection while providing valuable, current information._
diff --git a/src/tools/__snapshots__/tool-naming-convention.test.ts.snap b/src/tools/__snapshots__/tool-naming-convention.test.ts.snap
index a6c1d9d..204a4e5 100644
--- a/src/tools/__snapshots__/tool-naming-convention.test.ts.snap
+++ b/src/tools/__snapshots__/tool-naming-convention.test.ts.snap
@@ -39,8 +39,8 @@ exports[`Tool Naming Convention should maintain consistent tool list (snapshot t
   },
   {
     "className": "GetMapboxDocSourceTool",
-    "description": "Fetch and return Mapbox documentation source collection content from llms.txt",
-    "toolName": "get_mapbox_doc_source_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.",
+    "toolName": "get_latest_mapbox_docs_tool",
   },
   {
     "className": "ListStylesTool",
diff --git a/src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.test.ts b/src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.test.ts
index 20b3033..d857e42 100644
--- a/src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.test.ts
+++ b/src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.test.ts
@@ -13,8 +13,12 @@ describe('GetMapboxDocSourceTool', () => {
   });
 
   it('should have correct name and description', () => {
-    expect(tool.name).toBe('get_mapbox_doc_source_tool');
-    expect(tool.description).toContain('Fetch and return Mapbox documentation');
+    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 () => {
diff --git a/src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.ts b/src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.ts
index 77d7c21..3474146 100644
--- a/src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.ts
+++ b/src/tools/get-mapbox-doc-source-tool/GetMapboxDocSourceTool.ts
@@ -7,9 +7,9 @@ import {
 export class GetMapboxDocSourceTool extends BaseTool<
   typeof GetMapboxDocSourceSchema
 > {
-  name = 'get_mapbox_doc_source_tool';
+  name = 'get_latest_mapbox_docs_tool';
   description =
-    'Fetch and return Mapbox documentation source collection content from llms.txt';
+    '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 });

From 7a37933843eaa2d8057656139da7578e8d55effa Mon Sep 17 00:00:00 2001
From: Mofei Zhu <13761509829@163.com>
Date: Fri, 5 Sep 2025 11:42:37 +0300
Subject: [PATCH 3/7] update doc

---
 README.md | 97 +++++++++++++++++++++++++++++++++----------------------
 1 file changed, 58 insertions(+), 39 deletions(-)

diff --git a/README.md b/README.md
index 8dcf324..108b84d 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,25 @@ A Model Context Protocol (MCP) server that provides AI assistants with direct ac
 
 ![Mapbox MCP DevKit Server Demo](./assets/mcp_server_devkit.gif)
 
+## 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:
@@ -59,9 +78,35 @@ The `MAPBOX_ACCESS_TOKEN` environment variable is required. **Each tool requires
 
 ## Tools
 
-### Mapbox API tools
+### Documentation 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.
+
+**Parameters:** None required
+
+**Example:**
+
+```json
+{}
+```
+
+**Returns:** Complete Mapbox documentation including all current APIs, SDKs, tools, and developer resources. Always up-to-date and more reliable than web search results.
+
+**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
+### Style Management Tools
 
 Complete set of tools for managing Mapbox styles via the Styles API:
 
@@ -115,7 +160,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,33 +234,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"
 
-#### 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.
-
-**Parameters:** None required
-
-**Example:**
-
-```json
-{}
-```
-
-**Returns:** Complete Mapbox documentation including all current APIs, SDKs, tools, and developer resources. Always up-to-date and more reliable than web search results.
-
-**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)**
-
-### Local processing tools
+### Local Processing Tools
 
 #### GeoJSON Preview tool (Beta)
 
@@ -341,11 +360,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.
 
@@ -386,9 +405,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
@@ -398,7 +417,7 @@ npm run build
 npx @modelcontextprotocol/inspector node dist/index.js
 ```
 
-### Using Docker
+#### Using Docker
 
 ```sh
 # Build the Docker image
@@ -408,7 +427,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
@@ -458,9 +477,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.
 

From 3db477a560c848ba337a4a4619fcf5b5774fd248 Mon Sep 17 00:00:00 2001
From: Mofei Zhu <13761509829@163.com>
Date: Fri, 5 Sep 2025 11:47:07 +0300
Subject: [PATCH 4/7] update doc

---
 docs/mapbox-docs-tool-demo.md | 36 ++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/docs/mapbox-docs-tool-demo.md b/docs/mapbox-docs-tool-demo.md
index 24fe940..5878fde 100644
--- a/docs/mapbox-docs-tool-demo.md
+++ b/docs/mapbox-docs-tool-demo.md
@@ -2,6 +2,8 @@
 
 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.
@@ -112,6 +114,14 @@ Try this complete conversation flow:
 2. Provide specific details about iOS/Android Navigation SDKs
 3. Include links to relevant documentation
 
+> **📝 Note**: The actual behavior may vary depending on your MCP client and AI model. Some models might:
+>
+> - Choose web search instead of the documentation tool
+> - Use the tool but focus on different aspects of the documentation
+> - Require more specific prompting to trigger the desired tool selection
+>
+> If the tool isn't being selected, try using more explicit language like "I need the most current official information" or "please use the latest documentation."
+
 ## 🔍 What Makes These Prompts Effective
 
 These prompts work because they:
@@ -166,6 +176,30 @@ We're currently using [other platform]. What are all the Mapbox services that co
 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.
+
 ---
 
-_This demo file is designed to help developers and AI assistants make the most of the Mapbox Documentation Tool. The prompts are crafted to naturally trigger the correct tool selection while providing valuable, current information._
+## 📋 **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._

From 4ee486e9b49a35af8802cf669018dbac0e8f0c97 Mon Sep 17 00:00:00 2001
From: Mofei Zhu <13761509829@163.com>
Date: Fri, 5 Sep 2025 11:50:16 +0300
Subject: [PATCH 5/7] update doc

---
 docs/mapbox-docs-tool-demo.md | 96 +++++++++++++++++++++--------------
 1 file changed, 57 insertions(+), 39 deletions(-)

diff --git a/docs/mapbox-docs-tool-demo.md b/docs/mapbox-docs-tool-demo.md
index 5878fde..2543ee2 100644
--- a/docs/mapbox-docs-tool-demo.md
+++ b/docs/mapbox-docs-tool-demo.md
@@ -19,108 +19,126 @@ What are the latest Mapbox APIs available for developers? I want to make sure I'
 ```
 
 ```
-Show me all current Mapbox services and SDKs available for developers.
+I need the most up-to-date official Mapbox documentation. Can you provide a complete overview?
 ```
 
 ```
-I need the most up-to-date Mapbox documentation for my project planning.
+Please show me all current Mapbox services and APIs using the latest documentation.
 ```
 
-### 2. Development Planning
+### 2. Development Planning (More Direct Approach)
 
 ```
-I'm building a location-based mobile application. What Mapbox tools and APIs should I consider for my tech stack?
+Can you get the latest official Mapbox documentation and help me understand what developer tools are available?
 ```
 
 ```
-Help me understand the complete Mapbox developer platform - what options do I have?
+I need current information from Mapbox documentation about their complete developer platform.
 ```
 
 ```
-What mapping solutions does Mapbox offer? I need to choose the right approach for my web application.
+Please use the most recent Mapbox documentation to show me all mapping solutions they offer.
 ```
 
 ### 3. Learning & Research
 
 ```
-Give me a comprehensive overview of Mapbox's current product ecosystem.
+Using the latest Mapbox documentation, give me a comprehensive overview of their current product ecosystem.
 ```
 
 ```
-What are Mapbox's navigation and routing capabilities? Please provide current details.
+I need up-to-date official information about Mapbox's navigation and routing capabilities.
 ```
 
 ```
-Explain the differences between Mapbox web SDKs and mobile SDKs.
+Please check the current Mapbox documentation and explain the differences between their web and mobile SDKs.
 ```
 
 ```
-I'm new to Mapbox development. Can you give me an overview of their documentation and resources?
+I'm new to Mapbox. Can you get the latest official documentation and give me an overview of their resources?
 ```
 
 ### 4. Architecture Decisions
 
 ```
-For a real estate application with interactive maps and address search, what Mapbox APIs would be most relevant?
+Can you check the latest Mapbox documentation and tell me what APIs are available for real estate applications with maps and search?
 ```
 
 ```
-I need to implement mapping, geocoding, and turn-by-turn routing. What are my Mapbox options?
+I need current Mapbox documentation about mapping, geocoding, and routing options. What's available?
 ```
 
 ```
-Compare Mapbox solutions for web applications versus mobile app implementations.
+Using the latest official Mapbox documentation, compare their web versus mobile solutions.
 ```
 
 ```
-I'm building a logistics platform. What Mapbox services should I evaluate?
+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? I want to make sure I'm aware of all current offerings.
+What's new in the Mapbox ecosystem? Please use the latest official documentation to show me all current offerings.
 ```
 
 ```
-Are there any recent additions to Mapbox's API collection that I should know about?
+Can you get the most recent Mapbox documentation and tell me about any recent additions to their APIs?
 ```
 
 ```
-Give me a current state overview of Mapbox developer tools and services.
+I need the current state of Mapbox developer tools - please check their latest documentation.
 ```
 
 ```
-I last used Mapbox 2 years ago. What has changed and what new services are available?
+I last used Mapbox 2 years ago. Can you get the latest documentation and show me what has changed?
 ```
 
 ## 🎪 Interactive Demo Session
 
-Try this complete conversation flow:
+### More Effective Examples (Based on Real Testing):
 
-**You:** "I'm planning a food delivery app with real-time tracking and route optimization. What current Mapbox services would be relevant?"
+**Try these prompts that are more likely to trigger the documentation tool:**
 
-**Expected AI behavior:**
+**Example 1:**
 
-1. The AI should use `get_latest_mapbox_docs_tool`
-2. Provide specific recommendations based on current Mapbox offerings
-3. Include relevant APIs like Navigation SDK, Directions API, etc.
+```
+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?"**
 
-**Follow-up:** "Can you give me more details about the Navigation SDK options?"
+- _Problem_: Implementation-focused, may trigger general coding help
 
-**Expected AI behavior:**
+### Why Some Examples Work Better:
 
-1. Reference the already-fetched documentation
-2. Provide specific details about iOS/Android Navigation SDKs
-3. Include links to relevant documentation
+✅ **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"
 
-> **📝 Note**: The actual behavior may vary depending on your MCP client and AI model. Some models might:
->
-> - Choose web search instead of the documentation tool
-> - Use the tool but focus on different aspects of the documentation
-> - Require more specific prompting to trigger the desired tool selection
->
-> If the tool isn't being selected, try using more explicit language like "I need the most current official information" or "please use the latest documentation."
+> **📝 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
 
@@ -153,19 +171,19 @@ These prompts work because they:
 ### Complex Project Planning
 
 ```
-I need to architect a complete geospatial solution with mapping, search, routing, and analytics. Based on the latest Mapbox offerings, what would be the optimal combination of services?
+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 mapping platforms. What are all the current Mapbox capabilities I should consider in my 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 currently using [other platform]. What are all the Mapbox services that could replace our current functionality?
+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

From 069bb515990ffec80ccdae6f236e7dde226d655f Mon Sep 17 00:00:00 2001
From: Mofei Zhu <13761509829@163.com>
Date: Fri, 5 Sep 2025 15:34:41 +0300
Subject: [PATCH 6/7] 0.3.2

---
 package-lock.json | 4 ++--
 package.json      | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

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",

From 2916dfa93c96a92c71d46dd38f6645436114474c Mon Sep 17 00:00:00 2001
From: Mofei Zhu <13761509829@163.com>
Date: Fri, 5 Sep 2025 15:46:00 +0300
Subject: [PATCH 7/7] Update README.md

---
 README.md | 21 +++++----------------
 1 file changed, 5 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index 108b84d..94c4885 100644
--- a/README.md
+++ b/README.md
@@ -23,18 +23,18 @@ A Model Context Protocol (MCP) server that provides AI assistants with direct ac
 
 ## Quick Start
 
-## Integration with Developer Tools
+### 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:
 
@@ -58,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.**
 
@@ -80,19 +80,8 @@ The `MAPBOX_ACCESS_TOKEN` environment variable is required. **Each tool requires
 
 ### Documentation Tools
 
-#### get_latest_mapbox_docs_tool
+**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.
 
-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.
-
-**Parameters:** None required
-
-**Example:**
-
-```json
-{}
-```
-
-**Returns:** Complete Mapbox documentation including all current APIs, SDKs, tools, and developer resources. Always up-to-date and more reliable than web search results.
 
 **Example prompts:**