Gravalist-MCP

🌟 The Power of Decoupled Telemetry

Standard mobile operating systems aggressively restrict background processes, making real-time telemetry computation, caching, and custom routing widgets incredibly difficult to sustain. Gravalist bridges this gap by exposing a completely standalone, read-only developer microservice.

Features

• High-End Routes: Query precise, curated 500-Series gravel routes containing micro-elevation maps, grade changes, and surface breakdowns.

• Weather Pacing: Retrieve predictive weather forecasts mapped specifically to rider-speed intervals for absolute clarity on wind shifts.

• MCP Integration: Integrate our JSON-standard MCP manifest to allow local AI agents to autonomously scout route gaps and identify locked gates.

Related MCP server: BikeScout

🚀 Getting Started

To interact with the Gravalist MCP Server, you will need to authenticate your requests using a Developer API Key. Follow these 3 steps to start querying telemetry:

1. Create a Gravalist Profile

All developers must have an active rider profile.

• Navigate to app.gravalist.com.

• Sign up or log in to your account.

2. Generate Your API Key

To protect system resources and cap telemetry usage, you must generate a secure access token.

• Inside the Gravalist web app, open your Profile.

• Navigate to Developer Settings.

• Click Generate API Token.

• Copy this secure x-api-key (you will not be able to view it again).

Note: Test tokens are subject to rate limiting and monthly quota caps. If you require higher limits for production use cases, please contact our support team.

3. Query the API

Pass your secure access token inside the x-api-key headers to start streaming granular route geometries or invoking tools.

Test an API Endpoint

curl -H "x-api-key: YOUR_GENERATED_API_KEY" http://localhost:8080/api/v1/routes

Fetch the MCP Manifest

curl http://localhost:8080/mcp/manifest

💻 Local Development

If you want to run the standalone telemetry server locally:

1. Clone the repository:

   git clone https://github.com/Collective-Social/Gravalist-MCP.git
   cd Gravalist-MCP

2. Install dependencies:

   npm install

3. Run the server:

   npm start

   The server will start on port 8080.

📚 API Endpoints

GET /api/v1/routes

Retrieves a rich listing of premium gravel routes containing micro-elevation data and safety sector mappings.

GET /api/v1/routes/:id/weather

Retrieves pre-computed, debounced predictive wind, rain, and temperature pacing intervals mapped to the specific route ID.

GET /mcp/manifest

Retrieves the official Model Context Protocol (MCP) server JSON manifest, defining active tools for LLM agent integration.