nextbillion-mcp 0.3.0 → 0.3.1

package/dist/index.js

@@ -6212,7 +6212,7 @@ var init_text_search = __esm({
         "places/search/search-places-api/search-places-apis"
       ],
       title: "Search Places",
-      description: 'Search for places, points of interest and businesses with a free-text query (e.g. "gas station", "coffee"), ranked by relevance around a location. Use geocode_forward for plain address-to-coordinates conversion. For how-to questions about this API, use search_documentation. Parameters: query (required); optional near {latitude, longitude} (recommended), radius_m (with near), country_codes, bounding_box {west, south, east, north}, limit, language, view. Example: {"query": "coffee", "near": {"latitude": 37.7749, "longitude": -122.4194}, "radius_m": 1000, "limit": 5}',
+      description: 'Search for places, points of interest and businesses with a free-text query (e.g. "gas station", "coffee"), ranked by relevance around a location. Use geocode_forward for plain address-to-coordinates conversion. Documentation for this API is available through search_documentation. Parameters: query (required); optional near {latitude, longitude} (recommended), radius_m (with near), country_codes, bounding_box {west, south, east, north}, limit, language, view. Example: {"query": "coffee", "near": {"latitude": 37.7749, "longitude": -122.4194}, "radius_m": 1000, "limit": 5}',
       path: "/discover",
       noun: "place"
     });
