Skip to content

cablate/mcp-google-map / .agents/skills/project-docs

mcp-google-map-project

Unverified

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.

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

AspectSummary
WhatMCP server providing Google Maps tools for AI agents
StackTypeScript, Node.js, Express, MCP SDK, Zod
Tools18 tools (14 atomic + 4 composite)
Transportsstdio, Streamable HTTP, standalone exec CLI
APIsPlaces API (New), Directions, Geocoding, Elevation, Timezone, Weather, Air Quality, Static Maps, Search Along Route

Reference Files

FileContentWhen to read
references/architecture.mdSystem architecture, 3-layer design, transport modes, tool registration flow, 9-file checklist, code mapStart here when onboarding. Also read when adding new tools.
references/google-maps-api-guide.mdAll Google Maps API endpoints used, pricing, coverage limits, rate limits, common gotchas, Places New vs LegacyWhen debugging API errors, evaluating new APIs, or checking costs
references/geo-domain-knowledge.mdGIS fundamentals — coordinates, distance, geocoding, place types, spatial search, map projection, Japan-specific knowledgeWhen making tool design decisions that involve geographic concepts
references/decisions.md10 Architecture Decision Records (ADR) with context and rationaleWhen 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

TriggerWhat to update
Architecture changereferences/architecture.md
New Google Maps API integratedreferences/google-maps-api-guide.md
New design decision madereferences/decisions.md (add ADR)
New GIS concept relevant to toolsreferences/geo-domain-knowledge.md
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 318kUpdated Claude CodeCodexUnverifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall