feat: tool annotations + actionable error messages + CHANGELOG (#31)

* feat: migrate to registerTool with annotations and improve error messages

- Migrate from deprecated server.tool() to server.registerTool() API
- Add MCP Tool Annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) to all 7 tools
- Improve Google Maps API error messages with actionable guidance for HTTP 403, 429, ZERO_RESULTS, OVER_QUERY_LIMIT, REQUEST_DENIED, INVALID_REQUEST
- Type-strengthen ToolConfig interface (schema: Record<string, z.ZodTypeAny>)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add CHANGELOG.md and strengthen smoke tests

- Add CHANGELOG.md following Claude Code's format (version + bullet points)
- Add annotations verification (readOnlyHint, destructiveHint) for all 7 tools
- Add inputSchema presence check for all tools
- Add E2E tests for reverse geocode, elevation, and distance matrix
- Test coverage: 21 → 55 assertions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: add PR/issue templates, auto-changelog, and GitHub Releases

- Add pull request template with summary/changes/test plan/changelog sections
- Add issue templates for bug reports and feature requests
- Update release workflow to auto-generate CHANGELOG entries from commit messages
- Add GitHub Release creation on publish

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: cablate

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior
+labels: bug
+---
+
+## Description
+
+<!-- What happened? -->
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behavior
+
+<!-- What should have happened? -->
+
+## Environment
+
+- Package version:
+- Node.js version:
+- MCP client (Claude Code / Cursor / other):
+- OS:
+
+## Logs
+
+<!-- Paste any relevant error messages or logs -->
+
+```
+
+```

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature Request
+about: Suggest a new tool or improvement
+labels: enhancement
+---
+
+## Problem
+
+<!-- What problem does this solve? -->
+
+## Proposed solution
+
+<!-- How should it work? -->
+
+## Alternatives considered
+
+<!-- Any other approaches you've thought about? -->

.github/pull_request_template.md

@@ -0,0 +1,28 @@
+## Summary
+
+<!-- What does this PR do? 1-3 bullet points -->
+
+-
+
+## Changes
+
+<!-- List the key files/areas changed -->
+
+| File | Change |
+|------|--------|
+| | |
+
+## Test plan
+
+- [ ] `npm run build` succeeds
+- [ ] `npm run lint` — 0 errors
+- [ ] `npm test` — all pass
+- [ ] Manual verification (if applicable)
+
+## Changelog entry
+
+<!-- Copy this to CHANGELOG.md under the next version -->
+
+```
+-
+```

.github/workflows/release.yml

@@ -13,6 +13,8 @@ jobs:
       contents: write
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - uses: actions/setup-node@v4
         with:
@@ -31,6 +33,31 @@ jobs:
       - name: Bump version
         run: npm version patch --no-git-tag-version
 
+      - name: Update CHANGELOG
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          PREV_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+
+          # Collect commit messages since last tag
+          if [ -n "$PREV_TAG" ]; then
+            COMMITS=$(git log ${PREV_TAG}..HEAD --pretty=format:"- %s" --no-merges | grep -v "^- chore: release")
+          else
+            COMMITS=$(git log --pretty=format:"- %s" --no-merges -10 | grep -v "^- chore: release")
+          fi
+
+          # Prepend new version to CHANGELOG.md
+          HEADER="## ${VERSION}"
+          TMPFILE=$(mktemp)
+          echo "# Changelog" > "$TMPFILE"
+          echo "" >> "$TMPFILE"
+          echo "$HEADER" >> "$TMPFILE"
+          echo "" >> "$TMPFILE"
+          echo "$COMMITS" >> "$TMPFILE"
+          echo "" >> "$TMPFILE"
+          # Append existing content (skip the first "# Changelog" line)
+          tail -n +2 CHANGELOG.md >> "$TMPFILE"
+          mv "$TMPFILE" CHANGELOG.md
+
       - name: Publish to npm
         run: npm publish --access public
         env:
@@ -41,8 +68,21 @@ jobs:
           VERSION=$(node -p "require('./package.json').version")
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add package.json package-lock.json
+          git add package.json package-lock.json CHANGELOG.md
           git commit -m "chore: release v${VERSION}"
           git tag "v${VERSION}"
           git push
           git push --tags
+
+      - name: Create GitHub Release
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          PREV_TAG=$(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || echo "")
+          if [ -n "$PREV_TAG" ]; then
+            NOTES=$(git log ${PREV_TAG}..v${VERSION} --pretty=format:"- %s" --no-merges | grep -v "^- chore: release")
+          else
+            NOTES="Initial release"
+          fi
+          gh release create "v${VERSION}" --title "v${VERSION}" --notes "$NOTES"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## 0.0.21
+
+- Migrated from deprecated `server.tool()` to `server.registerTool()` API for MCP SDK v1.27+ compatibility
+- Added MCP Tool Annotations to all tools — clients can now auto-approve read-only, non-destructive API queries without user confirmation
+- Improved Google Maps API error messages with actionable guidance (e.g. HTTP 403 now suggests enabling the Places API, HTTP 429 links to quota settings)
+- Added CI workflow for automated build, lint, and smoke tests on pull requests
+- Added release workflow for automated npm publishing on merge to main
+- Added ESLint 9 flat config with TypeScript and Prettier integration
+- Added smoke test suite for annotations, multi-tool E2E, and concurrent session validation
+
+## 0.0.20
+
+- Upgraded `@modelcontextprotocol/sdk` from ^1.11.0 to ^1.27.1 — fixes cross-client response data leakage between concurrent sessions (GHSA-345p-7cg4-v4c7, CVSS 7.1)
+- Upgraded `zod` to ^3.25.0 (peer dependency of SDK v1.23+)
+- Fixed multi-session crash by creating per-session McpServer instances in HTTP mode
+- Added smoke test suite covering server init, tools/list, geocode, and concurrent sessions
+- Pinned `@types/express` to v4
+
+## 0.0.19
+
+- Updated to Google's new Places API (New) to resolve HTTP 403 errors with the legacy API
+
+## 0.0.18
+
+- Standardized all error messages to English with more detailed information
+
+## 0.0.17
+
+- Added HTTP header authentication — API keys via `X-Google-Maps-API-Key` header
+- Fixed concurrent user issues — each session uses its own API key
+- Fixed npx execution module bundling issues
+- Improved documentation with clearer setup instructions
+
+## 0.0.14
+
+- Added streamable HTTP transport support
+- Improved CLI interface with emoji indicators
+- Enhanced error handling and logging
+- Added comprehensive tool descriptions for LLM integration
+- Updated to latest MCP SDK version

src/config.ts

@@ -8,8 +8,16 @@ import { ReverseGeocode, ReverseGeocodeParams } from "./tools/maps/reverseGeocod
 import { DistanceMatrix, DistanceMatrixParams } from "./tools/maps/distanceMatrix.js";
 import { Directions, DirectionsParams } from "./tools/maps/directions.js";
 import { Elevation, ElevationParams } from "./tools/maps/elevation.js";
+
+// All Google Maps tools are read-only API queries
+const MAPS_TOOL_ANNOTATIONS = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true,
+} as const;
+
 interface ServerInstanceConfig {
-  // Renamed from ServerConfig and modified
   name: string;
   portEnvVar: string;
   tools: ToolConfig[];
@@ -24,42 +32,49 @@ const serverConfigs: ServerInstanceConfig[] = [
         name: SearchNearby.NAME,
         description: SearchNearby.DESCRIPTION,
         schema: SearchNearby.SCHEMA,
+        annotations: MAPS_TOOL_ANNOTATIONS,
         action: (params: SearchNearbyParams) => SearchNearby.ACTION(params),
       },
       {
         name: PlaceDetails.NAME,
         description: PlaceDetails.DESCRIPTION,
         schema: PlaceDetails.SCHEMA,
+        annotations: MAPS_TOOL_ANNOTATIONS,
         action: (params: PlaceDetailsParams) => PlaceDetails.ACTION(params),
       },
       {
         name: Geocode.NAME,
         description: Geocode.DESCRIPTION,
         schema: Geocode.SCHEMA,
+        annotations: MAPS_TOOL_ANNOTATIONS,
         action: (params: GeocodeParams) => Geocode.ACTION(params),
       },
       {
         name: ReverseGeocode.NAME,
         description: ReverseGeocode.DESCRIPTION,
         schema: ReverseGeocode.SCHEMA,
+        annotations: MAPS_TOOL_ANNOTATIONS,
         action: (params: ReverseGeocodeParams) => ReverseGeocode.ACTION(params),
       },
       {
         name: DistanceMatrix.NAME,
         description: DistanceMatrix.DESCRIPTION,
         schema: DistanceMatrix.SCHEMA,
+        annotations: MAPS_TOOL_ANNOTATIONS,
         action: (params: DistanceMatrixParams) => DistanceMatrix.ACTION(params),
       },
       {
         name: Directions.NAME,
         description: Directions.DESCRIPTION,
         schema: Directions.SCHEMA,
+        annotations: MAPS_TOOL_ANNOTATIONS,
         action: (params: DirectionsParams) => Directions.ACTION(params),
       },
       {
         name: Elevation.NAME,
         description: Elevation.DESCRIPTION,
         schema: Elevation.SCHEMA,
+        annotations: MAPS_TOOL_ANNOTATIONS,
         action: (params: ElevationParams) => Elevation.ACTION(params),
       },
     ],

