Merge pull request #41 from mapbox/otel_docs_fix

[otel] Update DevKit Server docs with OTEL information

Author: mattpodwysocki

.env.example

@@ -9,14 +9,6 @@
 # Get your token at: https://account.mapbox.com/access-tokens
 MAPBOX_ACCESS_TOKEN=your-mapbox-token-here
 
-# =============================================================================
-# Optional MCP Configuration
-# =============================================================================
-
-# Disable console logging (recommended when using stdio transport)
-# Uncomment to enable:
-# MCP_DISABLE_LOGGING=true
-
 # =============================================================================
 # OpenTelemetry Tracing (Optional)
 # =============================================================================
@@ -35,9 +27,12 @@ OTEL_SERVICE_NAME=mapbox-mcp-devkit-server
 # Resource attributes (customize as needed)
 OTEL_RESOURCE_ATTRIBUTES=service.name=mapbox-mcp-devkit-server,service.version=0.4.5
 
-# Optional: Console tracing for development (SSE transport only)
-# ⚠️  Do NOT enable with stdio transport - it breaks JSON-RPC communication
-# OTEL_EXPORTER_CONSOLE_ENABLED=true
+# Optional: OTEL diagnostic log level (default: NONE)
+# This server uses stdio transport exclusively. OTEL diagnostic logs are disabled
+# by default to prevent corrupting JSON-RPC communication.
+# Set to DEBUG, INFO, WARN, or ERROR only for troubleshooting OTEL configuration issues.
+# Valid values: NONE (default), ERROR, WARN, INFO, DEBUG, VERBOSE
+# OTEL_LOG_LEVEL=ERROR
 
 # Optional: OTLP authentication headers (for production backends)
 # OTEL_EXPORTER_OTLP_HEADERS={"Authorization": "Bearer your-token"}

CLAUDE.md

@@ -56,10 +56,10 @@ This server includes OpenTelemetry (OTEL) instrumentation for distributed tracin
 ### Environment Variables
 
 - `OTEL_EXPORTER_OTLP_ENDPOINT` — OTLP endpoint URL (e.g., `http://localhost:4318`). If not set, tracing is disabled.
-- `OTEL_EXPORTER_CONSOLE_ENABLED` — Set to `true` to log traces to console (avoid with stdio transport)
 - `OTEL_TRACING_ENABLED` — Set to `false` to explicitly disable tracing even if endpoint is configured
 - `OTEL_SERVICE_NAME` — Override service name (default: `mapbox-mcp-devkit-server`)
 - `OTEL_EXPORTER_OTLP_HEADERS` — JSON string of additional headers for OTLP exporter
+- `OTEL_LOG_LEVEL` — OTEL diagnostic log level: `NONE` (default), `ERROR`, `WARN`, `INFO`, `DEBUG`, `VERBOSE`. Defaults to `NONE` to prevent diagnostic logs from corrupting stdio transport.
 
 ### What Gets Traced
 

README.md

