feat: Add API endpoint explorer tool

[mattpodwysocki]

Summary

Implements explore_mapbox_api_tool to provide structured, queryable information about Mapbox API endpoints, operations, parameters, and authentication requirements. Resolves #71.

Features

• List all APIs: Shows 7 Mapbox APIs with descriptions and operation counts
• View operations: Lists all operations for a specific API with HTTP methods and endpoints
• Get endpoint details: Complete information including:
  • HTTP method and endpoint URL
  • Path, query, and body parameters with types and descriptions
  • Required token scopes
  • Rate limits
  • Example requests/responses (with details: true)

API Coverage

Documented 7 APIs with 24 total operations:

• Geocoding (2 ops) - Forward/reverse geocoding
• Styles (5 ops) - CRUD operations for map styles
• Tokens (5 ops) - Token management
• Static Images (2 ops) - Static map generation
• Directions (1 op) - Route calculation
• Tilequery (1 op) - Vector tile queries
• Feedback (2 ops) - User feedback events

Implementation Details

• Created /src/constants/mapboxApiEndpoints.ts with curated API definitions
• Implemented tool extending BaseTool with proper input/output schemas
• Returns both markdown content (human-readable) and structured content (machine-readable)
• Proper MCP structured content support with separated text and data
• No API access required - works with static curated data

Testing

• ✅ 21 comprehensive test cases covering all functionality
• ✅ All 574 project tests pass
• ✅ Tool snapshot updated
• ✅ Build successful
• ✅ Tested in MCP Inspector - structured content validates correctly
• ✅ Tested in Claude Desktop - natural language queries work perfectly

Documentation

• Updated README.md with tool description and usage examples
• Updated CHANGELOG.md with feature entry
• Complements existing get_latest_mapbox_docs_tool by providing structured API reference data

Screenshots

Successfully tested in both MCP Inspector (structured content validation) and Claude Desktop (natural language queries).

🤖 Generated with Claude Code

[ctufts]

What is the plan to scale this and/or keep it up to date? Might it be worth talking to the docs team about keeping generated Open API specs( or an equivalent) in https://github.com/mapbox/help as the source of truth, then consume them downstream here to prevent manual updates from being necessary?

[mattpodwysocki]

Great question about scalability! This is definitely something we should address.

Current Approach (MVP)

This PR uses a manually curated list as an MVP to:

• ✅ Prove the concept and gather feedback
• ✅ Cover the most commonly used APIs (Geocoding, Styles, Directions, etc.)
• ✅ Provide immediate value without infrastructure dependencies

Scaling Strategy

You're absolutely right that manual maintenance doesn't scale. Here's the path forward:

Short-term (This PR)

• Ship the MVP with core APIs covered
• Gather feedback on the structure and usefulness
• Document which APIs are included

Medium-term (Follow-up)

Option 1: OpenAPI Spec Generation ✨

• Collaborate with docs team to maintain OpenAPI specs in mapbox/help
• Build a generator script that converts OpenAPI → TypeScript definitions
• Automate updates via CI/CD when specs change

Option 2: Fetch from Documentation

• Parse structured data from docs.mapbox.com programmatically
• Cache locally, update periodically
• Requires stable documentation structure

Long-term

• Ideally, OpenAPI specs become the single source of truth
• This tool (and others) consume from that canonical source
• Updates happen automatically as APIs evolve

Action Items

1. Merge this PR as the foundational structure
2. Create follow-up issue to discuss OpenAPI spec generation with docs team
3. Design generator script that transforms OpenAPI → our TypeScript interface
4. Automate updates once we have a stable spec source

Questions for Discussion

• Does the docs team already maintain OpenAPI specs we could consume?
• If not, what's the effort to create and maintain them?
• Could we pilot this with 1-2 APIs first to validate the approach?

Would love to sync with the docs team on this! The manual approach gets us started, but automated spec generation is definitely the right long-term solution.

What do you think about this phased approach?