@@ -6257,7 +6257,7 @@ var init_geocode_batch = __esm({
     geocodeBatch = {
       name: "geocode_batch",
       title: "Batch Geocode",
-      description: 'Forward-geocode up to 100 free-text queries in one request; returns one ranked result set per query, in input order. Prefer this over repeated geocode_forward calls - this endpoint has its own low rate limit (60 requests per minute), so batch as much as possible into each call. Parameters: queries (required array; each item: query (required), optional near {latitude, longitude}, radius_m, country_codes, bounding_box, limit, language, view, types); optional top-level types (houseNumber | addressBlock | street | intersection | place | area) as the default for all queries (a per-query types overrides it). Example: {"queries": [{"query": "600-699 Golden Gate Ave, San Francisco, CA", "types": ["addressBlock"]}, {"query": "Empire State Building", "country_codes": ["USA"]}]}',
+      description: 'Forward-geocode up to 100 free-text queries in one request; returns one ranked result set per query, in input order. Use it instead of repeated geocode_forward calls when several addresses are needed: this endpoint has its own rate limit of 60 requests per minute, so larger batches per call stay within it. Parameters: queries (required array; each item: query (required), optional near {latitude, longitude}, radius_m, country_codes, bounding_box, limit, language, view, types); optional top-level types (houseNumber | addressBlock | street | intersection | place | area) as the default for all queries (a per-query types overrides it). Example: {"queries": [{"query": "600-699 Golden Gate Ave, San Francisco, CA", "types": ["addressBlock"]}, {"query": "Empire State Building", "country_codes": ["USA"]}]}',
       inputSchema: Schema,
       annotations: READ_ONLY,
       docs: ["places/geocoding/batch-geocode/batch-geocode"],
@@ -6574,7 +6574,7 @@ var init_directions = __esm({
     directions = {
       name: "directions",
       title: "Directions",
-      description: 'Calculate a route between an origin and a destination with optional waypoints; returns distance (meters), duration (seconds) and an encoded polyline per route - pass the polyline to static_route_map to draw it. Use distance_matrix for many pairs. pairs. For how-to questions about this API, use search_documentation. Parameters: origin, destination {latitude, longitude} (required); optional waypoints (array, max 200), mode (car | truck | motorcycle | bike | walk), service ("flexible" default: all modes and options; "fast": car/truck only, lower latency), route_type, departure_time (UNIX seconds), avoid (soft filter), exclude (strict filter), road_info (max_speed, toll_*, truck_route, stop_sign, traffic_light), honor_restrictions, alternatives, steps (fast only), geometry (polyline | polyline6), truck options: truck_size_cm {height, width, length}, truck_weight_kg, truck_axle_load (tonnes), hazmat_type, emission_class (euro0-euro9), cross_border. Example: {"origin": {"latitude": 37.7749, "longitude": -122.4194}, "destination": {"latitude": 34.0522, "longitude": -118.2437}, "mode": "truck", "truck_weight_kg": 18000, "hazmat_type": ["flammable_liquid"]}',
+      description: 'Calculate a route between an origin and a destination with optional waypoints; returns distance (meters), duration (seconds) and an encoded polyline per route, which static_route_map can draw. Use distance_matrix for many pairs. Documentation for this API is available through search_documentation. Parameters: origin, destination {latitude, longitude} (required); optional waypoints (array, max 200), mode (car | truck | motorcycle | bike | walk), service ("flexible" default: all modes and options; "fast": car/truck only, lower latency), route_type, departure_time (UNIX seconds), avoid (soft filter), exclude (strict filter), road_info (max_speed, toll_*, truck_route, stop_sign, traffic_light), honor_restrictions, alternatives, steps (fast only), geometry (polyline | polyline6), truck options: truck_size_cm {height, width, length}, truck_weight_kg, truck_axle_load (tonnes), hazmat_type, emission_class (euro0-euro9), cross_border. Example: {"origin": {"latitude": 37.7749, "longitude": -122.4194}, "destination": {"latitude": 34.0522, "longitude": -118.2437}, "mode": "truck", "truck_weight_kg": 18000, "hazmat_type": ["flammable_liquid"]}',
       inputSchema: Schema7,
       annotations: READ_ONLY,
       docs: ["routing/directions-api/directions-api"],
@@ -6664,7 +6664,7 @@ var init_distance_matrix = __esm({
     distanceMatrix = {
       name: "distance_matrix",
       title: "Distance Matrix",
-      description: 'Compute travel distance (meters) and duration (seconds) for every origin-to-destination pair in one call; one row per origin with one element per destination, in input order. Use it instead of repeated directions calls when several pairs are needed. For how-to questions about this API, use search_documentation. Parameters: origins, destinations (arrays of {latitude, longitude}, required); optional mode, service ("fast" default: up to 1000x1000 points; "flexible": the options below, max 50x50), route_type, departure_time, avoid (soft), exclude (strict), honor_restrictions, route_failed_prompt (unroutable pairs return -1 instead of 0), truck options: truck_size_cm {height, width, length}, truck_weight_kg, truck_axle_load, hazmat_type, emission_class, cross_border. Example: {"origins": [{"latitude": 1.29, "longitude": 103.85}], "destinations": [{"latitude": 1.35, "longitude": 103.99}, {"latitude": 1.3, "longitude": 103.77}], "route_failed_prompt": true}',
+      description: 'Compute travel distance (meters) and duration (seconds) for every origin-to-destination pair in one call; one row per origin with one element per destination, in input order. Use it instead of repeated directions calls when several pairs are needed. Documentation for this API is available through search_documentation. Parameters: origins, destinations (arrays of {latitude, longitude}, required); optional mode, service ("fast" default: up to 1000x1000 points; "flexible": the options below, max 50x50), route_type, departure_time, avoid (soft), exclude (strict), honor_restrictions, route_failed_prompt (unroutable pairs return -1 instead of 0), truck options: truck_size_cm {height, width, length}, truck_weight_kg, truck_axle_load, hazmat_type, emission_class, cross_border. Example: {"origins": [{"latitude": 1.29, "longitude": 103.85}], "destinations": [{"latitude": 1.35, "longitude": 103.99}, {"latitude": 1.3, "longitude": 103.77}], "route_failed_prompt": true}',
       inputSchema: Schema8,
       annotations: READ_ONLY,
       docs: ["routing/distance-matrix/synchronous", "routing/distance-matrix/asynchronous"],
@@ -6733,7 +6733,7 @@ var init_isochrone = __esm({
     isochrone = {
       name: "isochrone",
       title: "Isochrone",
-      description: 'Calculate the area reachable from a point within given travel times or distances; returns a GeoJSON FeatureCollection of contours (geometry coordinates are [longitude, latitude]). To draw the result, pass each contour ring to static_route_map as paths[].geojson_coordinates with a fill_color. For how-to questions about this API, use search_documentation. Parameters: origin {latitude, longitude} (required); exactly one of contours_minutes (array, up to 4 values, max 40) or contours_meters (array, up to 4 values, max 60000); optional mode, polygons (true for Polygon geometry), denoise, generalize (meters), contours_colors (hex without #, one per contour), departure_time. Example: {"origin": {"latitude": 37.7749, "longitude": -122.4194}, "contours_minutes": [5, 10], "polygons": true}',
+      description: 'Calculate the area reachable from a point within given travel times or distances; returns a GeoJSON FeatureCollection of contours (geometry coordinates are [longitude, latitude]). Each contour ring can be drawn with static_route_map by passing it as paths[].geojson_coordinates with a fill_color. Documentation for this API is available through search_documentation. Parameters: origin {latitude, longitude} (required); exactly one of contours_minutes (array, up to 4 values, max 40) or contours_meters (array, up to 4 values, max 60000); optional mode, polygons (true for Polygon geometry), denoise, generalize (meters), contours_colors (hex without #, one per contour), departure_time. Example: {"origin": {"latitude": 37.7749, "longitude": -122.4194}, "contours_minutes": [5, 10], "polygons": true}',
       inputSchema: Schema9,
       annotations: READ_ONLY,
       docs: ["routing/isochrone-api/isochrone-api"],
@@ -7159,7 +7159,7 @@ var init_static_route_map = __esm({
     staticRouteMap = {
       name: "static_route_map",
       title: "Static Route Map",
-      description: 'Render a static map auto-fitted to a route and/or overlays: a route from directions, and/or lines and filled polygons such as isochrone contours; very long geometry is simplified automatically to fit the map API URL limit (distances unaffected). Returns the image inline and, if NBAI_IMAGE_DIR is set, also saves it as a file (path in the result text). Parameters: at least one of encoded_polyline (the geometry string from directions, preferred), route_points (array of {latitude, longitude}) or paths (array of {points OR geojson_coordinates [[longitude, latitude], ...], stroke_color, stroke_width, fill_color}); optional markers (array of {latitude, longitude, color, icon_url, anchor, scale}), stroke_color, stroke_width (route line), padding, width, height, style, format, retina. Example (isochrone contours) - Example: {"paths": [{"geojson_coordinates": [[-122.42, 37.77], [-122.40, 37.78], [-122.41, 37.79], [-122.42, 37.77]], "fill_color": "rgba(29,78,216,0.35)", "stroke_color": "#1d4ed8"}], "markers": [{"latitude": 37.7749, "longitude": -122.4194, "color": "red"}]}',
+      description: 'Render a static map auto-fitted to a route and/or overlays: a route from directions, and/or lines and filled polygons such as isochrone contours; very long geometry is simplified automatically to fit the map API URL limit (distances unaffected). Returns the image inline and, if NBAI_IMAGE_DIR is set, also saves it as a file (path in the result text). Parameters: at least one of encoded_polyline (the geometry string from directions, preferred), route_points (array of {latitude, longitude}) or paths (array of {points OR geojson_coordinates [[longitude, latitude], ...], stroke_color, stroke_width, fill_color}); optional markers (array of {latitude, longitude, color, icon_url, anchor, scale}), stroke_color, stroke_width (route line), padding, width, height, style, format, retina. The example draws isochrone contours. Example: {"paths": [{"geojson_coordinates": [[-122.42, 37.77], [-122.40, 37.78], [-122.41, 37.79], [-122.42, 37.77]], "fill_color": "rgba(29,78,216,0.35)", "stroke_color": "#1d4ed8"}], "markers": [{"latitude": 37.7749, "longitude": -122.4194, "color": "red"}]}',
       inputSchema: Schema12,
       annotations: READ_ONLY,
       docs: ["maps/static-images-api/static-images-api"],
@@ -7382,9 +7382,9 @@ var SERVER_INSTRUCTIONS, SEARCH_DOCUMENTATION_DESCRIPTION, GET_DOCUMENTATION_DES
 var init_descriptions = __esm({
   "src/tools/docs/descriptions.ts"() {
     "use strict";
-    SERVER_INSTRUCTIONS = "For questions about how a NextBillion API or SDK works, use search_documentation and cite the returned source_url. The other tools execute real requests; use them only when the user wants an actual result, such as a route or a geocode.";
-    SEARCH_DOCUMENTATION_DESCRIPTION = `Search NextBillion's official API and SDK documentation. Use for any question about how NextBillion works: calling an API, what a parameter means, which API to use, or SDK setup. The map tools (directions, place_search, etc.) execute real requests; do not use them to answer such questions.
-Search with the docs' own terms and exact parameter names (truck_weight, option=flexible), not everyday phrasing; retry with other API terms if results are thin. Results are excerpts: for multi-part questions, search again or fetch pages with get_documentation. Cite source_url; related_tools names the tool that performs the operation.
+    SERVER_INSTRUCTIONS = "This server provides two kinds of tools. The four documentation tools (search_documentation, get_documentation, get_api_parameters, list_documentation_topics) answer questions about how NextBillion.ai APIs and SDKs work from a bundled copy of the official documentation and make no network requests; their results include a source_url for citation. The other tools call the NextBillion.ai API and return live results such as geocodes, places, routes, travel-time matrices, isochrones and map images.";
+    SEARCH_DOCUMENTATION_DESCRIPTION = `Search NextBillion's official API and SDK documentation. Use for any question about how NextBillion works: calling an API, what a parameter means, which API to use, or SDK setup. Answers come from the bundled documentation index, not from live API calls.
+Queries match best with the docs' own terms and exact parameter names (truck_weight, option=flexible) rather than everyday phrasing; when results are thin, other API terms may match. Results are excerpts: get_documentation returns a full page. Each result carries a source_url for citation and related_tools, the name of the tool that performs the operation.
 Parameters:
 - query (string, required): search terms.
 - category (string, optional): e.g. Routing, Places.
@@ -7393,13 +7393,9 @@ Parameters:
 - limit (integer, optional): default 5, max 10.
 - include_examples (boolean, optional): default false.
 Example: {"query": "truck_size truck_weight routing", "api": "Directions"}`;
-    GET_DOCUMENTATION_DESCRIPTION = 'Fetch the full text of one documentation page by its doc_id, as returned by search_documentation. Use when an excerpt is not enough to answer accurately. Pages over the size limit return truncated: true and a section list; request one section with section. Sample request and response bodies are omitted unless include_examples is true.\nParameters:\n- doc_id (string, required): page id from search results.\n- section (string, optional): heading of one section to return.\n- include_examples (boolean, optional): default false.\nExample: {"doc_id": "routing/directions-api/examples/legal-routes-for-a-given-truck-weight"}';
-    GET_API_PARAMETERS_DESCRIPTION = 'Get structured parameter details for a NextBillion REST API endpoint: type, required, default, allowed values, units and description. Prefer this over searching prose for questions about a specific parameter. Returns every matching API variant (e.g. directions/flexible and directions/fast); check heading_path. Empty units means the docs do not state the unit; do not infer it. SDK methods are not covered.\nParameters:\n- endpoint (string, required unless doc_id given): API slug, optionally with variant, e.g. directions or directions/flexible.\n- doc_id (string, optional): page id instead of endpoint.\n- name (string, optional): one parameter name.\nExample: {"endpoint": "directions", "name": "truck_weight"}';
-    LIST_DOCUMENTATION_TOPICS_DESCRIPTION = `List the available documentation categories, APIs and pages, with index metadata. Use when you don't yet know the right terms to search for, e.g. to see which APIs exist for a problem area before searching.
-Parameters:
-- category (string, optional): limit to one category.
-- sdk (string, optional): Android, iOS or Flutter.
-Example: {"category": "Optimization"}`;
+    GET_DOCUMENTATION_DESCRIPTION = 'Fetch the full text of one documentation page by its doc_id, as returned by search_documentation. Use when an excerpt is not enough to answer accurately. Pages over the size limit return truncated: true and a section list; a single section can be requested with section. Sample request and response bodies are omitted unless include_examples is true.\nParameters:\n- doc_id (string, required): page id from search results.\n- section (string, optional): heading of one section to return.\n- include_examples (boolean, optional): default false.\nExample: {"doc_id": "routing/directions-api/examples/legal-routes-for-a-given-truck-weight"}';
+    GET_API_PARAMETERS_DESCRIPTION = 'Get structured parameter details for a NextBillion REST API endpoint: type, required, default, allowed values, units and description. More precise than a prose search for questions about one specific parameter. Returns every matching API variant (e.g. directions/flexible and directions/fast), identified by heading_path. Empty units means the documentation does not state a unit. SDK methods are not covered.\nParameters:\n- endpoint (string, required unless doc_id given): API slug, optionally with variant, e.g. directions or directions/flexible.\n- doc_id (string, optional): page id instead of endpoint.\n- name (string, optional): one parameter name.\nExample: {"endpoint": "directions", "name": "truck_weight"}';
+    LIST_DOCUMENTATION_TOPICS_DESCRIPTION = 'List the available documentation categories, APIs and pages, with index metadata. Useful before searching, when the right terms are not yet known, e.g. to see which APIs exist for a problem area.\nParameters:\n- category (string, optional): limit to one category.\n- sdk (string, optional): Android, iOS or Flutter.\nExample: {"category": "Optimization"}';
     DOCS_TOOL_ANNOTATIONS = {
       readOnlyHint: true,
       destructiveHint: false,
@@ -22962,7 +22958,7 @@ function extractApiMessage(bodyText) {
 }
 
 // src/index.ts
-var pkg = true ? { version: "0.3.0" } : createRequire(import.meta.url)("../package.json");
+var pkg = true ? { version: "0.3.1" } : createRequire(import.meta.url)("../package.json");
 function main() {
   const args = process.argv.slice(2);
   if (args.includes("--version") || args.includes("-v")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextbillion-mcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "MCP server exposing NextBillion.ai location APIs (geocoding, places, routing, maps) as tools for AI agents",
   "license": "Apache-2.0",
   "type": "module",