[cursor] Adding bug fixes for known Cursor issues

Author: mattpodwysocki

CLAUDE.md

@@ -71,6 +71,7 @@ This file provides Claude and developers with essential context, commands, and s
 
 ## Known Issues & Warnings
 
+- **Cursor + OpenAI models compatibility issue** - ALL OpenAI models (GPT-4, GPT-3.5, o1, o1-mini) fail with `[invalid_argument]` errors in Cursor when using `create_style_tool` and `update_style_tool` (works fine in VS Code, works fine with Claude in Cursor). Root cause: Cursor can't handle tools with complex input schemas when used with OpenAI models. **Workaround:** Set `CURSOR_OPENAI_MODE=true` to auto-disable the problematic tools. You'll still have 15/17 tools working.
 - Large GeoJSON files may cause slow performance in preview tools
 - Always check token scopes if a tool fails with authentication errors
 - Use `VERBOSE_ERRORS=true` for detailed error output

README.md

@@ -35,6 +35,10 @@ https://github.com/user-attachments/assets/8b1b8ef2-9fba-4951-bc9a-beaed4f6aff6
     - [Creating New Tools](#creating-new-tools)
     - [Environment Variables](#environment-variables)
       - [VERBOSE_ERRORS](#verbose_errors)
+      - [CURSOR_OPENAI_MODE](#cursor_openai_mode)
+  - [Troubleshooting](#troubleshooting)
+    - [Cursor + OpenAI Models Issues](#cursor--openai-models-issues)
+    - [General Troubleshooting](#general-troubleshooting)
   - [Contributing](#contributing)
 
 ## Quick Start
@@ -558,6 +562,109 @@ Set `VERBOSE_ERRORS=true` to get detailed error messages from the MCP server. Th
 
 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.
 
+#### CURSOR_OPENAI_MODE
+
+Set `CURSOR_OPENAI_MODE=true` when using **any OpenAI model (GPT-4, GPT-3.5, o1, o1-mini) in Cursor**. This is a simple workaround for Cursor's bug with OpenAI models and complex tool schemas.
+
+**What it does:**
+
+- Automatically disables `create_style_tool` and `update_style_tool`
+- These tools have complex input schemas that break Cursor's OpenAI integration
+- You'll still have 15 out of 17 tools working (all read/query/preview operations)
+
+**When to use:**
+
+- ✅ Using GPT-4, GPT-3.5, o1, or o1-mini in Cursor
+- ❌ Not needed for Claude models in Cursor (all tools work)
+- ❌ Not needed in VS Code (all tools work with all models)
+
+**Example:**
+
+```json
+{
+  "mcpServers": {
+    "mapbox-devkit": {
+      "env": {
+        "MAPBOX_ACCESS_TOKEN": "your-token",
+        "CURSOR_OPENAI_MODE": "true"
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### Cursor + OpenAI Models Issues
+
+**Problem:** When using **any OpenAI model (GPT-4, GPT-3.5, o1, o1-mini)** in Cursor, the `create_style_tool` and `update_style_tool` cause failures with `[invalid_argument]` errors.
+
+**Example error:**
+
+```
+ConnectError: [invalid_argument] Error
+The model returned an error. Try disabling MCP servers, or switch models.
+```
+
+**Cause:** This is a Cursor-specific bug with o1 model MCP integration. The same server works fine with o1 in VS Code and other MCP clients.
+
+**Root Cause:** Cursor's integration with OpenAI models fails when tools have complex input schemas with `.passthrough()` (like `create_style_tool` and `update_style_tool` which accept full Mapbox Style Specification objects). The error is: `[AiService] streamResponse ConnectError: [invalid_argument]`
+
+**Affected:**
+
+- ❌ Cursor + GPT-4 - Fails with these 2 tools
+- ❌ Cursor + GPT-3.5 - Fails with these 2 tools
+- ❌ Cursor + o1/o1-mini - Fails with these 2 tools
+- ✅ Cursor + Claude - Works with all tools
+- ✅ VS Code + any model - Works with all tools
+
+**Simple Fix - Use CURSOR_OPENAI_MODE:**
+Add `CURSOR_OPENAI_MODE=true` to automatically disable the problematic tools:
+
+```json
+{
+  "mcpServers": {
+    "mapbox-devkit": {
+      "command": "node",
+      "args": ["/path/to/dist/esm/index.js"],
+      "env": {
+        "MAPBOX_ACCESS_TOKEN": "your-token",
+        "CURSOR_OPENAI_MODE": "true"
+      }
+    }
+  }
+}
+```
+
+This automatically disables `create_style_tool` and `update_style_tool` which have complex input schemas that break Cursor's OpenAI integration. You'll still have **15 out of 17 tools** working, including all read/query operations.
+
+**Other Solutions:**
+
+1. **Use Claude in Cursor** - All 17 tools work perfectly with Claude models in Cursor
+2. **Use VS Code** - All OpenAI models work with all 17 tools in VS Code (no workaround needed)
+3. **Manually disable tools:**
+   ```json
+   {
+     "args": [
+       "/path/to/dist/esm/index.js",
+       "--disable-tools",
+       "create_style_tool,update_style_tool"
+     ]
+   }
+   ```
+
+**Status:** This is a Cursor bug with how it handles OpenAI models + MCP tools with complex input schemas. The same tools work fine in VS Code.
+
+### General Troubleshooting
+
+**Issue:** Tools fail with authentication errors
+
+**Solution:** Check that your `MAPBOX_ACCESS_TOKEN` has the required scopes for the tool you're using. See the token scopes section above.
+
+**Issue:** Large GeoJSON files cause slow performance
+
+**Solution:** The GeoJSON preview tool may be slow with very large files. Consider simplifying geometries or using smaller datasets for preview purposes.
+
 ## Contributing
 
 We welcome contributions to the Mapbox Development MCP Server! Please review our standards and guidelines before contributing:

src/index.ts

@@ -16,6 +16,14 @@ const config = parseToolConfigFromArgs();
 
 // Get and filter tools based on configuration
 const allTools = getAllTools();
+
+// Cursor + OpenAI models have issues with complex input schemas (create_style_tool, update_style_tool)
+// This provides an easy workaround
+const cursorOpenAiMode = process.env.CURSOR_OPENAI_MODE === 'true';
+if (cursorOpenAiMode && !config.disabledTools) {
+  config.disabledTools = ['create_style_tool', 'update_style_tool'];
+}
+
 const enabledTools = filterTools(allTools, config);
 
 // Create an MCP server