@@ -27,15 +27,20 @@ https://github.com/user-attachments/assets/8b1b8ef2-9fba-4951-bc9a-beaed4f6aff6
       - [Coordinate Conversion tool](#coordinate-conversion-tool)
       - [Bounding Box tool](#bounding-box-tool)
   - [Resources](#resources)
-  - [Observability & Tracing](#observability--tracing)
+  - [Observability \& Tracing](#observability--tracing)
+    - [Features](#features)
+    - [Quick Start with Jaeger](#quick-start-with-jaeger)
+    - [Supported Backends](#supported-backends)
+    - [Documentation](#documentation)
+    - [Environment Variables](#environment-variables)
   - [Development](#development)
     - [Testing](#testing)
       - [Tool Snapshot Tests](#tool-snapshot-tests)
     - [Inspecting Server](#inspecting-server)
       - [Using Node.js](#using-nodejs)
       - [Using Docker](#using-docker)
     - [Creating New Tools](#creating-new-tools)
-    - [Environment Variables](#environment-variables)
+    - [Environment Variables](#environment-variables-1)
       - [VERBOSE_ERRORS](#verbose_errors)
   - [Troubleshooting](#troubleshooting)
   - [Contributing](#contributing)
@@ -48,6 +53,8 @@ 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
+- [Cursor Integration](./docs/cursor-integration.md) - Cursor IDE integration
+- [VS Code Integration](./docs/vscode-integration.md) - Visual Studio Code with GitHub Copilot
 
 ### DXT Package Distribution
 
@@ -592,11 +599,8 @@ npm test -- --updateSnapshot
 #### Using Node.js
 
 ```sh
-# Build
-npm run build
-
-# Inspect
-npx @modelcontextprotocol/inspector node dist/esm/index.js
+# Run the built image
+npm run inspect:build
 ```
 
 #### Using Docker

docs/claude-code-integration.md

@@ -95,8 +95,8 @@ If you want to use a local version (need to clone and build from this repo):
 {
   "mcpServers": {
     "mapbox-devkit": {
-      "command": "/path/to/your/node",
-      "args": ["/path/to/mapbox-mcp-devkit/dist/esm/index.js"],
+      "command": "node",
+      "args": ["/absolute/path/to/mapbox-mcp-devkit/dist/esm/index.js"],
       "env": {
         "MAPBOX_ACCESS_TOKEN": "your_token_here"
       }

docs/claude-desktop-integration.md

@@ -106,8 +106,8 @@ If you want to use a local version (need to clone and build from this repo):
 {
   "mcpServers": {
     "mapbox-devkit": {
-      "command": "/path/to/your/node",
-      "args": ["/path/to/mapbox-mcp-devkit/dist/esm/index.js"],
+      "command": "node",
+      "args": ["/absolute/path/to/mapbox-mcp-devkit/dist/esm/index.js"],
       "env": {
         "MAPBOX_ACCESS_TOKEN": "your_token_here"
       }

docs/cursor-integration.md

@@ -0,0 +1,129 @@
+# Cursor Integration
+
+This guide explains how to configure Cursor IDE for use with the Mapbox MCP DevKit Server.
+
+## Requirements
+
+- [Cursor](https://www.cursor.com/) installed
+- Mapbox MCP DevKit Server [built locally](../README.md#development-setup)
+
+```sh
+# from repository root:
+# using node
+npm run build
+
+# or alternatively, using docker
+docker build -t mapbox-mcp-devkit .
+```
+
+## Setup Instructions
+
+### Configure Cursor to use Mapbox MCP DevKit Server
+
+1. Go to Cursor Settings/ MCP Tools and click on "Add Custom MCP".
+2. Add either of the following MCP config:
+   - **NPM version** (recommended for simplicity)
+
+     ```json
+     {
+       "mcpServers": {
+         "MapboxDevKit": {
+           "type": "stdio",
+           "command": "npx",
+           "args": ["-y", "@mapbox/mcp-devkit-server"],
+           "env": {
+             "MAPBOX_ACCESS_TOKEN": "<YOUR_TOKEN>"
+           }
+         }
+       }
+     }
+     ```
+
+   - **Docker version** (recommended for isolation)
+
+     ```json
+     {
+       "mcpServers": {
+         "MapboxDevKit": {
+           "type": "stdio",
+           "command": "docker",
+           "args": [
+             "run",
+             "-i",
+             "--rm",
+             "--env",
+             "MAPBOX_ACCESS_TOKEN=<YOUR_TOKEN>",
+             "mapbox-mcp-devkit"
+           ]
+         }
+       }
+     }
+     ```
+
+   - **Node version** (for local development)
+     ```json
+     {
+       "mcpServers": {
+         "MapboxDevKit": {
+           "type": "stdio",
+           "command": "node",
+           "args": ["/absolute/path/to/repo/dist/esm/index.js"],
+           "env": {
+             "MAPBOX_ACCESS_TOKEN": "<YOUR_TOKEN>"
+           }
+         }
+       }
+     }
+     ```
+
+3. Click "Save" to apply the configuration.
+
+## Important Notes
+
+### Token Scopes
+
+Your Mapbox access token must have the appropriate scopes for the tools you want to use. See the [main README](../README.md#tools) for required token scopes per tool.
+
+### Configuration Options
+
+Additional environment variables you can set:
+
+- `OTEL_EXPORTER_OTLP_ENDPOINT` - Enable OpenTelemetry tracing (see [tracing docs](./tracing.md))
+- `OTEL_SERVICE_NAME` - Override service name for tracing
+- `MAPBOX_API_ENDPOINT` - Override Mapbox API endpoint (advanced)
+
+## Troubleshooting
+
+### Server Not Appearing
+
+If the Mapbox DevKit Server doesn't appear in Cursor's MCP tools:
+
+1. Check that your `MAPBOX_ACCESS_TOKEN` is valid
+2. For Docker: ensure the image is built with `docker images | grep mapbox-mcp-devkit`
+3. Check Cursor's logs for any error messages
+
+### Connection Errors
+
+If you see JSON-RPC or parsing errors:
+
+1. If using Node version, verify the path to `dist/esm/index.js` is correct
+2. Run `npm run build` to ensure the latest build is available
+
+### Tool Execution Failures
+
+If tools fail to execute:
+
+1. Verify your Mapbox token has the required scopes (see [README](../README.md))
+2. Check if you're hitting rate limits (429 errors)
+3. Enable verbose errors by adding `"VERBOSE_ERRORS": "true"` to the env config
+
+## Example Usage
+
+Once configured, you can use natural language to interact with Mapbox tools:
+
+- "List all my Mapbox styles"
+- "Show me the bounding box for San Francisco"
+- "Convert these coordinates to lat/lng: -122.4194, 37.7749"
+- "Create a new Mapbox style called 'my-custom-map'"
+
+See the [README](../README.md#example-prompts) for more example prompts.

docs/tracing-verification.md

@@ -73,9 +73,7 @@ npm run tracing:jaeger:stop
 
 ### Successful Tracing Setup
 
-✅ **Console output shows**: `OpenTelemetry tracing: enabled`
-
-✅ **Jaeger UI shows traces** for your service
+✅ **Jaeger UI shows traces** for your service after tool execution
 
 ✅ **Trace details include**:
 
@@ -193,34 +191,16 @@ OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io/v1/traces
 OTEL_EXPORTER_OTLP_HEADERS='{"x-honeycomb-team":"YOUR_API_KEY"}'
 ```
 
-## Alternative Methods
-
-### Console Tracing (Development Only)
-
-**⚠️ Not recommended for stdio transport**
-
-```bash
-# Add to .env (only works well with SSE transport)
-OTEL_EXPORTER_CONSOLE_ENABLED=true
-```
-
-This prints traces to stderr. Only use this for debugging, as it can interfere with MCP's stdio communication.
-
-### Verifying Different Transports
+## Diagnostic Logging
 
-#### stdio Transport (Default) - Silent Operation
+By default, OpenTelemetry diagnostic logs are disabled to prevent interference with stdio transport. If you need to troubleshoot OTEL configuration issues, you can enable diagnostic logging:
 
 ```bash
-# Normal operation
-npm run inspect:build
+# Add to .env - only for debugging OTEL issues
+OTEL_LOG_LEVEL=ERROR
 ```
 
-#### SSE Transport - Full Logging
-
-```bash
-# If your inspector supports SSE transport
-SERVER_TRANSPORT=sse npm run inspect:build
-```
+**⚠️ Warning:** Any console output (including OTEL diagnostic logs) can corrupt stdio communication. Only enable diagnostic logging when actively troubleshooting, and disable it once resolved.
 
 ## Production Considerations
 

docs/tracing.md

@@ -2,16 +2,11 @@
 
 This MCP server includes comprehensive distributed tracing using OpenTelemetry (OTEL), providing production-ready observability for tool executions and HTTP requests.
 
-## ⚠️ Important MCP Transport Compatibility
+## ⚠️ Important: Stdio Transport Only
 
-**Console tracing should be avoided with stdio transport** as console output interferes with MCP's stdio JSON-RPC communication.
+**This server uses stdio transport exclusively.** Only OTLP exporters are supported for tracing.
 
-**Transport-specific recommendations:**
-
-- **stdio transport (default):** Use OTLP exporters only, avoid console tracing
-- **SSE transport:** Console tracing is safe to use for development
-
-The server automatically detects the transport type and adjusts logging behavior accordingly.
+Console output is incompatible with stdio and will corrupt JSON-RPC communication. All diagnostic logging is disabled by default to ensure reliable operation.
 
 ## Features
 
@@ -56,14 +51,15 @@ The tracing system supports several configuration options through environment va
 #### Basic Configuration
 
 ```bash
-# Enable console tracing (development)
-OTEL_EXPORTER_CONSOLE_ENABLED=true
-
-# OTLP HTTP endpoint (production)
+# OTLP HTTP endpoint (required to enable tracing)
 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
 
 # Optional OTLP headers for authentication
 OTEL_EXPORTER_OTLP_HEADERS='{"Authorization": "Bearer your-token"}'
+
+# Optional: OTEL diagnostic log level (default: NONE)
+# Only use for troubleshooting OTEL configuration issues
+OTEL_LOG_LEVEL=ERROR
 ```
 
 #### Service Configuration
@@ -82,29 +78,23 @@ OTEL_TRACES_SAMPLER=traceidratio
 OTEL_TRACES_SAMPLER_ARG=0.1  # Sample 10% of traces
 ```
 
-### Transport-Specific Configuration
+### Enabling Tracing
 
-**For stdio transport (default):**
+Tracing is opt-in and disabled by default. To enable tracing, you must configure an OTLP endpoint:
 
 ```bash
-# ✅ RECOMMENDED: Use OTLP exporter for stdio transport
+# Enable tracing by setting the OTLP endpoint
 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
 
-# ❌ AVOID: Console output interferes with stdio JSON-RPC
-# OTEL_EXPORTER_CONSOLE_ENABLED=true
-```
-
-**For SSE transport:**
-
-```bash
-# ✅ SAFE: Console tracing works with SSE transport
-SERVER_TRANSPORT=sse
-OTEL_EXPORTER_CONSOLE_ENABLED=true
+# Optionally customize the service name
+OTEL_SERVICE_NAME=mapbox-mcp-devkit-server
 
-# ✅ ALSO GOOD: OTLP exporter works with any transport
-OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+# For debugging OTEL configuration issues only
+# OTEL_LOG_LEVEL=ERROR
 ```
 
+**Note:** Console exporters are not supported due to stdio transport limitations.
+
 ### Verification
 
 To verify tracing is working correctly, see the [Tracing Verification Guide](./tracing-verification.md) which shows how to: