Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Tilequery: describe_tileset + tilequery tools, starting with elevation along a route

Open
  • Is something wrong?
#289 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Active
Tech stack
typescript
Domain
api, backend-api-design

Research direction

Start by reading the existing directions tool and the linked devkit tilequery implementation; the issue names no repository files or tests. The proposal spans TileJSON discovery, tile queries, built-in tileset notes, and route elevation, with open questions about duplication, defaults, permissions, and accuracy. Done means those choices are resolved and the requested tools and route profile work with documented elevation limits.

Written by the indexing model from the issue text.

Description

enhancement

Problem

Some questions need data that's in Mapbox tilesets but not behind any tool in this server:

  • "How high is this point?" and "How hilly is this bike route?" (terrain)
  • "How tall is this building?" (Streets v8 building.height)
  • "Is this spot in a park or an industrial area?" (Streets v8 landuse.class)
  • "Which of our sales territories is this address in?" (a customer's own tileset)

mcp-devkit-server has a generic tilequery_tool, but a model can only use it well if it already knows the tileset id, layer names and fields. Most models outside a developer setting don't.

Proposal

1. describe_tileset_tool

Takes a tileset id and returns its layers, with field names, geometry type and zoom range, read from the tileset's TileJSON. TileJSON already carries this. For example:

  • mapbox.mapbox-streets-v8: 16 layers.
    • building: height, min_height, underground, extrude
    • road: class, lane_count, bike_lane, access
    • landuse: class, type
    • natural_label: elevation_m
  • mapbox.mapbox-terrain-v2: contour (ele, index), landcover, hillshade

It's cheap and cacheable, and it works on the user's own tilesets too.

2. tilequery_tool

Tilequery API: tileset, point, radius, layers, limit, geometry type. It returns only the matched features' properties and distances, not full geometry, to keep results small. Its result includes a mapboxRender.ref so the hits can go on the map.

3. Built-in notes for Mapbox-owned tilesets

A few lines in the tool descriptions for Streets v8, Terrain v2 and Traffic v1: what each is good for, and the fields TileJSON leaves out. For example, Traffic v1's TileJSON lists no fields, but its tiles carry congestion, class and structure (checked against a live tile while working on #278). With these, common questions don't need a describe call first.

4. First use case: elevation along a route

A tool built on top of the two above. It takes a directions_tool ref or a line, samples points along it against the terrain tileset, and returns:

  • total climb and descent
  • the highest and lowest points
  • a small profile the map could chart

It's a clear gap today (this server has no elevation at all), and it pairs well with routes on the map. A single point's elevation falls out of the same work.

Open questions

  • Duplication with devkit. Do we copy devkit's tilequery_tool here, move it here and keep devkit for developer and admin work, or share the code?
  • On by default? Two more general tools add to tool-selection load. Off by default, at least for the hosted connector? Run the tool-selection eval (#274) either way.
  • Listing tilesets. Listing a user's own tilesets needs the broader tilesets:list token permission. Leave listing to devkit, and have users name the tileset?
  • Terrain precision. Vector contours come in fixed elevation steps. Check what tilequery gives on Terrain v2 versus the terrain DEM before promising elevation accuracy.
  • Resource too? Claude Desktop and ChatGPT don't let the model read resources on its own, so describe has to be a tool. Should it also be a mapbox://tilesets/{id} resource for hosts that do support reading them?
Dominant language
TypeScript
Stars
363
Forks
45
Avg merge
22h 36m
Merged PRs (30d)
20

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from mapbox/mcp-server

All issues in mapbox/mcp-server

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.