[security] Add MCP elicitation for secure preview token handling

[mattpodwysocki]

Summary

Implements MCP elicitation for secure token management in `preview_style_tool` and `style_comparison_tool`, following the principle of least privilege. Elicitation ensures that only minimal-scope public tokens (pk.) appear in preview URLs, while your powerful server token (sk.) stays secure.

The Security Problem

Previously, `preview_style_tool` and `style_comparison_tool` required users to provide an `accessToken` directly in the tool input, which created security and UX risks:

• ⚠️ Risk of exposing powerful server token - Users might accidentally pass through their server token (sk.*) with write permissions
• ⚠️ Over-privileged tokens - Users might manually provide tokens with more permissions than needed
• ❌ No guided workflow for token selection
• ❌ Users had to manually create and manage tokens
• ❌ Token management friction

The Solution: Elicitation with Least Privilege

This PR implements MCP elicitation to enforce the principle of least privilege:

• Server token stays secure - Your powerful secret token (sk.*) with write permissions NEVER appears in chat history or URLs
• Minimal-scope public tokens - Preview URLs only contain read-only public tokens (pk.*) with scopes: styles:read, styles:tiles, fonts:read
• Acceptable security trade-off - Even if preview URLs are shared, they only expose read-only access to styles, not your admin token

How It Works

When a user calls `preview_style_tool` or `style_comparison_tool` without providing an `accessToken`:

1. Check for cached token - If a preview token was already created this session, use it
2. Elicit token from user - Present a guided dialog with three options:
   • Provide existing token - User pastes a public token they already have
   • Create new preview token - System creates a new token with optional URL restrictions
   • Auto-create basic token - System auto-creates a simple preview token (recommended)
3. Cache for session - Store token in memory to avoid re-prompting
4. Generate preview/comparison URL - Use the minimal-scope public token in the URL

Key Security Properties:

• Server token (sk.*) is only used server-side to create limited tokens via Mapbox API
• Created tokens are always public (pk.*) with minimal read-only scopes
• No risk of exposing write permissions (styles:write, tokens:write, etc.)

Testing

Test Case 1: First Time Preview (Elicitation Shown)

Steps:

1. Start MCP server with valid Mapbox token
2. Call `preview_style_tool` with only `styleId` (no `accessToken`)
3. Observe elicitation dialog with three options
4. Select "Auto-create a basic preview token for me"
5. Verify preview URL is generated

Expected:

• Elicitation dialog appears with token options
• Dialog shows existing public tokens (if any)
• After selection, preview URL is returned
• Server token NEVER appears anywhere - only the minimal-scope public token in URL

Screenshot locations:

• Elicitation dialog with options

• Preview URL result (only public token in URL)

• Token not in tool call log

Test Case 2: Subsequent Preview (Cached Token)

Steps:

1. After Test Case 1, call `preview_style_tool` again with different styleId
2. No `accessToken` provided

Expected:

• No elicitation dialog (token is cached)

• Preview URL generated immediately

• Same minimal-scope token used from cache

Test Case 3: Force New Token Selection

Steps:

1. Call `preview_style_tool` with `useCustomToken: true`
2. This time select "I have a token to provide"
3. Paste a valid public token

Expected:

• Elicitation dialog appears despite cache

• Token field accepts input
• New token replaces cached token

Test Case 4: Create Token with URL Restrictions

Steps:

1. Call `preview_style_tool` with new styleId, `useCustomToken: true`
2. Select "Create a new preview token with custom settings"
3. Enter token name: "Test Preview Token"
4. Enter URL restrictions: "https://example.com/*,https://test.com/*"

Expected:

• New token created via Mapbox API with minimal scopes

• Token includes URL restrictions for additional security

• Preview URL generated with new token

Test Case 5: Backward Compatibility

Steps:

1. Call `preview_style_tool` with both `styleId` AND `accessToken`

Expected:

• No elicitation dialog (token provided directly)

• Works exactly like before this PR
• Preview URL generated with provided token

Test Case 6: Elicitation Cancellation

Steps:

1. Call `preview_style_tool` without `accessToken`
2. When elicitation dialog appears, click "Cancel" or "Decline"

Expected:

• Tool returns error: "Token elicitation was cancelled or declined by user"

- No preview URL generated - Graceful error handling

Test Case 7: Works in Cursor

• Run Elicitation

- Get result

Test Case 8: Works in VS Code

• Run Elicitation

• Get result

Test Case 9: Works in Claude Desktop without support for Elicitation

• Run tool

• Ask to create a token for you

MCP Inspector Testing

To test in MCP Inspector:

```bash
npm run inspect:build
```

Then:

1. Connect to the server in MCP Inspector
2. Find `preview_style_tool` or `style_comparison_tool` in tools list
3. Call with: `{"styleId": "cmi189f9600lj01sc7evj2vhs"}` or `{"before": "mapbox/streets-v12", "after": "mapbox/outdoors-v12"}`
4. Observe elicitation dialog in Inspector UI
5. Test all three token options

Key Features

🔐 Security Improvements

• Principle of least privilege - Only minimal-scope read-only tokens (pk.*) appear in URLs
• Server token protection - Powerful server token (sk.*) with write permissions never exposed
• Reduced blast radius - Even if preview URL is shared, only read-only access to styles is exposed
• URL-restricted tokens - Users can create tokens that only work on specific domains
• Minimal scopes - Auto-created tokens only get `styles:read`, `styles:tiles`, `fonts:read`

🎯 User Experience

• Guided workflow - Three clear options for token management (provide, create, or auto-create)
• Session caching - Token only requested once per session
• Smart defaults - Auto-create option requires zero configuration
• No repeated prompts - Session storage remembers choice
• Backward compatible - Can still provide token directly via `accessToken` parameter
• Force re-selection - `useCustomToken: true` forces new token dialog
• Client capability checks - Gracefully falls back for clients without elicitation support

🛠️ Implementation Details

New Files:

• `src/utils/tokenElicitation.ts` - Elicitation utility with session storage
• `test/utils/tokenElicitation.test.ts` - Unit tests for token storage (10 tests)

Modified Files:

• `src/tools/preview-style-tool/PreviewStyleTool.ts` - Integrated elicitation flow with capability checks
• `src/tools/preview-style-tool/PreviewStyleTool.input.schema.ts` - Made `accessToken` optional, added `useCustomToken`
• `src/tools/style-comparison-tool/StyleComparisonTool.ts` - Integrated elicitation flow with capability checks
• `src/tools/style-comparison-tool/StyleComparisonTool.schema.ts` - Made `accessToken` optional, added `useCustomToken`
• `test/tools/preview-style-tool/PreviewStyleTool.test.ts` - Added elicitation behavior tests (2 tests)
• `test/tools/style-comparison-tool/StyleComparisonTool.test.ts` - Added elicitation behavior tests (2 tests)
• `README.md` - Updated documentation emphasizing security model

Test Results

• ✅ All 529 tests pass (added 14 new tests)
• ✅ Build succeeds with no type errors
• ✅ Backward compatibility maintained
• ✅ Manual testing in MCP Inspector - All test cases pass
• ✅ Manual testing in Cursor - Works perfectly
• ✅ Manual testing in VS Code - Works perfectly
• ✅ Manual testing in Claude Desktop - Graceful fallback works

Breaking Changes

None - This is fully backward compatible:

• Existing code providing `accessToken` works exactly as before
• New behavior only activates when `accessToken` is omitted
• Clients without elicitation support work via capability checks

Security Model

What We Protect:

• ✅ Server token (sk.*) with write permissions never appears in chat history or URLs
• ✅ Only minimal-scope public tokens (pk.*) with read-only access can appear in URLs
• ✅ Enforces principle of least privilege automatically

Acceptable Security Trade-off:

• Public tokens (pk.*) with read-only scopes appear in preview URLs
• This is acceptable because:
  • They only grant read access to styles/tiles (no write permissions)
  • URL restrictions can further limit where tokens work
  • Much safer than exposing the server token with admin permissions