src/core/BaseMcpServer.ts

@@ -1,10 +1,11 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { isInitializeRequest, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import express, { Request, Response } from "express";
 import { Server } from "http";
 import { randomUUID } from "node:crypto";
+import { z } from "zod";
 import { Logger } from "../index.js";
 import { ApiKeyManager } from "../utils/apiKeyManager.js";
 import { runWithContext } from "../utils/requestContext.js";
@@ -15,8 +16,9 @@ const VERSION = "0.0.1";
 export interface ToolConfig {
   name: string;
   description: string;
-  schema: any; // Adjust type as per actual SDK (e.g., ZodSchema)
-  action: (params: any) => Promise<any>; // Adjust type for params and return
+  schema: Record<string, z.ZodTypeAny>;
+  annotations?: ToolAnnotations;
+  action: (params: any) => Promise<any>;
 }
 
 export interface SessionContext {
@@ -43,7 +45,15 @@ export class BaseMcpServer {
       { capabilities: { logging: {}, tools: {} } }
     );
     this.tools.forEach((tool) => {
-      server.tool(tool.name, tool.description, tool.schema, async (params: any) => tool.action(params));
+      server.registerTool(
+        tool.name,
+        {
+          description: tool.description,
+          inputSchema: z.object(tool.schema),
+          annotations: tool.annotations,
+        },
+        async (params: any) => tool.action(params)
+      );
     });
     return server;
   }

src/services/NewPlacesService.ts

@@ -235,12 +235,16 @@ export class NewPlacesService {
   }
 
   private extractErrorMessage(error: any): string {
-    const apiError = error?.message || error?.details || error?.status;
+    const statusCode = error?.code;
+    const message = error?.message || error?.details;
 
-    if (apiError) {
-      return `${apiError}`;
+    if (statusCode === 7 || statusCode === 403) {
+      return "API key invalid or Places API (New) not enabled. Check: console.cloud.google.com → APIs & Services → Enable 'Places API (New)'";
+    }
+    if (statusCode === 8 || statusCode === 429) {
+      return "API quota exceeded. Wait and retry, or check quota at console.cloud.google.com → Quotas";
     }
 
-    return error instanceof Error ? error.message : String(error);
+    return message || (error instanceof Error ? error.message : String(error));
   }
 }

src/services/toolclass.ts

@@ -37,19 +37,39 @@ interface GeocodeResult {
 }
 
 /**
- * Extracts a meaningful error message from various error types
- * Prioritizes Google Maps API error messages when available
+ * Extracts a meaningful, actionable error message from Google Maps API errors.
  */
 function extractErrorMessage(error: any): string {
-  // Extract Google API error message if available
-  const apiError = error?.response?.data?.error_message;
   const statusCode = error?.response?.status;
+  const apiError = error?.response?.data?.error_message;
+  const apiStatus = error?.response?.data?.status;
+
+  // Map common HTTP status codes to actionable messages
+  if (statusCode === 403) {
+    return "API key invalid or required API not enabled. Check: console.cloud.google.com → APIs & Services → Enable the relevant API (Places, Geocoding, etc.)";
+  }
+  if (statusCode === 429) {
+    return "API quota exceeded. Wait and retry, or check quota at console.cloud.google.com → Quotas";
+  }
+
+  // Map Google Maps API status codes
+  if (apiStatus === "ZERO_RESULTS") {
+    return "No results found. Try broader search terms or a larger radius.";
+  }
+  if (apiStatus === "OVER_QUERY_LIMIT") {
+    return "API quota exceeded. Wait and retry, or upgrade your billing plan.";
+  }
+  if (apiStatus === "REQUEST_DENIED") {
+    return `Request denied by Google Maps API. ${apiError || "Check your API key and enabled APIs."}`;
+  }
+  if (apiStatus === "INVALID_REQUEST") {
+    return `Invalid request parameters. ${apiError || "Check your input values."}`;
+  }
 
   if (apiError) {
     return `${apiError} (HTTP ${statusCode})`;
   }
 
-  // Fallback to standard error message
   return error instanceof Error ? error.message : String(error);
 }