feat: add maps_batch_geocode MCP tool — geocode up to 50 addresses in one call

- New tool: maps_batch_geocode with addresses[] param (max 50)
- Parallel geocoding with per-address error handling
- Returns { total, succeeded, failed, results[] }
- Full test coverage: MCP tool call + exec mode + registration
- All 9 files synced per Tool Change Checklist (15 → 16 tools)
- 125 smoke test assertions, 0 failures

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: cablate

README.md

@@ -6,15 +6,15 @@
 
 Give your AI agent the ability to understand the physical world — geocode, route, search, and reason about locations.
 
-- **15 tools** — 12 atomic + 3 composite (explore-area, plan-route, compare-places)
+- **16 tools** — 13 atomic + 3 composite (explore-area, plan-route, compare-places)
 - **3 modes** — stdio, StreamableHTTP, standalone exec CLI
 - **Agent Skill** — built-in skill definition teaches AI how to chain geo tools ([`skills/google-maps/`](./skills/google-maps/))
 
 ### vs Google Grounding Lite
 
 | | This project | [Grounding Lite](https://cloud.google.com/blog/products/ai-machine-learning/announcing-official-mcp-support-for-google-services) |
 |---|---|---|
-| Tools | **15** | 3 |
+| Tools | **16** | 3 |
 | Geocoding | Yes | No |
 | Step-by-step directions | Yes | No |
 | Elevation | Yes | No |
@@ -62,6 +62,7 @@ Special thanks to [@junyinnnn](https://github.com/junyinnnn) for helping add sup
 | `maps_weather` | Get current weather conditions or forecast — temperature, humidity, wind, UV, precipitation. |
 | `maps_air_quality` | Get air quality index, pollutant concentrations, and health recommendations by demographic group. |
 | `maps_static_map` | Generate a map image with markers, paths, or routes — returned inline for the user to see directly. |
+| `maps_batch_geocode` | Geocode up to 50 addresses in one call — returns coordinates for each. |
 | **Composite Tools** | |
 | `maps_explore_area` | Explore what's around a location — searches multiple place types and gets details in one call. |
 | `maps_plan_route` | Plan an optimized multi-stop route — geocodes, finds best order, returns directions. |
@@ -115,7 +116,7 @@ Then configure your MCP client:
 ### Server Information
 
 - **Transport**: stdio (`--stdio`) or Streamable HTTP (default)
-- **Tools**: 15 Google Maps tools (12 atomic + 3 composite)
+- **Tools**: 16 Google Maps tools (13 atomic + 3 composite)
 
 ### CLI Exec Mode (Agent Skill)
 
@@ -126,7 +127,7 @@ npx @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
 npx @cablate/mcp-google-map exec search-places '{"query":"ramen in Tokyo"}'
 ```
 
-All 15 tools available: `geocode`, `reverse-geocode`, `search-nearby`, `search-places`, `place-details`, `directions`, `distance-matrix`, `elevation`, `timezone`, `weather`, `air-quality`, `static-map`, `explore-area`, `plan-route`, `compare-places`. See [`skills/google-maps/`](./skills/google-maps/) for the agent skill definition and full parameter docs.
+All 16 tools available: `geocode`, `reverse-geocode`, `search-nearby`, `search-places`, `place-details`, `directions`, `distance-matrix`, `elevation`, `timezone`, `weather`, `air-quality`, `static-map`, `batch-geocode-tool`, `explore-area`, `plan-route`, `compare-places`. See [`skills/google-maps/`](./skills/google-maps/) for the agent skill definition and full parameter docs.
 
 ### Batch Geocode
 
@@ -234,6 +235,7 @@ src/
 │       ├── weather.ts            # maps_weather tool
 │       ├── airQuality.ts         # maps_air_quality tool
 │       ├── staticMap.ts          # maps_static_map tool
+│       ├── batchGeocode.ts       # maps_batch_geocode tool
 │       ├── exploreArea.ts        # maps_explore_area (composite)
 │       ├── planRoute.ts          # maps_plan_route (composite)
 │       └── comparePlaces.ts      # maps_compare_places (composite)

skills/google-maps/SKILL.md

@@ -35,7 +35,7 @@ Without this Skill, the agent can only guess or refuse when asked "how do I get
 
 ## Tool Map
 
-15 tools in five categories — pick by scenario:
+16 tools in five categories — pick by scenario:
 
 ### Place Discovery
 | Tool | When to use | Example |
@@ -45,6 +45,7 @@ Without this Skill, the agent can only guess or refuse when asked "how do I get
 | `search-nearby` | Know a location, find nearby places by type | "Coffee shops near my hotel" |
 | `search-places` | Natural language place search | "Best ramen in Tokyo" |
 | `place-details` | Have a place_id, need full info | "Opening hours and reviews for this restaurant?" |
+| `batch-geocode` | Geocode multiple addresses at once (max 50) | "Get coordinates for all these offices" |
 
 ### Routing & Distance
 | Tool | When to use | Example |

skills/google-maps/references/tools-api.md

@@ -26,6 +26,33 @@ Response:
 
 ---
 
+## batch-geocode
+
+Geocode multiple addresses in one call (max 50).
+
+```bash
+exec batch-geocode-tool '{"addresses": ["Tokyo Tower", "Eiffel Tower", "Statue of Liberty"]}'
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| addresses | string[] | yes | List of addresses or landmarks (max 50) |
+
+Response:
+```json
+{
+  "total": 3,
+  "succeeded": 3,
+  "failed": 0,
+  "results": [
+    { "address": "Tokyo Tower", "success": true, "data": { "location": { "lat": 35.658, "lng": 139.745 }, "formatted_address": "..." } },
+    ...
+  ]
+}
+```
+
+---
+
 ## reverse-geocode
 
 Convert GPS coordinates to a street address.

src/cli.ts

@@ -92,6 +92,7 @@ const EXEC_TOOLS = [
   "compare-places",
   "air-quality",
   "static-map",
+  "batch-geocode-tool",
 ] as const;
 
 async function execTool(toolName: string, params: any, apiKey: string): Promise<any> {
@@ -183,6 +184,22 @@ async function execTool(toolName: string, params: any, apiKey: string): Promise<
     case "maps_static_map":
       return searcher.getStaticMap(params);
 
+    case "batch-geocode-tool":
+    case "maps_batch_geocode": {
+      const results = await Promise.all(
+        (params.addresses as string[]).map(async (address: string) => {
+          try {
+            const result = await searcher.geocode(address);
+            return { address, ...result };
+          } catch (error: any) {
+            return { address, success: false, error: error.message };
+          }
+        })
+      );
+      const succeeded = results.filter((r) => r.success).length;
+      return { success: true, data: { total: params.addresses.length, succeeded, failed: params.addresses.length - succeeded, results } };
+    }
+
     default:
       throw new Error(`Unknown tool: ${toolName}. Available: ${EXEC_TOOLS.join(", ")}`);
   }

src/config.ts

@@ -16,6 +16,7 @@ import { PlanRoute, PlanRouteParams } from "./tools/maps/planRoute.js";
 import { ComparePlaces, ComparePlacesParams } from "./tools/maps/comparePlaces.js";
 import { AirQuality, AirQualityParams } from "./tools/maps/airQuality.js";
 import { StaticMap, StaticMapParams } from "./tools/maps/staticMap.js";
+import { BatchGeocode, BatchGeocodeParams } from "./tools/maps/batchGeocode.js";
 
 // All Google Maps tools are read-only API queries
 const MAPS_TOOL_ANNOTATIONS = {
@@ -141,6 +142,13 @@ const serverConfigs: ServerInstanceConfig[] = [
         annotations: MAPS_TOOL_ANNOTATIONS,
         action: (params: StaticMapParams) => StaticMap.ACTION(params),
       },
+      {
+        name: BatchGeocode.NAME,
+        description: BatchGeocode.DESCRIPTION,
+        schema: BatchGeocode.SCHEMA,
+        annotations: MAPS_TOOL_ANNOTATIONS,
+        action: (params: BatchGeocodeParams) => BatchGeocode.ACTION(params),
+      },
     ],
   },
 ];

src/tools/maps/batchGeocode.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { PlacesSearcher } from "../../services/PlacesSearcher.js";
+import { getCurrentApiKey } from "../../utils/requestContext.js";
+
+const NAME = "maps_batch_geocode";
+const DESCRIPTION =
+  "Geocode multiple addresses in one call — up to 50 addresses, returns coordinates for each. Use when the user provides a list of addresses and needs all their coordinates, e.g. 'geocode these 10 offices' or 'get coordinates for all these restaurants'. For more than 50, use the CLI batch-geocode command instead.";
+
+const SCHEMA = {
+  addresses: z
+    .array(z.string())
+    .min(1)
+    .max(50)
+    .describe("List of addresses or landmark names to geocode (max 50)"),
+};
+
+export type BatchGeocodeParams = z.infer<z.ZodObject<typeof SCHEMA>>;
+
+async function ACTION(params: any): Promise<{ content: any[]; isError?: boolean }> {
+  try {
+    const apiKey = getCurrentApiKey();
+    const searcher = new PlacesSearcher(apiKey);
+    const addresses: string[] = params.addresses;
+
+    const results = await Promise.all(
+      addresses.map(async (address: string) => {
+        try {
+          const result = await searcher.geocode(address);
+          return { address, ...result };
+        } catch (error: any) {
+          return { address, success: false, error: error.message };
+        }
+      })
+    );
+
+    const succeeded = results.filter((r) => r.success).length;
+    const failed = results.filter((r) => !r.success).length;
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ total: addresses.length, succeeded, failed, results }, null, 2),
+        },
+      ],
+      isError: false,
+    };
+  } catch (error: any) {
+    const errorMessage = error instanceof Error ? error.message : JSON.stringify(error);
+    return {
+      isError: true,
+      content: [{ type: "text", text: `Error batch geocoding: ${errorMessage}` }],
+    };
+  }
+}
+
+export const BatchGeocode = {
+  NAME,
+  DESCRIPTION,
+  SCHEMA,
+  ACTION,
+};

tests/smoke.test.ts

@@ -212,6 +212,7 @@ async function testListTools(session: McpSession): Promise<void> {
     "maps_weather",
     "maps_air_quality",
     "maps_static_map",
+    "maps_batch_geocode",
   ];
 
   for (const name of expectedTools) {
@@ -459,6 +460,24 @@ async function testToolCalls(session: McpSession): Promise<void> {
       assert(typeof imageContent.data === "string" && imageContent.data.length > 100, "Static map returns base64 data");
     }
   }
+
+  // Test batch geocode
+  const batchResult = await sendRequest(session, "tools/call", {
+    name: "maps_batch_geocode",
+    arguments: { addresses: ["Tokyo Tower", "Eiffel Tower"] },
+  });
+  const batchContent = batchResult?.result?.content ?? [];
+  assert(batchContent.length > 0, "Batch geocode returns content");
+  if (batchContent.length > 0) {
+    let valid = false;
+    try {
+      const parsed = JSON.parse(batchContent[0].text);
+      valid = parsed?.total === 2 && parsed?.succeeded === 2 && Array.isArray(parsed?.results);
+    } catch {
+      /* ignore parse errors */
+    }
+    assert(valid, "Batch geocode returns 2 results with correct counts");
+  }
 }
 
 async function testMultiSession(): Promise<void> {