[resources] Add new resources to server with fallback tool #34
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.




Description
This PR adds MCP Resources and a reference tool to expose static Mapbox documentation and schemas, making it easier for AI assistants to build correct styles, tokens, and filters by providing essential reference information about Streets v8 fields, token scopes, and layer type mappings.
Motivation
When building Mapbox styles or creating tokens, AI assistants need to know:
class: 'park'for landuse layer)Previously, this information wasn't easily accessible, leading to trial-and-error or incorrect configurations. This PR provides comprehensive reference documentation directly through the MCP server.
Changes
1. MCP Resources Implementation
Added four new MCP resources exposing static reference data:
MapboxStreetsV8FieldsResource(resource://mapbox-streets-v8-fields)['park', 'cemetery', 'hospital', ...])MapboxTokenScopesResource(resource://mapbox-token-scopes)MapboxLayerTypeMappingResource(resource://mapbox-layer-type-mapping)MapboxStyleLayersResource(existing, now documented)2. GetReferenceTool - Claude Desktop Workaround
Added
get_reference_toolto work around Claude Desktop's current limitation:readCallback()and returns content3. Infrastructure Updates
BaseResource Class
ReadResourceResulttype from MCP SDK (likeCallToolResultfor tools)readCallbackfromprotectedtopublicfor tool accessRequestHandlerExtraparameter_extranaming convention for intentionally unused parametersESLint Configuration
@typescript-eslint/no-unused-varsrule withargsIgnorePattern: '^_'_extraparameter convention without lint errorsResource Registry
resourceRegistry.ts4. Testing
Added comprehensive test coverage:
MapboxStreetsV8FieldsResource.test.ts- 5 testsMapboxTokenScopesResource.test.ts- 8 testsMapboxLayerTypeMappingResource.test.ts- 11 testsreadCallbacksignature5. Documentation
Updated README.md with:
get_reference_toolTechnical Details
Resource vs. Tool Design Decision
Resources (static reference data):
Tools (dynamic, user-specific data):
list_styles_tool- fetches user's styleslist_tokens_tool- fetches user's tokensThis separation aligns with MCP best practices: resources for static knowledge, tools for dynamic data and actions.
Claude Desktop Limitation
From research and GitHub issues:
resources/listsuccessfullyresources/readget_reference_toolprovides same data via tool interfaceType Safety Improvements
ReadResourceResulttype from@modelcontextprotocol/sdk/types.jsCallToolResultExample Usage
With Claude Desktop (using tool)
User: "What fields are available for the landuse layer?"
Assistant: Uses
get_reference_toolwithresource://mapbox-streets-v8-fieldsand finds:{ "landuse": { "class": { "values": ["park", "cemetery", "hospital", "school", "industrial", ...] } } }User: "What scopes do I need for a public token that displays maps?"
Assistant: Uses
get_reference_toolwithresource://mapbox-token-scopesand recommends:With Future MCP Clients (using resources directly)
Clients that support automatic resource fetching can access the data directly without the tool workaround.
Testing
Cursor can read resources:

Claude Code can read resources:

Claude Desktop can read resources via tool usage:

Cursor can read the Mapbox Streets V8 fields:

Claude Desktop can read the Mapbox Streets V8 fields:

Claude Code can read the Mapbox Streets V8 fields:

Checklist
Additional Notes