# MCP Google Map Project

> Project knowledge for developing and maintaining @cablate/mcp-google-map. Architecture, Google Maps API guide, GIS domain knowledge, and design decisions. Read this skill to onboard onto the project or make informed development decisions.

- Skill: `cablate/mcp-google-map-project` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add cablate/mcp-google-map-project`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cablate/mcp-google-map-project/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: cablate (https://skillmd.com/u/cablate)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cablate/mcp-google-map-project

---


# mcp-google-map — Project Knowledge

## Overview

This skill contains everything needed to develop, maintain, and extend the `@cablate/mcp-google-map` MCP server. Reading these files gives you full context on architecture, API specifics, domain knowledge, and the reasoning behind design decisions.

For the **agent skill** (how to USE the tools), see `skills/google-maps/SKILL.md`.

---

## Quick Orientation

| Aspect | Summary |
|--------|---------|
| **What** | MCP server providing Google Maps tools for AI agents |
| **Stack** | TypeScript, Node.js, Express, MCP SDK, Zod |
| **Tools** | 17 tools (14 atomic + 3 composite) |
| **Transports** | stdio, Streamable HTTP, standalone exec CLI |
| **APIs** | Places API (New), Directions, Geocoding, Elevation, Timezone, Weather, Air Quality, Static Maps, Search Along Route |

---

## Reference Files

| File | Content | When to read |
|------|---------|--------------|
| `references/architecture.md` | System architecture, 3-layer design, transport modes, tool registration flow, 9-file checklist, code map | **Start here** when onboarding. Also read when adding new tools. |
| `references/google-maps-api-guide.md` | All Google Maps API endpoints used, pricing, coverage limits, rate limits, common gotchas, Places New vs Legacy | When debugging API errors, evaluating new APIs, or checking costs |
| `references/geo-domain-knowledge.md` | GIS fundamentals — coordinates, distance, geocoding, place types, spatial search, map projection, Japan-specific knowledge | When making tool design decisions that involve geographic concepts |
| `references/decisions.md` | 10 Architecture Decision Records (ADR) with context and rationale | When asking "why was X built this way?" or considering changes to existing design |

---

## How to Add a New Tool

See `references/architecture.md` § "9-File Tool Change Checklist" for the complete procedure. Summary:

1. Create `src/tools/maps/<toolName>.ts` (NAME, DESCRIPTION, SCHEMA, ACTION)
2. Register in `src/config.ts`
3. Add exec case in `src/cli.ts`
4. Add to `tests/smoke.test.ts` (expectedTools + API call test)
5. Update `README.md` (count + table + exec list + project structure)
6. Update `skills/google-maps/SKILL.md` (Tool Map)
7. Update `skills/google-maps/references/tools-api.md` (params + chaining)
8. Check `server.json` and `package.json` descriptions

---

## When to Update This Skill

| Trigger | What to update |
|---------|----------------|
| Architecture change | `references/architecture.md` |
| New Google Maps API integrated | `references/google-maps-api-guide.md` |
| New design decision made | `references/decisions.md` (add ADR) |
| New GIS concept relevant to tools | `references/geo-domain-knowledge.md` |